Даведнік 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 вяртаецца для пустога 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 з версіяй у чарзе. Апытвайце атрымаць тлумачэнне, пакуль галоўная версія не стане 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.