> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://uploadcare.com/docs/llms.txt. # Background removal > Automatically remove the image background and leave the object of interest. The Background removal operation allows leaving only the object of interest on an image. The removed background turns into a transparent area. It reduces the time for editing images since you no longer need to remove the background manually. The feature is currently available on the REST API v0.7 or higher via [add-ons API](https://uploadcare.com/docs/api/rest/add-ons/remove-bg-execute). ## How it works Background removal works asynchronously through the REST API, unlike the [image processing operations](/docs/transformations/image/#image-transformations-list) performed on the fly. It generates encoded output as a separate file while the original file remains intact. 1. Start a processing job via REST API. Send an input file UUID with necessary processing operations. 2. Wait until the processing job status becomes `done`. 3. The processed file can be addressed via its new UUID, as well as an URL with operations provided in a processing request. This will create a new file with an image on a transparent background. ## Example To remove the background from an image, first get your [API keys](https://app.uploadcare.com/projects/-/api-keys/). ### Execute background removal on a target UUID ```bash curl -L "https://api.uploadcare.com/addons/remove_bg/execute/" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.uploadcare-v0.7+json" \ -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \ -d "{\"target\": \"$UUID\"}" ``` Check out [REST API remove bg](https://uploadcare.com/docs/api/rest/add-ons/remove-bg-execute) to see how to execute add-on on a target UUID. ### Webhook event To get the job result, you need to enable `file.uploaded` in the [Webhook section](/docs/webhooks/#webhook-notifications) of the dashboard. After completing the processing job, the webhook will be sent to the endpoint you specified in the webhook settings. File information in response: ```json "initiator": { "type": "addon", "detail": { "addon_name": "remove_bg", "request_id": "d8985400-7ca9-4e1b-9751-2e238a104754", "source_file_uuid": ":UUID" } } "hook": { ... "event": "file.uploaded", "is_active": true, "version": "0.7", "created_at": "2023-10-26T09:32:40.114516Z", "updated_at": "2023-10-26T09:32:40.114516Z" }, "uuid": ":UUID", "is_image": true, "is_ready": true, "metadata": {}, "appdata": { "remove_bg": { "data": { "foreground_type": "product" }, "version": "1.0", "datetime_created": "2023-11-07T18:00:57.596Z", "datetime_updated": "2023-11-07T18:00:57.596Z" } } ``` ### Check the execution status If your application does not have a backend or uses a mobile version, you can submit the request yourself. Use request ID returned by the add-on execution request described above. ```bash curl -L "https://api.uploadcare.com/addons/remove_bg/execute/status/?request_id=$REQUEST_ID" \ -X GET \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.uploadcare-v0.7+json" \ -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" ``` Check out [REST API remove bg status](https://uploadcare.com/docs/api/rest/add-ons/remove-bg-execution-status) to check the execution status. As a request result, you will receive an UUID of the file when status is done. ```json { "result": { "file_id": "b6d7b8f7-a982-4719-bc0b-3c00f2b56b06" }, "status": "done" } ``` ## Use cases If you need to set additional options when removing the background, such as a specific background color, the output request should look like this: ```bash curl -L "https://api.uploadcare.com/addons/remove_bg/execute/" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.uploadcare-v0.7+json" \ -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \ -d "{\"target\": \"$UUID\", \"params\": {\"crop\": true, \"bg_color\": \"81d4fa77\"}}" ``` ## List of params | **Parameter** | **Description** | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `crop` | Whether to crop off all empty regions | | `crop_margin` | Adds a margin around the cropped subject e.g 30px or 30% | | `scale` | Scales the subject relative to the total image size e.g 80% | | `add_shadow` | Whether to add an artificial shadow to the result | | `type_level` | Classification level of the detected foreground type | | `type` | Foreground type | | `semitransparency` | Whether to have semi-transparent regions in the result | | `channels` | Request either the finalized image ('rgba' default) or an alpha mask ('alpha') | | `roi` | Only the contents of this given rectangular area can be detected as foreground. Anything outside is considered background and will be removed | | `position` | Positions the subject within the image canvas | Check out [REST API remove bg](https://uploadcare.com/docs/api/rest/add-ons/remove-bg-execute) to see full list of request body schema parameters. ## Limitations * This operation is not available on the Free plan. * Removes the background from a JPG/PNG image. * File size: up to 12 MB. * Image ัontent: any photo with a foreground (e.g., people, products, animals, cars, etc). * Output resolutions available: up to 25 megapixels. If the output image is larger than that, it will be automatically compressed to 25 megapixels. * Output file formats: PNG. ## API integrations \[#integrations] You don't have to code most of the low-level API integrations. We have high-level libraries for all popular platforms: * [JavaScript](/docs/integrations/javascript/) * [PHP](/docs/integrations/php/) * [Python & Django](/docs/integrations/python/) * [Ruby](/docs/integrations/ruby/) * [Rails](/docs/integrations/rails/) * [Swift](/docs/integrations/swift/) ## Billing * This feature is available on [paid plans](https://uploadcare.com/pricing/). * This operation uploads a new file. * Learn how we [charge](/docs/billing/) for this operation.