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.

  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.


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

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" \
     "" \
     -d "{\"target\": \"$UUID\", \"params\": {\"crop\": true, \"bg_color\": \"81d4fa77\"}}"

List of params

cropWhether to crop off all empty regions
crop_marginAdds a margin around the cropped subject
scaleScales the subject relative to the total image size
add_shadowWhether to add an artificial shadow to the result
type_levelClassification level of the detected foreground type
typeForeground type
semitransparencyWhether to have semi-transparent regions in the result
channelsRequest either the finalized image ('rgba'
roiOnly the contents of this given rectangular area can be detected as foreground. Anything outside is considered background and will be removed
positionPositions the subject within the image canvas

Check out REST API reference to see full list of request body schema parameters.


  • 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:


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