Cutmatte

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

  1. Sign in with your email and create an API key. Every account gets 50 free previews a month.
  2. 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

ParameterValue
image_fileThe image file (multipart only). JPG, PNG or WebP, up to 22 MB and 50 megapixels.
image_file_b64The image as a base64 string. A data:image/...;base64, prefix is accepted.
image_urlAn http or https URL we download the image from: up to 22 MB, 20 seconds, 5 redirects. Addresses in private networks are refused.
roiRegion 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.

sizeOutputCost
preview (default), small, regularup to 0.25 MP, e.g. 625×400a free call, or 0.25 credit when this month's 50 free calls are used
mediumup to 1.5 MP1 credit
hdup to 4 MP1 credit
full, 4kup to 25 MP1 credit
50MPup to 50 MP1 credit
autofull if the account has at least 1 credit, otherwise previewas 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

ParameterValue
formatauto (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.
channelsrgba (default): the cut-out. alpha: only the matte, as a grayscale image (JPG unless you ask for another format).
semitransparencyAccepted. It does not change the result: see differences.

Background

ParameterValue
bg_colorHex colour (81d4fa, fff, or with alpha 81d4fa77) or a colour name (green). Default: transparent.
bg_image_urlURL of a background image, downloaded like image_url.
bg_image_fileA 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

ParameterValue
croptrue: crop away empty space around the subject (and its shadow). Default false.
crop_marginMargin 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.
scale10% 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.
positionoriginal (default), center, one value for both axes (0% = top left, 100% = bottom right) or two values: horizontal and vertical, e.g. 50% 100%.

Shadow

ParameterValue
shadow_typenone (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_opacity0 to 100, or auto (50). Per type: shadow_opacity[product]=80.
add_shadow deprecatedAs 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

ParameterValue
typeauto (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_level1 (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}}
HeaderMeaning
X-Credits-ChargedCredits used by this request: 0 for a free call, 0.25 or 1.
X-Width, X-HeightSize of the result in pixels.
X-Max-Width, X-Max-HeightLargest result available for this image up to 25 MP; X-Max-50mp-Width and -Height up to 50 MP.
X-Foreground-Top, -Left, -Width, -HeightBox around the subject (and its shadow) in pixels of the input image.
X-TypeThe foreground type, see type.
X-RateLimit-Limit, -Remaining, -ResetSee 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"}]}
StatusCodeWhen
400missing_source, multiple_sourcesNo image source, or more than one
400invalid_image_url, failed_image_downloadBad image_url, or it could not be downloaded
400file_too_largeOver 22 MB
400invalid_file_type, failed_to_read_image, invalid_dimensionsNot a JPG, PNG or WebP, or the file is damaged
400resolution_too_highInput over 50 megapixels
400unknown_foregroundNo subject found (in the roi, if given). Not charged.
400invalid_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_opacityA parameter value is not valid
400multiple_bg_sources, multiple_shadow_params, failed_bg_downloadConflicting background or shadow parameters, or the background could not be downloaded
400unsupported_shadow_type3D or car shadow requested
402insufficient_creditsNot enough credits for this size
403auth_failedMissing or invalid API key
429rate_limit_exceededOver the rate limit; wait Retry-After seconds
500processing_failedOur 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

FeatureCutmatte
3D and car shadowsNot available: 400 unsupported_shadow_type. Drop shadows work.
Automatic type detectionX-Type is other unless you pass type.
semitransparencyIgnored. remove.bg uses it for car windows; windows are cut out like the rest of the car.
/v1.0/improveNot available: we do not keep images.
Edge colour correctionEdge 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.