रेफ़रेंस

API रेफ़रेंस

Chasca API v1: HTTPS पर JSON, और ऑथेंटिकेशन के लिए Bearer API key। जिन कामों में समय लगता है (जनरेशन, बदलाव और एडिट), वे 202 लौटाते हैं, साथ में कतार में लगा एक रिकॉर्ड, जिसे आप पोल या स्ट्रीम कर सकते हैं।

बेस URL https://app.trychasca.com/api

ऑथेंटिकेशन

आवाज़ों और भाषाओं वाले एंडपॉइंट को छोड़कर, हर /v1 एंडपॉइंट के लिए API key चाहिए, जिसे Authorization: Bearer chk_live_… के रूप में भेजा जाता है। ऐप के Settings → API keys में जाकर key बनाएं। API एक्सेस Plus प्लान से शुरू होता है, और API से बनने वाले वीडियो में प्लान के मिनट 2x खर्च होते हैं।

सामान्य नियम

बॉडी JSON में होती है (Content-Type: application/json)। टाइमस्टैम्प ISO 8601 फ़ॉर्मेट में, UTC में होते हैं।
कतार में जाने वाले काम पर 202 मिलता है; कॉपी बनाने पर 201; डिलीट करने पर 204।
एक्सप्लेनर का स्टेटस queued → generating → rendering → ready क्रम में बदलता है, या failed पर रुक जाता है, और तब error में साफ़ शब्दों में वजह लिखी होती है। बीच का स्टेप stage और progress (0–1) से पता चलता है।
मीडिया URL signed होते हैं और करीब एक हफ़्ते बाद एक्सपायर हो जाते हैं। नए लिंक के लिए एक्सप्लेनर को दोबारा fetch करें।

एंडपॉइंट

POST `/v1/explainer`

नया एक्सप्लेनर कतार में डालें। जवाब में 202 और कतार में डाला गया रिकॉर्ड मिलता है।

एक्सप्लेनर बनाने वाली रिक्वेस्ट की बॉडी के फ़ील्ड
फ़ील्ड	टाइप	विवरण
`input`	string	क्या समझाना है: कोई टॉपिक, कोई सवाल या किसी डॉक्यूमेंट का पूरा टेक्स्ट (200,000 कैरेक्टर तक)। दूसरा नाम: `prompt`। `input`, `source` या `sceneGraph` में से कोई एक ज़रूरी है।
`length`	string \| number	`"M:SS"` (जैसे `"1:30"`) या सेकंड में, 30-30 के स्टेप में, 1800 (30 मिनट) तक। 360 से ज़्यादा होने पर वीडियो चैप्टर में बंट जाता है। लंबाई ऑटो रखने के लिए इसे न भेजें। दूसरा नाम: `lengthSeconds`।
`aspect`	string	`16:9` (डिफ़ॉल्ट), `9:16` या `1:1`।
`voice`	string	नैरेटर का ID, जैसे `chasca:sulafat` (डिफ़ॉल्ट) या `chasca:kore`। हर नैरेटर हर भाषा बोलता है। आवाज़ें पेज देखें।
`language`	string	नैरेशन की भाषा का कोड, जैसे `en`, `es-419`, `ja`। भाषाएं पेज देखें।
`source`	string	वह सोर्स टेक्स्ट, जिससे समझाना है (400,000 कैरेक्टर तक)। स्क्रिप्ट इसी टेक्स्ट पर आधारित रहती है, इससे बाहर नहीं जाती।
`preset`	string	ड्रॉइंग स्टाइल: `marker` (डिफ़ॉल्ट), `chalkboard`, `pencil`, `blueprint`, `crayon` या `clean`।
`fillMode`	string	हर आउटलाइन बनने के बाद उसमें रंग कैसे भरता है: `A` फ़ेड, `B` वाइप, `C` हर हिस्से में फैलता रंग (डिफ़ॉल्ट), `D` आड़ी-तिरछी लकीरें।
`hand`	string	बोर्ड पर ड्रॉ करता हाथ, जिसका पेन हर लकीर पर चलता है: `marker-light`, `marker-medium`, `marker-dark`, `pencil` या `sketch`, `off`, या `auto` (डिफ़ॉल्ट: हाथ तभी, जब अनुरोध उसे दिखाने को कहे)।
`pace`	string	`relaxed`, `balanced` (डिफ़ॉल्ट) या `brisk`।
`music`	boolean	नैरेशन के पीछे हल्का बैकग्राउंड म्यूज़िक जोड़ें। डिफ़ॉल्ट `false`।
`sceneGraph`	object	स्क्रिप्ट लिखने का स्टेप छोड़ें और अपना सीन ग्राफ़ रेंडर करें (सीन, जिनमें नैरेशन, हेडिंग और एलिमेंट हों)।

