Compress and upscale videos from your own code. How the API authenticates, how a task runs from start to finish, and what it costs.
9 min read
Vidaio's API puts the same compression and upscaling you'd run by hand into your own apps and pipelines: send it a video's link, and it hands back a link to the processed video. This guide covers how the API works from start to finish: your key, the life of a task, the limits and what it costs. The API reference (opens in a new tab) lists every endpoint with its fields, for when you write the requests.
You'll need three things:
The API knows who you are from your key alone. Send it with every request, in the X-API-Key header:
X-API-Key: YOUR_VIDAIO_API_KEYOr, if your HTTP client prefers it, as a bearer token:
Authorization: Bearer YOUR_VIDAIO_API_KEYProcessing a video takes a while, so the API doesn't keep you waiting on one request. Each video is a task that runs on its own, in three steps:
callback_url and Vidaio calls it when the task ends.Keep each task's id with whatever it belongs to (the upload, the record in your database), so you can check on it later, even after a restart.
A task is always in one of these states:
| State | What it means |
|---|---|
queued | Accepted, and waiting to start |
validating | Vidaio is downloading the video and checking it can be processed |
processing | Running. Your task history calls it Active |
completed | Done: its result is ready to collect |
failed | It couldn't be processed: its code and message say why. See if something's wrong |
cancelled | Cancelled before processing started |
completed, failed and cancelled are final: once a task reaches one, stop checking on it.
| Operation | Videos up to | Options |
|---|---|---|
| Compression | 10 minutes (about 6 at 1080p 30 fps, about 90 seconds at 4K) | Quality Low, Medium or High; Standard or Premium tier |
| Upscaling, Standard | 200 seconds, up to 2400×1365 for 2x and 1200 pixels wide for 4x | 2x or 4x |
| Upscaling, Premium | 20 seconds (less at larger sizes), up to 1280 pixels on the long edge for 2x and 960 for 4x | 2x or 4x |
Compression makes the file smaller and returns it as AV1. Its compression_type sets the quality you keep: Low gives the smallest files, High (the default) the best picture. Both tiers aim for the same quality: Standard encodes on CPUs, Premium on GPUs, so it finishes sooner and costs more. It takes H.264, HEVC and AV1 videos.
Upscaling doubles (2x) or quadruples (4x) the video's resolution. It takes H.264 and HEVC videos. Standard (the default) uses AI super-resolution, with a fast turnaround. Premium uses generative AI, which creates new fine detail, so small details (lettering, faces in the background, textures) can differ from the original. It keeps the video's frame rate and audio, and takes a few minutes a clip. It takes short clips from small sources: sources up to 720p for 2x and 540p for 4x, and clips from about 20 seconds at small sizes down to about 4.5 seconds at 1440p and 5 at 4K. A longer clip or a larger source is refused (INPUT_TOO_LONG or INPUT_OPTION_UNAVAILABLE) before anything is charged. Premium's results are AI-generated: the Terms of Service say how they may be used.
Tasks are charged by the minute of video, at these rates:
| Operation | Credits a minute |
|---|---|
| Compression, Standard | 3.33 (200 an hour) |
| Compression, Premium | 6.67 (400 an hour) |
| Upscaling, Standard 2x | 10 |
| Upscaling, Standard 4x | 25 |
| Upscaling, Premium 2x | 300 |
| Upscaling, Premium 4x | 1,200 |
So upscaling a 3-minute clip at Standard 2x costs 30 credits, and a 10-second clip at Premium 2x costs 50. GET /estimate works out a video's price before you start, and GET /pricing returns this list; neither needs a key.
Starting a task needs a positive balance. Once Vidaio has checked the video and knows its length, the task's cost is set aside from your balance; it's charged when the task completes, and handed back if the task fails or is cancelled, so a failed task costs nothing. The billing page shows your balance, what it covers and the same price list, and every task you run appears in the task history on the API page, with its state.
A task can take seconds or many minutes, depending on the video's length and what you asked for. Each key can start 3 tasks and make 30 other requests a minute; past that the API answers 429 with a Retry-After header saying how many seconds to wait. A few habits keep your code quick to hear about results without hitting those limits:
Idempotency-Key header (any unique string, such as your own job id) when you start a task. If the request times out and you send it again with the same key, you get the original task back instead of a second one, and you're never charged twice.Here's that loop in TypeScript, around a checkStatus function of your own that asks the API for a task's state:
type TaskState = "queued" | "validating" | "processing" | "completed" | "failed" | "cancelled";
const FINAL: TaskState[] = ["completed", "failed", "cancelled"];
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
/** Checks on a task until it's finished, waiting a little longer each time. */
export const waitForTask = async (
checkStatus: () => Promise<TaskState>,
{ timeoutMs = 30 * 60_000 } = {},
) => {
const deadline = Date.now() + timeoutMs;
let delay = 5_000;
while (Date.now() < deadline) {
const state = await checkStatus();
if (FINAL.includes(state)) return state;
await sleep(delay);
delay = Math.min(delay * 1.5, 60_000);
}
throw new Error("The task is still running: check on it again later");
};Instead of checking on a task, give it a callback_url when you start it: an HTTPS address of yours. When the task completes or fails, Vidaio sends it a POST with the task's id, status, and its download_url or failure code and message, and retries for a while if your server doesn't answer with a 2xx.
The start response includes a callback_token. Each call to your callback_url carries it in the X-Vidaio-Callback-Token header, so you can check the call really came from Vidaio for that task. It also carries an X-Vidaio-Signature header, an HMAC-SHA256 of the request body keyed with the same token, if you'd rather verify the body itself.
To have the result land in your own bucket rather than collecting it from a link, add an output when you start the task, with a pre-signed PUT URL you've made in your storage (S3, Cloudflare R2, Google Cloud Storage or Azure, for instance):
{
"video_url": "https://example.com/videos/launch.mp4",
"compression_type": "High",
"output": {
"put_url": "https://my-bucket.s3.amazonaws.com/out/launch.mp4?X-Amz-Signature=...",
"headers": { "Content-Type": "video/mp4" }
}
}The URL has to stay valid for at least 6 hours. Include in headers any header the URL was signed with. When the task completes, Vidaio uploads the result there, retrying if your storage is busy; the task's status shows how the delivery went in its delivery field. If a delivery fails for good, for instance because the URL expired, send a fresh one to POST /compression/{task_id}/deliver (or /upscaling/...). The usual download link still works either way.
GET /tasks, newest first, with their states and links.POST /compression/{task_id}/cancel (or /upscaling/...). Once it's processing it can't be stopped, and it's only charged if it completes.Every error comes back as JSON with a human-readable detail, a stable code your code can act on, and a request_id to quote if you contact us.
X-API-Key exactly as it is (or after Bearer in Authorization), with no quotes or stray spaces, and that it's your current key: re-rolling it retires the old one.INPUT_URL_NOT_ALLOWED means the video's link isn't a public HTTPS address.code says why. INPUT_* codes mean the video itself: too long or too large for its operation, a format it doesn't take, already well compressed, or a link that doesn't open without signing in (or has expired, if it's pre-signed). CREDITS_INSUFFICIENT means the balance didn't cover the video's length: top up and start it again. TASK_LOST means something went wrong on our side: you weren't charged, so start it again. Your task history on the API page shows every task's state.429 with Retry-After: wait that long, and space your checks out, as above. A 503 means Vidaio is busy or briefly unavailable: wait for its Retry-After and try again.Would you rather ask than code? Vidaio's tools also work from your AI assistant: see Connect your AI assistant to Vidaio.