Uniqly API

Копії твого відео
за HTTP-запитом.

Той самий сервіс, що в боті, тільки для твоїх скриптів та інструментів. Надсилаєш одне відео, просиш до 10 копій, опитуєш завдання й завантажуєш файли.

Базова адресаhttps://api.uniqly.video

$ curl -X POST "https://api.uniqly.video/v1/jobs?copies=3" \
    -H "Authorization: Bearer uq_YOUR_KEY" \
    -H "Idempotency-Key: clip-01" \
    --data-binary @clip.mp4

201 Created
{
  "id": "Zq3vK8mTn4Lx0bW2cYd9Eg",
  "status": "queued",
  "copies_requested": 3,
  "copies_ready": 0
}

Один акаунт

Акаунт API це твій акаунт Uniqly: той самий баланс, план або команда й денний ліміт, що в боті.

Платиш за готові копії

Копія коштує стільки ж, скільки в боті. Копії, які не були видані, не списуються.

Файли зберігаються 24 години

До кожної копії додано її sha256. Завантаж її протягом 24 годин після кінця завдання.

Як отримати ключ

Ключ можна отримати в кабінеті на сайті або в боті, це той самий ключ. Він починається з uq_ і показується один раз, коли виданий: сервіс зберігає його хеш, а не сам ключ.

На сайті

У кабінеті

Увійди, відкрий кабінет і натисни «Отримати ключ». Там же видно, коли ключем користувалися, і там же його можна вимкнути.

Відкрити кабінет

У Telegram

У боті

Надішли /apikey new в особистому чаті з @UniqlyVideoBot. /apikey показує ключ, /apikey off вимикає його.

Відкрити бота
  • В акаунта один чинний ключ. Новий ключ, із бота чи з кабінету на сайті, одразу замінює попередній.
  • Перший ключ отримує акаунт, якому бот дозволяє робити копії: з кредитами, планом, у команді або з безкоштовним доступом.
  • Завдання належать акаунту, а не ключу: новий ключ бачить усі завдання, створені старим.

Бережи ключ як пароль: копії, зроблені з ним, списуються з тебе. Надсилай його тільки в заголовку Authorization і тільки через HTTPS.

Авторизація

Кожен запит, крім GET /v1/health, несе рівно один заголовок із ключем:

Authorization: Bearer uq_YOUR_KEY

Немає заголовка, він повторений, інша схема, невідомий чи вимкнений ключ: на все одна відповідь, 401 з кодом unauthorized.

  • Щоб читати свій акаунт і завдання, завантажувати й видаляти файли, потрібен лише ключ. Це працює і з порожнім балансом, і після кінця плану, тож оплачене лишається доступним.
  • Створити завдання чи ні, бот вирішує за своїми правилами на кожен запит: той самий доступ, денний ліміт і кредити. Акаунт, якому бот відмовив би, отримує 403 forbidden.

Завдання від початку до кінця

Чотири запити через curl. Один раз задай базову адресу й ключ:

API=https://api.uniqly.video
KEY=uq_YOUR_KEY
  1. Створи завдання

    Надішли відео тілом запиту й вкажи, скільки копій потрібно. Idempotency-Key обов'язковий: будь-який рядок до 64 літер, цифр і _ . -, новий для цього завдання.

    # 1. Створити завдання: три копії clip.mp4, файл іде тілом запиту
    curl -sS -X POST "$API/v1/jobs?copies=3" \
      -H "Authorization: Bearer $KEY" \
      -H "Idempotency-Key: clip-2026-10-01-a" \
      -H "Content-Type: video/mp4" \
      --data-binary @clip.mp4
    # 201 з об'єктом завдання: візьми з нього "id"
    JOB=Zq3vK8mTn4Lx0bW2cYd9Eg
  2. Опитуй завдання

    Запитуй раз на кілька секунд, доки status не стане done або failed. copies_ready росте під час роботи, і готові копії можна завантажувати, не чекаючи кінця.

    # 2. Опитувати, доки "status" не стане "done" або "failed"
    curl -sS "$API/v1/jobs/$JOB" -H "Authorization: Bearer $KEY"
  3. Завантаж кожну копію

    Шляхи лежать у files об'єкта завдання. Обірване завантаження можна продовжити заголовком Range, наприклад curl -C -.

    # 3. Завантажити готову копію, номери починаються з 1
    curl -sS -o copy-1.mp4 "$API/v1/jobs/$JOB/files/1" \
      -H "Authorization: Bearer $KEY"
  4. Перевір файл

    Порівняй хеш файлу з sha256 цієї копії. ETag завантаження це той самий хеш у лапках.

    # 4. Хеш має збігтися з "sha256" цієї копії
    shasum -a 256 copy-1.mp4    # sha256sum copy-1.mp4

