Référence

Référence de l’API

L’API Chasca v1 : du JSON sur HTTPS, avec des clés API envoyées en Bearer. Les opérations qui prennent du temps (génération, changements et modifications) renvoient un 202 avec un enregistrement en file d’attente, que vous pouvez suivre par polling ou en streaming.

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

Authentification

Tous les endpoints /v1, sauf ceux des voix et des langues, exigent une clé API, envoyée sous la forme Authorization: Bearer chk_live_…. Créez vos clés dans l’application, sous Settings → API keys. L’accès à l’API commence avec l’offre Plus, et les générations via l’API comptent double sur les minutes de l’offre.

Conventions

Les corps sont en JSON (Content-Type: application/json). Les horodatages sont au format ISO 8601, en UTC.
Un traitement mis en file d’attente renvoie 202 ; la création d’une copie renvoie 201 ; une suppression renvoie 204.
Le statut d’une vidéo explicative passe par queued → generating → rendering → ready, ou se termine par failed avec un message lisible dans error. stage et progress (de 0 à 1) indiquent où en est le traitement entre deux statuts.
Les URL des médias sont signées et expirent au bout d’une semaine environ. Récupérez de nouveau la vidéo explicative pour obtenir des liens à jour.

Endpoints

POST `/v1/explainer`

Met en file d’attente une nouvelle vidéo explicative. Renvoie 202 avec l’enregistrement en file d’attente.

Champs du corps de la requête pour créer une vidéo explicative
Champ	Type	Description
`input`	string	Ce qu’il faut expliquer : un sujet, une question ou le texte intégral d’un document (jusqu’à 200 000 caractères). Alias : `prompt`. L’un des champs `input`, `source` ou `sceneGraph` est obligatoire.
`length`	string \| number	`"M:SS"` (par exemple `"1:30"`) ou un nombre de secondes, multiple de 30, jusqu’à 1800 (30 minutes). Au-delà de 360, la vidéo est racontée en chapitres. Omettez ce champ pour une durée automatique. Alias : `lengthSeconds`.
`aspect`	string	`16:9` (par défaut), `9:16` ou `1:1`.
`voice`	string	Un identifiant de narrateur, comme `chasca:sulafat` (par défaut) ou `chasca:kore`. Chaque narrateur parle toutes les langues. Voir Voix.
`language`	string	Code de la langue de narration, par exemple `en`, `es-419`, `ja`. Voir Langues.
`source`	string	Texte source sur lequel s’appuie l’explication (jusqu’à 400 000 caractères). Le script lui reste fidèle.
`preset`	string	Style de dessin : `marker` (par défaut), `chalkboard`, `pencil`, `blueprint`, `crayon` ou `clean`.
`fillMode`	string	Manière dont la couleur s’applique après chaque contour : `A` fondu, `B` balayage, `C` lavis par zone (par défaut), `D` gribouillis.
`hand`	string	Une main qui dessine le tableau, le crayon sur chaque trait à mesure qu’il apparaît : `marker-light`, `marker-medium`, `marker-dark`, `pencil` ou `sketch`, `off`, ou `auto` (par défaut : une main seulement quand la demande veut la voir).
`pace`	string	`relaxed`, `balanced` (par défaut) ou `brisk`.
`music`	boolean	Ajoute un fond musical discret sous la narration. Valeur par défaut : `false`.
`sceneGraph`	object	Permet de sauter l’étape d’écriture et de générer la vidéo à partir de votre propre graphe de scènes (des scènes avec narration, titre et éléments).

Requête

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`

Une vidéo explicative avec toutes ses données : statut, videoUrl, posterUrl, subtitlesUrl, le sceneGraph modifiable, le minutage de chaque scène dans scenes, et toutes les entrées de versions.

Requête

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

200 OK (extrait)

{
  "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`

Vos vidéos explicatives, de la plus récente à la plus ancienne. limit va de 1 à 100 (50 par défaut). Les résumés n’incluent ni le graphe de scènes ni les versions.

Requête

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

200 OK (extrait)

