Uniqly API

Copies of your video,
by HTTP request.

The same service as the bot, for your scripts and tools. Upload one video, ask for up to 10 copies, poll the job, download the files.

Base URLhttps://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
}

One account

Your API account is your Uniqly account: the same balance, plan or team and daily limit as in the bot.

You pay for delivered copies

A copy costs what it costs in the bot. Copies that were not delivered are not charged.

Files kept 24 hours

Each copy comes with its sha256. Download it within 24 hours of the job's end.

Getting a key

Get a key in your account on the site or in the bot: it is the same key. It starts with uq_ and is shown once, when it is made: the service keeps a hash of it, never the key.

On the site

In your account

Sign in, open your account and press Get a key. The account also shows when the key was last used, and switches it off.

Open your account

In Telegram

In the bot

Send /apikey new in a private chat with @UniqlyVideoBot. /apikey shows your key, /apikey off switches it off.

Open the bot
  • An account has one active key. A new key, from the bot or from your account on the site, replaces the previous one at once.
  • A first key is issued to an account the bot lets make copies: with credits, a plan, a team or free access.
  • Jobs belong to the account, not to the key: a new key reads every job the old one created.

Treat the key like a password: copies made with it are charged to you. Send it only in the Authorization header, over HTTPS.

Authentication

Every request except GET /v1/health carries exactly one header with the key:

Authorization: Bearer uq_YOUR_KEY

A missing header, a repeated one, another scheme, an unknown key and a revoked key all get the same answer: 401 with the code unauthorized.

  • Reading your account and your jobs, downloading and deleting files needs only the key. It keeps working when the balance is empty or a plan has ended, so what you paid for stays downloadable.
  • Creating a job is decided by the bot's own rules for each request: the same access, daily limit and credits. An account the bot would refuse gets 403 forbidden.

A job from start to finish

Four requests with curl. Set the base URL and your key once:

API=https://api.uniqly.video
KEY=uq_YOUR_KEY
  1. Create a job

    Send the video as the raw request body and say how many copies. Idempotency-Key is required: any string of up to 64 letters, digits and _ . - that is new for this job.

    # 1. Create a job: three copies of clip.mp4, the file is the raw body
    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 with the job object: take "id" from it
    JOB=Zq3vK8mTn4Lx0bW2cYd9Eg
  2. Poll the job

    Ask every few seconds until status is done or failed. copies_ready grows while the job runs, and ready copies can be downloaded before it ends.

    # 2. Poll until "status" is "done" or "failed"
    curl -sS "$API/v1/jobs/$JOB" -H "Authorization: Bearer $KEY"
  3. Download each copy

    The paths are in files of the job object. A download that was cut resumes with a Range header, for example curl -C -.

    # 3. Download a ready copy, indexes start at 1
    curl -sS -o copy-1.mp4 "$API/v1/jobs/$JOB/files/1" \
      -H "Authorization: Bearer $KEY"
  4. Check the file

    Compare the file's hash with sha256 of that copy. The download's ETag is the same hash in quotes.

    # 4. The hash must equal "sha256" of that copy
    shasum -a 256 copy-1.mp4    # sha256sum copy-1.mp4

Routes

Every path is under the base URL. Times are in UTC, sizes in bytes.

Method and pathKeyWhat it does
POST /v1/jobsyesupload one video and create a job
GET /v1/jobs/{id}yesthe job: status, copies, what it cost
GET /v1/jobs/{id}/files/{index}yesdownload one ready copy
DELETE /v1/jobs/{id}/filesyesdelete a finished job's files before they expire
GET /v1/meyesyour account: mode, daily limit, credits
GET /v1/healthnowhether the service is up

Any other path answers 404 not_found, a method a path does not take answers 405 with an Allow header. Every answer carries Cache-Control: private, no-store.

Your account

GET /v1/me shows the account as the bot's Balance screen does, also when there is nothing left to spend. mode is credits, paid (a plan), team, comp (free access given by Uniqly, which may have an end) or denied. The day is the server's calendar day in UTC.

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

