Referință API

Fiecare endpoint, cu forma cererii și răspunsului său. Toate rutele sunt relative la https://sketchie.ai/api.

Convenții

Fiecare endpoint /v1/* necesită antetul Authorization: Bearer sk_.... Erorile revin ca JSON cu un indicator error și un message:

Răspuns de eroare

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

Endpoint-urile de generare sunt limitate la 20 de cereri pe minut. Toate celelalte endpoint-uri împart o limită de 200 pe minut.

Creați un explicativ

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

Pornește o generare și returnează 202 Accepted cu înregistrarea în coadă. Interogați obținerea unui explicativ până este ready.

Corpul cererii

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

Câmp	Tip	Note
`input`	string	Ce să explice. Un prompt scurt sau textul complet al unui document. Obligatoriu dacă nu este prezent `source` sau `sceneGraph`. Alias: `prompt`.
`length`	string or number	Lungime țintă ca `"M:SS"` (`"0:30"`, `"1:00"`) sau secunde. Multiplu pozitiv al lui 30, până la 360. Omiteți pentru lungime automată. Alias: `lengthSeconds` (număr).
`voice`	string	Opțional. O referință de voce. Implicit naratorul standard (Nora). Vedeți Voci.
`language`	string	Opțional. Un cod de limbă acceptat (implicit `en`). Vedeți Limbi.
`aspect`	string	Opțional. `16:9` (implicit), `9:16`, sau `1:1`.
`source`	string	Opțional. Un document, articol sau transcriere de transformat într-un explicativ. Când e prezent, `input` devine îndrumare opțională.
`preset`	string	Stil de desen opțional: `marker` (implicit), `chalkboard`, `pencil`, `blueprint`, `crayon`, `clean`.
`fillMode`	string	Tehnică de umplere a dezvăluirii opțională: `A`, `B`, `C` (implicit), sau `D`.
`sceneGraph`	object	Opțional. Un scene graph pre-scris. Worker-ul sare peste generarea grafului și îl randează direct, dar acest endpoint tot creează un explicativ nou și consumă alocarea gratuită normală sau cota planului plătit a apelantului. Pentru a edita un explicativ existent, folosiți editarea unui explicativ.

Returnează înregistrarea explicativului: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null până e gata) și sceneGraph (null până e generat). Un 400 revine pentru un input gol fără source, un length malformat, sau un aspect, preset, fillMode ori language nevalid.

Obținerea unui explicativ

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

Returnează înregistrarea completă: status curent, videoUrl odată ready, sceneGraph editabil, istoricul versiunilor (versions) și chunks-urile de scenă ale versiunii principale. Un id lipsă returnează 404.

Listarea explicativelor

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

Listează explicativele cheii apelante, cele mai noi primele. Limitat la proprietarul cheii. limit este limitat între 1 și 100 (implicit 50). Returnează rezumate ușoare (fără scene graph sau versiuni). Folosiți obținerea unui explicativ pentru înregistrarea completă.

Editarea unui explicativ

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

Pana editabilității. Transformați o instrucțiune în limbaj simplu într-o re-randare țintită. Doar scenele afectate sunt re-randate, producând o versiune nouă. Returnează 202 cu versiunea în coadă. Interogați obținerea unui explicativ până când versiunea principală este ready. Aceasta se adaugă la videoclipul existent, deci nu consumă un alt slot de creare video gratuit. Prima re-randare a fiecărui videoclip este gratuită. Cele ulterioare folosesc minute din planul plătit, iar conturilor gratuite li se cere să înceapă un plan. Explicativul trebuie să fie deja ready (altfel 409).

Corpul cererii

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

Revenirea la o versiune

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

Reorientează capul către o versiune gata anterioară și oglindește graful și videoclipul ei pe înregistrare. Ținta trebuie să fie o versiune ready cu un videoclip (altfel 409).

Corpul cererii

{ "versionId": "..." }

Flux de stare live

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

Un flux Server-Sent Events (text/event-stream). Deschideți o conexiune și fiecare tranziție de stare pe oricare dintre explicativele voastre ajunge ca un cadru event: status, astfel încât puteți actualiza o stare "video gata" în momentul în care worker-ul termină, în loc de interogare. Fluxul este limitat la proprietarul cheii voastre.

Voci

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

Catalogul vocilor de narațiune. Opționalul ?language=<code> filtrează la vocile native acelei limbi. Returnează voices (fiecare cu un name prietenos, id-ul de trecut ca voice, language, isDefault și un preview_url redabil) plus default-ul global. Vedeți Voci.

Limbi

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

Limbile de narațiune acceptate, ca { code, label, native }. Fiecare code este un language valid la creare. Vedeți Limbi.

Starea contului

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

Returnează videosGenerated (pe viață), image-ul contului și isAdmin. Necesită autentificare.

Starea facturării

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

Necesită autentificare și returnează 200 atât pentru conturi gratuite, cât și plătite. Un cont gratuit returnează plan: "free" cu videoAllowance, videosUsed și videosRemaining. Un cont plătit returnează și planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining și bonusMinutes.

Configurare de execuție și sănătate

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

Public. Returnează { "authEnforced": true }. O verificare de vitalitate se află la GET /health.