Citas

Cuando creas un explicador a través de la API a partir de tus propios archivos, puedes hacer que la narración los cite. Cada línea hablada registra entonces de qué parte de qué archivo enseña, y tú lo lees como datos.

Úsalo para mostrar la fuente junto al video, para comprobar la lección contra el archivo del que salió, o para enlazar una frase de la narración con las líneas exactas que describe.

Activar las citas

Envía cite_attachments: true con la solicitud de creación, junto con al menos un adjunto de texto. El explicador se escribe con las citas incluidas; nada cambia en su página.

curl -s "$SCRIMBA/api/v1/explainers" \
  -H "Authorization: Bearer $SCRIMBA_KEY" \
  -F "prompt=Walk through how this handler checks the token" \
  -F "cite_attachments=true" \
  -F "[email protected]"

Solo se citan archivos de texto y código, nunca imágenes ni PDF. Sin cite_attachments, el explicador se crea como siempre y cada lista de citas queda vacía. Un valor que no sea true ni false responde 400 invalid_cite_attachments.

Leerlas

Cuando el explicador está listo, GET /api/v1/explainers/:id/transcript devuelve la narración como una lista de entradas, una por pasaje hablado en orden de reproducción. Cada entrada lleva sus citas en references.

{
  "index": 3,
  "slide": 2,
  "title": "Checking the token",
  "text": "The handler reads the token from the header, then compares it to the stored secret.",
  "references": [
    {
      "text": "reads the token from the header",
      "text_start": 12,
      "text_end": 43,
      "attachment": 1,
      "offset": 412,
      "length": 39,
      "lines": [10, 10],
      "cited_text": "const token = req.headers.authorization"
    }
  ]
}

Una cita une palabras de la narración con una parte de un archivo:

• text, text_start y text_end son las palabras de la entrada que la cita respalda, y dónde están en el text de la entrada.
• attachment es el archivo, por el número ref que el objeto explicador lista en attachments.
• offset, length, lines y cited_text son la parte citada de ese archivo: su posición en caracteres, su primera y última línea contadas desde 1, y el texto en sí.

Mientras el explicador todavía se está generando, o después de que falló, el endpoint responde 409 not_ready.

Qué esperar

El modelo decide qué citar. Cita la frase, el valor o el pasaje del que sale un punto, la parte útil más pequeña, y un pasaje puede llevar varias citas a un archivo o a varios. Una línea que no enseña nada de los archivos no tiene ninguna.

• text_start y text_end son null cuando la narración no dice las palabras citadas exactamente como están escritas; en ese caso, busca tú mismo en text.
• Un archivo de texto se lee hasta 30.000 caracteres, y offset cuenta dentro de lo leído.
• Una cita cuya parte citada no se encuentra en el archivo se omite.

Para la referencia campo por campo, ve La API de explicadores.