Маршрути

Усі шляхи йдуть від базової адреси. Час в UTC, розміри в байтах.

Метод і шляхКлючЩо робить
POST /v1/jobsтакнадіслати одне відео й створити завдання
GET /v1/jobs/{id}такзавдання: статус, копії, скільки коштувало
GET /v1/jobs/{id}/files/{index}такзавантажити одну готову копію
DELETE /v1/jobs/{id}/filesтаквидалити файли завершеного завдання до терміну
GET /v1/meтактвій акаунт: режим, денний ліміт, кредити
GET /v1/healthнічи працює сервіс

Будь-який інший шлях відповідає 404 not_found, метод, який шлях не приймає, відповідає 405 із заголовком Allow. У кожній відповіді є Cache-Control: private, no-store.

Твій акаунт

GET /v1/me показує акаунт так само, як екран балансу в боті, навіть коли витрачати вже нічого. mode буває credits, paid (план), team, comp (безкоштовний доступ від Uniqly, у нього може бути термін) або denied. День це календарний день сервера за UTC.

{
  "mode": "credits",
  "daily_limit": 50,
  "used_today": 3,
  "left_today": 47,
  "credits": {"available": 7, "reserved": 3}
}

Параметри надсилання

POST /v1/jobs створює одне завдання з одного файлу. Пакетного надсилання, multipart-форми й надсилання за посиланням немає.

ДеІм'яОбов'язковийЗначення
querycopiesтакскільки копій, ціле число від 1 до 10, і не більше, ніж одне завдання може зробити з цього відео
querystrengthніn (за замовчуванням), s або x, див. нижче
queryallow_repeatніtrue або false (за замовчуванням): зробити завдання, навіть якщо частина копій повторить попередню нарізку, див. нижче
queryallow_copyніtrue або false (за замовчуванням): прийняти файл, який сам є копією від сервісу
заголовокAuthorizationтакBearer і твій ключ
заголовокIdempotency-Keyтаквід 1 до 64 символів з A-Z a-z 0-9 _ . -, новий для кожного завдання
тілотаксаме відео, один файл MP4 або MOV до 95 МіБ

Сила

КодУ ботіЩо змінюється
nЗвичайналегкий зум, по краях кадру зрізається зовсім трохи
sСильназум більший, по краях іде трохи більше
xДзеркалояк Сильна, плюс віддзеркалення по горизонталі (текст читається задом наперед)

Що відповідає надсилання

  • 201: нове завдання. У тілі об'єкт завдання, у Location його шлях.
  • 200: цей Idempotency-Key уже створив завдання. У тілі це завдання в поточному вигляді, нічого нового не списано.
  • Відмова (400, 401, 402, 403, 408, 409 no_fresh_framing і copy_of_copy, 413, 415, 422, будь-який 429, 503 maintenance) означає, що цей запит не створив завдання, нічого не зарезервував і не залишив файлу.
  • Після 500 або 503 busy результат невідомий: повтори той самий запит із тим самим Idempotency-Key.

Копії без повторів

Сервіс пам'ятає, де він нарізав кожну копію файлу для твого акаунта (і команди), і ріже кожну нову копію того самого файлу осторонь від усіх попередніх. Кожна сила має обмежену кількість таких нарізок на файл: n найменше, s і x більше.

  • Якщо для потрібних копій не вистачає нарізок, що лишилися в цієї сили для файлу, завдання відхиляється з 409 no_fresh_framing; error.fresh_left показує залишок для кожної сили. Попроси менше копій, обери іншу силу або надішли allow_repeat=true.
  • Файл, який сам є копією від сервісу, відхиляється з 409 copy_of_copy. Надішли оригінал або allow_copy=true.
  • Кожен запис files має fresh: true, якщо нарізка нова для цього файлу й акаунта, false, якщо вона повторює попередню.

