Referenz

API-Referenz

Chasca-API v1: JSON über HTTPS mit API-Keys als Bearer-Token. Alles, was Zeit braucht (Generierung, Änderungen und Bearbeitungen), antwortet mit 202 und einem Eintrag in der Warteschlange, den du pollen oder streamen kannst.

Basis-URL https://app.trychasca.com/api

Authentifizierung

Alle /v1-Endpoints außer denen für Stimmen und Sprachen erfordern einen API-Schlüssel, den du als Authorization: Bearer chk_live_… sendest. Schlüssel erstellst du in der App unter Settings → API keys. API-Zugriff gibt es ab Plus, und Generierungen über die API verbrauchen die Minuten deines Tarifs doppelt.

Konventionen

Anfragen und Antworten verwenden JSON (Content-Type: application/json). Zeitstempel sind im Format ISO 8601 und in UTC angegeben.
Für eingereihte Aufträge antwortet die API mit 202, beim Erstellen einer Kopie mit 201 und beim Löschen mit 204.
Der Status eines Erklärvideos durchläuft queued → generating → rendering → ready oder endet mit failed und einem verständlichen error. stage und progress (0–1) zeigen den aktuellen Zwischenschritt.
Medien-URLs sind signiert und laufen nach etwa einer Woche ab. Ruf das Erklärvideo erneut ab, um neue Links zu erhalten.

Endpoints

POST `/v1/explainer`

Stellt ein neues Erklärvideo in die Warteschlange. Gibt 202 mit dem eingereihten Datensatz zurück.

Felder im Body der Anfrage zum Erstellen eines Erklärvideos
Feld	Typ	Beschreibung
`input`	string	Was erklärt werden soll: ein Thema, eine Frage oder der vollständige Text eines Dokuments (bis zu 200.000 Zeichen). Alias: `prompt`. Eines der Felder `input`, `source` oder `sceneGraph` ist erforderlich.
`length`	string \| number	`"M:SS"` (z. B. `"1:30"`) oder Sekunden, ein Vielfaches von 30 bis 1800 (30 Minuten). Über 360 wird das Video in Kapiteln erzählt. Ohne Angabe wird die Länge automatisch gewählt. Alias: `lengthSeconds`.
`aspect`	string	`16:9` (Standard), `9:16` oder `1:1`.
`voice`	string	Die ID einer Stimme, etwa `chasca:sulafat` (Standard) oder `chasca:kore`. Jede Stimme beherrscht alle Sprachen. Siehe Stimmen.
`language`	string	Sprachcode für den Sprechertext, z. B. `en`, `es-419`, `ja`. Siehe Sprachen.
`source`	string	Ausgangstext für die Erklärung (bis zu 400.000 Zeichen). Das Skript hält sich eng an diese Vorlage.
`preset`	string	Zeichenstil: `marker` (Standard), `chalkboard`, `pencil`, `blueprint`, `crayon` oder `clean`.
`fillMode`	string	Wie die Farbe nach jedem Umriss einfließt: `A` Einblenden, `B` Wischblende, `C` flächiges Einfärben (Standard), `D` Kritzeln.
`hand`	string	Eine Hand, die die Tafel zeichnet, mit dem Stift auf jeder Linie, während sie entsteht: `marker-light`, `marker-medium`, `marker-dark`, `pencil` oder `sketch`, `off` oder `auto` (Standard: eine Hand nur, wenn die Anfrage sie sehen will).
`pace`	string	`relaxed`, `balanced` (Standard) oder `brisk`.
`music`	boolean	Legt einen leisen Musikteppich unter die Sprecherstimme. Standard: `false`.
`sceneGraph`	object	Überspringt das Schreiben des Skripts und rendert deinen eigenen Szenengraphen (Szenen mit Sprechertext, Überschrift und Elementen).

Anfrage

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`

Ein einzelnes Erklärvideo mit allen Details: Status, videoUrl, posterUrl, subtitlesUrl, der bearbeitbare sceneGraph, die Zeitangaben pro Szene in scenes und alle Einträge in versions.

Anfrage

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

200 OK (gekürzt)

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

Deine Erklärvideos, neueste zuerst. limit liegt zwischen 1 und 100, Standard ist 50. Die Kurzfassungen enthalten weder Szenengraph noch Versionen.

Anfrage

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

200 OK (gekürzt)

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

Nimmt genau eine Änderung an einem fertigen Erklärvideo vor; alles andere bleibt genau so, wie es war. Der Body beschreibt diese eine Änderung, deren Art kind festlegt:

captions: captions (true oder false) und optional captionStyle (pop, bold, clean, marker, typewriter oder story).
style: preset, fillMode oder beides.
hand: hand, die ID einer Hand oder off.
music: music (true oder false).
logo oder credit: position, etwa top-right (eine Credit-Zeile kann auch auf top-center oder bottom-center stehen), oder off. Ab Pro.
voice: voice und optional pace.
aspect: aspect, also 16:9, 9:16 oder 1:1.

Gibt 202 zurück. Untertitel, Stil, Musik, Logo und Credit-Zeile ergeben kostenlos eine neue Version dieses Videos, { "made": "version", "version": { ... } }: Sie behält die Vertonung und kostet keine Minuten, und sobald ihr status den Wert ready hat, zeigt die videoUrl des Erklärvideos auf sie. Eine neue Stimme oder ein neues Format ergibt ein eigenes Erklärvideo aus demselben Skript und denselben Zeichnungen, das wie ein neues Video berechnet wird: { "made": "video", "explainer": { ... } }.

Anfrage

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`

