Remove-The-Background Editing Add-on

Overview

Cloudinary is a cloud-based service that provides an end-to-end image management solution that covers image uploads, storage, manipulations, optimizations and delivery.

Cloudinary offers a very rich set of image manipulation capabilities and allows you to upload images to the cloud, crop them on-the-fly and have them further manipulated to match the graphic design of your websites and mobile applications.

Pixelz is a leading vendor of image editing solutions components, including powerful background removal of photos, done by a team of human experts. Cloudinary provides a Remove-The-Background add-on for using Pixelz's image editing capabilities, fully integrated into Cloudinary's image management and manipulation pipeline.

With Pixelz's image editing add-on, you can extend Cloudinary's image manipulation capabilities with automatic background removal from your photos, resulting with a transparent-background image focusing on the main object of your photo.

Remove image background

You can try the Remove-The-Background image editing add-on for free and later on subscribe to an add-on plan that best matches your usage requirements. Note that the Remove-The-Background add-on is only free-to-try for Cloudinary paid accounts: the add-on is not available to the Cloudinary free-tier accounts.

To simplify the add-on integration, you can use Cloudinary's client libraries for: Ruby on Rails, Python & Django, PHP, Node.js, javascript, jQuery, Angular, Java, .NET, iOS, Android and Scala.

In order to remove the background from your images, you will first need to upload images to Cloudinary. Requesting background removal can be done either while uploading files to Cloudinary (from your server-side code or directly from the browser), or by updating an existing image, either programatically or interactively.

Note: The criteria for background removal can be customized by contacting us.

The following code sample shows how to upload a photo to Cloudinary, while telling Cloudinary to remove its background. In order to remove the background of the uploaded image, the 'background_removal' parameter should be set to 'pixelz'.

RubyPHPPythonNode.jsJavaAll
Ruby:
Cloudinary::Uploader.upload("wood_chair.jpg",
  :public_id => "wood_chair",
  :background_removal => 'pixelz')
PHP:
\Cloudinary\Uploader::upload("wood_chair.jpg", 
  array(
    "public_id" => "wood_chair",
    "background_removal" => "pixelz"
  ));
Python:
cloudinary.uploader.upload("wood_chair.jpg",
  public_id = "wood_chair",
  background_removal = "pixelz")
Node.js:
cloudinary.uploader.upload("wood_chair.jpg", 
  function(result) { console.log(result); }, 
  { public_id: "wood_chair",
    background_removal: "pixelz" });
Java:
cloudinary.uploader().upload("wood_chair.jpg", ObjectUtils.asMap(
  "public_id", "wood_chair",
  "background_removal", "pixelz"));

Background removal is performed asynchronously in the background after the upload call is completed.

Note: Background removal is done by a team of human experts. Therefore, editing is completed within 24 hours.

The response of the uploaded request mentions that the editing process is in the pending status.

RubyPHPPythonNode.jsJavaAll
Ruby:
{ 
  "public_id" => "wood_chair",
  "version" => 1414316122,
  "resource_type" => "image",
  "type" => "upload",
  "url" =>
   "https://res.cloudinary.com/demo/image/upload/v1414316122/wood_chair.jpg"
  "info" => { "background_removal" => 
    { "remove_the_background" => { "status" => "pending" }}
  },
  ...
}
PHP:
array(11) {
  ["public_id"]=>
  string(25) "wood_chair"
  ["version"]=>
  int(1414316122)
  ["resource_type"]=>
  string(3) "image"
  ["type"]=>
  string(6) "upload"
  ["info"]=>
  array(1) {
    ["background_removal"]=>
    array(1) {
      ["remove_the_background"]=>
      array(1) {
        ["status"]=>
        string(9) "pending"
      }
    }
  }
  ["url"]=>
  string(79) "https://res.cloudinary.com/demo/image/upload/v1414316122/wood_chair.jpg"
  ...
}
Python:
{ u'info': { u'background_removal': { u'remove_the_background': { u'status': u'pending'}}},
  u'public_id': u'wood_chair',
  u'resource_type': u'image',
  u'type': u'upload',
  u'url': u'https://res.cloudinary.com/demo/image/upload/v1414316122/wood_chair.jpg',
  u'version': 1414316122 }
Node.js:
{ 
  public_id: "wood_chair",
  version: 1414316122,
  resource_type: "image",
  type: "upload",
  url:
   "https://res.cloudinary.com/demo/image/upload/v1414316122/wood_chair.jpg"
  info: { background_removal: { remove_the_background: { status: "pending" }}},
  ...
}
Java:
{
  "public_id":"wood_chair",
  "version":1414316122,
  "resource_type":"image",
  "type":"upload",
  "url":"http://res.cloudinary.com/demo/image/upload/v1414316122/wood_chair.jpg",
  "info":{"background_removal":{"remove_the_background":{"status":"pending"}}},
  ...
}

