Background Removal API
Add background removal to your app, shop or workflow with a few lines of code. Compatible with the remove.bg API.
Quick start
Create an API key in your account and send your first request:
Authentication
Send your API key in the X-Api-Key header with every request. Create and revoke keys in your account.
X-Api-Key: bg_xxxxxxxxxxxxxxxxxxxxxxxx
POST/v1.0/removebg
Removes the background of an image. The body can be multipart/form-data, application/x-www-form-urlencoded or application/json. Provide exactly one source: image_file, image_file_b64 or image_url.
| Parameter | Description |
|---|---|
| image_file | Image file to upload (JPG, PNG, WebP…; max 20 MB). |
| image_file_b64 | Base64-encoded image. |
| image_url | URL of the image to download. |
| size | preview · small · regular · medium · hd · 4k · full · 50mp · auto (default). auto: full resolution if you have credits, otherwise preview. |
| format | auto (default: PNG if transparent, else JPG) · png · jpg · webp. |
| bg_color | Background color: hex (81d4fa, #fff) or a color name (white). Transparent if omitted. |
| bg_image_url / bg_image_file | Image to use as background (URL or file), placed behind the subject with “cover” fit. |
| crop | If true, empty space around the subject is cropped away. |
| crop_margin | Crop margin: 30px or 10% (max 500px / 50%). |
| add_shadow | If true, a soft drop shadow is added under the subject. |
| channels | rgba (default) or alpha (grayscale mask only). |
| model | fast (default, ~3 s) or hd (sharper edges, ~40 s). bgless extension. |
Response
A successful response is the image itself (image/png, image/jpeg or image/webp) with these headers:
| X-Credits-Charged | Credits charged for this request (e.g. 1, 0.25, 0). |
| X-Width, X-Height | Size of the result image. |
| X-Foreground-Top/Left/Width/Height | Position and size of the subject within the result (pixels). |
Send Accept: application/json to receive the image base64-encoded in JSON:
{"data": {"result_b64": "iVBORw0KGgo…", "foreground_top": 120, "foreground_left": 45,
"foreground_width": 519, "foreground_height": 288}}
GET/v1.0/account
Returns your credit balance and the free API previews left this month. Free of charge.
{"data": {"attributes": {
"credits": {"total": 42.5, "subscription": 0, "payg": 42.5, "enterprise": 0},
"api": {"free_calls": 47, "sizes": "all"}
}}}
Credits & limits
| size | Resolution | Credits |
|---|---|---|
| preview, small, regular | ≤ 0.25 MP | 50 free per month, then 0.25 |
| medium | ≤ 1.5 MP | 1 |
| hd | ≤ 4 MP | 1 |
| 4k | ≤ 10 MP | 1 |
| full, 50mp | ≤ 36 MP | 1 |
| auto | full or preview depending on balance | 0–1 |
Rate limit: 60 requests per minute per API key. Exceeding it returns 429.
Errors
Failed requests return a JSON body with an errors array:
{"errors": [{"title": "Insufficient credits", "code": "insufficient_credits"}]}
| 400 | Invalid parameter, or missing / unreadable image. |
| 402 | Insufficient credits. |
| 403 | Missing or invalid API key. |
| 413 | Image larger than 20 MB. |
| 429 | Rate limit exceeded. |