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аккаунт заблокировали до того, как задание пошло