API видеоконвертера

Создайте Bearer-токен в личном кабинете. Лимит запросов зависит от тарифа.

Машиночитаемая спецификация OpenAPI 3.1 доступна для генерации клиентов и тестирования. openapi.json

Scopes API-токенов

Создавайте отдельные токены только с теми правами, которые нужны интеграции. Токены, созданные до миграции scopes, для обратной совместимости сохраняют все права.

Scope	Разрешает
`usage:read`	Чтение тарифа и квоты
`jobs:read`	Чтение статусов jobs/batches
`jobs:write`	Создание и reprocess заданий
`jobs:cancel`	Отмена заданий
`files:download`	Скачивание готовых результатов

Идемпотентное создание задач

Все POST-endpoint’ы, создающие задание, принимают необязательный Idempotency-Key. Повтор того же запроса с тем же ключом возвращает исходный ответ и повторно не расходует API-квоту.

Idempotency-Key: order-2026-08-10-001

Если тот же ключ повторно используется для другого endpoint или с другими параметрами/метаданными файлов, API возвращает HTTP 409. Завершённые записи идемпотентности хранятся 24 часа.

Создание задачи

POST /api/v1/jobs
Authorization: Bearer <token>
Idempotency-Key: job-001
Content-Type: multipart/form-data

file=@video.mov
format=mp4
codec=h264
width=1920
height=1080
fit=contain
speed=1.5
normalizeAudio=1

Конвертировать этот исходник ещё раз

POST /api/v1/jobs/{id}/reprocess
Authorization: Bearer <token>
Idempotency-Key: reprocess-001
Content-Type: application/x-www-form-urlencoded

format=webm
codec=vp9
width=1280

Исходник копируется или hardlink-ится внутри сервера. Пока исходный файл не удалён по TTL, повторная загрузка не требуется.

Отменить задание

POST /api/v1/jobs/{id}/cancel
Authorization: Bearer <token>

Ожидающее задание снимается с Redis. Выполняющееся переходит в canceling, а worker завершает его FFmpeg-процесс.

Пакетная конвертация

POST /api/v1/batches
Authorization: Bearer <token>
Idempotency-Key: batch-001
Content-Type: multipart/form-data

files[]=@one.mov
files[]=@two.mov
format=mp4
codec=h264

Объединить видео

POST /api/v1/merge
Authorization: Bearer <token>
Idempotency-Key: merge-001
Content-Type: multipart/form-data

files[]=@part1.mp4
files[]=@part2.mp4
format=mp4
codec=h264

Разделить видео

POST /api/v1/split
Authorization: Bearer <token>
Idempotency-Key: split-001
Content-Type: multipart/form-data

file=@long-video.mp4
splitMode=duration
segmentDuration=60
format=mp4
codec=h264

Добавить субтитры к видео

POST /api/v1/subtitles
Authorization: Bearer <token>
Idempotency-Key: subtitles-001
Content-Type: multipart/form-data

file=@video.mp4
subtitle=@captions.srt
format=mp4
codec=h264
fontSize=28
marginV=36

Добавить водяной знак на видео

POST /api/v1/watermark
Authorization: Bearer <token>
Idempotency-Key: watermark-001
Content-Type: multipart/form-data

file=@video.mp4
watermark=@logo.png
position=bottom-right
widthPercent=20
opacity=0.85

Извлечь кадры из видео

POST /api/v1/frames
Authorization: Bearer <token>
Idempotency-Key: frames-001
Content-Type: multipart/form-data

file=@video.mp4
mode=interval
intervalSeconds=10
imageFormat=jpg
width=1280

Создать обложку из видео

POST /api/v1/thumbnail
Authorization: Bearer <token>
Idempotency-Key: thumb-001
Content-Type: multipart/form-data

file=@video.mp4
timestamp=12.5
imageFormat=webp
width=1280

Лимиты и использование

GET /api/v1/usage
Authorization: Bearer <token>

Возвращает текущий тариф, максимальный размер файла, feature flags, часовой лимит, использованные/оставшиеся единицы и время сброса.

Webhooks

В кабинете можно настроить подписанные HTTPS webhook для job.completed и job.failed. Сетевые ошибки, 408/409/425/429 и 5xx повторяются с backoff; постоянные 4xx сразу завершают delivery ошибкой.

X-Webhook-Id: evt_123
X-Webhook-Timestamp: 1786350000
X-Webhook-Signature: v1=<hmac_sha256>
Content-Type: application/json

{"id":"evt_123","type":"job.completed","data":{"job":{"id":"...","status":"completed"}}}

Проверяйте HMAC-SHA256 от строки «timestamp.raw_body» секретом, который показывается один раз при создании webhook. В своём приложении также отклоняйте слишком старые timestamp.

Статус

GET /api/v1/jobs/{id}
GET /api/v1/batches/{id}
Authorization: Bearer <token>

Скачивание

GET /api/v1/jobs/{id}/download
GET /api/v1/batches/{id}/download
Authorization: Bearer <token>

Batch, merge, split, субтитры, watermark, извлечение кадров, изменение скорости, нормализация громкости и сжатие до целевого размера зависят от возможностей тарифа. Создание одной обложки не требует отдельного Pro-флага.