Довідник 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.