Dokumentacja API

Każdy endpoint z kształtem jego żądania i odpowiedzi. Wszystkie trasy są względne do https://sketchie.ai/api.

Konwencje

Każdy endpoint /v1/* wymaga nagłówka Authorization: Bearer sk_.... Błędy wracają jako JSON z flagą error i message:

Odpowiedź błędu

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

Endpointy generowania są ograniczone do 20 żądań na minutę. Wszystkie inne endpointy dzielą limit 200 na minutę.

Utwórz objaśnienie

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

Rozpoczyna generowanie i zwraca 202 Accepted z rekordem w kolejce. Odpytuj pobierz objaśnienie, aż będzie ready.

Ciało żądania

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

Pole	Typ	Uwagi
`input`	string	Co objaśnić. Krótki prompt lub pełny tekst dokumentu. Wymagane, chyba że obecne jest `source` lub `sceneGraph`. Alias: `prompt`.
`length`	string or number	Docelowa długość jako `"M:SS"` (`"0:30"`, `"1:00"`) lub sekundy. Dodatnia wielokrotność 30, do 360. Pomiń dla automatycznej długości. Alias: `lengthSeconds` (liczba).
`voice`	string	Opcjonalne. Referencja głosu. Domyślnie standardowy narrator (Nora). Zobacz Głosy.
`language`	string	Opcjonalne. Obsługiwany kod języka (domyślnie `en`). Zobacz Języki.
`aspect`	string	Opcjonalne. `16:9` (domyślnie), `9:16` lub `1:1`.
`source`	string	Opcjonalne. Dokument, artykuł lub transkrypcja do zamiany w objaśnienie. Gdy obecne, `input` staje się opcjonalną wskazówką.
`preset`	string	Opcjonalny styl rysowania: `marker` (domyślnie), `chalkboard`, `pencil`, `blueprint`, `crayon`, `clean`.
`fillMode`	string	Opcjonalna technika wypełnienia odsłaniania: `A`, `B`, `C` (domyślnie) lub `D`.
`sceneGraph`	object	Opcjonalne. Wcześniej przygotowany scene graph. Worker pomija generowanie grafu i renderuje go bezpośrednio, ale ten endpoint nadal tworzy nowe objaśnienie i zużywa normalny darmowy przydział lub limit planu płatnego wywołującego. Aby edytować istniejące objaśnienie, użyj edytuj objaśnienie.

Zwraca rekord objaśnienia: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null do gotowości) i sceneGraph (null do wygenerowania). 400 wraca dla pustego input bez source, źle sformatowanej length lub nieprawidłowego aspect, preset, fillMode lub language.

Pobierz objaśnienie

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

Zwraca pełny rekord: bieżący status, videoUrl po ready, edytowalny sceneGraph, historię wersji (versions) i sceniczne chunks wersji głównej. Brakujące id zwraca 404.

Listuj objaśnienia

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

Listuje objaśnienia klucza wywołującego, najnowsze pierwsze. Ograniczone do właściciela klucza. limit jest zaciskany od 1 do 100 (domyślnie 50). Zwraca lekkie podsumowania (bez scene graph ani wersji). Dla pełnego rekordu użyj pobierz objaśnienie.

Edytuj objaśnienie

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

Klin edytowalności. Zamień polecenie w prostym języku w ukierunkowane ponowne renderowanie. Tylko dotknięte sceny są renderowane ponownie, tworząc nową wersję. Zwraca 202 z wersją w kolejce. Odpytuj pobierz objaśnienie, aż wersja główna będzie ready. To dołącza do istniejącego wideo, więc nie zużywa kolejnego slotu tworzenia darmowego wideo. Pierwsze ponowne renderowanie każdego wideo jest darmowe. Kolejne używają minut planu płatnego, a darmowe konta są proszone o rozpoczęcie planu. Objaśnienie musi już być ready (w przeciwnym razie 409).

Ciało żądania

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

Przywróć do wersji

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

Ponownie kieruje głowę na wcześniejszą gotową wersję i odzwierciedla jej graf i wideo na rekordzie. Cel musi być wersją ready z wideo (w przeciwnym razie 409).

Ciało żądania

{ "versionId": "..." }

Strumień statusu na żywo

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

Strumień Server-Sent Events (text/event-stream). Otwórz jedno połączenie, a każde przejście statusu na dowolnym z twoich objaśnień przychodzi jako ramka event: status, więc możesz zaktualizować stan "wideo gotowe" w momencie, gdy worker skończy, zamiast odpytywać. Strumień jest ograniczony do właściciela twojego klucza.

Głosy

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

Katalog głosów narracji. Opcjonalny ?language=<code> filtruje do głosów natywnych dla tego języka. Zwraca voices (każdy z przyjaznym name, id do przekazania jako voice, language, isDefault i odtwarzalnym preview_url) plus globalny default. Zobacz Głosy.

Języki

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

Obsługiwane języki narracji, jako { code, label, native }. Każdy code to prawidłowy language przy tworzeniu. Zobacz Języki.

Stan konta

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

Zwraca videosGenerated (za całe życie), image konta i isAdmin. Wymaga uwierzytelnienia.

Status rozliczeń

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

Wymaga uwierzytelnienia i zwraca 200 zarówno dla kont darmowych, jak i płatnych. Konto darmowe zwraca plan: "free" z videoAllowance, videosUsed i videosRemaining. Konto płatne zwraca też planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining i bonusMinutes.

Konfiguracja wykonawcza i kondycja

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

Publiczne. Zwraca { "authEnforced": true }. Sprawdzenie żywotności znajduje się pod GET /health.