API Documentation

Quickstart

Your first request only needs input.image_base64. Omit input.output to keep the original-size transparent output used by existing clients.

curl --request POST   --url https://removezero.com/api/v1/remove-background   --header "Authorization: Bearer ${REMOVEZERO_API_KEY}"   --header "Content-Type: application/json"   --header "Idempotency-Key: image-2026-08-28-0001"   --data '{"input":{"image_base64":"BASE64_IMAGE_DATA"}}'

Authenticate with a Bearer key

Create an API Key from Personal, then send it in the Authorization header for every request.

Authorization: Bearer rz_live_your_api_key

• Keep keys in a server environment variable or secret manager.
• Never place a key in browser code, mobile bundles, extensions, URLs, public repositories, or logs.
• Use separate keys for separate services or environments when practical.
• Revoke and replace a key immediately if it may have been exposed.

Call the API from your server

Use the path browser or client → your server → RemoveZero API. The Bearer key can authorize paid processing, so a public client cannot keep it secret. Paid server requests must omit the Origin header.

Send a background removal request

Send one strict JSON request from your server. Required headers are validated before Credit reservation or image processing.

POST https://removezero.com/api/v1/remove-background
Authorization: Bearer rz_live_your_api_key
Content-Type: application/json
Idempotency-Key: order-2026-08-25-0001

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA"
  }
}

• Content-Type must be application/json; a charset parameter is allowed.
• Content-Encoding must be omitted or identity; compressed request bodies are rejected.
• Do not send an Origin header.
• Idempotency-Key must be 1–128 characters using letters, numbers, periods, underscores, colons, or hyphens.
• image_base64 must contain standard Base64 image bytes without a data:image/... prefix.

Customize the output

The input.output object is optional. It changes the canvas after the same single background-removal inference, so customization does not use another Credit.

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA",
    "output": {
      "format": "webp",
      "background": "#ffffff",
      "width": 1600,
      "height": 1600,
      "padding_ratio": 0.08
    }
  }
}

Fixed contain + center behavior

Fit is not a request field. RemoveZero always preserves the subject’s aspect ratio and fits it inside the available canvas.

• The complete subject remains visible and centered.
• The subject is not cropped or stretched.
• Remaining canvas space uses transparency or the requested color.
• Cover, smart crop, gravity positions, and arbitrary coordinates are not supported.

Backward compatibility

Existing clients can omit input.output and keep sending only input.image_base64. Add output only when you need a custom format, background, canvas, or padding.

Successful response

A successful image returns HTTP 200 and uses 1 Credit. The output includes the exact content type and canvas dimensions, plus Base64 data your server can decode.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "id": "REQUEST_ID",
  "status": "COMPLETED",
  "output": {
    "ok": true,
    "content_type": "image/webp",
    "width": 1600,
    "height": 1600,
    "output_base64": "BASE64_IMAGE_RESULT"
  },
  "usage": {
    "units": 1,
    "credits_used": 1
  }
}

Decode the result

1. Confirm HTTP 200, ok: true, and status: COMPLETED.
2. Read output.content_type and accept only image/png or image/webp.
3. Decode output.output_base64 once and save the bytes with the matching extension.
4. When dimensions were requested, verify output.width and output.height.

The result is returned inline, not as a permanent URL. Save the decoded bytes in your own application if you need to keep or deliver the image.

import { writeFile } from "node:fs/promises";

const payload = await response.json();

if (!response.ok || payload.ok !== true || payload.status !== "COMPLETED") {
  throw new Error(payload.error?.code ?? "REMOVEZERO_REQUEST_FAILED");
}

const { content_type: type, output_base64: base64 } = payload.output ?? {};
const extension = type === "image/png" ? "png" : type === "image/webp" ? "webp" : null;

if (!extension || typeof base64 !== "string") {
  throw new Error("REMOVEZERO_OUTPUT_INVALID");
}

await writeFile(`removezero-result.${extension}`, Buffer.from(base64, "base64"));

Billing and Credit returns

Each request processes one image. RemoveZero validates the request, atomically reserves 1 Credit, and settles it only after both background removal and the requested output succeed. Output customization never adds another inference or Credit.

Credit lifecycle

If the request or its return cannot be verified yet, the API returns REFUND_PENDING with the request ID and Retry-After: 30. Keep the same Idempotency-Key and do not submit the same image with a new key.

HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "REFUND_PENDING"
  },
  "request_id": "REQUEST_ID"
}

Idempotency and retries

Idempotency-Key binds the exact serialized JSON body, including the image and every supplied output field. Preserve the original request bytes as well as the key.

• Same key and exact same body: safe retry without a second reservation or processing request.
• Same key and changed body: 409 IDEMPOTENCY_CONFLICT.
• Same key after a terminal request: 409 IDEMPOTENCY_REPLAY_UNAVAILABLE; completed Base64 results are not stored for replay.
• New key: a new request that may reserve another Credit.
• A semantically equal JSON body may still differ if whitespace, property order, or explicit defaults change.

Retry-After guidance

429 RATE_LIMITED

Wait 60 seconds, then retry the exact body with the same key.

503 REFUND_PENDING

Wait 30 seconds, then retry the exact body with the same key.

503 UPSTREAM_BUSY

Wait 10 seconds. Use a new key only for an intentional new attempt.

Network timeout or API_UNAVAILABLE

Treat the outcome as unknown and keep the original body and key until resolved.

Examples

Replace the placeholders on your server. The API key must never be exposed in a public browser bundle.

curl --request POST \
  --url https://removezero.com/api/v1/remove-background \
  --header 'Authorization: Bearer rz_live_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-08-25-0001' \
  --data '{"input":{"image_base64":"BASE64_IMAGE_DATA","output":{"format":"webp","background":"#ffffff","width":1600,"height":1600,"padding_ratio":0.08}}}'

Common output starting points

These recipes are starting points, not permanent marketplace or category compliance guarantees. Platform names are labels, not API enum values.

{"format":"png","background":"transparent","width":1600,"height":1600,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1600,"height":2000,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1500,"height":2000,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":1920,"height":1080,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":2000,"height":2000,"padding_ratio":0.075}

{"format":"webp","background":"#ffffff","width":2048,"height":2048,"padding_ratio":0.08}

Errors and troubleshooting

Errors use a stable HTTP status and a short code in the JSON response.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE"
  }
}

Safe troubleshooting

1. Record the HTTP status, error code, request_id when present, timestamp, and your Idempotency-Key.
2. Never log or send the Bearer key, complete image_base64, or a complete response containing image data.
3. Correct 4xx request, credential, balance, or header errors before trying again.
4. Honor Retry-After and preserve the original body and key for unresolved requests.
5. Contact support with non-secret identifiers if an unresolved state persists.

Request limits

Send one JPG, PNG, or WebP image per request as standard Base64. The decoded input may be at most 5 MiB and the complete JSON body at most 7,500,000 bytes. Custom output is limited to 4,096 px per side and 4,194,304 pixels. If an exact requested result cannot fit the inline response limit, processing fails and the reserved Credit is returned; the API never silently changes the requested size or format.