Video Enhancement API Documentation
The Unblur Video API lets you enhance videos programmatically: upload a file (or point us at a URL), create an upscale job, wait until the result is downloadable, and download it.
Base URL: https://unblurvideo.ai/api/v1
GET https://unblurvideo.ai/api/v1 is an unauthenticated discovery endpoint that returns the API version, documentation URL, OpenAPI description, and resource paths. All resource endpoints below require authentication.
Version 1 creates video upscaling jobs (1080p, 2k or 4k output). The website's other tools are not available through the API yet.
Requests and responses are JSON unless a presigned upload URL explicitly asks for raw file bytes. JSON responses share one envelope:
{ "success": true, "data": { } }
Failed requests return success: false with an error message and a machine-readable code:
{ "success": false, "error": "Insufficient credits.", "code": "INSUFFICIENT_CREDITS" }
Request fields use snake_case (upload_id, target_resolution); response fields use camelCase (uploadId, creditCost). Write requests reject unknown fields with 400 INVALID_INPUT, so check spelling. For example, preview is optional and a job without it is a paid full job.
API access is included in the Growth and Pro plans. Requests from accounts without an active Growth or Pro subscription are rejected with
403 API_ACCESS_REQUIRED, including free previews: a preview started through the API or the Agent Skill needs API access too. Without a plan, try free previews on the website instead. See pricing.
On this page: Authentication · Quick start · Claude Code or Codex · Endpoints · Credits and pricing · Rate limits · Webhooks · Errors
Authentication
Create an API key in your dashboard, then pass it as a Bearer token on every request:
curl -H "Authorization: Bearer ubv_your_key_here" https://unblurvideo.ai/api/v1/credits
Keys start with ubv_ and are shown only once at creation time. Treat them like passwords: store them in your server's environment, never in client-side code or a repository. You can revoke a key at any time from the dashboard.
Keys can have an expiration and limited permissions: uploads:write for upload/confirm, jobs:write for creating jobs, jobs:read for job queries and estimates, and credits:read for balance checks. Existing keys retain their previous access. A valid key missing a required permission returns 403 INSUFFICIENT_SCOPE.
Responses include X-Request-Id. Include this identifier and the job ID when reporting an integration issue; never send your API key or temporary download URL.
A missing or invalid key returns 401 with a standard WWW-Authenticate: Bearer ... challenge. API responses use Cache-Control: no-store and are marked X-Robots-Tag: noindex, nofollow; the human-readable page you are reading remains the canonical, indexable documentation.
Quick start
Source videos can be up to 60 seconds long, 500 MB, and 1080 px on the short edge / 1920 px on the long edge (landscape or portrait).
1. Upload. The fastest way is to pass a public video URL. We download and analyze it in one call:
curl -X POST -H "Authorization: Bearer ubv_..." -H "Content-Type: application/json" \
-d '{"mode": "source_url", "source_url": "https://example.com/video.mp4"}' \
https://unblurvideo.ai/api/v1/uploads
2. Get a quote. This is free and doesn't create a job:
curl -X POST -H "Authorization: Bearer ubv_..." -H "Content-Type: application/json" \
-d '{"upload_id": "UPLOAD_ID", "target_resolution": "4k"}' \
https://unblurvideo.ai/api/v1/estimate-cost
3. Optional: a free preview. preview: true renders a watermarked clip of about 3 seconds at no credit cost. Each account gets five successful previews (API access is still required).
curl -X POST -H "Authorization: Bearer ubv_..." -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
-d '{"upload_id": "UPLOAD_ID", "target_resolution": "4k", "preview": true}' \
https://unblurvideo.ai/api/v1/jobs
4. Run the full job. Pass the quoted creditCost as max_credit_cost so a job is never charged more than you approved:
curl -X POST -H "Authorization: Bearer ubv_..." -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
-d '{"upload_id": "UPLOAD_ID", "target_resolution": "4k", "max_credit_cost": 33}' \
https://unblurvideo.ai/api/v1/jobs
5. Poll and download. Poll the job until outputReady is true, then download the temporary outputUrl:
curl -H "Authorization: Bearer ubv_..." https://unblurvideo.ai/api/v1/jobs/JOB_ID
Use with Claude Code or Codex
The open-source Unblur Video Agent Skill wraps this API in a dependency-free Python CLI, so Claude Code or Codex can upload a video, quote it, run a free preview or full job, and download the result for you. It needs the same Growth or Pro plan and API key as the API.
Install on macOS or Linux, for Claude Code:
git clone https://github.com/Unblur-Video/4k-video-upscaler.git
mkdir -p ~/.claude/skills
cp -R 4k-video-upscaler/skills/unblurvideo-enhance-video ~/.claude/skills/
For Codex:
git clone https://github.com/Unblur-Video/4k-video-upscaler.git
mkdir -p ~/.agents/skills
cp -R 4k-video-upscaler/skills/unblurvideo-enhance-video ~/.agents/skills/
Then save your API key once from a separate terminal window (not Claude Code's ! prefix, which cannot show the hidden prompt). For Codex, use ~/.agents/skills in the path:
python3 ~/.claude/skills/unblurvideo-enhance-video/scripts/unblurvideo.py login
Ask your agent something like "make a free preview of clip.mp4 with Unblur Video" or "upscale interview.mov to 2K". A step-by-step guide is on the Agent Skill page; Windows commands and troubleshooting are in the GitHub README.
Endpoints
POST /uploads
Register a video to process. Two modes:
Mode 1 — source_url. We fetch a public https URL server-side (max 500 MB; mp4, mov or webm). Metadata is extracted before the call returns, so you can create a job immediately.
curl -X POST -H "Authorization: Bearer ubv_..." -H "Content-Type: application/json" -d '{"mode": "source_url", "source_url": "https://example.com/video.mp4"}' https://unblurvideo.ai/api/v1/uploads
{
"success": true,
"data": {
"uploadId": "0c9d…",
"status": "uploaded",
"sizeBytes": 10485760,
"contentType": "video/mp4",
"metadata": { "resolution": "720p", "width": 1280, "height": 720, "duration": 12.4, "fps": 30 },
"metadataStatus": "ready"
}
}
Mode 2 — presigned upload. For local files: request an upload URL, PUT the file to it, then confirm.
curl -X POST -H "Authorization: Bearer ubv_..." -H "Content-Type: application/json" -d '{"filename": "clip.mp4", "content_type": "video/mp4", "size_bytes": 10485760}' https://unblurvideo.ai/api/v1/uploads
The response contains uploadId and a temporary uploadUrl (valid 10 minutes). Upload the raw file bytes to it:
{
"success": true,
"data": {
"uploadId": "0c9d…",
"uploadUrl": "https://…",
"expiresInSeconds": 600
}
}
curl -X PUT -H "Content-Type: video/mp4" --data-binary @clip.mp4 "UPLOAD_URL"
POST /uploads/{id}/confirm
Confirm a presigned upload after the PUT succeeds. Verifies the stored file and extracts video metadata synchronously (this call can take a few seconds).
curl -X POST -H "Authorization: Bearer ubv_..." https://unblurvideo.ai/api/v1/uploads/UPLOAD_ID/confirm
The response uses the same public upload fields as source_url mode:
{
"success": true,
"data": {
"uploadId": "0c9d…",
"status": "uploaded",
"sizeBytes": 10485760,
"metadata": { "resolution": "720p", "width": 1280, "height": 720, "duration": 12.4, "fps": 30 },
"metadataStatus": "ready"
}
}
If metadataStatus is "failed", the video could not be analyzed — try a different file.
POST /estimate-cost
Quote an uploaded video before creating a job. The request accepts upload_id, target_resolution, and optional preview (default false). It uses server-extracted metadata and current pricing without creating a job, reserving preview quota, or deducting credits.
curl -X POST -H "Authorization: Bearer ubv_..." -H "Content-Type: application/json" -d '{"upload_id": "UPLOAD_ID", "target_resolution": "4k"}' https://unblurvideo.ai/api/v1/estimate-cost
The response includes uploadId, taskType, targetResolution, preview, creditCost, fullCost, previewCost, totalCredits, hasEnoughCredits, canCreate, freePreviews, and metadata. Balances and eligibility are snapshots; creation checks them again. Pass the quoted creditCost as max_credit_cost when submitting to enforce a spending ceiling. The discovery endpoint lists this route as endpoints.estimateCost.
POST /jobs
Create an enhancement job for an uploaded video.
| Field | Type | Description |
|---|---|---|
upload_id | string | Required. The uploadId from an upload call. |
target_resolution | string | Required. 1080p, 2k or 4k (case-insensitive, so 4K also works). |
preview | boolean | Optional. true renders a free ~3-second watermarked preview and reserves one lifetime preview slot. |
max_credit_cost | number | Optional. Nonnegative ceiling with at most two decimals (maximum 999999999999.99). A new job costing more is rejected with 409 CREDIT_COST_EXCEEDS_LIMIT before any charge. |
curl -X POST \
-H "Authorization: Bearer ubv_..." \
-H "Idempotency-Key: 7f7f2f78-3cb4-4e2d-92e2-5d7dc7cf70f9" \
-H "Content-Type: application/json" \
-d '{"upload_id": "UPLOAD_ID", "target_resolution": "1080p"}' \
https://unblurvideo.ai/api/v1/jobs
Returns 201 with the job, including its creditCost. Credits are deducted when the job is created and automatically refunded if processing fails. If an identical job is already active, the existing job is returned with 200 and "duplicate": true — no double charge.
Each registered account can successfully complete five free previews over its lifetime, including paid accounts. Through the API, previews also require API access (an active Growth or Pro plan); accounts without it get 403 API_ACCESS_REQUIRED and can use their previews on the website. An in-flight preview temporarily reserves a slot. A failed or cancelled preview releases its reservation; a completed, downloadable preview consumes it permanently. Check GET /credits before submission. If all five previews have completed, the API returns 403 FREE_PREVIEW_LIMIT_REACHED; if the remaining slots are all in flight, it returns 409 FREE_PREVIEW_SLOTS_RESERVED. Never silently replace a rejected preview with a paid full job.
If metadata extraction is still in progress you get 409 METADATA_PENDING with a Retry-After header; retry after that many seconds.
Idempotent retries
Send a unique Idempotency-Key header when creating a job (1–128 characters; a UUID is a good choice). The key is scoped to your account:
- Repeating the same key with the same request returns the original job with
200and"duplicate": true, even if the first HTTP response was lost. - Reusing that key with different
upload_id,target_resolution, orpreviewvalues returns409 IDEMPOTENCY_KEY_REUSED. - If the job created with that key was later deleted, replaying the key returns
409 IDEMPOTENCY_KEY_JOB_DELETEDand nothing is charged; use a new key to create another job. - The raw key is never stored; the server stores SHA-256 hashes of the key and normalized request.
max_credit_costguards new execution and is excluded from idempotency identity. Replaying a key returns the original job even if this ceiling changes; it does not create another job or charge.
Idempotency-Key is optional for backward compatibility, but strongly recommended for every production integration.
GET /jobs/{id}
Read the latest stored job state. A background worker advances API jobs and transfers completed output independently of client polling. Poll no faster than retryAfterSeconds (15 seconds while queued, 10 while processing, 5 while the output is being saved), or receive webhook notifications.
curl -H "Authorization: Bearer ubv_..." https://unblurvideo.ai/api/v1/jobs/JOB_ID
Key response fields:
| Field | Description |
|---|---|
status | pending, in_queue, processing, completed, failed or cancelled. |
deliveryState | processing, transferring, ready, failed, cancelled, or reconciliation_required. Processing completion can precede download availability. |
outputReady | true when the completed result has a usable download URL and needs no reconciliation. Continue polling while completed has outputReady: false. |
retryAfterSeconds | Suggested minimum delay before polling again: 15 while queued, 10 while processing, 5 while transferring; null when no automatic progress is expected. |
outputUrl | Present after the completed output is persisted: a temporary download URL (valid 4 hours). Re-poll for a fresh one. Provider URLs are never exposed. |
creditCost | Credits charged for this job. |
errorMessage | Present when failed or cancelled; explains the failure and the refund outcome. |
failureCode | PROCESSING_FAILED (the source usually cannot be processed), PROCESSING_TIMED_OUT, SUBMISSION_FAILED, or CANCELLED; null otherwise. |
retryable | For failed or cancelled jobs, whether submitting the same upload again is expected to help. Do not automatically resubmit when false. |
refundStatus | refunded, pending (an automatic refund is still being retried), or not_required (free previews and jobs that did not fail). |
needsReconciliation | When true, the job needs manual review. Check this before treating any status as final. Stop polling, do not resubmit, and contact support with the job ID. |
The public response intentionally excludes internal R2 object keys, RunPod identifiers, provider payloads, and worker metadata.
GET /jobs
List your jobs, newest first. Query parameters: limit (default 20, max 100), offset, and optional status filter.
Lists and details include the account's website video jobs: video_upscale, frame_interpolation, background_removal, and watermark_removal. Creating jobs through v1 currently supports video upscaling only. Each item includes the same delivery-readiness fields described above.
curl -H "Authorization: Bearer ubv_..." "https://unblurvideo.ai/api/v1/jobs?status=completed&limit=10"
GET /credits
Check your credit balance and plan.
Credit balances can have up to two decimal places; integrations must accept fractional numbers.
curl -H "Authorization: Bearer ubv_..." https://unblurvideo.ai/api/v1/credits
{
"success": true,
"data": {
"totalCredits": 3600,
"subscriptionCredits": 3400,
"oneTimeCredits": 200,
"planName": "Pro",
"subscriptionStatus": "active",
"currentPeriodEnd": "2026-08-01T00:00:00.000Z",
"freePreviews": {
"limit": 5,
"completed": 2,
"reserved": 1,
"remaining": 2
},
"apiAccess": {
"enabled": true,
"source": "plan",
"expiresAt": null
}
}
}
freePreviews.remaining is the number of Preview jobs that can be started immediately. It equals the lifetime limit minus successful completions and in-flight reservations.
apiAccess.source is plan for a Growth or Pro subscription and grant for access granted by our team, in which case planName is null and expiresAt is when the grant ends.
Credits and pricing
Jobs are billed in credits based on video duration and target resolution:
| Target resolution | Credits per second of video |
|---|---|
| 1080p | 1.0 |
| 2k | 1.6 |
| 4k | 3.23 |
The total cost is first calculated from the full video duration and exact rate to two decimal places, then rounded up once to the next whole credit for both display and charging. For example, 10 seconds at the 4k rate is 32.30 credits, charged as 33. Previews cost no credits, but each account can successfully complete at most five over its lifetime. Source videos may be at most 60 seconds, 500 MB, and 1080 px on the short edge / 1920 px on the long edge. Credits come with your subscription and can be topped up with one-time packs from the pricing page.
Rate limits
Limits apply per account (all keys share them). Rate-limited responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). When exceeded, requests return 429 with a Retry-After header.
| Scope | Limit |
|---|---|
| Uploads (presigned or confirm) | 30 / hour each |
| Uploads via source_url | 10 / hour |
| Job creation | 45 / hour |
| Polling and quotes (job status, job list, credits, estimate-cost) | 120 / minute |
Webhooks
Configure up to three public HTTPS endpoints in the API dashboard. New endpoints and secret rotation require API access; deletion remains available after a subscription expires. The dashboard shows the latest 20 delivery attempts. No event is sent merely to test a newly registered address.
Notifications cover job.ready, job.failed, job.cancelled, and job.reconciliation_required for jobs handled by the API worker. job.ready means the output is persisted; call GET /jobs/{id} for a fresh download URL. Payloads contain no provider or signed download URLs:
{
"id": "EVENT_UUID",
"type": "job.ready",
"createdAt": "2026-10-03T00:00:00.000Z",
"data": {
"jobId": "JOB_UUID",
"taskType": "video_upscale",
"status": "completed",
"creditCost": 13,
"preview": false,
"needsReconciliation": false
}
}
Delivery is at least once. Return a 2xx response after durably accepting an event, and deduplicate by its stable id. The same event ID is reused on retries; ordering is not guaranteed. We allow 10 seconds per request and at most eight attempts, with retry delays of 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours, and 12 hours. An exhausted delivery remains visible as failed. Redirects are rejected; only public HTTPS on port 443 is supported. Deleting an endpoint removes queued deliveries, but an in-progress request may still arrive.
The signing secret is shown once when creating or rotating an endpoint. Store it securely. Each request has UnblurVideo-Webhook-Id, UnblurVideo-Webhook-Timestamp (Unix seconds), and UnblurVideo-Webhook-Signature (v1= followed by a hex HMAC-SHA256). Signatures cover the exact bytes of timestamp + "." + raw_request_body using the full signing secret. Verify the raw body before JSON parsing, reject timestamps more than five minutes old or in the future, and compare signatures in constant time. For example, in Node.js:
import { createHmac, timingSafeEqual } from "node:crypto";
function verifyWebhook(rawBody, timestamp, signature, secret) {
if (!/^\d+$/.test(timestamp ?? "")) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const match = /^v1=([0-9a-f]{64})$/.exec(signature ?? "");
if (!match) return false;
const expected = createHmac("sha256", secret)
.update(timestamp + ".").update(rawBody).digest();
return timingSafeEqual(expected, Buffer.from(match[1], "hex"));
}
After signature verification, confirm that the payload id matches UnblurVideo-Webhook-Id. Rotating the secret makes subsequent retries use the new secret; update your receiver immediately and account for requests already in flight.
Errors
Every error body has success: false, a human-readable error, a stable code, the requestId (same as the X-Request-Id header; quote it when contacting support) and a docs link:
{ "success": false, "error": "Insufficient credits.", "code": "INSUFFICIENT_CREDITS", "requestId": "3f1c…", "docs": "https://unblurvideo.ai/docs/api#errors" }
Branch on code, not on the message text. Treat a code you do not recognize as a generic error for its HTTP status; the OpenAPI description lists each response's codes under x-error-codes.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_JSON, INVALID_INPUT, INVALID_IDEMPOTENCY_KEY, INVALID_SOURCE_URL, UNSUPPORTED_TARGET_RESOLUTION | The request syntax, fields, ID, query, URL, target resolution, or idempotency header is invalid. |
| 400 | UNSUPPORTED_FILE_EXTENSION, UNSUPPORTED_FILE_TYPE, FILE_TYPE_EXTENSION_MISMATCH | The declared filename and MIME type are unsupported or do not match. |
| 400 | FILE_SIZE_REQUIRED, FILE_SIZE_UNVERIFIED, FILE_SIZE_MISMATCH, FILE_TYPE_UNVERIFIED, FILE_TYPE_MISMATCH, FILE_NOT_FOUND, INVALID_OBJECT_KEY, UPLOAD_NOT_READY | The stored upload could not be verified or is not ready for processing. |
| 401 | MISSING_API_KEY, INVALID_API_KEY, KEY_EXPIRED, PREVIEW_LOGIN_REQUIRED | Missing, wrong or revoked key, or preview access requires a registered account. |
| 402 | INSUFFICIENT_CREDITS | Not enough credits for this job. |
| 403 | API_ACCESS_REQUIRED, INSUFFICIENT_SCOPE, USER_BANNED, FREE_PREVIEW_LIMIT_REACHED | Your plan or key permissions do not include this operation, the account is unavailable, or all five lifetime previews have been completed. |
| 404 | UPLOAD_NOT_FOUND, JOB_NOT_FOUND, USAGE_NOT_FOUND | Resource or billing record does not exist or is not yours. |
| 409 | METADATA_PENDING | Video still being analyzed; retry after Retry-After seconds. |
| 409 | UPLOAD_STATUS_CONFLICT, JOB_ALREADY_CREATING, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_KEY_JOB_DELETED, FREE_PREVIEW_SLOTS_RESERVED | State, idempotency, or in-flight preview reservation conflict. |
| 409 | CREDIT_COST_EXCEEDS_LIMIT | The new job exceeds the requested spending ceiling; no job was created or charged. |
| 405 | METHOD_NOT_ALLOWED | The path does not support this HTTP method; the Allow header lists the ones it does. |
| 413 | FILE_TOO_LARGE | Video exceeds 500 MB. |
| 422 | VIDEO_TOO_LONG | The source video is longer than 60 seconds; trim it and upload again. |
| 422 | METADATA_UNAVAILABLE, VIDEO_UNDECODABLE, RESOLUTION_TOO_HIGH | The source video cannot be analyzed, its frames cannot be decoded (re-export it, for example as H.264 MP4), or it exceeds the supported input resolution. |
| 422 | SOURCE_URL_FORBIDDEN, SOURCE_URL_UNRESOLVABLE, SOURCE_URL_TOO_MANY_REDIRECTS | The remote URL is unsafe, cannot resolve, or redirects too many times. |
| 429 | RATE_LIMIT_EXCEEDED | Slow down; respect Retry-After. |
| 500 / 503 | INTERNAL_SERVER_ERROR, RUNPOD_FAILED, IDEMPOTENCY_STORAGE_FAILED, SERVER_MISCONFIGURED, SERVICE_UNAVAILABLE, JOB_RECONCILIATION_REQUIRED | Temporary server or processing backend failure. Reconciliation-required jobs retain their charge and must not be resubmitted. |
| 502 / 504 | SOURCE_FETCH_FAILED, SOURCE_FETCH_TIMEOUT | We couldn't download your source_url. |