Referencia

Referencia de la API

API v1 de Chasca: JSON sobre HTTPS con claves de API de tipo Bearer. El trabajo que lleva tiempo (la generación, los cambios y las ediciones) devuelve un 202 con un registro en cola que puedes consultar con polling o seguir por streaming.

URL base https://app.trychasca.com/api

Autenticación

Todos los endpoints de /v1, excepto los de voces e idiomas, necesitan una clave de API, que se envía como Authorization: Bearer chk_live_…. Crea las claves en la app, en Settings → API keys. El acceso a la API empieza en Plus, y los videos generados por API consumen el doble de minutos del plan (2x).

Convenciones

Los cuerpos son JSON (Content-Type: application/json). Las marcas de tiempo están en ISO 8601, en UTC.
Las operaciones que quedan en cola devuelven 202; crear una copia devuelve 201, y eliminar, 204.
El estado de un video explicativo avanza por queued → generating → rendering → ready, o termina en failed con un error legible. stage y progress (de 0 a 1) describen el paso en curso entre un estado y el siguiente.
Las URL de los archivos multimedia están firmadas y expiran después de aproximadamente una semana. Vuelve a solicitar el video explicativo para obtener enlaces nuevos.

Endpoints

POST `/v1/explainer`

Pone en cola un nuevo video explicativo. Devuelve 202 con el registro en cola.

Campos del cuerpo de la solicitud para crear un video explicativo
Campo	Tipo	Descripción
`input`	string	Qué explicar: un tema, una pregunta o el texto completo de un documento (hasta 200,000 caracteres). Alias: `prompt`. Es obligatorio enviar `input`, `source` o `sceneGraph`.
`length`	string \| number	`"M:SS"` (como `"1:30"`) o segundos, en múltiplos de 30 hasta 1800 (30 minutos). Por encima de 360, el video se cuenta en capítulos. Omítelo para que la duración sea automática. Alias: `lengthSeconds`.
`aspect`	string	`16:9` (predeterminado), `9:16` o `1:1`.
`voice`	string	El id de un narrador, como `chasca:sulafat` (predeterminado) o `chasca:kore`. Todos los narradores hablan todos los idiomas. Consulta Voces.
`language`	string	Código del idioma de la narración, por ejemplo, `en`, `es-419` o `ja`. Consulta Idiomas.
`source`	string	Texto de origen en el que se basa la explicación (hasta 400,000 caracteres). El guion se mantiene fiel a ese texto.
`preset`	string	Estilo de dibujo: `marker` (predeterminado), `chalkboard`, `pencil`, `blueprint`, `crayon` o `clean`.
`fillMode`	string	Cómo entra el color después de cada contorno: `A` fundido, `B` barrido, `C` relleno por zonas (predeterminado), `D` garabato.
`hand`	string	Una mano que dibuja la pizarra, con el lápiz en cada línea mientras aparece: `marker-light`, `marker-medium`, `marker-dark`, `pencil` o `sketch`, `off`, o `auto` (predeterminado: una mano solo cuando la petición pide verla).
`pace`	string	`relaxed`, `balanced` (predeterminado) o `brisk`.
`music`	boolean	Agrega música de fondo suave bajo la narración. Valor predeterminado: `false`.
`sceneGraph`	object	Omite el paso de escritura y renderiza tu propio grafo de escenas (escenas con narración, título y elementos).

Solicitud

curl -X POST https://app.trychasca.com/api/v1/explainer \
  -H "Authorization: Bearer $CHASCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "How does compound interest snowball?",
    "length": "1:30",
    "aspect": "9:16",
    "voice": "chasca:sulafat",
    "language": "en",
    "preset": "chalkboard",
    "pace": "balanced"
  }'

202 Accepted

{
  "id": "0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60",
  "status": "queued",
  "stage": null,
  "progress": 0,
  "title": null,
  "prompt": "How does compound interest snowball?",
  "lengthSeconds": 90,
  "voice": "chasca:sulafat",
  "language": "en",
  "aspect": "9:16",
  "preset": "chalkboard",
  "fillMode": "C",
  "pace": "balanced",
  "music": false,
  "videoUrl": null,
  "posterUrl": null,
  "subtitlesUrl": null,
  "durationSeconds": null,
  "watermarked": false,
  "sceneGraph": null,
  "headVersionId": null,
  "source": null,
  "error": null,
  "createdVia": "api",
  "createdAt": "2026-09-23T09:14:02.118Z",
  "updatedAt": "2026-09-23T09:14:02.118Z"
}

