API для разработчиков

Создать задание

Передайте либо file (затем загрузите его по upload), либо url — тогда файл скачаем мы и задание сразу встанет в очередь.

В ответе upload — одно из двух:

• put_url и headers — файл до 64 МБ загружается одним PUT с этими заголовками;
• part_size, part_count, parts — файл больше загружается частями по part_size байт (последняя короче); в parts первые 50 ссылок, остальные — через POST /jobs/{id}/parts.

Для url блок upload пуст.

Тело запроса (JSON)

Пример

curl -s -X POST https://convr.app/api/v1/jobs -H "Authorization: Bearer $CONVR_KEY" -H "Content-Type: application/json" \
  -d '{"converter":"mp4-mp4","options":{"target_mb":"25"},
       "file":{"name":"video.mp4","size":187654321}}'

Ответ

201 Created
{
  "batch_id": "01m6he8m2e…",
  "job": { "id": "01m6he8nmn…", "state": "awaiting_input", … },
  "upload": {
    "put_url": "https://…",
    "headers": { "Content-Type": "video/quicktime" }
  }
}

// a file over 64 MB:
  "upload": {
    "part_size": 16777216,
    "part_count": 32,
    "parts": [{ "n": 1, "url": "https://…" }, …]
  }

Ошибки

• unknown_converter400 Нет такого конвертера — смотрите GET /registry.
• invalid_options400 Неизвестная настройка или недопустимое значение.
• invalid_file400 Не указаны имя или размер файла.
• invalid_url400 Ссылка не http(s) или вместе с ней передан файл.
• invalid_webhook400 Адрес вебхука не http(s).
• file_too_large413 Файл больше, чем позволяет тариф (limit — в байтах).
• limit_active429 Слишком много заданий выполняется одновременно.
• limit_daily429 Исчерпан суточный лимит заданий.
• speech_limit429 Исчерпаны минуты распознавания речи за 30 дней.
• links_unavailable503 Скачивание с видеосайтов временно недоступно.

Загрузить файл

Запрос идёт напрямую в хранилище — без ключа API, с заголовками из upload.headers. Тело — сам файл, ровно file.size байт. Ссылка действует 15 минут.

При загрузке частями: PUT каждой части по её url, тело — part_size байт (последняя — остаток). Части можно грузить параллельно и в любом порядке; собирать их не нужно.

Пример

curl -X PUT "$PUT_URL" -H "Content-Type: video/mp4" --data-binary @video.mp4

# parts: split -b 16777216 big.mov part_ && upload part_aa to parts[0].url, …
curl -X PUT "$PART_1_URL" --data-binary @part_aa

Ещё ссылки на части

Подписанные ссылки для частей с from по to включительно, не больше 50 за раз.

Тело запроса (JSON)

Пример

curl -s -X POST https://convr.app/api/v1/jobs/JOB/parts -H "Authorization: Bearer $CONVR_KEY" -H "Content-Type: application/json" -d '{"from":51,"to":100}'

Ответ

{ "parts": [{ "n": 51, "url": "https://…" }, …] }

Ошибки

• bad_range400 from/to вне частей файла или больше 50 за раз.
• no_upload409 У задания нет незавершённой загрузки частями.

Запустить после загрузки

Проверяет, что файл загружен целиком и нужного размера, и ставит задание в очередь. Тело не нужно.

Пример

curl -s -X POST https://convr.app/api/v1/jobs/JOB/uploaded -H "Authorization: Bearer $CONVR_KEY"

Ответ

{ "id": "…", "state": "…", … }   // the job object

Ошибки

• upload_incomplete400 Файл (или часть) не загружен целиком.
• upload_size_mismatch400 Загружено не столько байт, сколько указано в file.size.
• already_uploaded409 Задание уже запущено.

Статус задания

Текущее состояние, этап и прогресс.

Пример

curl -s https://convr.app/api/v1/jobs/JOB -H "Authorization: Bearer $CONVR_KEY"

Ответ

{ "id": "…", "state": "leased", "stage": "converting", "progress": 42, … }

Ошибки

• not_found404 Задания нет или оно не ваше.

Ссылка на результат

Подписанная ссылка CDN на 30 минут (не дольше срока хранения). Скачивание по ней — без ключа. Запрашивайте заново, когда нужно.

