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/from-url
Authorization: Bearer <token>
Idempotency-Key: remote-001
Content-Type: application/json

{
  "url": "https://example.com/video/123",
  "sourceQuality": "1080",
  "format": "mp4",
  "codec": "h264"
}

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

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

Ранее загруженный исходник можно обработать повторно без новой загрузки, пока файл ещё доступен в Видиха.

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

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

Ожидающее задание отменяется сразу. Выполняющееся переходит в состояние отмены и останавливается при первой возможности.

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

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=custom
xPercent=82
yPercent=12
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-флага.