Remove background
On this page
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\"}"
bash
Check out REST API reference 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 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"
}
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
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.