remove.bg API Migration Guide

1

Read this first

The four things that are not the same.

size defaults to preview, as on remove.bg — but here preview is a free, watermarked image up to 640 px (remove.bg: 0.25 megapixels without watermark). An integration that never sets size will get watermarked previews; pass size=auto or a paid tier for the watermark-free result.
We do not claim SDK-level compatibility. Three third-party clients — the PyPI removebg package, the official npm remove.bg package and removebg-cli — passed our tests on 22 September 2026, but we do not regression-test them release by release; hand-written HTTP clients are the path we support.
shadow_type, shadow_opacity, add_shadow and semitransparency are accepted and validated but never change the output — as on remove.bg for non-car subjects; there is no car-specific model.
Each call counts as one image against your key's limit of 40 images per minute — remove.bg allows 500. Handle 429 with Retry-After, or contact us to raise the limit.

2

Before and after

The same request against each service.

remove.bg

1curl -X POST "https://api.remove.bg/v1.0/removebg" \2  -H "X-Api-Key: REMOVEBG_KEY" \3  -F "[email protected]" \4  -F "size=auto" \5  -o out.png

PixMiller

1curl -X POST "https://api.pixmiller.com/v1.0/removebg" \2  -H "X-Api-Key: PIXMILLER_KEY" \3  -F "[email protected]" \4  -F "size=auto" \5  -o out.png6# 200 OK → image bytes, written straight to out.png7# X-Credits-Charged: 1   X-Width: 1200   X-Height: 1600   X-Type: product

3

Parameter support

Parameter	Status	Notes
`image_file`	Same	Multipart upload. JPG / PNG / WebP, up to 20 MB (remove.bg: 22 MB).
`image_url`	Same	Public image URL, fetched on our side with the same 20 MB limit.
`image_file_b64`	Same	Base64-encoded image in the request body, same as remove.bg.
`size`	Differs	Same values, same default (preview) and same megapixel caps — but preview is a free watermarked image up to 640 px, not 0.25 MP without watermark. medium / hd / 4k / full / 50MP cost 1 credit each; auto uses the paid tier while credits remain.
`format`	Same	auto / png / jpg / webp / zip — zip contains color.jpg and alpha.png as on remove.bg. Accept: application/json returns the base64 envelope. PNG output is capped at 10 megapixels.
`type, type_level`	Differs	Accepted; type is mapped onto our own models. X-Type reports a coarse class — person, product, animal, car or other — and type_level=2 / latest return the same coarse classes.
`crop, crop_margin`	Same	Crops to the subject with the same margin syntax and the same 50% / 500 px cap.
`roi`	Same	Region of interest in pixels or percent, as on remove.bg.
`scale, position`	Same	Subject scale (10%–100% or original) and position, as on remove.bg.
`channels`	Same	rgba (default) or alpha for the mask only.
`bg_color`	Same	Transparent by default; 3 / 4 / 6 / 8-digit hex with or without #, or a colour name.
`bg_image_file, bg_image_url`	Same	Scaled to cover the output and centred; cannot be combined with bg_color.
`add_shadow, shadow_type, shadow_opacity`	No effect	Validated against remove.bg's values, but no shadow is ever rendered.
`semitransparency`	No effect	Accepted; semi-transparent areas are always handled automatically.

Every parameter is validated with remove.bg's own value ranges, so an invalid value is a 400 invalid_parameter rather than silently ignored — exactly as remove.bg answers.

4

What behaves differently

Status code 200 OK with the image bytes, the same as remove.bg — code that asserts == 200 keeps working. (PixMiller's own /api/v1/remove endpoint answers 201 with JSON; this compatibility path deliberately does not.)

Response body The image bytes, exactly like remove.bg. Send Accept: application/json to get remove.bg's base64 envelope instead, or format=zip for color.jpg plus alpha.png.

Response headers X-Credits-Charged, X-Width, X-Height, X-Type, X-Foreground-Top / -Left / -Width / -Height and X-RateLimit-Limit / -Remaining / -Reset are all returned. X-Type is a coarse class (person / product / animal / car / other) rather than remove.bg's finer vocabulary.

Errors Errors use remove.bg's JSON:API shape: {"errors":[{"title":"…","code":"…"}]} — an array, so errors[0].title reads the same as it did before. A missing key is 403 auth_failed and a wrong one 403 invalid_api_key, an empty balance is 402, throttling is 429.

Credits preview is free; every paid tier costs 1 credit per image, charged only after the result has been fetched, so a failed call never costs a credit. There is no monthly free quota.

Rate limit 40 images per minute per key (remove.bg: 500). Each call counts as one image, and X-RateLimit-Limit / -Remaining / -Reset report that per-image budget; handle 429 with Retry-After.

5

Checking your balance

The account endpoint reports the key's remaining credit balance under data.attributes.credits, so a balance check written against remove.bg keeps its shape. There is no monthly free quota, so free_calls is always 0.

GET /v1.0/account

1curl "https://api.pixmiller.com/v1.0/account" \2  -H "X-Api-Key: PIXMILLER_KEY"

6

Errors

400 invalid_parameter A value outside remove.bg's range for size / format / crop / scale / … or a missing image source; the title names the parameter.

400 file_too_large The input image exceeds 20 MB.

400 unknown_foreground No foreground could be found in the image.

402 insufficient_credits A paid tier was requested but the balance is empty. Nothing is charged.

403 auth_failed / invalid_api_key The X-Api-Key header is missing (auth_failed) or wrong (invalid_api_key) — 403 as on remove.bg, not 401.

429 rate_limit_exceeded Rate limit exceeded. Retry after the Retry-After header.

502 result_fetch_failed The result could not be fetched from storage. Nothing was charged — retry the request.

The status code carries the meaning, and code uses remove.bg's own vocabulary — a switch on errors[0].code keeps working.

remove.bg Alternative Contact us