Об'єкт завдання

GET /v1/jobs/{id} відповідає завданням. Завдання чужого акаунта відповідає 404, точно як неіснуючий id.

{
  "id": "Zq3vK8mTn4Lx0bW2cYd9Eg",
  "status": "done",
  "copies_requested": 3,
  "copies_ready": 3,
  "strength": "n",
  "billing": "credits",
  "credits": {"reserved": 3, "consumed": 3, "lost": 0, "returned": 0, "forfeited": 0},
  "error": null,
  "created_at": "2026-10-01T11:58:20.512094+00:00",
  "finished_at": "2026-10-01T12:00:00.184312+00:00",
  "expires_at": "2026-10-02T12:00:00.184312+00:00",
  "files": [
    {
      "index": 1,
      "size": 4812345,
      "sha256": "be501d782587b077db6446b897d5037bfa4b68a590e761020be1979a2a484349",
      "url": "/v1/jobs/Zq3vK8mTn4Lx0bW2cYd9Eg/files/1"
    }
  ]
}
status
queued, running, done або failed.
copies_ready
скільки копій уже видано з copies_requested.
billing
credits, якщо завдання витрачає кредити, quota, якщо воно йде в денний ліміт (план, команда, виданий доступ).
credits
у завдання на кредитах: скільки reserved, скільки consumed за видані копії і returned за решту; forfeited і lost, якщо пакет сплив або його повернули, поки завдання йшло.
quota
у завдання на ліміті: copies_counted, скільки зараховано в день.
error
null або, у невдалого завдання, один із кодів із розділу «Помилки».
expires_at
коли файли перестануть віддаватися, за замовчуванням через 24 години після кінця завдання.
files
по запису на кожну готову копію: index, size, sha256, url (її шлях) і fresh. Порожньо, коли файли спливли або видалені.

Час в ISO 8601 за UTC зі зсувом +00:00. url і Location це шляхи: додавай перед ними базову адресу.

Скільки коштує

Ціна як у боті: один кредит за копію для акаунта на кредитах. План, команда або виданий доступ натомість зараховують копії в денний ліміт.

  • Списуються лише видані копії. Копія видана, коли вона збережена і є у files, байдуже, завантажив ти її чи ні.
  • Коли завдання прийняте, кредити на всі його копії резервуються. Коли воно закінчується, видані копії списуються, решта повертається.
  • Невдале завдання з готовими копіями списує лише їх, і їх можна завантажити. Невдале завдання без копій нічого не коштує.
  • Відхилений запит нічого не коштує.
  • Видалення файлів до терміну і їхнє спливання нічого не повертають: копії були видані.
Пакети кредитів і плани

Ліміти

ЩоЛіміт
Тіло запитудо 95 МіБ (99 614 720 байтів), і заявлене, і фактичне
ФайлMP4 або MOV, перший блок якого ftyp. Один самодостатній файл, без плейлистів
Тривалістьвід 0,5 до 180 секунд
Кадрдо 8 294 400 пікселів, вертикальний чи горизонтальний (3840 × 2160)
Частота кадрівдо 61 кадру на секунду і до 257 126 400 пікселів на секунду загалом (31 кадр на секунду на найбільшому кадрі)
Копіївід 1 до 10 за завдання, і не більше, ніж одне завдання може зробити з цього відео
Час надсиланнябез пауз довших за 30 секунд, цілком за 10 хвилин
Завдань одночасно2 активних на акаунт, разом із надсиланнями, що йдуть
Завантажень одночасно16 на акаунт, 64 на весь сервіс
Запити120 на хвилину на ключ, разом з опитуванням і завантаженням
Невдалі авторизації30 на хвилину на весь сервіс, 10 на хвилину з однієї адреси
Зберігання результатів24 години після кінця завдання
Обробка15 хвилин з моменту, коли завдання взято в роботу, або для довгого відео в 1,5 раза більше розрахункового часу його копій, залежно від того, що довше