Пример

curl -sL "$(curl -s https://convr.app/api/v1/jobs/JOB/download -H "Authorization: Bearer $CONVR_KEY" | jq -r .url)" -o result.mp4

Ответ

{ "url": "https://dl.…/clip.mp4?token=…&expires=…", "expires_at": "2026-11-04T12:30:00Z" }

Ошибки

• not_ready409 Результата ещё нет: задание не в состоянии done.
• not_found404 Задания нет или оно не ваше.

Отменить

Останавливает задание, если оно ещё не завершилось.

Пример

curl -s -X POST https://convr.app/api/v1/jobs/JOB/cancel -H "Authorization: Bearer $CONVR_KEY"

Ответ

{ "id": "…", "state": "…", … }   // the job object

Удалить файлы

Отменяет задание и сразу удаляет исходник и результат, не дожидаясь срока хранения.

Пример

curl -s -X DELETE https://convr.app/api/v1/jobs/JOB -H "Authorization: Bearer $CONVR_KEY"

Ответ

204 No Content

Задания пакета

Все задания пакета в порядке создания.

Ответ

{ "id": "…", "jobs": [ { "id": "…", "state": "done", … }, … ] }

Поток событий (SSE)

Server-Sent Events: сначала snapshot со всеми заданиями, затем job при каждом изменении. Соединение держится открытым; после обрыва переподключайтесь — снова придёт snapshot.

Пример

curl -N https://convr.app/api/v1/batches/BATCH/events -H "Authorization: Bearer $CONVR_KEY"

Ответ

event: snapshot
data: [{"id":"…","state":"queued",…}]

event: job
data: {"id":"…","state":"leased","stage":"converting","progress":37,…}

Упаковать в ZIP

Создаёт задание-архив из всех готовых результатов пакета (от двух). Повторный вызов для того же набора вернёт тот же архив.

Ответ

{ "id": "…", "state": "…", … }   // the job object

Ошибки

• nothing_to_zip400 В пакете меньше двух готовых результатов.
• zip_too_large413 Архив вышел бы слишком большим.

Содержимое папки

Папки и файлы, путь к папке, занятое место и квота.

Параметры строки запроса

Ответ

{ "folder": null, "path": [], "folders": [ { "id": "…", "name": "Работа", "files": 3, "size": 1048576 } ],
  "files": [ { "id": "…", "name": "report.pdf", "size": 52011, "format": "pdf", "state": "ready" } ],
  "used": 1100587, "quota": 2147483648, "count": 4 }

Загрузить файл

Резервирует место и выдаёт ссылку для загрузки (как POST /jobs). После загрузки — POST /drive/files/{id}/uploaded.

Тело запроса (JSON)

Ответ

{ "file": { "id": "…", "state": "uploading", … }, "upload": { "put_url": "…", "headers": { … } } }

Ошибки

• drive_full
• drive_unavailable
• file_too_large413 Файл больше, чем позволяет тариф (limit — в байтах).

Конвертировать из облака

Создаёт задание, которое читает файл прямо из облака; результат кладётся в папку файла (save: false — не класть).

Тело запроса (JSON)

Ответ

{ "id": "…", "state": "…", … }   // the job object

Результат — в облако

Копирует готовый результат задания в облако (внутри хранилища, без скачивания).

Тело запроса (JSON)

Ошибки

• drive_full
• not_ready409 Результата ещё нет: задание не в состоянии done.

Ссылка на скачивание

Подписанная ссылка CDN на время.

Ответ

{ "url": "https://…", "expires_at": "…" }

Переименовать или переместить

name и/или folder ("" — верхний уровень). Папки — PATCH /drive/folders/{id} с name и parent.

Удалить файл

Сразу освобождает место. Папка удаляется вместе с содержимым: DELETE /drive/folders/{id}.

Анализ видео

Обычное создание задания с конвертером mp4-scan (mov-scan, mkv-scan…). Результат анализа — в поле result готового задания: громкость, смены сцен и лучшие моменты для клипов по 15, 30, 60 и 90 секунд с оценкой 0–100. Анализ загруженного файла не расходует суточный лимит заданий.

Ответ

