מדריך API

כל endpoint, עם צורת הבקשה והתגובה שלו. כל הנתיבים יחסיים ל-https://sketchie.ai/api.

מוסכמות

כל endpoint /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 עם הרשומה בתור. בצעו poll ל-קבלת הסבר עד שהוא 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 שנכתב מראש. ה-worker מדלג על יצירת הגרף ומרנדר אותו ישירות, אך endpoint זה עדיין יוצר הסבר חדש וצורך את המכסה החינמית הרגילה או מכסת התוכנית בתשלום של המתקשר. לעריכת הסבר קיים, השתמשו ב-עריכת הסבר.

מחזיר את רשומת ההסבר: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null עד שמוכן) ו-sceneGraph (null עד שנוצר). 400 חוזר עבור input ריק ללא 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 עם הגרסה בתור. בצעו poll ל-קבלת הסבר עד שגרסת הראש היא 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, כך שתוכלו לעדכן מצב "וידאו מוכן" ברגע שה-worker מסיים במקום לבצע poll. הזרם מוגבל לבעל המפתח שלכם.

קולות

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.