La API de explicadores

Crea explicadores visuales y narrados a partir de tu propio código, y luego compártelos, incrústalos o elimínalos, y lee su narración como texto. Seis endpoints, una API key y JSON de entrada y de salida.

La API está en beta. Para usarla, solicita acceso a la API.

Conceptos básicos

Todos los endpoints están bajo una misma URL base y responden en JSON.

https://scrimba.com/api/v1

Cada solicitud envía tu API key como bearer token:

Authorization: Bearer scr_live_…

El cuerpo de una solicitud es application/json, o multipart/form-data cuando lleva archivos. Las fechas de las respuestas son cadenas ISO 8601 en UTC. Los ids son cadenas opacas. Una respuesta de error también es JSON; mira Errores.

La versión va en la ruta. Las respuestas pueden recibir campos nuevos sin cambiar de versión; dentro de v1, ningún campo se elimina ni cambia de nombre.

API keys

Una API key pertenece a una cuenta de Scrimba. Todo lo que crea la key le pertenece a esa cuenta, se descuenta de su asignación mensual y aparece en el sitio bajo esa cuenta.

1. Inicia sesión en scrimba.com. Desde el menú de tu perfil, abre Settings y luego la sección API keys.
2. Elige Create API key y ponle un nombre, por ejemplo el del servidor que la va a guardar.
3. Copia el secreto del diálogo. Empieza con scr_live_ y se muestra una sola vez: Scrimba solo guarda un hash de él.

La API está en beta. Una cuenta necesita acceso a la API antes de que se abra el diálogo de la API key. Hasta que Scrimba habilite la cuenta, el diálogo y todas las llamadas a la API responden 403 api_not_enabled.

Guarda el secreto en tu servidor, nunca en un navegador ni en una app que distribuyas. Para desactivar una key, elige Revoke en su fila, en la misma sección. Una key revocada responde 401 desde ese momento y no se puede restaurar; en su lugar, crea una nueva. Una cuenta puede tener como máximo 20 keys activas, y todas comparten los límites de la cuenta.

Los ejemplos de abajo usan dos variables de shell:

export SCRIMBA=https://scrimba.com
export SCRIMBA_KEY=scr_live_your_secret_here

Inicio rápido

Crea un explicador, espera a que termine y luego comparte su enlace. La llamada de creación responde de inmediato; el explicador se genera en segundo plano y su página se renderiza en vivo mientras se construye.

const base = 'https://scrimba.com/api/v1'
const headers = {Authorization: `Bearer ${process.env.SCRIMBA_KEY}`}

const created = await fetch(`${base}/explainers`, {
  method: 'POST',
  headers: {...headers, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID()},
  body: JSON.stringify({prompt: 'Explain how the Node.js event loop schedules work', privacy: 'unlisted'})
})
if (!created.ok) throw new Error((await created.json()).error.message)

let explainer = await created.json()
while (explainer.status === 'generating') {
  await new Promise(resolve => setTimeout(resolve, 5000))
  explainer = await (await fetch(`${base}/explainers/${explainer.id}`, {headers})).json()
}
console.log(explainer.status, explainer.url)

Un explicador corto está listo en menos de un minuto. Uno largo puede tardar unos minutos. Consulta su estado cada 5 segundos, más o menos.

GET /api/v1/me

La cuenta detrás de la key, la key en sí, el plan y el uso mensual de la cuenta, y los nombres que acepta el endpoint de creación.

curl -s "$SCRIMBA/api/v1/me" -H "Authorization: Bearer $SCRIMBA_KEY"

{
  "account": {"id": "u1a2b3c", "alias": "acme", "name": "Acme Learning"},
  "key": {"id": "ak9x", "name": "server", "prefix": "scr_live_abc123", "created_at": "2026-10-09T10:12:00.000Z"},
  "tier": {"name": "pro", "requests_per_minute": 120, "concurrent_generations": 3, "explainers_per_month": 100},
  "explainers": {"used": 12, "remaining": 88, "resets_at": "2026-11-01T00:00:00.000Z"},
  "teachers": ["eli5", "standard", "per", "tom", "lol", "professor", "tldr"],
  "modes": ["landscape", "portrait", "square"],
  "privacy": ["private", "unlisted", "public"]
}

key.prefix es el inicio del secreto, suficiente para distinguir una key de otra. tier.explainers_per_month es el límite mensual de la cuenta: el número de su nivel, o uno que Scrimba fijó para la cuenta. explainers.resets_at es el momento en que el conteo mensual vuelve a empezar.

POST /api/v1/explainers

