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

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

Публичный API

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

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

Что делает API

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

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

Ключ доступа

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

Кредиты

Обработка оплачивается кредитами: один кредит — одна начатая минута видео. На бесплатном тарифе API недоступен, тариф Pro даёт 60 кредитов в месяц, счётчик обнуляется первого числа.

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

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

  1. POST /v1/videos со ссылкой {"url": "…"} — прогон стартует сразу.
  2. POST /v1/videos без ссылки — в ответе придёт upload_url: залейте файл методом PUT.
  3. POST /v1/videos/{id}/start — запуск для залитого файла.

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

Писем публичный 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 недоступен.
  • 409 — видео ещё не залито, уже запущено или ещё не готово к экспорту.
  • 422 — неизвестный формат, стиль или некорректная ссылка.