المرجع

مرجع API

واجهة API v1 من Chasca: بيانات JSON عبر HTTPS مع مفاتيح API من نوع Bearer. والعمليات التي تستغرق وقتًا (الإنشاء والتغييرات والتعديلات) تُرجع الرمز 202 مع سجل في قائمة الانتظار، يمكنك الاستعلام عنه دوريًا أو متابعته بالبث المباشر.

عنوان URL الأساسي https://app.trychasca.com/api

المصادقة

تتطلب كل نقاط النهاية تحت /v1، ما عدا الأصوات واللغات، مفتاح API يُرسَل بالشكل Authorization: Bearer chk_live_…. أنشئ المفاتيح في التطبيق من Settings → API keys. يبدأ الوصول إلى API من خطة Plus، وتُحتسب الفيديوهات المُنشأة عبر API من دقائق الخطة مضروبةً في 2.

الاصطلاحات

أجسام الطلبات والاستجابات بصيغة JSON (Content-Type: application/json). والطوابع الزمنية بصيغة ISO 8601 وبتوقيت UTC.
الطلبات التي تضع عملًا في قائمة الانتظار تُرجع 202، وإنشاء نسخة يُرجع 201، والحذف يُرجع 204.
تنتقل حالة فيديو الشرح عبر queued → generating → rendering → ready، أو تنتهي بـfailed مع رسالة error مفهومة. ويصف الحقلان stage وprogress (من 0 إلى 1) المرحلة الجارية بين حالة وأخرى.
روابط الوسائط موقَّعة وتنتهي صلاحيتها بعد أسبوع تقريبًا. اجلب فيديو الشرح مجددًا للحصول على روابط جديدة.

نقاط النهاية

POST `/v1/explainer`

ضع فيديو شرح جديدًا في قائمة الانتظار. يُرجع 202 مع السجل الجديد في قائمة الانتظار.

حقول جسم طلب إنشاء فيديو الشرح
الحقل	النوع	الوصف
`input`	string	ما تريد شرحه: موضوع، أو سؤال، أو النص الكامل لمستند (حتى 200,000 حرف). اسم بديل: `prompt`. يلزم إرسال واحد من `input` أو `source` أو `sceneGraph`.
`length`	string \| number	`"M:SS"` (مثل `"1:30"`) أو عدد من الثواني من مضاعفات 30 حتى 1800 (30 دقيقة). وبعد 360 يُروى الفيديو في فصول. احذفه لتُحدَّد المدة تلقائيًا. اسم بديل: `lengthSeconds`.
`aspect`	string	`16:9` (افتراضي)، أو `9:16`، أو `1:1`.
`voice`	string	معرّف راوٍ مثل `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، معرّف يد أو 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`

غيّر الكلمات أو الرسوم بنفسك: اجلب فيديو الشرح، وعدّل 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 مع كل تغيّر في حالة أيٍّ من فيديوهات الشرح الخاصة بك. أبقِ اتصالًا واحدًا مفتوحًا بدلًا من الاستعلام الدوري.

الطلب

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` لا يتطلب مفتاحًا

قائمة الأصوات. كل راوٍ يتحدث كل اللغات، لذا فالقائمة نفسها لكل اللغات. لكل صوت نبرة 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` لا يتطلب مفتاحًا

كل لغات التعليق الصوتي. اللغات المعلَّمة بـ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`

صاحب المفتاح، وعدد الفيديوهات التي أنشأها.

الطلب

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`

الخطة المرتبطة بالمفتاح وموقعك من الدورة الحالية: الدقائق المستخدمة والمتبقية، والمزايا المشمولة. أما الحسابات المجانية فتحصل بدلًا من ذلك على 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.

الطلب

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` لا يتطلب مفتاحًا

فحص يؤكد أن الخدمة تعمل، لموازنات الأحمال وأدوات مراقبة التوفر.

الطلب

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	لم يُرسَل مفتاح، أو المفتاح خاطئ أو أُلغي.
402	api_requires_plan, branding_requires_plan	يبدأ الوصول إلى API وMCP من خطة Plus، وتغيير الشعار وسطر التعريف من خطة Pro.
402	minutes_exhausted, minutes_short	نفدت دقائق هذه الدورة، أو لا تكفي للمدة التي طلبتها.
404	not_found	لا يوجد فيديو شرح بهذا المعرّف في حسابك.
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.