Создать субтитры →Создать

Автоматизация

Публичный API

Запуск обработки видео из своего кода: ключ доступа, кредиты, статус задачи и скачивание файла в выбранном стиле.

Время чтения: 7 минут

Что делает API

Публичный API повторяет путь редактора без интерфейса: вы отдаёте видео, сервис распознаёт речь, размечает слова, разбирает кадр, пишет плашки и собирает оформленные субтитры, а вы забираете готовый файл.

  • Базовый адрес — https://api.captions.space/v1
  • Формат запросов и ответов — JSON.
  • Полный пайплайн запускается один раз на видео.

Ключ доступа

  1. Откройте в кабинете раздел «Разработчикам».
  2. Создайте ключ и сразу скопируйте его.
  3. Передавайте ключ заголовком Authorization: Bearer cs_live_…

Кредиты

Обработка оплачивается кредитами: один кредит — одна начатая минута видео. Баланс общий с кабинетом: минуты, потраченные в редакторе, списываются с того же счёта. На бесплатном тарифе API недоступен, тариф Pro даёт 1000 кредитов на каждый 30-дневный период подписки — запас обновляется в день продления, а не первого числа.

  • При запуске резервируется потолок длительности тарифа, но не больше остатка баланса; после обработки списание уточняется по фактической длине ролика. Ролик длиннее, чем покрывает остаток, получает отказ credits_exhausted.
  • Упавший прогон не стоит ничего — резерв возвращается.
  • Экспорт файлов кредитов не тратит: платите за обработку, а не за каждую выгрузку.
  • Остаток видно в кабинете, в разделе «Разработчикам» и по запросу GET /v1/me.

Запуск обработки

  1. POST /v1/videos со ссылкой {"url": "…"} на видеофайл или YouTube — прогон стартует сразу.
  2. POST /v1/videos без ссылки — в ответе придёт upload_url: залейте файл методом PUT (ссылка действует час).
  3. Если PUT в хранилище из вашей сети недоступен, залейте файл через сам API: POST /v1/videos/{id}/file, multipart-полем file.
  4. POST /v1/videos/{id}/start — запуск для залитого файла.

Видео и справочники

  • GET /v1/videos — видео аккаунта, свежие сверху; параметр limit — до 200 (по умолчанию 50).
  • DELETE /v1/videos/{id} — удалить видео и его файлы. Списанные кредиты не возвращаются.
  • GET /v1/styles — шаблоны оформления: id для поля style и название.
  • GET /v1/formats — форматы выгрузки, их расширения и тип (video или subtitles).
  • GET /v1/me — тариф, запас и остаток кредитов.

API и редактор

Видео, созданные через API, лежат в вашем кабинете: любое можно открыть в редакторе, поправить слово или тайминг, добавить шаблоны надписей и свой водяной знак. Следующий видеофайл, заказанный через API, придёт уже с этим оформлением — сервер собирает кадр из тех же правок, что и редактор.

Статус задачи

Писем публичный API не отправляет — об окончании работы интеграция узнаёт опросом GET /v1/videos/{id}. В ответе приходит status (awaiting_upload, processing, ready, failed), progress в процентах, код ошибки и фактическое списание кредитов.

  • Опрашивайте статус не чаще одного раза в несколько секунд.
  • Обработка на CPU идёт минутами — это нормальная длительность, а не зависание.

Скачивание результата

  1. POST /v1/videos/{id}/exports с полем format: srt, vtt, ass, mp4, mov, hevc или webm.
  2. При необходимости передайте style — субтитры пересоберутся в выбранном шаблоне.
  3. GET /v1/videos/{id}/exports вернёт ссылку на готовый файл.

Коды ответов

  • 401 — ключ не передан, неизвестен или отозван.
  • 402 — кредиты периода закончились.
  • 403 — на текущем тарифе API недоступен.
  • 404 — видео не найдено или принадлежит другому аккаунту.
  • 409 — видео ещё не залито, уже запущено или ещё не готово к экспорту.
  • 422 — неизвестный формат, стиль или некорректная ссылка.