रिक्वेस्ट

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`

एक एक्सप्लेनर, पूरी जानकारी के साथ: स्टेटस, videoUrl, posterUrl, subtitlesUrl, एडिट किया जा सकने वाला sceneGraph, scenes में हर सीन की टाइमिंग, और versions में हर वर्ज़न।

रिक्वेस्ट

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

200 OK (संक्षिप्त)

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

आपके एक्सप्लेनर, सबसे नए पहले। limit 1–100 के बीच होता है, डिफ़ॉल्ट 50। लिस्ट में सिर्फ़ समरी होती है, सीन ग्राफ़ और वर्ज़न नहीं।

रिक्वेस्ट

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

200 OK (संक्षिप्त)

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

तैयार एक्सप्लेनर में एक बदलाव; बाकी सब बिल्कुल वैसा ही रहता है। बॉडी में एक ही बदलाव होता है, जिसे kind से चुना जाता है:

captions: captions (true या false), और चाहें तो captionStyle (pop, bold, clean, marker, typewriter या story)।
style: preset, fillMode, या दोनों।
hand: hand, किसी हाथ की id या off।
music: music (true या false)।
logo या credit: position, जैसे top-right (क्रेडिट लाइन top-center या bottom-center पर भी रह सकती है), या off। Pro और उससे ऊपर के प्लान में।
voice: voice, और चाहें तो pace।
aspect: aspect, यानी 16:9, 9:16 या 1:1।

जवाब में 202 मिलता है। सबटाइटल, स्टाइल, म्यूज़िक, लोगो और क्रेडिट लाइन से इसी वीडियो का एक फ़्री नया वर्ज़न बनता है, { "made": "version", "version": { ... } }: इसमें नैरेशन वही रहता है और कोई मिनट खर्च नहीं होता, और इसका status ready होते ही एक्सप्लेनर का videoUrl इसी वर्ज़न का लिंक हो जाता है। नई आवाज़ या नया फ़ॉर्मेट उसी स्क्रिप्ट और ड्रॉइंग से एक अलग एक्सप्लेनर बनाता है, जिसका खर्च नए वीडियो जितना ही होता है: { "made": "video", "explainer": { ... } }।

रिक्वेस्ट

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`

शब्द या ड्रॉइंग खुद बदलें: एक्सप्लेनर fetch करें, उसका sceneGraph एडिट करें, और उसे { "sceneGraph": { ... } } के रूप में वापस भेजें। जवाब में 202 और कतार में डाला गया वर्ज़न मिलता है। सिर्फ़ बदले हुए सीन फिर से बनते हैं, और हर वीडियो को पहली बार फिर से रेंडर करना फ़्री है। वर्ज़न के status के ready होने का इंतज़ार करें; उसके बाद एक्सप्लेनर का videoUrl इसी वर्ज़न का लिंक होता है।

रिक्वेस्ट

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

किसी पुराने, तैयार वर्ज़न को फिर से मौजूदा वर्ज़न बनाएं। बॉडी: { "versionId": "..." }। जवाब में एक्सप्लेनर मिलता है।

रिक्वेस्ट

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`

एक्सप्लेनर की कॉपी बनाएं, सीन ग्राफ़ समेत सब कुछ, ताकि आप उसे किसी नई दिशा में ले जा सकें। जवाब में 201 और कॉपी मिलती है।

रिक्वेस्ट

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`

एक्सप्लेनर डिलीट करें। जवाब में 204 मिलता है, बिना बॉडी के।

रिक्वेस्ट

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`

एक Server-Sent Events स्ट्रीम: आपके किसी भी एक्सप्लेनर का स्टेटस बदलने पर हर बार एक event: status फ़्रेम आता है। बार-बार poll करने के बजाय एक ही कनेक्शन खुला रखें।

रिक्वेस्ट

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

स्ट्रीम

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` API key की ज़रूरत नहीं

