Familiar /v1.0/removebg request format
If you have existing scripts, cron jobs, or backend services written for common background-removal APIs, migrating should not require rewriting your HTTP client. Cutout Lab's API accepts POST requests to /v1.0/removebg authenticated with an X-Api-Key header.
Send an image using multipart/form-data, application/x-www-form-urlencoded, or application/json with one of three source fields—image_file, image_file_b64, or image_url. The same output parameters apply: size, format, channels, crop, crop_margin, scale, position, roi, bg_color, bg_image_url, and bg_image_file. Responses include X-Width, X-Height, X-Foreground-* and X-Credits-Charged headers, and a JSON body with result_b64 when you send Accept: application/json.
| Parameter / Header | Accepted values | Behavior |
|---|---|---|
| X-Api-Key (header) | Your Cutout Lab API key | Authenticates the request and tracks daily quota usage. |
| image_file, image_file_b64, image_url | One source per request | Non-animated JPEG, PNG, or WebP up to 12 MB and 12 megapixels. URLs are fetched with a 15-second timeout. |
| size | preview (default), medium, hd, full, auto, 50MP | Maximum output resolution. preview is about 0.25 megapixels; output never exceeds the input size. |
| format | auto (default), png, jpg, webp, zip | auto returns PNG when the result has transparency, otherwise JPG. zip contains color.jpg and alpha.png. |
| channels | rgba (default) or alpha | alpha returns the grayscale mask only. |
| crop, crop_margin | true/false; px or % values (1, 2, or 4 sides) | Crops to the subject and adds the margin, capped at 50% of the subject or 500 px per side. |
| scale, position | 10%–100% or original; center, original, or x% y% | Resizes and places the subject on the canvas. Scale centers the subject unless a position is given. |
| roi | x1 y1 x2 y2 in px or % | Only the region of interest can be kept as foreground. |
| bg_color, bg_image_url, bg_image_file | Hex color or color name; image URL or upload | Adds one background. Images are centered and cropped to fill the canvas. |
| type, type_level, semitransparency | remove.bg values | Accepted for compatibility. Types are not detected automatically; an explicit type is echoed in X-Type. |
| shadow_type, add_shadow | none | Shadows are not supported yet and return HTTP 400 when requested. |
Migrate an existing integration in two changes
To test Cutout Lab in a script that already calls https://api.remove.bg/v1.0/removebg, only the endpoint origin and API key need to change. GET /v1.0/account returns your remaining free calls in the same response shape. Requests that ask for shadows return HTTP 400 so you can catch the difference during testing rather than receiving an unexpected image.
- Request a free API key above using your email address and open the verification link.
- Point your HTTP client's base URL to the Cutout Lab API endpoint (/v1.0/removebg) and set the X-Api-Key header.
- Keep your existing parameters and write the returned image to disk or object storage.
Who it is for
The HTTP API is designed for work that should not depend on someone opening a browser tab or interactive design suite: e-commerce catalog ingestion, headless CMS webhooks, dealer inventory feeds, and CLI scripts that prepare product or profile cutouts in bulk.
For interactive edge refinement, custom background colors, 16 MP client-side mask upscaling, or quick batches of up to 10 images, the browser studio remains free with no account.