Crea un explicador e inicia su generación. Responde 201 con el objeto del explicador en cuanto el explicador existe; en ese momento, status es generating.

Campos

Campo	Valores	Predeterminado
prompt	Qué explicar, como una cadena de hasta 12,000 caracteres. Obligatorio, salvo que la solicitud tenga un adjunto.
mode	landscape (16:9), portrait (9:16), square (1:1). La forma de las diapositivas.	landscape
privacy	private (solo tu cuenta), unlisted (cualquiera con el enlace), public (aparece listado en el sitio).	private
language	Un código ISO 639-1, como en o pt-BR. La narración y el texto visible están en ese idioma, sin importar el idioma del prompt. Una región, como en pt-BR, selecciona esa variante del idioma.	El idioma del prompt
teacher	eli5, standard, per, tom, lol, professor, tldr. La voz y el estilo de la explicación.	eli5
watermark	true o false. false requiere una cuenta Pro.	true
attachments	Partes de archivo multipart, hasta 5. Mira Adjuntos.
cite_attachments	true o false. Con true, la narración cita las partes de tus adjuntos de texto de las que enseña, y la transcripción lleva esas citas.	false

Un campo que omites, o que envías como null, toma su valor predeterminado. Un campo que envías debe indicar un valor: language: false se rechaza, igual que privacy: false.

JSON

curl -s "$SCRIMBA/api/v1/explainers" \
  -H "Authorization: Bearer $SCRIMBA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-explainer" \
  -d '{
    "prompt": "Explain how HTTP caching headers decide what a browser keeps",
    "mode": "landscape",
    "privacy": "unlisted",
    "language": "en",
    "teacher": "standard"
  }'

Multipart, con adjuntos

Envía un cuerpo multipart/form-data. Los campos de texto son los mismos. Agrega cada archivo como una parte llamada attachments. El prompt es opcional cuando hay al menos un adjunto.

curl -s "$SCRIMBA/api/v1/explainers" \
  -H "Authorization: Bearer $SCRIMBA_KEY" \
  -F "prompt=Walk through this diagram and the code behind it" \
  -F "mode=portrait" \
  -F "[email protected]" \
  -F "[email protected]"

Idempotencia

Envía un header Idempotency-Key: una cadena propia de 1 a 200 caracteres imprimibles, una por cada explicador que quieras crear. Si una solicitud se corta antes de que leas la respuesta, repítela con la misma API key y el mismo header: la API responde con el explicador que ya creó, con 200 en lugar de 201, y no crea un segundo. Dos solicitudes que llegan a la vez con el mismo header crean un solo explicador. El header se recuerda por API key; cuando eliminas un explicador, su header queda libre.

Respuesta

{
  "id": "guide0abc123",
  "url": "https://scrimba.com/explain/guide0abc123",
  "status": "generating",
  "error": null,
  "title": "Explain how HTTP caching headers decide what a browser keeps",
  "description": null,
  "mode": "landscape",
  "privacy": "unlisted",
  "language": null,
  "created_at": "2026-10-09T10:15:02.000Z",
  "finished_at": null,
  "video_url": null,
  "embed": "<iframe src=\"https://scrimba.com/explain/guide0abc123\" …></iframe>",
  "attachments": [],
  "duration_ms": 0
}

Abre o comparte la url de inmediato. La página muestra cómo se construye el explicador y lo reproduce cuando está listo.

Una creación rechazada no crea nada ni gasta nada. Una creación que supera la asignación del mes responde 429 quota_exceeded, y una que llega cuando la cuenta ya tiene en curso todas las generaciones que permite su plan responde 429 too_many_running; ambas incluyen Retry-After.

GET /api/v1/explainers/:id

Un explicador que la cuenta creó a través de la API, con su estado actual.

curl -s "$SCRIMBA/api/v1/explainers/guide0abc123" -H "Authorization: Bearer $SCRIMBA_KEY"

status pasa de generating a ready o failed, y después ya no cambia. Cuando es ready, se completan finished_at, language y duration_ms. Cuando es failed, error indica el motivo, la página en url muestra que el explicador falló y el explicador no cuenta para el mes: se devuelve su crédito. Una generación que se detiene sin terminar, por ejemplo por un reinicio del servidor, se reporta como failed después de diez minutos.

Un explicador creado en el sitio, o creado a través de la API por otra cuenta, responde 404.

GET /api/v1/explainers/:id/transcript

La narración de un explicador listo: una entrada por pasaje hablado, en orden de reproducción, con las partes de tus adjuntos que cita cada pasaje. La narración señala la diapositiva como siempre; una cita dice de dónde vienen sus palabras.