GET `/v1/explainer/:id`

Un video explicativo con todo: el estado, videoUrl, posterUrl, subtitlesUrl, el sceneGraph editable, los tiempos de cada escena en scenes y todas las entradas de versions.

Solicitud

curl https://app.trychasca.com/api/v1/explainer/0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60 \
  -H "Authorization: Bearer $CHASCA_API_KEY"

200 OK (abreviado)

{
  "id": "0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60",
  "status": "ready",
  "stage": null,
  "progress": 1,
  "title": "How compound interest snowballs",
  "lengthSeconds": 90,
  "durationSeconds": 88.4,
  "videoUrl": "https://app.trychasca.com/media/explainers/0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60/v1/video.mp4?exp=1790000000&sig=…",
  "posterUrl": "https://app.trychasca.com/media/explainers/0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60/v1/poster.jpg?exp=1790000000&sig=…",
  "subtitlesUrl": "https://app.trychasca.com/media/explainers/0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60/v1/subtitles.vtt?exp=1790000000&sig=…",
  "sceneGraph": {
    "title": "How compound interest snowballs",
    "language": "en",
    "scenes": [
      {
        "id": "s1",
        "heading": "THE MONEY THAT GROWS ITSELF",
        "narration": "Picture planting a tiny seed…",
        "elements": [
          { "id": "seed", "type": "icon", "icon": "seedling", "label": "SEED", "revealWord": "seed" }
        ]
      }
    ]
  },
  "scenes": [
    { "id": "s1", "index": 0, "heading": "THE MONEY THAT GROWS ITSELF", "start": 0, "duration": 19.3 }
  ],
  "versions": [
    {
      "id": "5f1d…",
      "number": 1,
      "status": "ready",
      "note": null,
      "changedScenes": [],
      "videoUrl": "https://app.trychasca.com/media/…",
      "durationSeconds": 88.4,
      "minutesCharged": 2.947,
      "createdAt": "2026-09-23T09:14:02.301Z",
      "readyAt": "2026-09-23T09:14:49.870Z",
      "error": null
    }
  ],
  "shareUrl": null,
  "error": null
}

GET `/v1/explainer?limit=50`

Tus videos explicativos, del más reciente al más antiguo. limit va de 1 a 100 y su valor predeterminado es 50. Los resúmenes no incluyen el grafo de escenas ni las versiones.

Solicitud

curl "https://app.trychasca.com/api/v1/explainer?limit=20" \
  -H "Authorization: Bearer $CHASCA_API_KEY"

200 OK (abreviado)

{
  "explainers": [
    { "id": "0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60", "status": "ready", "title": "How compound interest snowballs", "durationSeconds": 88.4, "createdAt": "2026-09-23T09:14:02.118Z" }
  ]
}

POST `/v1/explainer/:id/change`

Un solo cambio en un video explicativo terminado; todo lo demás queda exactamente como estaba. El cuerpo es un único cambio, que se elige con kind:

captions: captions (true o false) y, opcionalmente, captionStyle (pop, bold, clean, marker, typewriter o story).
style: preset, fillMode o ambos.
hand: hand, el id de una mano u off.
music: music (true o false).
logo o credit: position, como top-right (una línea de créditos también puede ir en top-center o bottom-center), u off. A partir de Pro.
voice: voice y, opcionalmente, pace.
aspect: aspect, 16:9, 9:16 o 1:1.

Devuelve 202. Los subtítulos, el estilo, la música, el logo y la línea de créditos crean una nueva versión gratuita de este video, { "made": "version", "version": { ... } }: conserva la narración y no consume minutos, y cuando su status llega a ready, el videoUrl del video explicativo apunta a ella. Una voz o un formato nuevos crean un video explicativo aparte a partir del mismo guion y los mismos dibujos, que se cobra como un video nuevo: { "made": "video", "explainer": { ... } }.

Solicitud

curl -X POST https://app.trychasca.com/api/v1/explainer/0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60/change \
  -H "Authorization: Bearer $CHASCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "style", "preset": "chalkboard" }'

202 Accepted

{
  "made": "version",
  "version": {
    "id": "5d0e93b4-…",
    "number": 2,
    "status": "queued",
    "note": "Board style: Chalkboard",
    "changedScenes": [],
    "videoUrl": null,
    "posterUrl": null,
    "durationSeconds": null,
    "minutesCharged": 0,
    "createdAt": "2026-09-23T09:20:11.004Z",
    "readyAt": null,
    "error": null
  }
}

POST `/v1/explainer/:id/edit`

