Remove background

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.

How it works

Background removal works asynchronously through the REST API, unlike the image processing operations performed on the fly.

It generates encoded output as a separate file while the original file remains intact.

Start a processing job via REST API. Send an input file UUID with necessary processing operations.
Wait until the processing job status becomes done.
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.

Execute background removal on a target UUID

curl -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" \
     "https://api.uploadcare.com/addons/remove_bg/execute/" \
     -d "{\"target\": \"$UUID\"}"

Check out REST API reference 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 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:

"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.

curl -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" \
     "https://api.uploadcare.com/addons/remove_bg/execute/status/?request_id=$REQUEST_ID"

Check out REST API reference to check the execution status.

As a request result, you will receive an UUID of the file when status is done.

{
  "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:

curl -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" \
     "https://api.uploadcare.com/addons/remove_bg/execute/" \
     -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
`scale`	Scales the subject relative to the total image size
`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'
`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 reference 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

You don't have to code most of the low-level API integrations. We have high-level libraries for all popular platforms:

Billing

This feature is available on paid plans.
This operation uploads a new file.
Learn how we charge for this operation.