Ändere die Worte oder die Zeichnungen selbst: Ruf das Erklärvideo ab, bearbeite seinen sceneGraph und schick ihn als { "sceneGraph": { ... } } zurück. Gibt 202 mit der eingereihten Version zurück. Nur die geänderten Szenen werden neu gezeichnet, und das erste erneute Rendern ist bei jedem Video kostenlos. Warte, bis der status der Version den Wert ready hat; danach zeigt die videoUrl des Erklärvideos auf diese Version.

Anfrage

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

Macht eine frühere, fertige Version wieder zur aktuellen. Body: { "versionId": "..." }. Gibt das Erklärvideo zurück.

Anfrage

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`

Kopiert ein Erklärvideo samt Szenengraph, damit du es in eine neue Richtung weiterentwickeln kannst. Gibt 201 mit der Kopie zurück.

Anfrage

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`

Löscht ein Erklärvideo. Gibt 204 ohne Body zurück.

Anfrage

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`

Ein Stream mit Server-Sent Events, der bei jeder Statusänderung eines deiner Erklärvideos einen event: status-Frame sendet. Halte eine einzige Verbindung offen, statt zu pollen.

Anfrage

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

Event-Stream

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` Kein API-Key nötig

Der Stimmenkatalog. Jede Stimme beherrscht alle Sprachen, daher ist die Liste für jede Sprache gleich. Jeder Eintrag hat einen tone, eine group und eine preview_url. Mehr dazu auf der Seite Stimmen.

Anfrage

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

200 OK (gekürzt)

{
  "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` Kein API-Key nötig

Alle Sprachen für den Sprechertext. Als beta markierte Sprachen sind neu im Stimmmodell, daher kann die Qualität der Vertonung schwanken.

Anfrage

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

200 OK (gekürzt)

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

Wem der Schlüssel gehört und wie viele Videos diese Person bereits erstellt hat.

Anfrage

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`

Der Tarif hinter dem Schlüssel und der Stand im aktuellen Abrechnungszeitraum: verbrauchte und verbleibende Minuten und Berechtigungen. Kostenlose Konten erhalten stattdessen videoAllowance, videosUsed und videosRemaining.

Anfrage

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` Kein API-Key nötig

Öffentliche Konfiguration für Clients: unter welchen Adressen Website, App und API erreichbar sind.

Anfrage

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` Kein API-Key nötig

Liveness-Check für Load Balancer und Uptime-Monitoring.

Anfrage

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 }

Fehler

Jeder Fehler hat dieselbe Form, mit einem stabilen, maschinenlesbaren code und einer verständlichen Meldung, die du direkt anzeigen kannst:

402 Payment Required

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

Häufige Fehlercodes
Status	Code	Bedeutung
400	bad_request, empty_input, bad_voice	Die Anfrage ist fehlerhaft, oder es fehlt, was erklärt werden soll.
400	instruction_edits_retired	Eine Bearbeitung wurde als Anweisung in natürlicher Sprache gesendet. Sende eine Änderung oder einen bearbeiteten Szenengraphen.
401	unauthenticated	Kein Schlüssel, oder der Schlüssel ist falsch oder widerrufen.
402	api_requires_plan, branding_requires_plan	API- und MCP-Zugriff gibt es ab Plus, Änderungen an Logo und Credit-Zeile ab Pro.
402	minutes_exhausted, minutes_short	Im aktuellen Abrechnungszeitraum sind keine Minuten mehr übrig, oder sie reichen nicht für die gewünschte Länge.
404	not_found	In deinem Konto gibt es kein Erklärvideo mit dieser ID.
409	still_rendering, no_changes	Das Video wird gerade gerendert, oder die Änderung oder Bearbeitung ändert nichts.
409	no_logo, no_credit_line	Es gibt noch kein Logo bzw. keine Credit-Zeile, die platziert werden könnte. Füge sie in der App unter Settings → Branding hinzu.
429	rate_limited	Zu viele Anfragen. Warte die im Header Retry-After angegebene Zeit ab und versuche es dann erneut.
500	internal	Unser Fehler. Details werden bei uns protokolliert und nie weitergegeben.

Rate Limits

Generierung, Änderungen und Bearbeitungen (POST /v1/explainer, …/change, …/edit): 20 Anfragen pro Minute.
Alles andere: 200 Anfragen pro Minute.
Über dem Limit erhältst du 429 rate_limited mit einem Retry-After-Header in Sekunden. Das SDK wiederholt lesende Anfragen nach dieser Wartezeit einmal und gibt sie bei Fehlern als retryAfter an.