API reference & migration guide

Request parameters, response formats and migration differences for the remove.bg-compatible HD API.

POST https://removebgtool.net/v1.0/removebg

curl --fail-with-body --max-time 180 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'image_file=@image.jpg' \
  -F 'size=auto' \
  'https://removebgtool.net/v1.0/removebg' -o no-bg.png

Request

Send X-API-Key. Use multipart/form-data for image_file; JSON or URL-encoded bodies accept image_url or image_file_b64. Supply exactly one image source. crop defaults to false; format defaults to auto (PNG for transparency, JPG for opaque results). bg_color accepts CSS color names or 3/4/6/8-digit hex. JPG flattens transparency onto white.

curl --fail-with-body --max-time 180 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'image_url=https://example.com/photo.jpg' \
  -F 'format=png' \
  'https://removebgtool.net/v1.0/removebg' -o result.png

# JSON input and JSON output
curl --fail-with-body --max-time 180 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '{"image_file_b64":"YOUR_PADDED_BASE64","format":"png"}' \
  'https://removebgtool.net/v1.0/removebg'

import requests

with open('image.jpg', 'rb') as image:
    response = requests.post(
        'https://removebgtool.net/v1.0/removebg',
        headers={'X-API-Key': 'YOUR_API_KEY'},
        files={'image_file': image},
        data={'size': 'auto'},
        timeout=180,
    )
response.raise_for_status()
with open('no-bg.png', 'wb') as output:
    output.write(response.content)

import { readFile, writeFile } from 'node:fs/promises';

const form = new FormData();
form.append('image_file', new Blob([await readFile('image.jpg')]), 'image.jpg');
form.append('size', 'auto');
const response = await fetch('https://removebgtool.net/v1.0/removebg', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: form,
  signal: AbortSignal.timeout(180000),
});
if (!response.ok) throw new Error(await response.text());
await writeFile('no-bg.png', Buffer.from(await response.arrayBuffer()));

Response

HTTP 200 returns the image bytes. Use Accept: application/json for data.result_b64 and image dimensions. Headers include X-Width, X-Height, X-Credits-Charged, X-Foreground-Top/Left/Width/Height and X-Request-ID. Foreground coordinates refer to the normalized input canvas. Classification and X-Type are not provided. GET /v1.0/account returns data.attributes.credits and api.free_calls (0).

{
  "data": {
    "result_b64": "...",
    "result_width": 625,
    "result_height": 400,
    "credits_charged": 1
  }
}

Limits & differences

Input: ≤22 MB, ≤50 MP, each dimension 33–9999 pixels, single-frame JPG/PNG/WebP. HTTPS URLs must be public, direct and use port 443; redirects and private networks are rejected. size defaults to preview (0.25 MP); medium=1.5 MP, hd=4 MP, full/4k/auto=25 MP, 50MP=50 MP. PNG and auto are capped at 10 MP. Output never upscales. Unlike remove.bg, auto does not select a size based on your balance.

API calls use your existing credits. The current per-image charge appears in your dashboard and in X-Credits-Charged. Preview uses the same charge as full resolution. No separate free monthly API allowance is included.

Errors & retries

400 invalid input or unsupported parameters · 402 insufficient credits · 403 invalid key or plan · 409 idempotency conflict/in-progress/expired · 415 unsupported request encoding · 429 rate limit · 502/503 upstream failure or busy · 504 timeout. Follow Retry-After on 429/503. Use exponential backoff for transient 5xx errors. Keep keys on your server.

{
  "errors": [
    {
      "title": "Insufficient credits.",
      "code": "insufficient_credits"
    }
  ]
}

Optional Idempotency-Key: reuse the same key, image and parameters to replay a successful result for 10 minutes without another charge. A replay repeats the original X-Credits-Charged and adds X-Idempotent-Replayed: true. In-progress requests return 409. Failed or expired keys remain reserved: use a new key to start a new billable request. Without this header, each request is independent. Allow a client timeout of 180 seconds.

Migration checklist

1. Create a new key on an API-enabled plan. 2. Replace the domain, retaining /v1.0/removebg. 3. Check input limits and unsupported parameters. 4. Test your normal images, error handling and billing. 5. Switch production traffic. This service is independent of remove.bg.View migration guide →

A compatible interface does not mean identical AI results. Test your own images before migrating.