مرجع API

كل نقطة نهاية، بشكل طلبها واستجابتها. كل المسارات نسبية إلى https://sketchie.ai/api.

الأعراف

كل نقطة نهاية /v1/* تتطلب ترويسة Authorization: Bearer sk_.... تعود الأخطاء كـ JSON مع علامة error وmessage:

استجابة الخطأ

{
  "error": true,
  "message": "length must be a positive multiple of 30 seconds, at most 360"
}

نقاط نهاية الإنشاء محدودة بمعدل 20 طلبًا في الدقيقة. تتشارك كل نقاط النهاية الأخرى حدًا قدره 200 في الدقيقة.

إنشاء شرح

POST https://sketchie.ai/api/v1/explainer

يبدأ إنشاءً ويعيد 202 Accepted مع السجل في قائمة الانتظار. استعلم عن جلب شرح حتى يصبح ready.

جسم الطلب

{
  "input": "Explain how DNS resolves a domain name",
  "length": "0:30",
  "aspect": "16:9",
  "voice": "sketchie:sulafat",
  "language": "en"
}

الحقل	النوع	ملاحظات
`input`	string	ما يجب شرحه. مطالبة قصيرة أو نص مستند كامل. مطلوب ما لم يكن `source` أو `sceneGraph` موجودًا. اسم بديل: `prompt`.
`length`	string or number	المدة المستهدفة كـ `"M:SS"` (`"0:30"`، `"1:00"`) أو ثوانٍ. مضاعف موجب للعدد 30، حتى 360. احذف للمدة التلقائية. اسم بديل: `lengthSeconds` (رقم).
`voice`	string	اختياري. مرجع صوت. الافتراضي هو الراوي القياسي (Nora). انظر الأصوات.
`language`	string	اختياري. رمز لغة مدعوم (الافتراضي `en`). انظر اللغات.
`aspect`	string	اختياري. `16:9` (افتراضي)، `9:16`، أو `1:1`.
`source`	string	اختياري. مستند أو مقال أو نص مفرَّغ لتحويله إلى شرح. عند وجوده، يصبح `input` توجيهًا اختياريًا.
`preset`	string	أسلوب رسم اختياري: `marker` (افتراضي)، `chalkboard`، `pencil`، `blueprint`، `crayon`، `clean`.
`fillMode`	string	تقنية ملء الكشف اختيارية: `A`، `B`، `C` (افتراضي)، أو `D`.
`sceneGraph`	object	اختياري. scene graph مُعدّ مسبقًا. يتخطى العامل توليد الرسم البياني ويصيّره مباشرة، لكن هذه النقطة النهائية لا تزال تنشئ شرحًا جديدًا وتستهلك المخصّص المجاني العادي أو حصة الخطة المدفوعة للمتصل. لتحرير شرح موجود، استخدم تحرير شرح.

يعيد سجل الشرح: id، status، prompt، lengthSeconds، voice، language، aspect، videoUrl (null حتى الجاهزية)، وsceneGraph (null حتى التوليد). يعود 400 لإدخال فارغ بلا source، أو length مشوّهة، أو aspect أو preset أو fillMode أو language غير صالح.

جلب شرح

GET https://sketchie.ai/api/v1/explainer/:id

يعيد السجل الكامل: status الحالي، وvideoUrl حالما يصبح ready، وsceneGraph القابل للتحرير، وتاريخ الإصدارات (versions)، وchunks مشاهد الإصدار الرئيسي. id مفقود يعيد 404.

سرد الشروح

GET https://sketchie.ai/api/v1/explainer?limit=50

يسرد شروح المفتاح المتصل، الأحدث أولًا. مقيّد بمالك المفتاح. يُقيَّد limit من 1 إلى 100 (افتراضي 50). يعيد ملخصات خفيفة (بلا scene graph أو إصدارات). استخدم جلب شرح للسجل الكامل.

تحرير شرح

POST https://sketchie.ai/api/v1/explainer/:id/edit

إسفين القابلية للتحرير. حوّل تعليمة بلغة بسيطة إلى إعادة تصيير مستهدفة. تُعاد تصيير المشاهد المتأثرة فقط، مما يُنتج إصدارًا جديدًا. يعيد 202 مع الإصدار في قائمة الانتظار. استعلم عن جلب شرح حتى يصبح الإصدار الرئيسي ready. هذا يُلحق بالفيديو الموجود، فلا يستهلك خانة إنشاء فيديو مجانية أخرى. أول إعادة تصيير لكل فيديو مجانية. تستخدم عمليات إعادة التصيير اللاحقة دقائق الخطة المدفوعة، ويُطلب من الحسابات المجانية بدء خطة. يجب أن يكون الشرح ready بالفعل (وإلا 409).

جسم الطلب

{ "instruction": "Make the title scene shorter and warmer" }

التراجع إلى إصدار

POST https://sketchie.ai/api/v1/explainer/:id/revert

يعيد توجيه الرأس إلى إصدار جاهز أسبق ويعكس رسمه البياني وفيديوه على السجل. يجب أن يكون الهدف إصدار ready بفيديو (وإلا 409).

جسم الطلب

{ "versionId": "..." }

بث حالة حي

GET https://sketchie.ai/api/v1/explainer/events

بث Server-Sent Events (text/event-stream). افتح اتصالًا واحدًا وكل انتقال حالة على أي من شروحك يصل كإطار event: status، فتستطيع تحديث حالة "الفيديو جاهز" لحظة انتهاء العامل بدل الاستعلام. البث مقيّد بمالك مفتاحك.

الأصوات

GET https://sketchie.ai/api/v1/voices

كتالوج أصوات السرد. يقوم ?language=<code> الاختياري بالتصفية إلى الأصوات الأصلية لتلك اللغة. يعيد voices (لكل منها name ودّي، وid لتمريره كـ voice، وlanguage، وisDefault، وpreview_url قابل للتشغيل) بالإضافة إلى default العام. انظر الأصوات.

اللغات

GET https://sketchie.ai/api/v1/languages

لغات السرد المدعومة، كـ { code, label, native }. كل code هو language صالح عند الإنشاء. انظر اللغات.

حالة الحساب

GET https://sketchie.ai/api/v1/account/state

يعيد videosGenerated (مدى الحياة)، وimage الحساب، وisAdmin. يتطلب مصادقة.

حالة الفوترة

GET https://sketchie.ai/api/v1/billing/status

يتطلب مصادقة ويعيد 200 للحسابات المجانية والمدفوعة على حد سواء. يعيد الحساب المجاني plan: "free" مع videoAllowance وvideosUsed وvideosRemaining. يعيد الحساب المدفوع أيضًا planLabel وbillingInterval وtrialStatus وquotaMinutes وminutesUsedThisPeriod وminutesRemaining وbonusMinutes.

إعداد وقت التشغيل والصحة

GET https://sketchie.ai/api/config

عام. يعيد { "authEnforced": true }. يوجد فحص حيوية عند GET /health.