Background removal.
One API key.

Make your first request

1. Request API access and receive an issued pure API key. Keys and credits are provisioned by the provider; applying does not automatically create either.
2. Store your key in a server environment variable named REMOX_API_KEY.
3. Choose a JPG, PNG or static WebP within the size limits below, then run the example.

Never embed your key in a public website or mobile app. Send requests through your own backend. Examples use a 75-second client timeout to allow for the API’s 60-second processing wait.

Authentication

Send X-API-Key: YOUR_REMOX_API_KEY on every request. No Secret is required for this API. Issued keys start with remox_live_ or remox_test_. The prefix alone does not guarantee a sandbox or free processing.

A key identifies its customer and credit balance. Do not send X-Subuid, X-Platform-User or X-RapidAPI-User. Existing Key + Secret credentials cannot be used here. Key rotation preserves the customer identity and balance; a revoked or expired key returns 403.

Code examples

# Set REMOX_API_KEY in your environment first.
curl 'https://api.remox.ai/v1.0/removebg' \
  -H "X-API-Key: $REMOX_API_KEY" \
  -H 'Idempotency-Key: image-0001' \
  -F 'image_file=@/path/to/input.jpg' \
  -F 'size=auto' \
  --max-time 75 --fail-with-body \
  -D response-headers.txt -o remox-result.png
# On non-2xx, the output file contains error JSON, not a PNG.

Examples use input.jpg with MIME image/jpeg. For PNG or WebP, update both the filename and MIME type. Use a unique Idempotency-Key for each new image, and retain it for retries.

Request reference

POST /v1.0/removebg · multipart/form-data. Let your HTTP library set the multipart boundary.

Idempotency-Key is an optional header: 8–128 characters using letters, digits, dots, underscores, colons or hyphens. Strongly recommended for reliable retries. File URLs, Base64 input and object erasure are not supported by this pure-key endpoint.

Successful responses

200 · PNG image (default)

The response body is the PNG itself, with Content-Type: image/png. Write the bytes to a file. Headers include X-Request-ID, X-Task-ID and, on creation, X-Idempotency-Key.

200 · JSON with the original result URL

Add response_format=json to the same multipart request. The API still waits for completion.

curl https://api.remox.ai/v1.0/removebg \
  -H "X-API-Key: $REMOX_API_KEY" \
  -H "Idempotency-Key: image-json-0001" \
  -F "image_file=@input.jpg" -F "size=auto" \
  -F "response_format=json" --max-time 75 --fail-with-body

{
  "requestId": "req_…",
  "taskId": "task_…",
  "data": {
    "result_url": "https://storage.example/result.png?signature=…&expires=…"
  }
}

The URL is returned intact, including its signed query parameters. Its upstream expiry can differ from the Worker’s result expiry. Download promptly. REMOX returns data.result_url, not Base64.

Timeouts, task status & safe retries

The Worker checks the AI task about every 300 ms during the synchronous wait. After up to 60 seconds it returns 504; that does not mean the task failed or was cancelled.

{
  "requestId": "req_…",
  "errors": [
    {
      "code": "sync_timeout",
      "title": "The task is still processing. Query or retry with the same Idempotency-Key."
    }
  ],
  "retryable": true,
  "taskId": "task_…",
  "idempotencyKey": "image-0001"
}

1. If a taskId is available, query GET /v1.0/tasks/{taskId} with the same API key.
2. When status is completed, download GET /v1.0/tasks/{taskId}/result, or add ?response_format=json.
3. If there is no taskId, retry the original POST with exactly the same image bytes and Idempotency-Key. Respect Retry-After when present.

curl https://api.remox.ai/v1.0/tasks/TASK_ID \
  -H "X-API-Key: $REMOX_API_KEY" --fail-with-body

{
  "requestId": "req_…",
  "taskId": "task_…",
  "status": "completed",
  "progress": null,
  "pollAfterMs": 2000,
  "result": {
    "downloadPath": "/v1.0/tasks/task_…/result",
    "mimeType": "image/png",
    "expiresAt": "2026-10-17T00:00:00.000Z"
  }
}

Status values: creating, queued, processing, completed, failed, timed_out. Status reads return 200 even for a failed task; inspect status and the errors array. Follow pollAfterMs (normally 2000 ms) for client status queries. The task reconciliation deadline is 35 minutes.

The same idempotency key and image reuse one task and one charge. Switching between image and JSON does not create another charge. Different image bytes with the same key return 409.

Account, limits & credits

GET /v1.0/account returns customer quota and a credits object. Its available, reserved and consumed fields help you check the current balance. Request, hourly and concurrent-task limits are configured per customer.

curl https://api.remox.ai/v1.0/account \
  -H "X-API-Key: $REMOX_API_KEY" --fail-with-body

Credits are reserved when a task is created, consumed once on success, and released when it fails or reaches its task deadline. A synchronous 504 alone does not release the reservation. Key creation and reading your account do not automatically grant credits. The current cost depends on the provider’s configured credit price.

HTTP status & error codes

Non-2xx API responses contain an errors array with code and title. Use the code for program logic. Keep requestId for troubleshooting; never log your API key.

{
  "requestId": "req_…",
  "retryable": false,
  "errors": [
    {
      "code": "invalid_credentials",
      "title": "Invalid API key."
    }
  ]
}

retryable is true for 429 and 5xx responses. Always combine it with the error code and task state: an uncertain submission must not be retried as a brand-new task. Read Retry-After when supplied.

Compatibility & scope

The image_file + size=auto request and errors array follow familiar remove.bg conventions. This is not a drop-in implementation of all remove.bg options. response_format and data.result_url are REMOX extensions; image_url, result_b64, shadow, refine and background editing parameters are not supported here.

This page documents pure-key background removal only. Website object erasure and the separate Key + Secret / RapidAPI gateway use different routes and contracts.