Mientras el explicador se está generando, y cuando falló, la respuesta es 409 not_ready. Un explicador creado en el sitio, o creado a través de la API por otra cuenta, responde 404.

curl -s "$SCRIMBA/api/v1/explainers/guide0abc123/transcript" -H "Authorization: Bearer $SCRIMBA_KEY"

{
  "id": "guide0abc123",
  "attachments": [{"ref": 1, "name": "server.ts", "type": "text/plain"}],
  "entries": [
    {
      "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"
        }
      ]
    }
  ]
}

Campo	Tipo	Significado
attachments	array	La misma lista que lleva el objeto explicador, así que basta con una llamada.
entries[].index	number	La posición de la entrada en la narración, desde 0.
entries[].slide	number	La diapositiva que se muestra mientras suena la entrada, desde 0.
entries[].title	string o null	La etiqueta de narración que el explicador le dio al pasaje.
entries[].text	string	Las palabras habladas, tal como las muestra la transcripción de la página.
entries[].references	array	Las partes de tus adjuntos que cita la entrada, en el orden en que la narración las lista. Vacío cuando la entrada no cita ninguna.
references[].text	string	Las palabras de text que respalda la cita.
references[].text_start, text_end	number o null	Dónde están esas palabras en text: el índice del primer carácter y el índice posterior al último. Null cuando la narración no dice las palabras exactamente como las da la cita.
references[].attachment	number	El ref del archivo citado en attachments.
references[].offset, length	number	La parte citada del archivo: su primer carácter y cuántos caracteres abarca.
references[].lines	array	La primera y la última línea de la parte citada, contadas desde 1.
references[].cited_text	string	La parte citada en sí.

Las citas vienen de cite_attachments: true en la creación; Citas muestra cómo usarlas. Sin él, cada lista references está vacía. Solo se citan archivos de texto y código, nunca imágenes ni PDF.

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.

GET /api/v1/explainers

Los explicadores que la cuenta creó a través de la API, del más reciente al más antiguo, en páginas. Los explicadores creados en el sitio no aparecen en la lista.

Parámetro de consulta	Valores	Predeterminado
limit	Filas por página, de 1 a 100.	25
cursor	El next_cursor de la página anterior.	La primera página

curl -s "$SCRIMBA/api/v1/explainers?limit=25" -H "Authorization: Bearer $SCRIMBA_KEY"
# {"explainers": [{…}, {…}], "next_cursor": "guide0abc123"}

curl -s "$SCRIMBA/api/v1/explainers?limit=25&cursor=guide0abc123" -H "Authorization: Bearer $SCRIMBA_KEY"
# {"explainers": [{…}], "next_cursor": null}

Cada fila es un objeto del explicador sin duration_ms. next_cursor es null en la última página. Un cursor sigue siendo válido después de que se elimina su explicador; un cursor que nunca correspondió a uno de los explicadores de la API de la cuenta responde 400 invalid_cursor.

DELETE /api/v1/explainers/:id

Elimina un explicador que la cuenta creó a través de la API, junto con su video exportado si lo tiene. La página del explicador y su enlace dejan de funcionar, y desde ese momento el explicador responde 404. Su crédito no se devuelve.

curl -s -X DELETE "$SCRIMBA/api/v1/explainers/guide0abc123" -H "Authorization: Bearer $SCRIMBA_KEY"
# {"deleted": "guide0abc123"}

El objeto del explicador

Lo que POST, GET y la lista responden para un explicador.

Campo	Tipo	Significado
id	string	El id del explicador, que se usa en las rutas de arriba.
url	string	La página del explicador. Quién puede abrirla depende de privacy.
status	string	generating, ready o failed.
error	object o null	{"code": "generation_failed", "message": "…"} cuando status es failed; en otro caso, null.
title	string	El título del explicador: el prompt, o un nombre tomado de los adjuntos cuando no hay prompt.
description	string o null	Un resumen breve, que se completa cuando el explicador está listo.
mode	string	landscape, portrait o square.
privacy	string	private, unlisted o public.
language	string o null	El idioma de la narración, como una etiqueta del tipo en-us. null hasta que el explicador está listo.
created_at	string	Cuándo se creó el explicador.
finished_at	string o null	Cuándo terminó la generación; null mientras está en curso o si falló.
video_url	string o null	Un MP4 del explicador. Solo se completa cuando existe una exportación de video y el explicador es unlisted o public.
embed	string o null	Un fragmento <iframe> para tus propias páginas. Solo se completa cuando el explicador es unlisted o public: el iframe de un explicador private le muestra la pantalla de inicio de sesión a todos menos a ti.
attachments	array	Los archivos enviados con la solicitud, en el orden de envío: {"ref": 1, "name": "server.ts", "type": "text/plain"}. ref es el número con el que el explicador identifica el archivo.
duration_ms	number	La duración de la reproducción en milisegundos; 0 hasta que el explicador está listo. Solo en POST y GET, no en la lista.

