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.

FieldTypeDescription
upload_idstringRequired. The uploadId from an upload call.
target_resolutionstringRequired. 1080p, 2k or 4k (case-insensitive, so 4K also works).
previewbooleanOptional. true renders a free ~3-second watermarked preview and reserves one lifetime preview slot.
max_credit_costnumberOptional. 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 200 and "duplicate": true, even if the first HTTP response was lost.
  • Reusing that key with different upload_id, target_resolution, or preview values returns 409 IDEMPOTENCY_KEY_REUSED.
  • If the job created with that key was later deleted, replaying the key returns 409 IDEMPOTENCY_KEY_JOB_DELETED and 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_cost guards 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:

FieldDescription
statuspending, in_queue, processing, completed, failed or cancelled.
deliveryStateprocessing, transferring, ready, failed, cancelled, or reconciliation_required. Processing completion can precede download availability.
outputReadytrue when the completed result has a usable download URL and needs no reconciliation. Continue polling while completed has outputReady: false.
retryAfterSecondsSuggested minimum delay before polling again: 15 while queued, 10 while processing, 5 while transferring; null when no automatic progress is expected.
outputUrlPresent after the completed output is persisted: a temporary download URL (valid 4 hours). Re-poll for a fresh one. Provider URLs are never exposed.
creditCostCredits charged for this job.
errorMessagePresent when failed or cancelled; explains the failure and the refund outcome.
failureCodePROCESSING_FAILED (the source usually cannot be processed), PROCESSING_TIMED_OUT, SUBMISSION_FAILED, or CANCELLED; null otherwise.
retryableFor failed or cancelled jobs, whether submitting the same upload again is expected to help. Do not automatically resubmit when false.
refundStatusrefunded, pending (an automatic refund is still being retried), or not_required (free previews and jobs that did not fail).
needsReconciliationWhen 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 resolutionCredits per second of video
1080p1.0
2k1.6
4k3.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.

ScopeLimit
Uploads (presigned or confirm)30 / hour each
Uploads via source_url10 / hour
Job creation45 / 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.

HTTPCodeMeaning
400INVALID_JSON, INVALID_INPUT, INVALID_IDEMPOTENCY_KEY, INVALID_SOURCE_URL, UNSUPPORTED_TARGET_RESOLUTIONThe request syntax, fields, ID, query, URL, target resolution, or idempotency header is invalid.
400UNSUPPORTED_FILE_EXTENSION, UNSUPPORTED_FILE_TYPE, FILE_TYPE_EXTENSION_MISMATCHThe declared filename and MIME type are unsupported or do not match.
400FILE_SIZE_REQUIRED, FILE_SIZE_UNVERIFIED, FILE_SIZE_MISMATCH, FILE_TYPE_UNVERIFIED, FILE_TYPE_MISMATCH, FILE_NOT_FOUND, INVALID_OBJECT_KEY, UPLOAD_NOT_READYThe stored upload could not be verified or is not ready for processing.
401MISSING_API_KEY, INVALID_API_KEY, KEY_EXPIRED, PREVIEW_LOGIN_REQUIREDMissing, wrong or revoked key, or preview access requires a registered account.
402INSUFFICIENT_CREDITSNot enough credits for this job.
403API_ACCESS_REQUIRED, INSUFFICIENT_SCOPE, USER_BANNED, FREE_PREVIEW_LIMIT_REACHEDYour plan or key permissions do not include this operation, the account is unavailable, or all five lifetime previews have been completed.
404UPLOAD_NOT_FOUND, JOB_NOT_FOUND, USAGE_NOT_FOUNDResource or billing record does not exist or is not yours.
409METADATA_PENDINGVideo still being analyzed; retry after Retry-After seconds.
409UPLOAD_STATUS_CONFLICT, JOB_ALREADY_CREATING, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_KEY_JOB_DELETED, FREE_PREVIEW_SLOTS_RESERVEDState, idempotency, or in-flight preview reservation conflict.
409CREDIT_COST_EXCEEDS_LIMITThe new job exceeds the requested spending ceiling; no job was created or charged.
405METHOD_NOT_ALLOWEDThe path does not support this HTTP method; the Allow header lists the ones it does.
413FILE_TOO_LARGEVideo exceeds 500 MB.
422VIDEO_TOO_LONGThe source video is longer than 60 seconds; trim it and upload again.
422METADATA_UNAVAILABLE, VIDEO_UNDECODABLE, RESOLUTION_TOO_HIGHThe 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.
422SOURCE_URL_FORBIDDEN, SOURCE_URL_UNRESOLVABLE, SOURCE_URL_TOO_MANY_REDIRECTSThe remote URL is unsafe, cannot resolve, or redirects too many times.
429RATE_LIMIT_EXCEEDEDSlow down; respect Retry-After.
500 / 503INTERNAL_SERVER_ERROR, RUNPOD_FAILED, IDEMPOTENCY_STORAGE_FAILED, SERVER_MISCONFIGURED, SERVICE_UNAVAILABLE, JOB_RECONCILIATION_REQUIREDTemporary server or processing backend failure. Reconciliation-required jobs retain their charge and must not be resubmitted.
502 / 504SOURCE_FETCH_FAILED, SOURCE_FETCH_TIMEOUTWe couldn't download your source_url.