Cambia tú mismo las palabras o los dibujos: obtén el video explicativo, edita su sceneGraph y envíalo de vuelta como { "sceneGraph": { ... } }. Devuelve 202 con la versión en cola. Solo se vuelven a dibujar las escenas que cambiaron, y la primera vez que vuelves a renderizar cada video es gratis. Espera a que el status de la versión llegue a ready; a partir de ese momento, el videoUrl del video explicativo apunta a ella.

Solicitud

# graph.json: { "sceneGraph": { ... } }, the explainer's sceneGraph with your changes
curl -X POST https://app.trychasca.com/api/v1/explainer/0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60/edit \
  -H "Authorization: Bearer $CHASCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @graph.json

202 Accepted

{
  "id": "8a2c7e10-…",
  "number": 3,
  "status": "queued",
  "note": null,
  "changedScenes": [],
  "videoUrl": null,
  "posterUrl": null,
  "durationSeconds": null,
  "minutesCharged": 0,
  "createdAt": "2026-09-23T09:24:37.512Z",
  "readyAt": null,
  "error": null
}

POST `/v1/explainer/:id/revert`

Restaura como actual una versión anterior ya terminada. Cuerpo: { "versionId": "..." }. Devuelve el video explicativo.

Solicitud

curl -X POST https://app.trychasca.com/api/v1/explainer/0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60/revert \
  -H "Authorization: Bearer $CHASCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "versionId": "5f1d…" }'

POST `/v1/explainer/:id/duplicate`

Copia un video explicativo, con su grafo de escenas y todo lo demás, para que puedas llevarlo por otro camino. Devuelve 201 con la copia.

Solicitud

curl -X POST https://app.trychasca.com/api/v1/explainer/0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60/duplicate \
  -H "Authorization: Bearer $CHASCA_API_KEY"

DELETE `/v1/explainer/:id`

Elimina un video explicativo. Devuelve 204 sin cuerpo.

Solicitud

curl -X DELETE https://app.trychasca.com/api/v1/explainer/0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60 \
  -H "Authorization: Bearer $CHASCA_API_KEY"

GET `/v1/explainer/events`

Un flujo de Server-Sent Events con un mensaje event: status por cada cambio de estado de cualquiera de tus videos explicativos. Mantén una conexión abierta en lugar de hacer polling.

Solicitud

curl -N https://app.trychasca.com/api/v1/explainer/events \
  -H "Authorization: Bearer $CHASCA_API_KEY"

Flujo de eventos

event: status
data: {"type":"status","explainerId":"0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60","status":"generating","stage":"storyboard","progress":0.3}

event: status
data: {"type":"status","explainerId":"0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60","status":"rendering","stage":"drawing","progress":0.72}

event: status
data: {"type":"status","explainerId":"0b9c6f2e-5d1a-4c3e-9a47-2f8e1c7d4b60","status":"ready","stage":null,"progress":1}

GET `/v1/voices` No requiere clave

El catálogo de voces. Todos los narradores hablan todos los idiomas, así que la lista es la misma en cualquier idioma. Cada voz tiene un tone, un group y una preview_url. Más información en la página Voces.

Solicitud

curl "https://app.trychasca.com/api/v1/voices"

200 OK (abreviado)

{
  "default": "chasca:sulafat",
  "voices": [
    {
      "id": "chasca:sulafat",
      "name": "Sulafat",
      "description": "Warm and natural, like a favorite teacher. The all-purpose default.",
      "tone": "Warm",
      "group": "warm",
      "language": "en",
      "gender": "female",
      "isDefault": true,
      "multilingual": true,
      "kind": "narrator",
      "preview_url": "https://app.trychasca.com/api/v1/voices/chasca%3Anova/preview.mp3"
    },
    {
      "id": "edge:es-MX-DaliaNeural",
      "name": "Dalia",
      "description": "Friendly, Positive. Native es-MX speaker.",
      "language": "es-MX",
      "gender": "female",
      "isDefault": false,
      "multilingual": false,
      "kind": "native",
      "preview_url": "https://app.trychasca.com/api/v1/voices/edge%3Aes-MX-DaliaNeural/preview.mp3"
    }
  ]
}

GET `/v1/languages` No requiere clave

Todos los idiomas de narración. Los idiomas beta llevan menos tiempo en el modelo de voz, así que la calidad de la narración puede variar.

Solicitud

curl https://app.trychasca.com/api/v1/languages

200 OK (abreviado)

