为你的产品接入背景移除

Public API v1

Use one API key for both video and image background removal. The API is designed for server-to-server calls. Do not expose your key in browser code or public repositories.

Base URL and authentication

Set these placeholders in your server environment:

BASE_URL="https://backgroundremover.video"
API_KEY="<YOUR_API_KEY>"

Every API request requires the Bearer header:

Authorization: Bearer <YOUR_API_KEY>

API keys are account-wide. One key works for both capabilities. Requests are limited to 60 calls per 60 seconds across the key. A rate-limited response includes Retry-After.

Common asynchronous flow

Both capabilities use the same five-step flow:

1. Request a short-lived upload URL.
2. Upload the file with the exact returned PUT headers.
3. Create a task with a UUID Idempotency-Key.
4. Poll the task until status is completed or failed.
5. Download the completed result within 7 days.

The upload URL expires after 15 minutes and can create its object only once. Request a new upload URL if it expires; never reuse an uploadId across accounts or capabilities.

Image background removal

Image inputs support JPEG, PNG, WebP, GIF, and AVIF up to 10 MiB. Every image task costs 1 credit and returns a transparent PNG.

1. Request an image upload

curl --request POST "$BASE_URL/api/v1/image-background-removal/uploads" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "fileName": "<IMAGE_FILE_NAME.jpg>",
    "contentType": "image/jpeg",
    "contentLength": 123456
  }'

Example response:

{
  "uploadId": "<UPLOAD_ID>",
  "method": "PUT",
  "url": "<PRESIGNED_UPLOAD_URL>",
  "headers": {
    "Content-Type": "image/jpeg",
    "Content-Length": "123456",
    "If-None-Match": "*"
  },
  "expiresAt": "<UTC_TIMESTAMP>"
}

2. Upload the image

Send the exact headers returned by the upload request:

curl --request PUT "<PRESIGNED_UPLOAD_URL>" \
  --header "Content-Type: image/jpeg" \
  --header "Content-Length: 123456" \
  --header 'If-None-Match: *' \
  --upload-file "<LOCAL_IMAGE_PATH>"

3. Create the image task

Generate a UUID and reuse it only when retrying the identical request.

curl --request POST "$BASE_URL/api/v1/image-background-removal/tasks" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: <UUID>" \
  --data '{
    "uploadId": "<UPLOAD_ID>",
    "fileName": "<IMAGE_FILE_NAME.jpg>"
  }'

4. Poll the image task

curl "$BASE_URL/api/v1/image-background-removal/tasks/<TASK_ID>" \
  --header "Authorization: Bearer $API_KEY"

An image task includes the server-verified input MIME type and size:

{
  "id": "<TASK_ID>",
  "type": "image_background_removal",
  "status": "processing",
  "stage": "queued",
  "creditAmount": 1,
  "creditsReturned": false,
  "inputContentType": "image/jpeg",
  "inputSize": 123456,
  "createdAt": "<UTC_TIMESTAMP>",
  "expiresAt": null,
  "result": null,
  "error": null
}

5. Download the transparent PNG

curl --location "$BASE_URL/api/v1/image-background-removal/tasks/<TASK_ID>/download" \
  --header "Authorization: Bearer $API_KEY" \
  --output "<OUTPUT_FILE.png>"

Video background removal

Video inputs support MP4, MOV, WebM, M4V, and GIF. Each uploaded video must be shorter than 60 seconds. The server reads the uploaded media duration and charges 1 credit for each started second. There is no additional product-level file-size limit in v1.

1. Request a video upload

curl --request POST "$BASE_URL/api/v1/video-background-removal/uploads" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "fileName": "<VIDEO_FILE_NAME.mp4>",
    "contentType": "video/mp4",
    "contentLength": 12345678
  }'

2. Upload the video

Use the url and exact headers returned by the upload request:

curl --request PUT "<PRESIGNED_UPLOAD_URL>" \
  --header "Content-Type: video/mp4" \
  --header "Content-Length: 12345678" \
  --header 'If-None-Match: *' \
  --upload-file "<LOCAL_VIDEO_PATH>"

The upload route signs an object from fileName, contentType, and contentLength; it does not read the media bytes or determine duration. A signed upload therefore does not mean the video duration is accepted. The task route performs the authoritative duration check after the upload is complete.

3. Create the video task

The defaults are green, mp4_h264, preserveAudio: true, and autoZoom: false. This example requests a transparent WebM result:

