API documentation
The Cutmatte API takes the same requests and returns the same responses as the remove.bg API. If you already have a remove.bg integration, read Migrate from remove.bg: you change the address and the key.
Getting started
- Sign in with your email and create an API key. Every account gets 50 free previews a month.
- Send an image:
curl -H "X-Api-Key: YOUR_KEY" \
-F "image_file=@photo.jpg" \
-F "size=auto" \
-o no-bg.png https://api.cutmatte.com/v1.0/removebg
Base URL: https://api.cutmatte.com/v1.0. Request bodies may be multipart/form-data, application/json or application/x-www-form-urlencoded. Parameter values are case-insensitive; empty values count as not given.
Authentication
Send your key in the X-Api-Key header. Authorization: Bearer YOUR_KEY also works. An account can have up to 10 active keys; create and revoke them in the dashboard. We store only a hash of each key, so a key is shown once, when you create it.
POST /v1.0/removebg
Removes the background and returns the result. Give exactly one image source. All other parameters are optional.
Image source
| Parameter | Value |
|---|---|
image_file | The image file (multipart only). JPG, PNG or WebP, up to 22 MB and 50 megapixels. |
image_file_b64 | The image as a base64 string. A data:image/...;base64, prefix is accepted. |
image_url | An http or https URL we download the image from: up to 22 MB, 20 seconds, 5 redirects. Addresses in private networks are refused. |
roi | Region of interest: x1 y1 x2 y2 in px or %, for example 10% 10% 90% 90%. Only this region can be foreground. Default: the whole image. |
Size and credits
The output keeps the aspect ratio of the input and is never larger than the input.
size | Output | Cost |
|---|---|---|
preview (default), small, regular | up to 0.25 MP, e.g. 625×400 | a free call, or 0.25 credit when this month's 50 free calls are used |
medium | up to 1.5 MP | 1 credit |
hd | up to 4 MP | 1 credit |
full, 4k | up to 25 MP | 1 credit |
50MP | up to 50 MP | 1 credit |
auto | full if the account has at least 1 credit, otherwise preview | as chosen |
A PNG with transparency is limited to 10 MP. For larger transparent results use format=zip or webp. Requests that fail are not charged.
Output
| Parameter | Value |
|---|---|
format | auto (default): PNG when the result has transparent parts, otherwise JPG.png, jpg (quality 90; transparent parts become white), webp (lossless, keeps transparency).zip: color.jpg with the colours and alpha.png with the matte. Join them for the final image, e.g. convert color.jpg alpha.png -compose CopyOpacity -composite out.png. The fastest format for large images. |
channels | rgba (default): the cut-out. alpha: only the matte, as a grayscale image (JPG unless you ask for another format). |
semitransparency | Accepted. It does not change the result: see differences. |
Background
| Parameter | Value |
|---|---|
bg_color | Hex colour (81d4fa, fff, or with alpha 81d4fa77) or a colour name (green). Default: transparent. |
bg_image_url | URL of a background image, downloaded like image_url. |
bg_image_file | A background image file. |
Give at most one of the three. A background image is resized to fill the canvas, keeping its aspect ratio, and centred.
Crop, scale, position
| Parameter | Value |
|---|---|
crop | true: crop away empty space around the subject (and its shadow). Default false. |
crop_margin | Margin added around the cropped subject: one value for all sides, two (top/bottom, left/right) or four (top, right, bottom, left). Each in px or % of the subject's size; at most 500 px or 50%. Example: 10%, 30px 10px. Only with crop=true. |
scale | 10% to 100%: the subject is resized to fit that share of the canvas. original (default) keeps its size. Giving scale sets position=center unless you set position. |
position | original (default), center, one value for both axes (0% = top left, 100% = bottom right) or two values: horizontal and vertical, e.g. 50% 100%. |
Shadow
| Parameter | Value |
|---|---|
shadow_type | none (default) or drop: a soft shadow below and to the right of the subject. auto picks the shadow for the type: drop for products, animals, graphics and other subjects. Per type: shadow_type[product]=drop.3D and car are not available: they return 400 unsupported_shadow_type, including through auto for person, transportation and car. |
shadow_opacity | 0 to 100, or auto (50). Per type: shadow_opacity[product]=80. |
add_shadow deprecated | As in remove.bg: true means a car shadow for type=car (not available, returns 400) and nothing otherwise. Cannot be combined with shadow_type. |
Type
| Parameter | Value |
|---|---|
type | auto (default), person, product, animal, car, transportation, graphic. Sets the X-Type header and the shadow chosen by shadow_type=auto. With auto the type is reported as other. Unknown values are ignored. |
type_level | 1 (default), 2, latest or none (no X-Type header). |
Response
The image itself, with a matching Content-Type. Send Accept: application/json to get JSON instead:
{"data": {"result_b64": "iVBORw0KGgo...", "foreground_top": 116, "foreground_left": 55,
"foreground_width": 1046, "foreground_height": 692}}
| Header | Meaning |
|---|---|
X-Credits-Charged | Credits used by this request: 0 for a free call, 0.25 or 1. |
X-Width, X-Height | Size of the result in pixels. |
X-Max-Width, X-Max-Height | Largest result available for this image up to 25 MP; X-Max-50mp-Width and -Height up to 50 MP. |
X-Foreground-Top, -Left, -Width, -Height | Box around the subject (and its shadow) in pixels of the input image. |
X-Type | The foreground type, see type. |
X-RateLimit-Limit, -Remaining, -Reset | See rate limit. |
GET /v1.0/account
Credit balance and free calls left this month.
curl -H "X-Api-Key: YOUR_KEY" https://api.cutmatte.com/v1.0/account
{"data": {"attributes": {
"credits": {"subscription": 0, "payg": 120, "enterprise": 0, "total": 120},
"api": {"free_calls": 50, "sizes": "all"}}}}
All credits are prepaid, so they are reported as payg. POST /v1.0/improve returns 400 improvement_program_unavailable: we do not keep images.
Errors
Errors come as JSON with the HTTP status:
{"errors": [{"title": "Not enough credits", "code": "insufficient_credits"}]}
| Status | Code | When |
|---|---|---|
| 400 | missing_source, multiple_sources | No image source, or more than one |
| 400 | invalid_image_url, failed_image_download | Bad image_url, or it could not be downloaded |
| 400 | file_too_large | Over 22 MB |
| 400 | invalid_file_type, failed_to_read_image, invalid_dimensions | Not a JPG, PNG or WebP, or the file is damaged |
| 400 | resolution_too_high | Input over 50 megapixels |
| 400 | unknown_foreground | No subject found (in the roi, if given). Not charged. |
| 400 | invalid_size, invalid_format, invalid_channels, invalid_roi, roi_exceeds_bounds, invalid_crop_margin, invalid_scale, invalid_position, invalid_bg_color, invalid_bg_image_url, invalid_shadow_opacity | A parameter value is not valid |
| 400 | multiple_bg_sources, multiple_shadow_params, failed_bg_download | Conflicting background or shadow parameters, or the background could not be downloaded |
| 400 | unsupported_shadow_type | 3D or car shadow requested |
| 402 | insufficient_credits | Not enough credits for this size |
| 403 | auth_failed | Missing or invalid API key |
| 429 | rate_limit_exceeded | Over the rate limit; wait Retry-After seconds |
| 500 | processing_failed | Our failure. Not charged; retry. |
Rate limit
500 megapixel-images per minute per account. An image counts as its input size in megapixels, rounded up, at least 1: 500 images of 1 MP a minute, 50 images of 10 MP. Over the limit you get 429 with a Retry-After header in seconds. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time) come with every response.
The first request after a quiet period can take 15–35 seconds while a GPU starts. Set client timeouts to at least 60 seconds.
Differences from remove.bg
| Feature | Cutmatte |
|---|---|
| 3D and car shadows | Not available: 400 unsupported_shadow_type. Drop shadows work. |
| Automatic type detection | X-Type is other unless you pass type. |
semitransparency | Ignored. remove.bg uses it for car windows; windows are cut out like the rest of the car. |
/v1.0/improve | Not available: we do not keep images. |
| Edge colour correction | Edge colours are estimated by the model's own foreground refinement; results can differ slightly from remove.bg at hair and fur. |
Cutmatte is not affiliated with remove.bg or Canva. "remove.bg" is used only to describe API compatibility.