Remove a background

Remove a background and return an image in one request. Requires an API key. Accepts the remove.bg request: send multipart form data, a URL-encoded form or JSON. If processing takes more than 55 seconds, returns 202 with a job ID; poll that job instead of creating another.

POST/v1.0/removebg

Coming from remove.bg? Keep your requests. Change the host from https://api.remove.bg to https://clearcut.sh and send a Clearcut key in X-Api-Key. Read the API migration guide →

Authenticate with X-API-Key. Keep your key on your server; never embed it in a public website.

Request parameters

image_filebinary

JPG, PNG or WebP file, up to 22 MB. Choose exactly one input source.

image_urlstring

Public HTTP or HTTPS image URL. Private hosts, credentials, non-standard ports and unsafe redirects are rejected.

image_file_b64string

Base64-encoded image bytes. Choose this instead of a file or URL.

qualitystringdefault: fast

Fast uses 1 credit. Fine detail (quality) uses 2. Output resolution is independent of quality.

fastquality

sizestringdefault: preview

preview, small and regular fit within 625 × 400 pixels. medium is up to 1.5 MP and hd up to 4 MP. auto keeps the original size up to 25 MP. full, 4k and 50MP keep the original size up to 50 MP. Every size costs the same credits. No upscaling.

previewsmallregularmediumhdautofull4k50MP

typestringdefault: auto

Foreground type, accepted for remove.bg compatibility. Clearcut uses one model for every type. The type sets X-Type and the shadow that shadow_type=auto and add_shadow choose.

autopersonproductanimalcartransportationgraphicother

type_levelstringdefault: latest

none omits the X-Type response header.

none12latest

formatstringdefault: auto

auto returns PNG when the result has transparent areas and JPG when it does not. ZIP contains color.jpg and alpha.png.

autopngjpgwebpzip

roistringdefault: 0% 0% 100% 100%

Region of interest as "x1 y1 x2 y2", in pixels (px) or percent (%). Everything outside the region becomes background.

bg_colorstring

Hex color with 3, 4, 6 or 8 digits, with or without #, or a CSS color name such as green. 4- and 8-digit colors are translucent.

bg_image_urlstring

Public image URL for a replacement background. Mutually exclusive with bg_image_file.

bg_image_filebinary

Replacement background file, up to 22 MB.

cropbooleandefault: false

Crop to the detected subject bounds.

crop_marginstringdefault: 0

Padding around the cropped subject: pixels (30 or 30px, up to 1,000) or percent of the subject size (10%, up to 50%). Use 1, 2 or 4 values for all sides; top/bottom and left/right; or top, right, bottom, left.

scalestringdefault: original

Resize the subject to 10%–100% of the image size. A scaled subject is centered unless you set position.

positionstringdefault: original

Place the subject: original, center, or one or two percentages (horizontal, vertical). 0% is the left or top edge.

add_shadowbooleandefault: false

Add a shadow when shadow_type is none. Cars (type=car) get a car shadow; other subjects get a drop shadow.

shadow_typestringdefault: none

3D and ground add a contact shadow under the subject. auto picks car for cars, 3D for people and transportation, and drop for everything else. Set one value per type with shadow_type[car], shadow_type[product] and so on.

nonedropground3Dcarauto

shadow_opacitystringdefault: 35

Shadow opacity from 0 to 100, or auto (90 for cars, 50 otherwise). Set one value per type with shadow_opacity[car] and so on.

semitransparencybooleandefault: true

Preserve soft edges. false thresholds alpha at 128.

channelsstringdefault: rgba

Return color with transparency or a grayscale alpha mask.

rgbaalpha

remove.bg compatibility

This endpoint accepts remove.bg’s parameters, values and request formats. Most integrations and SDKs work after you change the host and the key. Check the rows marked Different before you switch.

remove.bg	Clearcut	Notes
`POST /v1.0/removebg`	Same	Change the host from https://api.remove.bg to https://clearcut.sh.
`X-Api-Key header`	Same	Use a Clearcut key. Authorization: Bearer also works.
`Multipart`, `URL-encoded and JSON bodies`	Same	Send any of the three, as remove.bg accepts.
`image_file`, `image_url`, `image_file_b64`	Same	Send exactly one.
`size`	Supported	All remove.bg values, including regular, medium, hd and 4k. No size means preview. auto keeps the original size up to 25 MP. Every size costs the same credits.
`size=preview`	Different	remove.bg resizes to 0.25 MP. Clearcut fits the image within 625 × 400, so tall images come back smaller (300 × 400 for a 3:4 portrait).
`type`, `type_level`	Supported	Accepted. Clearcut uses one model for every subject and does not classify images. X-Type repeats your type, or is other.
`format`, `channels`	Same	auto, png, jpg, webp, zip; rgba or alpha.
`roi`	Same	Pixels or percent.
`crop`, `crop_margin`	Same	Pixels or percent, with 1, 2 or 4 values.
`scale`, `position`	Same	Percentages, center or original.
`bg_color`, `bg_image_url`, `bg_image_file`	Same	Hex with 3, 4, 6 or 8 digits, or a CSS color name.
`shadow_type`, `shadow_opacity`	Supported	none, drop, car, 3D, auto and per-type values. 3D is Clearcut’s contact shadow. Clearcut does not detect the subject, so without type, auto gives a drop shadow. Without shadow_opacity, opacity is 35.
`add_shadow`	Different	remove.bg adds a shadow only to cars. Clearcut adds a car shadow when type=car and a drop shadow otherwise.
`semitransparency`	Same	false removes soft edges.
`Accept: application/json`	Same	data.result_b64 and the foreground_* fields. Outputs over 16 MB must be downloaded as binary.
`X-Width`, `X-Height`, `X-Credits-Charged`, `X-Type`, `X-Foreground-*`	Same	Sent with binary and JSON results.
`Errors`	Supported	Bodies include errors[].title and errors[].code. Invalid parameters return 422 (remove.bg uses 400) and an invalid key returns 401 (remove.bg uses 403).
`Long requests`	Different	If an image takes more than 55 seconds, Clearcut returns 202 with a job ID. Poll /api/jobs/{id}; do not submit again.
`SDK timeouts and retries`	Supported	A first image can take 20 seconds or more while a GPU starts, and some clients time out and resend (remove.bg’s Ruby gem resends twice after 20 seconds). An identical request from the same account within 10 minutes reuses the first job and is not charged again. Send a new Idempotency-Key to force a new job.
`GET /v1.0/account`	Supported	subscription is your monthly free credits and payg your purchased credits. free_calls is 0.
`X-RateLimit-* headers`	Not offered	A 429 response includes Retry-After.
`POST /v1.0/improve`	Not offered	Clearcut has no improvement program.

Response

200 · Success

{
  "binary": "PNG, JPG, WebP or ZIP bytes",
  "headers": {
    "X-Credits-Charged": "1",
    "X-Job-Id": "image_id",
    "X-Width": "1200",
    "X-Height": "800",
    "X-Type": "other",
    "X-Foreground-Top": "96",
    "X-Foreground-Left": "210",
    "X-Foreground-Width": "780",
    "X-Foreground-Height": "704"
  }
}

Errors use a structured error.code and error.message. See error handling →