Справочник 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.