As a result of the upload example above, the original image is automatically sent, behind the scenes, to Remove-The-Background for editing. When background removal is completed, the original image is automatically replaced with the edited one and is available for delivery via a fast CDN, without any code changes required. The original image is made available as a backed-up revision of the image and you can always revert to it, if needed.

For example, the following dynamic manipulation and delivery URL shows the original image of an uploaded wooden chair photo:

URLRubyPHPPythonNode.jsJavaJSjQueryReactAngular.NetAndroidAll
URL:
https://res.cloudinary.com/demo/image/upload/w_300/wood_chair_orig.jpg
Ruby:
cl_image_tag("wood_chair_orig.jpg", :width=>300, :crop=>"scale")
PHP:
cl_image_tag("wood_chair_orig.jpg", array("width"=>300, "crop"=>"scale"))
Python:
CloudinaryImage("wood_chair_orig.jpg").image(width=300, crop="scale")
Node.js:
cloudinary.image("wood_chair_orig.jpg", {width: 300, crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(300).crop("scale")).imageTag("wood_chair_orig.jpg")
JS:
cl.imageTag('wood_chair_orig.jpg', {width: 300, crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("wood_chair_orig.jpg", {width: 300, crop: "scale"})
React:
<Image publicId="wood_chair_orig.jpg" >
  <Transformation width="300" crop="scale" />
</Image>
Angular:
<cl-image public-id="wood_chair_orig.jpg" >
  <cl-transformation width="300" crop="scale">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Crop("scale")).BuildImageTag("wood_chair_orig.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(300).crop("scale")).generate("wood_chair_orig.jpg")
300 pixels wide original wood chair

Below you can see the result of Remove-The-Background editing:

URLRubyPHPPythonNode.jsJavaJSjQueryReactAngular.NetAndroidAll
URL:
https://res.cloudinary.com/demo/image/upload/w_300/wood_chair.jpg
Ruby:
cl_image_tag("wood_chair.jpg", :width=>300, :crop=>"scale")
PHP:
cl_image_tag("wood_chair.jpg", array("width"=>300, "crop"=>"scale"))
Python:
CloudinaryImage("wood_chair.jpg").image(width=300, crop="scale")
Node.js:
cloudinary.image("wood_chair.jpg", {width: 300, crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(300).crop("scale")).imageTag("wood_chair.jpg")
JS:
cl.imageTag('wood_chair.jpg', {width: 300, crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("wood_chair.jpg", {width: 300, crop: "scale"})
React:
<Image publicId="wood_chair.jpg" >
  <Transformation width="300" crop="scale" />
</Image>
Angular:
<cl-image public-id="wood_chair.jpg" >
  <cl-transformation width="300" crop="scale">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Crop("scale")).BuildImageTag("wood_chair.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(300).crop("scale")).generate("wood_chair.jpg")
300 pixels wide edited wood chair

Update existing images

The examples above show how to automatically schedule background removal of images during their upload process. As an alternative, you can use Cloudinary's Admin API to request background removal to already uploaded images, based on their public IDs.

For example, an image was uploaded to Cloudinary with the 'wood_chair' public ID. The following code sample uses Cloudinary's update API to apply background removal to the uploaded image that has the 'wood_chair' public ID.

RubyPHPPythonNode.jsJavaAll
Ruby:
Cloudinary::Api.update("wood_chair", 
  :background_removal => "pixelz")
PHP:
$api = new \Cloudinary\Api();
$api->update("wood_chair", 
  array("background_removal" => "pixelz"));
Python:
cloudinary.api.update("wood_chair",
  background_removal = "pixelz")
Node.js:
cloudinary.api.update("wood_chair", 
  function(result) { console.log(result); }, 
  { background_removal: "pixelz" });
Java:
cloudinary.api().update("wood_chair", ObjectUtils.asMap(
  "background_removal", "pixelz" ));

You can also use Cloudinary's media library to interactively tell Cloudinary to remove the background of an existing image via your web browser:

Remove-The-Background interactive UI

Status notification

The Remove-The-Background add-on edits images asynchronously. The image editing is done by a trained team of human experts and may take up to 24 hours to complete. As a result, you may want to get notified when the editing process is completed.

When calling the upload API with background removal request, you can set the 'notification_url' to a public HTTP or HTTPS URL of your online web application. Cloudinary sends a POST request to the specified endpoint when image editing is completed.

RubyPHPPythonNode.jsJavaAll
Ruby:
Cloudinary::Uploader.upload("wood_chair.jpg",
  :public_id => "wood_chair",
  :background_removal => 'pixelz',
  :notification_url => "http://mysite.example.com/hooks")
PHP:
\Cloudinary\Uploader::upload("wood_chair.jpg", 
  array(
    "public_id" => "wood_chair",
    "background_removal" => "pixelz",
    "notification_url" => "http://mysite.example.com/hooks"
  ));
Python:
cloudinary.uploader.upload("wood_chair.jpg",
  public_id = "wood_chair",
  background_removal = "pixelz",
  notification_url = "http://mysite.example.com/hooks")
Node.js:
cloudinary.uploader.upload("wood_chair.jpg", 
  function(result) { console.log(result); }, 
  { public_id: "wood_chair",
    background_removal: "pixelz",
    notification_url: "http://mysite.example.com/hooks"
  });
Java:
cloudinary.uploader().upload("wood_chair.jpg", ObjectUtils.asMap(
  "public_id", "wood_chair", 
  "background_removal", "pixelz", 
  "notification_url", "http://mysite.example.com/hooks"));

The following JSON snippet is an example of a POST request sent to the notification URL when image editing is completed: 

{ 
  "notification_type": "info",
  "info_kind": "remove_the_background",
  "info_status": "complete",
  "public_id": "wood_chair",
  "uploaded_at": "2014-10-26T11:35:22Z",
  "version": 1414316122,
  "url": 
    "https://res.cloudinary.com/demo/image/upload/v1393688588/wood_chair.jpg",
  "secure_url":
    "https://res.cloudinary.com/demo/image/upload/v1393688588/wood_chair.jpg",
  "etag": "a56e9e88c2add15cac1775c1f687bf73"
}

The JSON content is signed using the API Secret of your Cloudinary account. For more details regarding Cloudinary's notifications and webhooks, see this blog post.

Further image manipulations

Images edited for removing their backgrounds can be mixed with any of Cloudinary's rich set of image manipulation capabilities.

For example, the following dynamic manipulation and delivery URL generates a 200x200 padded version of the edited image. Image color saturation is increased by 50%. A shadow is added and so is a solid one pixel black border. This technique can be used to make sure that all product images on your e-commerce website share a consistent look & feel.

URLRubyPHPPythonNode.jsJavaJSjQueryReactAngular.NetAndroidAll
URL:
https://res.cloudinary.com/demo/image/upload/c_pad,w_200,h_200,e_saturation:50/e_shadow/bo_1px_solid_rgb:666/wood_chair.jpg
Ruby:
cl_image_tag("wood_chair.jpg", :transformation=>[
  {:width=>200, :height=>200, :effect=>"saturation:50", :crop=>"pad"},
  {:effect=>"shadow"},
  {:border=>"1px_solid_rgb:666"}
  ])
PHP:
cl_image_tag("wood_chair.jpg", array("transformation"=>array(
  array("width"=>200, "height"=>200, "effect"=>"saturation:50", "crop"=>"pad"),
  array("effect"=>"shadow"),
  array("border"=>"1px_solid_rgb:666")
  )))
Python:
CloudinaryImage("wood_chair.jpg").image(transformation=[
  {"width": 200, "height": 200, "effect": "saturation:50", "crop": "pad"},
  {"effect": "shadow"},
  {"border": "1px_solid_rgb:666"}
  ])
Node.js:
cloudinary.image("wood_chair.jpg", {transformation: [
  {width: 200, height: 200, effect: "saturation:50", crop: "pad"},
  {effect: "shadow"},
  {border: "1px_solid_rgb:666"}
  ]})
Java:
cloudinary.url().transformation(new Transformation()
  .width(200).height(200).effect("saturation:50").crop("pad").chain()
  .effect("shadow").chain()
  .border("1px_solid_rgb:666")).imageTag("wood_chair.jpg")
JS:
cl.imageTag('wood_chair.jpg', {transformation: [
  {width: 200, height: 200, effect: "saturation:50", crop: "pad"},
  {effect: "shadow"},
  {border: "1px_solid_rgb:666"}
  ]}).toHtml();
jQuery:
$.cloudinary.image("wood_chair.jpg", {transformation: [
  {width: 200, height: 200, effect: "saturation:50", crop: "pad"},
  {effect: "shadow"},
  {border: "1px_solid_rgb:666"}
  ]})
React:
<Image publicId="wood_chair.jpg" >
  <Transformation width="200" height="200" effect="saturation:50" crop="pad" />
  <Transformation effect="shadow" />
  <Transformation border="1px_solid_rgb:666" />
</Image>
Angular:
<cl-image public-id="wood_chair.jpg" >
  <cl-transformation width="200" height="200" effect="saturation:50" crop="pad">
  </cl-transformation>
  <cl-transformation effect="shadow">
  </cl-transformation>
  <cl-transformation border="1px_solid_rgb:666">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(200).Height(200).Effect("saturation:50").Crop("pad").Chain()
  .Effect("shadow").Chain()
  .Border("1px_solid_rgb:666")).BuildImageTag("wood_chair.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
  .width(200).height(200).effect("saturation:50").crop("pad").chain()
  .effect("shadow").chain()
  .border("1px_solid_rgb:666")).generate("wood_chair.jpg")
200x200 padded image with shadow and border

Another example, this time fitting the edited image to a 200x200 frame. The image is flipped horizontally and a watermark of Cloudinary's icon is added while increasing its brightness and making it semi-transparent.

URLRubyPHPPythonNode.jsJavaJSjQueryReactAngular.NetAndroidAll
URL:
https://res.cloudinary.com/demo/image/upload/w_200,h_200,c_fit,a_hflip/l_cloudinary_icon,w_0.4,fl_relative,g_north,x_15,y_35,a_4,e_brightness:200,o_70/wood_chair.jpg
Ruby:
cl_image_tag("wood_chair.jpg", :transformation=>[
  {:width=>200, :height=>200, :angle=>"hflip", :crop=>"fit"},
  {:overlay=>"cloudinary_icon", :width=>0.4, :flags=>"relative", :gravity=>"north", :x=>15, :y=>35, :angle=>4, :effect=>"brightness:200", :opacity=>70}
  ])
PHP:
cl_image_tag("wood_chair.jpg", array("transformation"=>array(
  array("width"=>200, "height"=>200, "angle"=>"hflip", "crop"=>"fit"),
  array("overlay"=>"cloudinary_icon", "width"=>0.4, "flags"=>"relative", "gravity"=>"north", "x"=>15, "y"=>35, "angle"=>4, "effect"=>"brightness:200", "opacity"=>70)
  )))
Python:
CloudinaryImage("wood_chair.jpg").image(transformation=[
  {"width": 200, "height": 200, "angle": "hflip", "crop": "fit"},
  {"overlay": "cloudinary_icon", "width": 0.4, "flags": "relative", "gravity": "north", "x": 15, "y": 35, "angle": 4, "effect": "brightness:200", "opacity": 70}
  ])
Node.js:
cloudinary.image("wood_chair.jpg", {transformation: [
  {width: 200, height: 200, angle: "hflip", crop: "fit"},
  {overlay: "cloudinary_icon", width: "0.4", flags: "relative", gravity: "north", x: 15, y: 35, angle: 4, effect: "brightness:200", opacity: 70}
  ]})
Java:
cloudinary.url().transformation(new Transformation()
  .width(200).height(200).angle("hflip").crop("fit").chain()
  .overlay("cloudinary_icon").width(0.4).flags("relative").gravity("north").x(15).y(35).angle(4).effect("brightness:200").opacity(70)).imageTag("wood_chair.jpg")
JS:
cl.imageTag('wood_chair.jpg', {transformation: [
  {width: 200, height: 200, angle: "hflip", crop: "fit"},
  {overlay: "cloudinary_icon", width: "0.4", flags: "relative", gravity: "north", x: 15, y: 35, angle: 4, effect: "brightness:200", opacity: 70}
  ]}).toHtml();
jQuery:
$.cloudinary.image("wood_chair.jpg", {transformation: [
  {width: 200, height: 200, angle: "hflip", crop: "fit"},
  {overlay: "cloudinary_icon", width: "0.4", flags: "relative", gravity: "north", x: 15, y: 35, angle: 4, effect: "brightness:200", opacity: 70}
  ]})
React:
<Image publicId="wood_chair.jpg" >
  <Transformation width="200" height="200" angle="hflip" crop="fit" />
  <Transformation overlay="cloudinary_icon" width="0.4" flags="relative" gravity="north" x="15" y="35" angle="4" effect="brightness:200" opacity="70" />
</Image>
Angular:
<cl-image public-id="wood_chair.jpg" >
  <cl-transformation width="200" height="200" angle="hflip" crop="fit">
  </cl-transformation>
  <cl-transformation overlay="cloudinary_icon" width="0.4" flags="relative" gravity="north" x="15" y="35" angle="4" effect="brightness:200" opacity="70">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(200).Height(200).Angle("hflip").Crop("fit").Chain()
  .Overlay("cloudinary_icon").Width(0.4).Flags("relative").Gravity("north").X(15).Y(35).Angle(4).Effect("brightness:200").Opacity(70)).BuildImageTag("wood_chair.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
  .width(200).height(200).angle("hflip").crop("fit").chain()
  .overlay("cloudinary_icon").width(0.4).flags("relative").gravity("north").x(15).y(35).angle(4).effect("brightness:200").opacity(70)).generate("wood_chair.jpg")
200x200 fitted flipped image with watermark

For a full list of additional Cloudinary's image manipulation options, see Image transformations.