curl --request POST "$BASE_URL/api/v1/video-background-removal/tasks" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: <UUID>" \
  --data '{
    "uploadId": "<UPLOAD_ID>",
    "fileName": "<VIDEO_FILE_NAME.mp4>",
    "backgroundColor": "transparent",
    "outputFormat": "webm_vp9",
    "preserveAudio": true,
    "autoZoom": false
  }'

backgroundColor accepts transparent, black, white, gray, red, green, blue, yellow, cyan, magenta, or orange. outputFormat accepts webm_vp9, mp4_h264, mp4_h265, mov_h265, mov_proresks, mkv_h264, mkv_h265, mkv_vp9, or gif. Transparent backgrounds require webm_vp9, mov_proresks, or mkv_vp9.

Do not send a duration, credit amount, provider, model, remote URL, storage key, or user ID. The server determines duration, credits, and ownership.

POST /tasks rejects a server-measured duration of exactly 60 seconds or longer with 400 INVALID_REQUEST and this message: The video must be shorter than 60 seconds. Shorten or split it, upload the new file, and try again. The rejection creates no task and consumes no credits. The uploaded object remains subject to the normal 7-day storage lifecycle, so upload a shortened or split file under a new upload URL before trying again.

4. Poll the video task

curl "$BASE_URL/api/v1/video-background-removal/tasks/<TASK_ID>" \
  --header "Authorization: Bearer $API_KEY"

A video task includes the server-verified duration and processing options:

{
  "id": "<TASK_ID>",
  "type": "video_background_removal",
  "status": "processing",
  "stage": "queued",
  "durationMs": 12500,
  "creditAmount": 13,
  "creditsReturned": false,
  "options": {
    "backgroundColor": "transparent",
    "outputFormat": "webm_vp9",
    "preserveAudio": true,
    "autoZoom": false
  },
  "createdAt": "<UTC_TIMESTAMP>",
  "expiresAt": null,
  "result": null,
  "error": null
}

5. Download the video result

curl --location "$BASE_URL/api/v1/video-background-removal/tasks/<TASK_ID>/download" \
  --header "Authorization: Bearer $API_KEY" \
  --output "<OUTPUT_FILE.webm>"

Video downloads support a single standard Range request. Unsatisfiable or multiple ranges are rejected.

Task status, results, and retention

Task status is processing, completed, or failed. While processing, stage is queued, running, or saving. A completed task provides a download path in result.downloadUrl; a failed task provides a safe product-level error and indicates whether consumed credits were returned.

Uploads and results expire after 7 days. This lifecycle also removes an uploaded video that is rejected when POST /tasks checks its duration. A completed task can become unavailable after its file expires, so copy results to your own storage promptly.

Idempotency

Every task creation request requires an Idempotency-Key containing a UUID. Retrying the same account, capability, key, and canonical JSON request returns the existing task. Reusing the key with different input or options returns 409 IDEMPOTENCY_CONFLICT. Image and video task IDs use separate namespaces.

Credits

• Image background removal costs exactly 1 credit.
• Video background removal costs ceil(durationMs / 1000) credits using the duration measured by the server.
• Task creation returns 402 INSUFFICIENT_CREDITS when the account balance is too low.
• Credits consumed for an eligible terminal processing failure are restored automatically.
• Buying any credit pack enables API key generation; API tasks then use the same account balance as the web product.

Errors

JSON errors use one stable envelope:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request is invalid."
  }
}

HTTP	Code	Meaning
400	INVALID_REQUEST, UNSUPPORTED_MEDIA	Invalid JSON or fields, a video that is not shorter than 60 seconds, or unsupported/unreadable media
401	INVALID_API_KEY	Missing, malformed, reset, or unknown Bearer key
402	INSUFFICIENT_CREDITS	The shared account balance is too low
403	ACCOUNT_NOT_ALLOWED	The account is unavailable, unverified, or banned
404	RESOURCE_NOT_FOUND	The upload or owned task does not exist
409	IDEMPOTENCY_CONFLICT, RESULT_NOT_READY	The UUID conflicts or processing is not complete
410	RESULT_UNAVAILABLE	The result expired or is no longer available
416	RANGE_NOT_SATISFIABLE	A video download range cannot be served
429	RATE_LIMITED	The key exceeded 60 requests in 60 seconds
500	INTERNAL_ERROR	A safe unexpected-error response

The API intentionally does not enable permissive browser CORS. Call it from a trusted server and keep API keys, upload URLs, and signed headers out of logs.