Upload parameters

POST /v1/jobs creates one job from one file. There is no batch endpoint, no multipart form and no upload by URL.

WhereNameRequiredValue
querycopiesyeshow many copies, a whole number from 1 to 10, and no more than one job of this video may make
querystrengthnon (the default), s or x, see below
queryallow_repeatnotrue or false (the default): make the job even if some copies repeat earlier framings, see below
queryallow_copynotrue or false (the default): take a file that is itself a copy the service made
headerAuthorizationyesBearer and your key
headerIdempotency-Keyyes1 to 64 characters of A-Z a-z 0-9 _ . -, new for each job
bodyyesthe video itself, one MP4 or MOV file of at most 95 MiB

Strength

CodeIn the botWhat changes
nNormala slight zoom that trims a little off the frame edges
sStronga larger zoom, a little more off the edges
xMirrorthe same as Strong, plus a horizontal flip (text reads backwards)

What the upload answers

  • 201: a new job. The body is the job object, Location is its path.
  • 200: this Idempotency-Key already created a job. The body is that job as it is now, nothing new is charged.
  • A refusal (400, 401, 402, 403, 408, 409 no_fresh_framing and copy_of_copy, 413, 415, 422, any 429, 503 maintenance) means this request created no job, reserved nothing and left no file.
  • After 500 or 503 busy the outcome is not known: repeat the same request with the same Idempotency-Key.

Copies without repeats

The service remembers where it cut every copy it made of a file for your account (and your team), and cuts each new copy of the same file away from all of them. Each strength has a limited number of such framings per file: n the fewest, s and x more.

  • When the copies you ask for need more framings than the strength has left for this file, the job is refused with 409 no_fresh_framing; error.fresh_left gives the number left for each strength. Ask for fewer copies, choose another strength, or send allow_repeat=true.
  • A file that is itself a copy the service made is refused with 409 copy_of_copy. Send the original, or allow_copy=true.
  • Each entry of files carries fresh: true when its framing is new for this file and account, false when it repeats an earlier one.

The job object

GET /v1/jobs/{id} answers with the job. A job of another account answers 404, exactly like an id that does not exist.

