VanceAI Open API documentation

The API exposes VanceAI's processing engine through a small, stable set of REST endpoints. You submit a job with a file or a URL, poll for completion, and download the result. Both image and video tools live under the same /v1/jobs resource: the tool you pick determines the media type and the operation.

All API requests are made to:

https://cloud-vanceai.vanceai.com/api/v1

Every response is application/json. All requests must be authenticated with an API key. See Authentication.

The API is fully asynchronous and built around three steps:

POST /v1/jobs            → returns a job_id immediately (status: "queued")
GET  /v1/jobs/{id}       → poll until status is "succeeded" or "failed"
GET  /v1/jobs/{id}/result → fetch a fresh, never-expiring download link

A POST never blocks while uploading or processing. It validates your request, reserves the job, and returns a job_id in milliseconds. A background worker then handles the upload, processing, and result, so even multi-gigabyte videos work without hitting HTTP timeouts.

• Authentication: get and use your API key.
• Quickstart: your first job in a few minutes.
• Jobs & lifecycle: the full endpoint reference.

Keys look like this and always start with the sk_live_ prefix:

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Create and revoke keys from your VanceAI account dashboard. The full key is shown only once, at creation time. Store it somewhere safe. If you lose it, revoke the key and create a new one. See Managing API keys.

Send your key in the Authorization header as a bearer token on every request:

Authorization: Bearer sk_live_a1b2c3d4e5f6...

For example, to check your credit balance:

curl https://cloud-vanceai.vanceai.com/api/v1/credits \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6..."

A missing, malformed, or revoked key returns 401 with a stable error code:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been disabled.",
    "type": "auth"
  }
}

See Errors for the full list of codes and how to handle them.

Send the image as multipart form data, along with the tool and its config. You can upload a file directly (up to 200 MB) or pass a public image_url instead.

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -F [email protected] \
  -F tool=upscale \
  -F 'config={"scale":4,"face_enhance":true}' \
  -F output_format=jpg

Or submit a URL with a JSON body:

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "tool": "upscale",
    "config": { "scale": 4, "face_enhance": true },
    "output_format": "jpg"
  }'

The response returns immediately with a job_id and a queued status:

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "upscale",
  "media": "image",
  "credits_estimated": 1.0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

Poll GET /v1/jobs/{job_id} until status becomes succeeded (or failed). For images, polling every ~2 seconds is plenty.

curl https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c... \
  -H "Authorization: Bearer sk_live_..."

{
  "job_id": "job_3f2a9c...",
  "status": "succeeded",
  "progress": 100,
  "tool": "upscale",
  "result_url": "https://.../preview?sign=...",
  "result": { "width": 4000, "height": 3000, "size": 2451234 },
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": "2026-06-11T08:30:42Z"
}

The result_url from step 2 is a signed link that eventually expires. For a link that never expires, call the result endpoint, which re-signs on demand:

curl -L https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c.../result \
  -H "Authorization: Bearer sk_live_..." \
  -o upscaled.jpg

Every job moves through these statuses:

While processing, the phase field narrows it down: uploading → syncing → processing. The numeric progress (0–100) is only meaningful once phase is processing; during upload/sync it stays 0. For large videos the upload phase can take minutes, so judge "is it stuck?" from phase, not progress.

Videos are uploaded directly to storage in two steps, so the bytes never pass through the API and multi-gigabyte files aren't limited by request size. First call POST /v1/uploads to get a one-time presigned upload URL, then PUT the file to it. Images skip this — upload them inline when you create the job (see below). Direct video multipart upload is not supported; source_url is still accepted as an alternative.

Request parameters

Example

curl https://cloud-vanceai.vanceai.com/api/v1/uploads \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "clip.mp4",
    "file_size": 734003200,
    "content_type": "video/mp4"
  }'

Response — 201 Created

{
  "upload_id": "upl_8f3b1c2a...",
  "put_url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
  "expires_at": "2026-06-13T08:30:00Z",
  "max_bytes": 5261334937
}

put_url is a presigned URL valid for 24 hours. Upload the raw bytes to it with a single PUT — no auth header, just the file:

curl -X PUT --upload-file clip.mp4 \
  -H "Content-Type: video/mp4" \
  "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=..."

Once the PUT succeeds, create the job by passing the upload_id instead of a file — see Create a job. Each upload_id is single-use.

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "upl_8f3b1c2a...",
    "tool": "video_upscale",
    "config": { "scale": 2, "codec": "h264" }
  }'

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "video_upscale",
  "media": "video",
  "credits_estimated": 0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

How you provide the media depends on the type. Images: a direct file upload (multipart) or a public URL. Videos: an upload_id from the upload step above, or a public source_url. The tool selects the media type and operation.

Request parameters

Idempotency

Pass an Idempotency-Key header to safely retry a create request without duplicating the job. See Rate limits & idempotency.

Example

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: a-unique-string" \
  -F [email protected] \
  -F tool=upscale \
  -F 'config={"scale":4,"face_enhance":true}'

Response: 202 Accepted

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "upscale",
  "media": "image",
  "credits_estimated": 1.0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

The response returns before any credits are charged (credits_charged is 0). credits_estimated is a pre-flight estimate; the authoritative charge appears once the job reaches processing. See Credits & billing.

Returns the current status of a job. Poll this until the job reaches a terminal status.

Response: 200 (processing)

{
  "job_id": "job_3f2a9c...",
  "status": "processing",
  "phase": "uploading",
  "progress": 0,
  "tool": "video_upscale",
  "media": "video",
  "result_url": null,
  "result": null,
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": null
}

Response: 200 (succeeded)

