Background Removal API Documentation

Create and manage your key

Sign in on the homepage, open your account panel and choose Create key. The complete secret is shown once. Reset key replaces it immediately; Revoke key disables it without issuing another. Store the secret in your server environment or secret manager.

The /api/v1 endpoints require an API key even if you have a browser session. Anonymous website trials do not provide free API credits. Add account credits before submitting images. Cross-origin browser requests are not supported.

• Open RemoveBGKit
• Current plans and credits

Endpoints

Paths below are relative to the base URL. All JSON errors contain ok: false, a machine-readable code and an error message.

• OpenAPI JSON

1. Submit an image

Use multipart/form-data with the image file in the image field. Let your HTTP client set the multipart boundary. The mode and quality fields below select a single photo cutout.

export RMBG_API_KEY='YOUR_PRIVATE_KEY'
# Generate once for this image. Keep this value for retries.
export RMBG_REQUEST_ID="$(uuidgen)"

curl --fail-with-body -i https://removebgkit.com/api/v1/process \
  -H "X-API-Key: $RMBG_API_KEY" \
  -H "Idempotency-Key: $RMBG_REQUEST_ID" \
  -F 'image=@./product.png' \
  -F 'mode=generic' \
  -F 'quality=fast'

2. Poll, then download

A new task returns 202 with taskId, status, statusUrl, pollAfterMs, createdAt and expiresAt. Times are Unix seconds. Follow statusUrl using the website origin, not by appending it to /api/v1 again. Active tasks also send Location and Retry-After: 2 headers.

Poll while status is pending or running. Completed tasks return 200 and include mattePreviewUrl, icons[].url, zipUrl, zipName and count. Download the returned URLs with the same account key. They are private, temporary URLs, not share links. Use icons[].url for individual PNGs and zipUrl for the archive.

# Replace TASK_ID with the taskId returned by the upload.
curl --fail-with-body https://removebgkit.com/api/v1/tasks/TASK_ID \
  -H "X-API-Key: $RMBG_API_KEY"

# After status=completed, use the returned zipUrl or icons[].url.
# RESULT_PATH is an origin-relative path beginning /api/v1/results/.
curl --fail-with-body "https://removebgkit.com$RESULT_PATH" \
  -H "X-API-Key: $RMBG_API_KEY" \
  -o result.zip

Complete Node.js example

This TypeScript example uploads, polls and downloads a ZIP. It retries network failures and selected temporary HTTP errors with the same request ID, checks returned URLs before sending credentials and has a 15-minute deadline. Run it with Node.js 22.18 or newer.

Keep RMBG_REQUEST_ID unchanged when restarting after an uncertain upload or timeout. For a different image or changed settings, generate a new ID. The command uses generic mode and fast quality; imported callers can also select auto, iconSheet, portrait or pro through its options.

curl --fail-with-body \
  https://removebgkit.com/static/examples/remove-background.mts \
  -o remove-background.mts

# Node.js 22.18+; no npm packages required.
export RMBG_API_KEY='YOUR_PRIVATE_KEY'
export RMBG_REQUEST_ID="$(uuidgen)"
node remove-background.mts ./product.png ./result.zip

• Download the complete TypeScript example

Processing options

auto chooses between general removal and the green-background icon path. generic processes one photograph or logo. iconSheet extracts separate components from a green-background icon sheet; it is not a general grid slicer. Small pixel sprites need a different workflow.

Quality applies to the general image path. fast uses the general model, portrait targets people and pro uses BiRefNet HR matting. Evaluate each on representative inputs; model choice is not a quality or completion-time guarantee.

Legacy fields inset, radiusRatio, maskFeather and aaScale are accepted and validated for compatibility but currently have no processing effect. Omit them in new integrations. Their values still participate in the request fingerprint, so changing them requires a new Idempotency-Key.

Limits, billing and retention

Current limits: 18 MiB image file, 20 MiB whole multipart request, 24 million pixels, and no dimension above 8,000 pixels. PNG, JPEG, WebP and GIF inputs are accepted; output is PNG/ZIP, not an animated GIF. Upload throttling is 20 requests per 60-second window per IP, including retries.

GET /account returns balance, reserved, available and costPerImage inside credits, plus live limits, resultsTTLSeconds and rateLimit. Every task reserves 5 credits before queuing. Success consumes the reservation once; terminal failure releases it. One icon sheet is one input image, even if it produces several icons.

expiresAt is measured from submission, not from completion or the last download. Store results before that deadline. There is no bulk upload endpoint, public webhook callback, hosted image-URL input or official SDK in this API version.

curl --fail-with-body https://removebgkit.com/api/v1/account \
  -H "X-API-Key: $RMBG_API_KEY"

• Current plans and credits

Idempotency and error recovery

Send a unique Idempotency-Key for each logical submission: 1-128 letters, numbers, dots, underscores, colons or hyphens. The key is scoped to your account. Identical file bytes and normalized processing options return the existing task, including after credits were consumed. Replays include Idempotency-Replayed: true. Filenames and multipart boundaries do not change the fingerprint.

Reusing a key with different bytes or settings returns 409. A retained expired task returns 410; after cleanup that key can be accepted again, so never intentionally reuse old keys for new work. Retry protection lasts for the task retention period, not forever. A failed task remains failed on replay; fix the cause and use a new key to start another task.

Integration guides

Start with the end-to-end tutorial, or compare the request and response changes before moving from remove.bg.

• Background removal API: a reliable upload-to-download workflow
• remove.bg API alternative: migration checklist