आवाज़ों का कैटलॉग। हर नैरेटर हर भाषा बोलता है, इसलिए यह लिस्ट सभी भाषाओं के लिए एक ही है। हर आवाज़ के साथ उसका tone, group और preview_url होता है। ज़्यादा जानकारी आवाज़ें पेज पर है।

रिक्वेस्ट

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

200 OK (संक्षिप्त)

{
  "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` API key की ज़रूरत नहीं

नैरेशन की सभी भाषाएं। beta भाषाएं वॉइस मॉडल के लिए नई हैं, इसलिए उनमें नैरेशन की क्वालिटी कम-ज़्यादा हो सकती है।

रिक्वेस्ट

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

200 OK (संक्षिप्त)

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

यह key किस अकाउंट की है, और उस अकाउंट से अब तक कितने वीडियो बने हैं।

रिक्वेस्ट

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`

इस key से जुड़ा प्लान और मौजूदा अवधि का हिसाब: कितने मिनट इस्तेमाल हुए और कितने बचे, और प्लान में शामिल सुविधाएं। फ़्री अकाउंट के लिए इनकी जगह videoAllowance, videosUsed और videosRemaining मिलते हैं।

रिक्वेस्ट

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` API key की ज़रूरत नहीं

क्लाइंट के लिए पब्लिक कॉन्फ़िगरेशन: साइट, ऐप और API कहां हैं।

रिक्वेस्ट

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` API key की ज़रूरत नहीं

लोड बैलेंसर और अपटाइम मॉनिटर के लिए लाइवनेस चेक: सर्विस चल रही है या नहीं।

रिक्वेस्ट

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 }

एरर

हर एरर का ढांचा एक जैसा होता है। उसमें मशीन के पढ़ने के लिए एक तय code होता है, जो बदलता नहीं, और एक मैसेज, जिसे आप सीधे लोगों को दिखा सकते हैं:

402 Payment Required

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

आम एरर कोड
स्टेटस	कोड	मतलब
400	bad_request, empty_input, bad_voice	रिक्वेस्ट सही फ़ॉर्मेट में नहीं है, या उसमें यह नहीं बताया गया कि क्या समझाना है।
400	instruction_edits_retired	एडिट में आसान शब्दों वाला निर्देश भेजा गया। एक बदलाव भेजें, या एडिट किया हुआ सीन ग्राफ़।
401	unauthenticated	कोई key नहीं भेजी गई, या key गलत है या रद्द की जा चुकी है।
402	api_requires_plan, branding_requires_plan	API और MCP एक्सेस Plus प्लान से शुरू होता है; लोगो और क्रेडिट लाइन के बदलाव Pro से।
402	minutes_exhausted, minutes_short	इस अवधि के मिनट खत्म हो गए हैं, या मांगी गई लंबाई के लिए काफ़ी नहीं हैं।
404	not_found	आपके अकाउंट में इस ID का कोई एक्सप्लेनर नहीं है।
409	still_rendering, no_changes	वीडियो अभी रेंडर हो रहा है, या बदलाव या एडिट से कुछ भी नहीं बदलता।
409	no_logo, no_credit_line	लगाने के लिए अभी कोई लोगो या क्रेडिट लाइन नहीं है। ऐप में Settings → Branding में जाकर जोड़ें।
429	rate_limited	कम समय में बहुत ज़्यादा रिक्वेस्ट आ गईं। Retry-After हेडर में बताए गए समय तक रुकें, फिर दोबारा कोशिश करें।
500	internal	गलती हमारी है। पूरा ब्योरा हमारी तरफ़ लॉग होता है, बाहर कभी नहीं जाता।

रेट लिमिट

जनरेशन, बदलाव और एडिट (POST /v1/explainer, …/change, …/edit): हर मिनट 20 रिक्वेस्ट।
बाकी सब: हर मिनट 200 रिक्वेस्ट।
लिमिट पार होने पर आपको 429 rate_limited मिलता है, साथ में Retry-After हेडर, जो सेकंड में बताता है कि कितनी देर रुकना है। SDK डेटा पढ़ने वाली रिक्वेस्ट को उतनी देर बाद एक बार दोबारा भेजता है, और एरर में यह समय retryAfter के रूप में देता है।