"result": {
  "duration": 312.4,
  "loudness": [0.12, 0.4, …],
  "scenes": [4.2, 17.9, …],
  "clips": {
    "30": [{ "start": 81.5, "end": 111.5, "score": 100 }, …],
    "60": [ … ]
  }
}

Нарезать клипы

{id} — задание scan. Один отрезок даёт MP4, несколько — ZIP с клипами. Доступны настройки видео: aspect (по умолчанию 9:16), fit, quality, заголовок, водяной знак, фильтры, музыка.

Тело запроса (JSON)

Пример

curl -s -X POST https://convr.app/api/v1/jobs/SCAN/clips -H "Authorization: Bearer $CONVR_KEY" -H "Content-Type: application/json" \
  -d '{"options":{"ranges":"81.5-111.5,140-170","aspect":"9:16","fit":"smart",
       "title":"Best moments"}}'

Ответ

201 Created
{ "id": "…", "converter": "mp4-clips", "state": "queued", … }

Ошибки

• not_a_scan400 {id} — не задание анализа (scan).
• not_uploaded409 Видео задания scan ещё не загружено или не скачано.
• source_gone409 Задание scan отменено или истекло — файла больше нет.
• invalid_options400 Неизвестная настройка или недопустимое значение.
• limit_active429 Слишком много заданий выполняется одновременно.
• limit_daily429 Исчерпан суточный лимит заданий.

Распознать речь

{id} — задание scan. Слова с таймкодами приходят в result готового задания. До 20 минут речи за задание; расходует минуты распознавания тарифа.

Тело запроса (JSON)

Пример

curl -s -X POST https://convr.app/api/v1/jobs/SCAN/transcribe -H "Authorization: Bearer $CONVR_KEY" -H "Content-Type: application/json" -d '{"options":{"ranges":"0-60","lang":"auto"}}'

Ответ

"result": {
  "language": "ru",
  "clips": [{
    "start": 0, "end": 60,
    "words": [{ "w": "Привет", "s": 0.32, "e": 0.71 }, …]
  }]
}

Ошибки

• speech_too_long400 Больше 20 минут речи (limit — секунды).
• speech_limit429 Исчерпаны минуты распознавания речи за 30 дней.
• speech_unavailable503 Распознавание речи временно недоступно.
• not_a_scan400 {id} — не задание анализа (scan).

Форматы и конвертеры

Все форматы, конвертеры и их настройки. Ключ не обязателен. Меняется редко — можно кешировать по version.

Ответ

{
  "version": 14,
  "formats": [{"id": "mov", "ext": "mov", "kind": "video", "mime": "video/quicktime"}, …],
  "converters": [{
    "id": "mov-mp4", "from": "mov", "to": "mp4", "engine": "ffmpeg",
    "options": [
      {"key": "quality", "type": "enum", "values": ["high", "medium", "small"], "default": "medium"},
      {"key": "trim_start", "type": "time", "max": 86400},
      …
    ]
  }, …],
  "tools": [ … ]
}

Лимиты тарифа

Лимиты вашего тарифа и израсходованные секунды распознавания.

Ответ

{
  "max_file_bytes": 10737418240,
  "max_jobs_day": 500,
  "max_active": 10,
  "max_duration_s": 14400,
  "retention_h": 72,
  "speech_minutes": 600,
  "speech_used_s": 1834.5
}

История

Задания аккаунта, от новых к старым, по 50. Для следующей страницы передайте created_at последнего в before.

Параметры строки запроса

Ответ

{ "jobs": [{ "id": "…", "state": "done", …, "created_at": "2026-11-04T09:12:44.123Z" }, …] }

Ошибки

• bad_cursor400 before — не время RFC 3339.

Картинка для водяного знака

Тело — PNG до 2 МБ и 2048×2048 (Content-Type: image/png). Полученный id передавайте в options.wm_image.

Пример

curl -s -X POST https://convr.app/api/v1/assets -H "Authorization: Bearer $CONVR_KEY" -H "Content-Type: image/png" --data-binary @logo.png

Ответ

201 Created
{ "id": "…", "width": 512, "height": 512 }

Ошибки

• invalid_image400 Не PNG или больше 2048×2048.
• file_too_large413 Файл больше, чем позволяет тариф (limit — в байтах).
• too_many_assets429 Слишком много картинок за сутки.