{
  "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`

Applique un seul changement à une vidéo explicative terminée ; tout le reste demeure exactement tel quel. Le corps décrit ce changement, dont le type est donné par kind :

captions : captions (true ou false), et éventuellement captionStyle (pop, bold, clean, marker, typewriter ou story).
style : preset, fillMode, ou les deux.
hand : hand, l’id d’une main ou off.
music : music (true ou false).
logo ou credit : position, par exemple top-right (une mention de crédit peut aussi se placer en top-center ou en bottom-center), ou off. Dès l’offre Pro.
voice : voice, et éventuellement pace.
aspect : aspect, soit 16:9, 9:16 ou 1:1.

Renvoie 202. Les sous-titres, le style, la musique, le logo et la mention de crédit créent gratuitement une nouvelle version de cette vidéo, { "made": "version", "version": { ... } } : elle garde la narration et ne consomme aucune minute, et dès que son status passe à ready, le videoUrl de la vidéo explicative pointe vers elle. Une nouvelle voix ou un nouveau format crée une vidéo explicative distincte à partir du même script et des mêmes dessins, facturée comme une nouvelle vidéo : { "made": "video", "explainer": { ... } }.

Requête

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`

Changez vous-même les mots ou les dessins : récupérez la vidéo explicative, modifiez son sceneGraph et renvoyez-le sous la forme { "sceneGraph": { ... } }. Renvoie 202 avec la version en file d’attente. Seules les scènes modifiées sont redessinées, et la première régénération de chaque vidéo est gratuite. Attendez que le status de la version passe à ready ; le videoUrl de la vidéo explicative pointe alors vers cette version.

Requête

# 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`

Rétablit une version antérieure terminée comme version courante. Corps : { "versionId": "..." }. Renvoie la vidéo explicative.

Requête

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`

Copie une vidéo explicative, graphe de scènes compris, pour la faire évoluer dans une autre direction. Renvoie 201 avec la copie.

Requête

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`

Supprime une vidéo explicative. Renvoie 204 sans corps.

Requête

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 flux Server-Sent Events qui envoie un message event: status à chaque changement de statut de l’une de vos vidéos explicatives. Gardez une seule connexion ouverte plutôt que de faire du polling.

Requête

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

Flux d’événements

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` Aucune clé requise

Le catalogue des voix. Chaque narrateur parle toutes les langues : la liste est donc la même pour chacune d’elles. Chaque voix a un tone, un group et une preview_url. Plus de détails sur la page Voix.

Requête

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

200 OK (extrait)

{
  "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` Aucune clé requise

Toutes les langues de narration. Les langues beta ont été ajoutées plus récemment au modèle de synthèse vocale : la qualité de la narration peut donc varier.

Requête

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

200 OK (extrait)

{
  "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`

Le titulaire de la clé et le nombre de vidéos qu’il a créées.

Requête

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`

L’offre associée à la clé et où vous en êtes sur la période : minutes utilisées et restantes et fonctionnalités incluses. Les comptes gratuits reçoivent à la place videoAllowance, videosUsed et videosRemaining.

Requête

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` Aucune clé requise

La configuration publique destinée aux clients : où se trouvent le site, l’application et l’API.

Requête

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` Aucune clé requise

Contrôle de disponibilité pour les répartiteurs de charge et les outils de surveillance.

Requête

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 }

Erreurs

Toutes les erreurs ont la même forme, avec un code stable, exploitable par programme, et un message que vous pouvez afficher à vos utilisateurs :

402 Payment Required

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

Codes d’erreur courants
Statut	Code	Signification
400	bad_request, empty_input, bad_voice	La requête est mal formée ou n’indique pas quoi expliquer.
400	instruction_edits_retired	Une modification a été envoyée sous forme d’instruction en langage naturel. Envoyez un changement, ou un graphe de scènes modifié.
401	unauthenticated	Aucune clé, ou une clé incorrecte ou révoquée.
402	api_requires_plan, branding_requires_plan	L’accès à l’API et au serveur MCP commence avec l’offre Plus ; les changements de logo et de mention de crédit, avec l’offre Pro.
402	minutes_exhausted, minutes_short	Plus aucune minute disponible sur la période en cours, ou pas assez pour la durée demandée.
404	not_found	Aucune vidéo explicative avec cet identifiant sur votre compte.
409	still_rendering, no_changes	La vidéo est en cours de génération, ou le changement ou la modification n’a aucun effet.
409	no_logo, no_credit_line	Il n’y a pas encore de logo ou de mention de crédit à placer. Ajoutez ce qu’il manque dans l’application, sous Settings → Branding.
429	rate_limited	Trop de requêtes. Attendez le délai indiqué par l’en-tête Retry-After, puis réessayez.
500	internal	Erreur de notre côté. Les détails sont consignés dans nos journaux, jamais divulgués.

Limites de débit

Générations, changements et modifications (POST /v1/explainer, …/change, …/edit) : 20 requêtes par minute.
Tout le reste : 200 requêtes par minute.
Au-delà de la limite, vous recevez une erreur 429 rate_limited avec un en-tête Retry-After exprimé en secondes. Le SDK relance une fois les requêtes de lecture après ce délai, et l’expose dans les erreurs sous le nom retryAfter.