One account
Your API account is your Uniqly account: the same balance, plan or team and daily limit as in the bot.
Uniqly API
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
}Your API account is your Uniqly account: the same balance, plan or team and daily limit as in the bot.
A copy costs what it costs in the bot. Copies that were not delivered are not charged.
Each copy comes with its sha256. Download it within 24 hours of the job's end.
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
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 accountIn Telegram
Send /apikey new in a private chat with @UniqlyVideoBot. /apikey shows your key, /apikey off switches it off.
Treat the key like a password: copies made with it are charged to you. Send it only in the Authorization header, over HTTPS.
Every request except GET /v1/health carries exactly one header with the key:
Authorization: Bearer uq_YOUR_KEYA missing header, a repeated one, another scheme, an unknown key and a revoked key all get the same answer: 401 with the code unauthorized.
403 forbidden.Four requests with curl. Set the base URL and your key once:
API=https://api.uniqly.video
KEY=uq_YOUR_KEYSend 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=Zq3vK8mTn4Lx0bW2cYd9EgAsk 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"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"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.mp4Every path is under the base URL. Times are in UTC, sizes in bytes.
| Method and path | Key | What it does |
|---|---|---|
POST /v1/jobs | yes | upload one video and create a job |
GET /v1/jobs/{id} | yes | the job: status, copies, what it cost |
GET /v1/jobs/{id}/files/{index} | yes | download one ready copy |
DELETE /v1/jobs/{id}/files | yes | delete a finished job's files before they expire |
GET /v1/me | yes | your account: mode, daily limit, credits |
GET /v1/health | no | whether 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.
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}
}POST /v1/jobs creates one job from one file. There is no batch endpoint, no multipart form and no upload by URL.
| Where | Name | Required | Value |
|---|---|---|---|
| query | copies | yes | how many copies, a whole number from 1 to 10, and no more than one job of this video may make |
| query | strength | no | n (the default), s or x, see below |
| query | allow_repeat | no | true or false (the default): make the job even if some copies repeat earlier framings, see below |
| query | allow_copy | no | true or false (the default): take a file that is itself a copy the service made |
| header | Authorization | yes | Bearer and your key |
| header | Idempotency-Key | yes | 1 to 64 characters of A-Z a-z 0-9 _ . -, new for each job |
| body | | yes | the video itself, one MP4 or MOV file of at most 95 MiB |
| Code | In the bot | What changes |
|---|---|---|
n | Normal | a slight zoom that trims a little off the frame edges |
s | Strong | a larger zoom, a little more off the edges |
x | Mirror | the same as Strong, plus a horizontal flip (text reads backwards) |
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.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.500 or 503 busy the outcome is not known: repeat the same request with the same Idempotency-Key.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.
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.409 copy_of_copy. Send the original, or allow_copy=true.files carries fresh: true when its framing is new for this file and account, false when it repeats an earlier one.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"
}
]
}statusqueued, running, done or failed.copies_readycopies_requested.billingcredits when the job spends credits, quota when it counts against a daily allowance (a plan, a team, an allowance).creditsreserved, consumed for delivered copies and returned for the rest; forfeited and lost when a pack expired or was refunded while the job ran.quotacopies_counted against the day.errornull, or for a failed job one of the codes under Errors.expires_atfilesindex, 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.
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.
files, whether or not you download it.| What | Limit |
|---|---|
| Request body | at most 95 MiB (99,614,720 bytes), declared and actual |
| File | MP4 or MOV whose first box is ftyp. One self-contained file, no playlists |
| Duration | from 0.5 to 180 seconds |
| Frame | at most 8,294,400 pixels, portrait or landscape (3840 × 2160) |
| Frame rate | at most 61 frames a second and 257,126,400 pixels a second in all (31 frames a second at the largest frame) |
| Copies | from 1 to 10 a job, and no more than one job of the video may make |
| Upload time | no gap longer than 30 seconds, complete within 10 minutes |
| Jobs at once | 2 active jobs an account, uploads in flight included |
| Downloads at once | 16 an account, 64 for the whole service |
| Requests | 120 a minute a key, polling and downloads included |
| Failed authentications | 30 a minute across the service, 10 a minute from one address |
| Results kept | 24 hours after the job finished |
| Processing | 15 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.
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.
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.
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"}}| Status | Code | Meaning |
|---|---|---|
400 | bad_request | a missing, malformed or repeated Idempotency-Key or query parameter, or a body that could not be read |
401 | unauthorized | the key is missing, malformed, unknown or revoked |
402 | insufficient_credits | fewer credits than copies; error.balance is your balance |
403 | forbidden | the bot does not give this account new work |
404 | not_found | no such path, no such job for this key, or no such delivered copy |
405 | method_not_allowed | the path does not take this method; Allow lists the ones it takes |
408 | timeout | the upload stalled or ran past its deadline |
409 | in_progress | a request with this Idempotency-Key is being processed right now |
409 | not_finished | DELETE on a job that is still queued or running |
409 | no_fresh_framing | the strength has too few framings left for this file; error.fresh_left gives the number for each strength |
409 | copy_of_copy | the file is a copy the service made; send the original, or allow_copy=true |
410 | gone | the copy has expired or was deleted |
413 | too_large | the body is over 95 MiB |
415 | unsupported_encoding | the body was sent with a Content-Encoding |
416 | range_not_satisfiable | the Range is outside the file |
422 | unsupported_media | not an MP4 or MOV file that starts with ftyp, not a readable video, or over a media limit |
422 | too_many_copies | more copies than one job of this video may make; error.max_copies is the most |
429 | busy | no room right now for an upload or a download; this request created nothing |
429 | daily_limit | today's limit does not cover copies |
429 | rate_limited | too many requests with this key, or too many failed authentications |
500 | internal | the server failed; on an upload a job may exist, so repeat it with the same Idempotency-Key |
503 | busy | the 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) |
503 | maintenance | new jobs are not accepted now (300 seconds in Retry-After); reading, downloads and a retry of an accepted Idempotency-Key still work |
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.
| Code | Meaning |
|---|---|
interrupted | the 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 |
timeout | the job ran into its processing deadline: 15 minutes, or for a long video 1.5 times the estimated time, whichever is longer |
processing_failed | a copy could not be made from this video |
storage_failed | a copy could not be stored |
banned | the account was blocked before the job ran |