--- description: Clearcut remove a background. Learn how to remove image backgrounds, manage jobs and work with credits in your application. title: Remove a background | Clearcut image: https://clearcut.sh/og/docs.png --- GUIDES [Quick start](https://clearcut.sh/docs)[Authentication](https://clearcut.sh/docs/authentication)[Credits & billing](https://clearcut.sh/docs/credits)[Limits & retries](https://clearcut.sh/docs/limits)[Examples](https://clearcut.sh/docs/examples)[Errors](https://clearcut.sh/docs/errors) API REFERENCE [POSTRemove a background](https://clearcut.sh/docs/remove-background)[GETremove.bg account info](https://clearcut.sh/docs/removebg-account)[POSTCreate an image job](https://clearcut.sh/docs/create-job)[GETGet a job](https://clearcut.sh/docs/get-job)[GETList images](https://clearcut.sh/docs/list-jobs)[DELETEDelete an image](https://clearcut.sh/docs/delete-job)[GETDownload a result](https://clearcut.sh/docs/download)[POSTExport an edited image](https://clearcut.sh/docs/export)[POSTUpload a background](https://clearcut.sh/docs/background)[POSTExport a ZIP batch](https://clearcut.sh/docs/batch-export)[POSTCopy a batch background](https://clearcut.sh/docs/batch-background)[POSTSmart Brush](https://clearcut.sh/docs/smart-brush)[POSTGenerate a scene](https://clearcut.sh/docs/generate-scene)[GETCredit balance](https://clearcut.sh/docs/account)[POSTRetry a failed image](https://clearcut.sh/docs/retry-job)[GETRecent usage](https://clearcut.sh/docs/usage)[Download OpenAPI](https://clearcut.sh/openapi.json) API reference / Remove a background # 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 →](https://clearcut.sh/blog/migrate-remove-bg-api) Authenticate with `X-API-Key`. Keep your key on your server; never embed it in a public website. ## Request parameters `image_file`binary JPG, PNG or WebP file, up to 22 MB. Choose exactly one input source. `image_url`string Public HTTP or HTTPS image URL. Private hosts, credentials, non-standard ports and unsafe redirects are rejected. `image_file_b64`string Base64-encoded image bytes. Choose this instead of a file or URL. `quality`stringdefault: fast Fast uses 1 credit. Fine detail (quality) uses 2\. Output resolution is independent of quality. `fast` `quality` `size`stringdefault: 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. `preview` `small` `regular` `medium` `hd` `auto` `full` `4k` `50MP` `type`stringdefault: 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. `auto` `person` `product` `animal` `car` `transportation` `graphic` `other` `type_level`stringdefault: latest none omits the X-Type response header. `none` `1` `2` `latest` `format`stringdefault: auto auto returns PNG when the result has transparent areas and JPG when it does not. ZIP contains color.jpg and alpha.png. `auto` `png` `jpg` `webp` `zip` `roi`stringdefault: 0% 0% 100% 100% Region of interest as "x1 y1 x2 y2", in pixels (px) or percent (%). Everything outside the region becomes background. `bg_color`string 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_url`string Public image URL for a replacement background. Mutually exclusive with bg\_image\_file. `bg_image_file`binary Replacement background file, up to 22 MB. `crop`booleandefault: false Crop to the detected subject bounds. `crop_margin`stringdefault: 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. `scale`stringdefault: original Resize the subject to 10%–100% of the image size. A scaled subject is centered unless you set position. `position`stringdefault: original Place the subject: original, center, or one or two percentages (horizontal, vertical). 0% is the left or top edge. `add_shadow`booleandefault: false Add a shadow when shadow\_type is none. Cars (type=car) get a car shadow; other subjects get a drop shadow. `shadow_type`stringdefault: 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. `none` `drop` `ground` `3D` `car` `auto` `shadow_opacity`stringdefault: 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. `semitransparency`booleandefault: true Preserve soft edges. false thresholds alpha at 128. `channels`stringdefault: rgba Return color with transparency or a grayscale alpha mask. `rgba` `alpha` ## 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 →](https://clearcut.sh/docs/errors) ## Example request Use full explicitly; the compatibility endpoint defaults to a small preview. cURLPythonNode.js ``` curl https://clearcut.sh/v1.0/removebg \ -H "X-API-Key: $CLEARCUT_API_KEY" \ -H 'Idempotency-Key: catalog-photo-001' \ -F 'image_file=@photo.jpg' \ -F 'size=full' -F 'format=png' \ -o cutout.png ``` [More examples →](https://clearcut.sh/docs/examples) Need help? Prefer email? [support@clearcut.sh](mailto:support@clearcut.sh) Remove a background | Clearcut ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://clearcut.sh/#organization","name":"Clearcut","url":"https://clearcut.sh","logo":"https://clearcut.sh/apple-touch-icon.png","email":"support@clearcut.sh","description":"An independent image background removal service operated by chern0.dev.","contactPoint":{"@type":"ContactPoint","email":"support@clearcut.sh","contactType":"customer support"}},{"@type":"WebSite","@id":"https://clearcut.sh/#website","url":"https://clearcut.sh","name":"Clearcut","description":"Remove image backgrounds with Clearcut. Get 30 free credits every month for the website and API. Full-resolution downloads, no watermark. Packs from $3.","inLanguage":"en","publisher":{"@id":"https://clearcut.sh/#organization"}}]} ```