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 that is 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 finished.
  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.

Execute add-on 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\"}"bash

Check out REST API references to see how to execute add-on on a target UUID.

Check the execution status

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

Check out REST API references 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"
}json

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

List of params

ParameterDescription
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 references 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.