{
  "job_id": "job_3f2a9c...",
  "status": "succeeded",
  "progress": 100,
  "tool": "upscale",
  "result_url": "https://.../preview?sign=...",
  "result": { "width": 4000, "height": 3000, "size": 2451234 },
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": "2026-06-11T08:30:42Z"
}

The result shape is { width, height, size } for images and { width, height, duration, size, codec } for video. The result_url is a signed link that will expire. For a permanent link, use the result endpoint below.

Redirects (302) to a freshly signed result URL, re-signed on every call, so the link never goes stale. Use this whenever you need to download the output, rather than caching result_url.

curl -L https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c.../result \
  -H "Authorization: Bearer sk_live_..." \
  -o result.jpg

Cancels a job that is still queued or processing. Mainly useful for long-running video jobs. Any reserved credits are refunded in full.

{ "job_id": "job_3f2a9c...", "status": "canceled" }

A job that has already succeeded, failed, or been canceled returns 409 not_cancelable.

Deletes a job record and its associated result: useful for cleaning up processed assets for privacy or compliance. If the job is still in progress, it is canceled (and credits refunded) first.

{ "job_id": "job_3f2a9c...", "deleted": true }

• Deleting an already-deleted job still returns 200 { "deleted": true } (idempotent).
• You can only delete jobs that belong to your own account; others return 404 job_not_found.

Image tools take a config object. The face_enhance option (boolean) is optional on most tools. Set output_format on the request to choose jpg / png / webp.

{ "scale": 4, "face_enhance": true }

Video tools are processed end to end (no preview-clip mode in v1). The quality (high / medium / low) and codec (h264 / h265) options apply to video_hdr and video_face_enhance only. For video_upscale the output encoding is determined by the upscaler engine, so quality / codec are not used (sending them has no effect).

{ "scale": 2 }

Requesting a tool that doesn't exist, or one that isn't available yet (the video translate, colorize, and subtitle operations are not in v1), returns 400 unsupported_tool.

The credit flow over a job's lifetime:

curl https://cloud-vanceai.vanceai.com/api/v1/credits \
  -H "Authorization: Bearer sk_live_..."

{ "balance": 999.8, "used": 234.2, "frozen": 12.5 }

Credit amounts are decimals (some operations cost a fraction of a credit).

Each API key has a request-rate limit. Exceeding it returns 429 rate_limited with headers describing your current window:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718093460

Responses may also include a Retry-After header (seconds); respect it before retrying.

Because a single video job can run for many minutes, request-rate alone isn't enough. There is also a cap on the number of jobs your account can have in flight (queued or processing) at once, typically lower for video than for images.

Submitting beyond the cap returns 429 concurrency_limit_exceeded. Wait for some in-flight jobs to finish, then retry. The count is aggregated per account, so spreading work across multiple keys does not bypass it.

v1 has no webhooks, so you poll GET /v1/jobs/{id}. To avoid hammering the API:

• Suggested interval: about 2s for images, 5–10s for video.
• Respect the Retry-After header when present; it's a hint for the next poll.
• Stop polling once the job reaches a terminal status (succeeded / failed / canceled).

Network blips can leave you unsure whether a POST /v1/jobs succeeded. To retry safely, send a unique Idempotency-Key header:

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 8f3b1c2a-...-unique" \
  -F [email protected] \
  -F tool=upscale

• Replaying the same key returns the original job: no duplicate job, no double charge.
• Generate one fresh key per logical request (a UUID works well).
• Reusing a key with a different tool or config returns 409 idempotency_conflict.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account does not have enough credits for this operation.",
    "type": "billing"
  }
}

code is a stable string, so branch on it. message is human-readable and may change. type is the broad category: auth, billing, validation, processing, rate_limit, or server.

When a request is rejected outright, you get the matching HTTP status and an error body:

When a job fails *asynchronously*, polling GET /v1/jobs/{id} returns HTTP 200 with status: "failed" and a code in error.code. Don't expect a 5xx for a failed job: the query itself succeeded.

In your dashboard, create a new key and give it a recognizable name (for example my-app-prod). The full secret (starting with sk_live_) is shown only once, right after creation.

The dashboard lists your keys by name, status, a short prefix (e.g. sk_live_a1b2) for identification, and the time each key was last used. The full secret is never displayed again, only the prefix.

Disabling a key takes effect immediately: any further request with it returns 401 invalid_api_key.

• Revocation is permanent. There is no re-enable; create a new key instead.
• You can only manage keys that belong to your own account.

Multiple active keys can coexist, which makes rotation seamless: create a new key, switch your application to it, confirm traffic has moved over, then revoke the old key. Using a distinct key per application or environment limits the blast radius if one is ever leaked.

The first stable version includes:

• Unified jobs API for both image and video: POST /v1/jobs, GET /v1/jobs/{id}, GET /v1/jobs/{id}/result, POST /v1/jobs/{id}/cancel, DELETE /v1/jobs/{id}, and GET /v1/credits.
• 8 image tools and 3 video tools (upscale, HDR, face enhancement).
• Large files: image direct uploads up to 200 MB; videos via two-phase direct upload; any media via source_url (SSRF-protected).
• Asynchronous processing with a pre-flight credit check and a background worker.
• Credit reservations with full refund on failure or cancellation.
• Stable error codes, Idempotency-Key support, per-key rate limits and per-account concurrency limits.
• Video two-phase direct upload — POST /v1/uploads issues a presigned URL so videos upload straight to storage (single PUT up to ~4.9 GB), bypassing the request-size limit.
• Accurate video billing — the server measures resolution, duration and frame rate with ffprobe, and pre-checks output resolution against the engine limit.