Один акаунт
Акаунт API це твій акаунт Uniqly: той самий баланс, план або команда й денний ліміт, що в боті.
Uniqly API
Той самий сервіс, що в боті, тільки для твоїх скриптів та інструментів. Надсилаєш одне відео, просиш до 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: той самий баланс, план або команда й денний ліміт, що в боті.
Копія коштує стільки ж, скільки в боті. Копії, які не були видані, не списуються.
До кожної копії додано її 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Надішли відео тілом запиту й вкажи, скільки копій потрібно. 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Запитуй раз на кілька секунд, доки status не стане done або failed. copies_ready росте під час роботи, і готові копії можна завантажувати, не чекаючи кінця.
# 2. Опитувати, доки "status" не стане "done" або "failed"
curl -sS "$API/v1/jobs/$JOB" -H "Authorization: Bearer $KEY"Шляхи лежать у files об'єкта завдання. Обірване завантаження можна продовжити заголовком Range, наприклад curl -C -.
# 3. Завантажити готову копію, номери починаються з 1
curl -sS -o copy-1.mp4 "$API/v1/jobs/$JOB/files/1" \
-H "Authorization: Bearer $KEY"Порівняй хеш файлу з 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-форми й надсилання за посиланням немає.
| Де | Ім'я | Обов'язковий | Значення |
|---|---|---|---|
| query | copies | так | скільки копій, ціле число від 1 до 10, і не більше, ніж одне завдання може зробити з цього відео |
| query | strength | ні | n (за замовчуванням), s або x, див. нижче |
| query | allow_repeat | ні | true або false (за замовчуванням): зробити завдання, навіть якщо частина копій повторить попередню нарізку, див. нижче |
| query | allow_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"
}
]
}statusqueued, running, done або failed.copies_readycopies_requested.billingcredits, якщо завдання витрачає кредити, quota, якщо воно йде в денний ліміт (план, команда, виданий доступ).creditsreserved, скільки consumed за видані копії і returned за решту; forfeited і lost, якщо пакет сплив або його повернули, поки завдання йшло.quotacopies_counted, скільки зараховано в день.errornull або, у невдалого завдання, один із кодів із розділу «Помилки».expires_atfilesindex, 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.
Завдання 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"}}| Статус | Код | Що означає |
|---|---|---|
400 | bad_request | немає, неправильний або повторений Idempotency-Key чи параметр запиту, або тіло не прочиталося |
401 | unauthorized | ключа немає, він неправильний, невідомий або вимкнений |
402 | insufficient_credits | кредитів менше, ніж copies; в error.balance твій баланс |
403 | forbidden | бот не дає цьому акаунту нову роботу |
404 | not_found | немає такого шляху, такого завдання в цього ключа або такої виданої копії |
405 | method_not_allowed | шлях не приймає цей метод; Allow перелічує ті, що приймає |
408 | timeout | надсилання зупинилося або не вклалося в термін |
409 | in_progress | запит із цим Idempotency-Key саме зараз обробляється |
409 | not_finished | DELETE для завдання, яке ще в черзі або в роботі |
409 | no_fresh_framing | у цієї сили для файлу лишилося замало нарізок; error.fresh_left показує залишок для кожної сили |
409 | copy_of_copy | файл сам є копією від сервісу; надішли оригінал або allow_copy=true |
410 | gone | копія спливла або видалена |
413 | too_large | тіло більше за 95 МіБ |
415 | unsupported_encoding | тіло надіслане з Content-Encoding |
416 | range_not_satisfiable | Range виходить за межі файлу |
422 | unsupported_media | не MP4 чи MOV, що починається з ftyp, нечитабельне відео або перевищено ліміт за медіа |
422 | too_many_copies | копій більше, ніж одне завдання може зробити з цього відео; error.max_copies це максимум |
429 | busy | зараз немає місця для надсилання чи завантаження; цей запит нічого не створив |
429 | daily_limit | сьогоднішній ліміт не покриває copies |
429 | rate_limited | забагато запитів із цим ключем або забагато невдалих авторизацій |
500 | internal | збій сервера; під час надсилання завдання могло створитися, повтори з тим самим Idempotency-Key |
503 | busy | сервер зараз не зміг вирішити; під час надсилання завдання могло створитися, повтори з тим самим Idempotency-Key після Retry-After (5 секунд) |
503 | maintenance | нові завдання зараз не приймаються (300 секунд у Retry-After); читання, завантаження і повтор прийнятого Idempotency-Key працюють |
Ці коди стоять у полі error завдання зі status failed. Невдале завдання може мати готові копії: вони у files, і списуються лише вони.
| Код | Що означає |
|---|---|
interrupted | сервіс перезапустився або зупинився, поки завдання чекало або йшло. Відео тут ні до чого: створи нове завдання з новим Idempotency-Key |
timeout | завдання вперлося в термін обробки: 15 хвилин або для довгого відео в 1,5 раза більше розрахункового часу, залежно від того, що довше |
processing_failed | із цього відео не вдалося зробити копію |
storage_failed | копію не вдалося зберегти |
banned | акаунт заблокували до того, як завдання пішло |