Background removal
Remove backgrounds from your images
You can remove the background from any image in your media library with the remove.bg third-party service using ImageKit's update and upload API. ImageKit consumes APIs provided by that service to generate the output image, and then uploads it to your media library. You can specify a few advanced parameters supported by the remove.bg.

How to use background removal?

    1.
    While uploading a new image: During an upload API call, you must specify inside the extensions parameter the name of the service to be used and optionally theoptions object. The background removal operation will begin after the image has been uploaded.\
    2.
    While updating an already existing image: You can remove the background from an existing image through an update API call. You must specify inside the extensions parameter the name of the service to be used and optionally the options object. The background removal operation will begin after the image has been updated.

Extensions parameter for background removal

The extensions parameter of both upload and update APIs takes an array of objects specifying the extensions to be used along with their parameters. Each object in this array is a self-contained block containing information about one single extension. This information includes the name of the extension and other parameters associated with that extension. The object for a background removal extension will have the following fields:
Parameter name
Type
Required
Valid input
name
string
Yes
remove-bg
options
object
No
An object containing fields that are directly sent to the third-party service as request parameters. Example: the remove.bg service supports the boolean parameter add_shadow See below for a list of available options

Supported options parameters

The options are passed to remove-bg service as it is. We support the following options:
Parameter name
Type
Description
add_shadow
boolean
Whether to add an artificial shadow to the result (default: false). NOTE: Adding shadows is currently only supported for car photos.
semitransparency
boolean
Whether to have semi-transparent regions in the result (default: true). NOTE: Semitransparency is currently only supported for car windows.
bg_color
string
Adds a solid color background. Can be a hex color code (e.g. 81d4fa, fff) or a color name (e.g. green). If this parameter is present, then bg_image_url must be empty.
bg_image_url
string
Adds a background image from a URL. If this parameter is present, then bg_color must be empty.
To learn more about what these do, refer to remove.bg's documentation.
Here's an example of an extensions parameter formation that will result in the execution of a background removal extension using the remove.bg service. Here, the add_shadow and bg_color options fields are directly sent to the remove.bg API as request body parameters.
1
// Request body for an update/upload API call
2
{
3
/*
4
...rest of the update/upload request parameters
5
*/
6
"extensions": [
7
{
8
"name": "remove-bg",
9
"options": {
10
"add_shadow": true,
11
"bg_color": "green"
12
}
13
}
14
]
15
}
Copied!

Asynchronous behavior

Background removal extensions always execute asynchronously i.e. executed after your main update/upload call has successfully completed and you have received the response for it.

Response structure

If an update/upload API call includes a valid extensions field array with a non-zero length, then the response will include an extensionStatus field object, which will contain the status of each extension at the time of completion of the update/upload request. For background removal extensions, the status has two possible values:
    failed: The extension has failed and will not be retried.
    pending: The extension will finish processing in some time. On completion, the final status (success/failure) will be sent to the webhookUrl provided
The response for an API call with the above request body might look like this
1
// Response body for an update/upload API call
2
{
3
/*
4
...rest of the update/upload response fields
5
*/
6
"extensionStatus": {
7
"remove-bg": "pending"
8
}
9
}
Copied!

Webhooks

You can include a webhookUrl parameter in your update/upload API calls. The final status of extensions after they have completed execution will be delivered to this endpoint as a POST request. The request body sent to this endpoint will look like the examples below.
To learn more about how ImageKit uses webhooks, refer here.
1
// A success response for a remove-bg extension
2
{
3
"service": "remove-bg",
4
"status": "SUCCESS",
5
"fileObject": {
6
"fileId": "5effaa5662679b5af2c58829",
7
/*
8
... rest of the fields in a file object
9
*/
10
},
11
}
Copied!
1
// A failure response for a remove-bg extension
2
{
3
"service": "remove-bg",
4
"status": "FAILURE",
5
"fileId": "5effaa5662679b5af2c58829",
6
"error": {
7
/* error description fields */
8
}
9
}
Copied!

Examples

Let's apply the background removal extension to the below image:

Using the upload API for background removal

