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 Забагато картинок за добу.