{
  "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 or failed.
copies_ready
copies delivered so far, out of copies_requested.
billing
credits when the job spends credits, quota when it counts against a daily allowance (a plan, a team, an allowance).
credits
on a credits job, what was reserved, consumed for delivered copies and returned for the rest; forfeited and lost when a pack expired or was refunded while the job ran.
quota
on a quota job, copies_counted against the day.
error
null, or for a failed job one of the codes under Errors.
expires_at
when the files stop being served, 24 hours after the job finished by default.
files
one entry per ready copy: index, size, sha256, url (its path) and fresh. Empty once the files expired or were deleted.

Times are ISO 8601 in UTC with the offset +00:00. url and Location are paths: put the base URL in front of them.

What it costs

The price is the bot's: one credit per copy for an account that pays with credits. A plan, a team or an allowance counts copies against its daily limit instead.

  • Only delivered copies are charged. A copy is delivered when it is stored and listed in files, whether or not you download it.
  • When a job is accepted, credits for all its copies are reserved. When it ends, delivered copies are consumed and the rest is returned.
  • A failed job with ready copies is charged for those copies, and they stay downloadable. A failed job with none costs nothing.
  • A refused request costs nothing.
  • Deleting files early and their expiry refund nothing: the copies were delivered.
Credit packs and plans

Limits

WhatLimit
Request bodyat most 95 MiB (99,614,720 bytes), declared and actual
FileMP4 or MOV whose first box is ftyp. One self-contained file, no playlists
Durationfrom 0.5 to 180 seconds
Frameat most 8,294,400 pixels, portrait or landscape (3840 × 2160)
Frame rateat most 61 frames a second and 257,126,400 pixels a second in all (31 frames a second at the largest frame)
Copiesfrom 1 to 10 a job, and no more than one job of the video may make
Upload timeno gap longer than 30 seconds, complete within 10 minutes
Jobs at once2 active jobs an account, uploads in flight included
Downloads at once16 an account, 64 for the whole service
Requests120 a minute a key, polling and downloads included
Failed authentications30 a minute across the service, 10 a minute from one address
Results kept24 hours after the job finished
Processing15 minutes from the moment a job is picked up, or for a long video 1.5 times the time its copies are estimated to take, whichever is longer

Some older QuickTime files do not start with ftyp and are refused: remux them first, ffmpeg -i in.mov -c copy out.mp4.

The queue, and what busy means

API jobs and the bot's jobs wait in one queue and are made one copy at a time. At most 2 API jobs are active at once across all accounts; the rest of the queue is kept for people in the bot. 429 busy means no room right now: wait for Retry-After (30 seconds) and send the same request with the same Idempotency-Key.

A long or very large video (4K, HDR, minutes long) may take fewer copies in one job than 10: a request for more is refused with 422 too_many_copies and error.max_copies. Ask for that many and send another job for the rest.

How long a job takes is not promised: it depends on the jobs ahead of it. Usual jobs take a few minutes. Poll and do not build on a fixed time.

How long results are kept

Files are served for 24 hours after the job finished, then answer 410 gone; the job itself keeps answering with an empty files. DELETE /v1/jobs/{id}/files removes them earlier. The uploaded source is not kept.

Errors

Every error has the same body. Build on code and the HTTP status: message is for people and may change. Every 429 and 503 carries Retry-After in seconds.

{"error": {"code": "busy", "message": "the service is at capacity, retry later"}}
StatusCodeMeaning
400bad_requesta missing, malformed or repeated Idempotency-Key or query parameter, or a body that could not be read
401unauthorizedthe key is missing, malformed, unknown or revoked
402insufficient_creditsfewer credits than copies; error.balance is your balance
403forbiddenthe bot does not give this account new work
404not_foundno such path, no such job for this key, or no such delivered copy
405method_not_allowedthe path does not take this method; Allow lists the ones it takes
408timeoutthe upload stalled or ran past its deadline
409in_progressa request with this Idempotency-Key is being processed right now
409not_finishedDELETE on a job that is still queued or running
409no_fresh_framingthe strength has too few framings left for this file; error.fresh_left gives the number for each strength
409copy_of_copythe file is a copy the service made; send the original, or allow_copy=true
410gonethe copy has expired or was deleted
413too_largethe body is over 95 MiB
415unsupported_encodingthe body was sent with a Content-Encoding
416range_not_satisfiablethe Range is outside the file
422unsupported_medianot an MP4 or MOV file that starts with ftyp, not a readable video, or over a media limit
422too_many_copiesmore copies than one job of this video may make; error.max_copies is the most
429busyno room right now for an upload or a download; this request created nothing
429daily_limittoday's limit does not cover copies
429rate_limitedtoo many requests with this key, or too many failed authentications
500internalthe server failed; on an upload a job may exist, so repeat it with the same Idempotency-Key
503busythe server could not decide right now; on an upload a job may exist, so repeat it with the same Idempotency-Key after Retry-After (5 seconds)
503maintenancenew jobs are not accepted now (300 seconds in Retry-After); reading, downloads and a retry of an accepted Idempotency-Key still work

Errors of a failed job

These are in the error field of a job whose status is failed. A failed job can still have ready copies: they are in files and are the only ones charged.

CodeMeaning
interruptedthe service restarted or stopped while the job was queued or running. Your video was not at fault: create a new job with a new Idempotency-Key
timeoutthe job ran into its processing deadline: 15 minutes, or for a long video 1.5 times the estimated time, whichever is longer
processing_faileda copy could not be made from this video
storage_faileda copy could not be stored
bannedthe account was blocked before the job ran