cURL
1
curl -X POST "https://upload.imagekit.io/api/v1/files/upload" \
2
-u your_private_api_key: \
3
-F '[email protected]/Users/username/Desktop/cafe_picture.jpg;type=image/jpg' \
4
-F 'fileName=my_file_name.jpg'
5
-F 'extensions="[
6
{
7
\"name\": \"remove-bg"
8
}
9
]"'
Copied!

Response

1
{
2
"fileId" : "598821f949c0a938d57563bd",
3
"name": "file1.jpg",
4
"url": "https://ik.imagekit.io/your_imagekit_id/images/products/file1.jpg",
5
"thumbnailUrl": "https://ik.imagekit.io/your_imagekit_id/tr:n-media_library_thumbnail/images/products/file1.jpg",
6
"height" : 300,
7
"width" : 200",
8
"size" : 83622,
9
"filePath": "/images/products/file1.jpg",
10
"AITags": null,
11
"fileType": "image",
12
"extensionStatus": {
13
"remove-bg": "pending"
14
}
15
}
Copied!
Output

Using the update API to background removal

cURL
Node.js
Python
PHP
Ruby
1
# The unique fileId of the uploaded file. fileId is returned in response of list files API and upload API.
2
curl -X PATCH "https://api.imagekit.io/v1/files/fileId/details" \
3
-H 'Content-Type: application/json' \
4
-u your_private_key: -d'
5
{
6
"extensions": [
7
{
8
"name": "remove-bg"
9
}
10
]
11
}
12
'
Copied!
1
var ImageKit = require("imagekit");
2
3
var imagekit = new ImageKit({
4
publicKey : "your_public_api_key",
5
privateKey : "your_private_api_key",
6
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
7
});
8
9
imagekit.updateFileDetails("file_id", {
10
extensions: [
11
{
12
name: "remove-bg"
13
}
14
]
15
}, function(error, result) {
16
if(error) console.log(error);
17
else console.log(result);
18
});
Copied!
1
from imagekitio import ImageKit
2
3
imagekit = ImageKit(
4
public_key='your_public_api_key',
5
private_key='your_private_api_key',
6
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
7
)
8
9
updated_detail = imagekit.update_file_details(
10
"file_id",
11
"extensions": [
12
{
13
"name": "remove-bg"
14
}
15
]
16
)
17
18
print("Updated detail-", updated_detail, end="\n\n")
Copied!
1
use ImageKit\ImageKit;
2
3
$public_key = "your_public_api_key";
4
$your_private_key = "your_private_api_key";
5
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
6
7
$imageKit = new ImageKit(
8
$public_key,
9
$your_private_key,
10
$url_end_point
11
);
12
13
$updateFileDetails = $imageKit->updateFileDetails("file_id", array("extensions" => [array("name" => "remove-bg")]));
14
15
echo("Updated detail : " . json_encode($updateFileDetails));
Copied!
1
imagekitio = ImageKit::ImageKitClient.new("your_private_key", "your_public_key", "your_url_endpoint")
2
updated_detail = imagekitio.update_file_details(
3
"file_id",
4
{
5
"extensions": [
6
{
7
"name": "remove-bg",
8
}
9
]
10
}
11
)
Copied!

Response

1
{
2
"fileId": "598821f949c0a938d57563bd",
3
"type": "file",
4
"name": "file1.jpg",
5
"filePath": "/images/products/file1.jpg",
6
"tags": null,
7
"AITags": null,
8
"isPrivateFile": false,
9
"customCoordinates": null,
10
"url": "https://ik.imagekit.io/your_imagekit_id/images/products/file1.jpg",
11
"thumbnail": "https://ik.imagekit.io/your_imagekit_id/tr:n-media_library_thumbnail/images/products/file1.jpg",
12
"fileType": "image",
13
"mime": "image/jpeg",
14
"width": 100,
15
"height": 100,
16
"size": 100,
17
"hasAlpha": false,
18
"createdAt": "2019-08-24T06:14:41.313Z",
19
"updatedAt": "2019-08-24T06:14:41.313Z",
20
"extensionStatus": {
21
"remove-bg": "pending"
22
}
23
}
Copied!
Output Image

Using the options parameters for advanced features

You can add any of the supported options parameters to your extensions object to perform certain advanced operations along with background removal.

Examples

    1.
    bg_color
1
2\. **add_shadow **(only works on car images)
Copied!
1
3\. **bg_image_url**
Copied!
Last modified 3d ago