Adjuntos

Una solicitud puede llevar hasta 5 archivos, como partes multipart llamadas attachments. El explicador los lee como contexto y puede mostrar imágenes que vengan de ellos.

Tipo	Se acepta como	Límite
Imágenes	png, jpeg, gif, webp	5 MB y 30 megapíxeles cada una
PDF	application/pdf	5 MB cada uno
Texto y código	Cualquier tipo text/*, o un nombre que termine en txt, md, log, env, conf, cfg, ini, js, jsx, ts, tsx, py, json, imba, html, css	30,000 caracteres cada uno
Notebooks de Jupyter	Un nombre que termine en .ipynb	Se guarda como markdown y se mide como texto: 30,000 caracteres

Una imagen o un PDF se identifica por sus bytes, sin importar el tipo de contenido que declare la parte. Cualquier otro archivo se identifica por el tipo declarado, o por sus bytes cuando la parte no declara ninguno o declara application/octet-stream. Un archivo de otro tipo responde 415 unsupported_attachment, y un archivo que supera su límite responde 413 too_large; ambas respuestas nombran el archivo. Una solicitud rechazada no guarda nada.

El cuerpo completo de la solicitud puede pesar como máximo 32 MB. Un cuerpo JSON, como máximo 256 KB.

Límites

Límite	Gratis	Pro
Explicadores al mes, por cuenta	5	100
Generaciones en curso a la vez, por cuenta	1	3
Solicitudes por minuto, sumando todas las keys de la cuenta	30	120
watermark: false	No	Sí

Pro es la suscripción Scrimba Pro de la cuenta. Scrimba puede dar a una cuenta un límite mensual propio, incluso 0; GET /api/v1/me y una respuesta quota_exceeded indican el límite que aplica.

El conteo mensual se reinicia el primer día del mes, en UTC; GET /api/v1/me indica la hora exacta. Solo cuentan los explicadores que se crean, y un explicador que falla devuelve su crédito. Una solicitud rechazada no gasta nada.

Un rechazo por límite es un 429 con un header Retry-After en segundos. Espera ese tiempo en lugar de reintentar de inmediato.

Errores

Todos los errores responden JSON con la misma forma, con un estado HTTP que indica el tipo de error y un código que indica la causa:

{"error": {"code": "invalid_prompt", "message": "The prompt is over 12000 characters"}}

Estado	Código	Significado
400	invalid_prompt, invalid_mode, invalid_privacy, invalid_language, invalid_teacher, invalid_watermark, invalid_cite_attachments, too_many_attachments, invalid_json, invalid_multipart, invalid_idempotency_key, invalid_limit, invalid_cursor	Un campo, un header o el cuerpo es incorrecto. El mensaje indica cuál.
401	unauthorized	El bearer token falta, es desconocido o fue revocado.
403	api_not_enabled	La cuenta todavía no está habilitada para la API.
403	pro_required	watermark: false en una cuenta sin Pro.
404	not_found	No hay ningún explicador con ese id en esta cuenta, o se eliminó.
409	not_ready	La transcripción de un explicador que todavía se está generando, o que falló.
413	too_large	Un cuerpo JSON supera 256 KB, un cuerpo multipart supera 32 MB, una imagen o un PDF supera 5 MB o 30 megapíxeles, o un archivo de texto supera 30,000 caracteres. El mensaje nombra el archivo.
415	unsupported_attachment, unsupported_media_type	Un archivo de un tipo que un explicador no acepta, o un cuerpo que no es ni JSON ni multipart.
429	rate_limited	Se superó el límite de solicitudes por minuto de la cuenta, o se están subiendo demasiadas imágenes en todo el sitio. Espera lo que indica Retry-After.
429	too_many_running	La cuenta ya tiene en curso todas las generaciones que permite su plan. Espera lo que indica Retry-After, o a que una termine.
429	quota_exceeded	Se agotaron los explicadores del mes. El mensaje indica cuándo se reinicia el conteo.
503	busy	El servidor tiene demasiadas subidas en este momento. Vuelve a intentarlo en unos instantes.
500	internal	Un fallo del lado de Scrimba. Vuelve a intentarlo más tarde; si el problema continúa, contacta a Scrimba con la hora y el id del explicador, si lo tienes.

Esta página describe la API de explicadores al 20 de octubre de 2026.