Деякі старі файли QuickTime починаються не з ftyp, і їх не приймуть: спершу перепакуй, ffmpeg -i in.mov -c copy out.mp4.

Черга і що означає busy

Завдання API і бота чекають в одній черзі й робляться по одній копії за раз. Одночасно активні не більше 2 завдань API на всі акаунти, решта черги лишається людям у боті. 429 busy означає, що місця зараз немає: зачекай Retry-After (30 секунд) і надішли той самий запит із тим самим Idempotency-Key.

З довгого або дуже важкого відео (4K, HDR, кілька хвилин) одне завдання може зробити менше 10 копій: запит на більше відхиляється з 422 too_many_copies і error.max_copies. Попроси стільки й надішли ще одне завдання на решту.

Скільки триватиме завдання, не обіцяємо: це залежить від завдань перед ним. Зазвичай кілька хвилин. Опитуй і не закладайся на фіксований час.

Скільки зберігаються результати

Файли віддаються 24 години після кінця завдання, потім відповідають 410 gone; саме завдання далі відповідає з порожнім files. DELETE /v1/jobs/{id}/files видаляє їх раніше. Надісланий вихідний файл не зберігається.

Помилки

У кожної помилки одне й те саме тіло. Спирайся на code і HTTP-статус: message написаний для людей і може змінюватися. Кожен 429 і 503 несе Retry-After у секундах.

{"error": {"code": "busy", "message": "the service is at capacity, retry later"}}
СтатусКодЩо означає
400bad_requestнемає, неправильний або повторений Idempotency-Key чи параметр запиту, або тіло не прочиталося
401unauthorizedключа немає, він неправильний, невідомий або вимкнений
402insufficient_creditsкредитів менше, ніж copies; в error.balance твій баланс
403forbiddenбот не дає цьому акаунту нову роботу
404not_foundнемає такого шляху, такого завдання в цього ключа або такої виданої копії
405method_not_allowedшлях не приймає цей метод; Allow перелічує ті, що приймає
408timeoutнадсилання зупинилося або не вклалося в термін
409in_progressзапит із цим Idempotency-Key саме зараз обробляється
409not_finishedDELETE для завдання, яке ще в черзі або в роботі
409no_fresh_framingу цієї сили для файлу лишилося замало нарізок; error.fresh_left показує залишок для кожної сили
409copy_of_copyфайл сам є копією від сервісу; надішли оригінал або allow_copy=true
410goneкопія спливла або видалена
413too_largeтіло більше за 95 МіБ
415unsupported_encodingтіло надіслане з Content-Encoding
416range_not_satisfiableRange виходить за межі файлу
422unsupported_mediaне MP4 чи MOV, що починається з ftyp, нечитабельне відео або перевищено ліміт за медіа
422too_many_copiesкопій більше, ніж одне завдання може зробити з цього відео; error.max_copies це максимум
429busyзараз немає місця для надсилання чи завантаження; цей запит нічого не створив
429daily_limitсьогоднішній ліміт не покриває copies
429rate_limitedзабагато запитів із цим ключем або забагато невдалих авторизацій
500internalзбій сервера; під час надсилання завдання могло створитися, повтори з тим самим Idempotency-Key
503busyсервер зараз не зміг вирішити; під час надсилання завдання могло створитися, повтори з тим самим Idempotency-Key після Retry-After (5 секунд)
503maintenanceнові завдання зараз не приймаються (300 секунд у Retry-After); читання, завантаження і повтор прийнятого Idempotency-Key працюють

Помилки невдалого завдання

Ці коди стоять у полі error завдання зі status failed. Невдале завдання може мати готові копії: вони у files, і списуються лише вони.

КодЩо означає
interruptedсервіс перезапустився або зупинився, поки завдання чекало або йшло. Відео тут ні до чого: створи нове завдання з новим Idempotency-Key
timeoutзавдання вперлося в термін обробки: 15 хвилин або для довгого відео в 1,5 раза більше розрахункового часу, залежно від того, що довше
processing_failedіз цього відео не вдалося зробити копію
storage_failedкопію не вдалося зберегти
bannedакаунт заблокували до того, як завдання пішло