{
  "languages": [
    { "code": "en", "label": "English", "native": "English", "beta": false },
    { "code": "es-419", "label": "Spanish (Latin America)", "native": "Español (Latinoamérica)", "beta": false },
    { "code": "pa", "label": "Punjabi", "native": "ਪੰਜਾਬੀ", "beta": true }
  ]
}

GET `/v1/account/state`

A quién pertenece la clave y cuántos videos ha creado su titular.

Solicitud

curl https://app.trychasca.com/api/v1/account/state \
  -H "Authorization: Bearer $CHASCA_API_KEY"

200 OK

{ "videosGenerated": 14, "image": null, "isAdmin": false, "name": "Ada Lovelace" }

GET `/v1/billing/status`

El plan asociado a la clave y en qué punto del periodo estás: minutos usados y restantes y lo que incluye el plan. Las cuentas gratuitas reciben en su lugar videoAllowance, videosUsed y videosRemaining.

Solicitud

curl https://app.trychasca.com/api/v1/billing/status \
  -H "Authorization: Bearer $CHASCA_API_KEY"

200 OK

{
  "plan": "pro",
  "planLabel": "Pro",
  "billingInterval": "monthly",
  "status": "active",
  "trialStatus": null,
  "quotaMinutes": 200,
  "bonusMinutes": 0,
  "minutesUsedThisPeriod": 41.5,
  "minutesRemaining": 158.5,
  "periodStart": "2026-09-01T00:00:00.000Z",
  "periodEnd": "2026-10-01T00:00:00.000Z",
  "cancelAtPeriodEnd": false,
  "overageEnabled": false,
  "overagePerMinute": 0.5,
  "pricePerMonth": 49.99,
  "maxLengthSeconds": 1800,
  "entitlements": { "api": true, "branding": true, "voiceClone": true, "priority": false, "watermark": false, "maxLength": 1800, "videoAllowance": null }
}

GET `/config` No requiere clave

Configuración pública para clientes: dónde están el sitio, la app y la API.

Solicitud

curl https://app.trychasca.com/api/config

200 OK

{
  "authEnforced": true,
  "googleEnabled": false,
  "requireEmailVerification": false,
  "siteUrl": "https://trychasca.com",
  "appUrl": "https://app.trychasca.com",
  "apiUrl": "https://app.trychasca.com/api",
  "devMail": false
}

GET `/health` No requiere clave

Comprobación de que el servicio está activo, para balanceadores de carga y monitores de disponibilidad.

Solicitud

curl https://app.trychasca.com/api/health

200 OK

{ "status": "ok", "service": "chasca-api", "time": "2026-09-23T09:14:00.000Z", "db": "postgres", "tts": "edge", "llmConfigured": true }

Errores

Todos los errores tienen la misma forma, con un code estable y legible por máquinas, y un mensaje que puedes mostrar a tus usuarios:

402 Payment Required

{
  "error": true,
  "code": "api_requires_plan",
  "message": "API and MCP access start on the Plus plan.",
  "status": 402
}

Códigos de error comunes
Estado	Código	Significado
400	bad_request, empty_input, bad_voice	La solicitud está mal formada o no indica qué explicar.
400	instruction_edits_retired	Una edición envió una instrucción en lenguaje natural. Envía un solo cambio o un grafo de escenas editado.
401	unauthenticated	Falta la clave, o es incorrecta o fue revocada.
402	api_requires_plan, branding_requires_plan	El acceso a la API y a MCP empieza en Plus; los cambios de logo y de línea de créditos, en Pro.
402	minutes_exhausted, minutes_short	No quedan minutos en este periodo, o no alcanzan para la duración que pediste.
404	not_found	No hay ningún video explicativo con ese id en tu cuenta.
409	still_rendering, no_changes	El video se está renderizando, o el cambio o la edición no modifican nada.
409	no_logo, no_credit_line	Todavía no hay un logo o una línea de créditos que colocar. Agrega el que falte en la app, en Settings → Branding.
429	rate_limited	Demasiadas solicitudes. Espera el tiempo que indica el encabezado Retry-After y vuelve a intentarlo.
500	internal	Es un error nuestro. Los detalles quedan registrados en nuestros sistemas y nunca se exponen.

Límites de frecuencia

Generación, cambios y ediciones (POST /v1/explainer, …/change, …/edit): 20 solicitudes por minuto.
Todo lo demás: 200 solicitudes por minuto.
Si superas el límite, recibes 429 rate_limited con un encabezado Retry-After que indica los segundos de espera. El SDK reintenta las solicitudes de lectura una vez, tras esa espera, y la expone en los errores como retryAfter.