Malabi – online image background remover, whitener and background editor Bulk background removal | Bulk Image background remover API | Malabi

Malabi Background Remover API

The most accurate bulk background removal API

Overview

Malabi is a unique and innovative tool for removing the background from images. It was designed to provide e-commerce sellers with a fast, accurate and most importantly automatic solution to enhance their images and increase conversion rates.

Integrating the Malabi Background Remover API into your platform will allow your users to enjoy the benefits of Malabi with the click of a button.
The Malabi API works in two main phases:

  • Automatic background removal – the original image is sent to the Malabi servers, automatically enhanced and sent back to the user
  • Manual fine tuning – this is an interactive process in which the user can manipulate the result by adding hints for the Malabi algorithm to follow

The advanced algorithm behind Malabi will automatically detect the object in the image and will extract it from the background. The second phase is available in order to allow the user to help Malabi in cases where it fails to detect the object automatically.

The RESTful API uses simple http/https calls (GET, POST, PUT), so any client technology may be used. We also provide a simple editing tool, built as a JavaScript widget inside an iFrame. We encourage you to use this widget in your integration in order to avoid the complexity of building your own UI for this process.

Follow this quick and simple guide to integrate the Malabi Background Remover API into your system.

Getting Started

A typical usage will include both backend and frontend integrations:

  1. The user uploads a new image onto your website
  2. Your backend server sends a request to the Malabi Background Remover API
  3. Malabi processes the image and returns a response
  4. The result is presented to the user
  5. ​The user can touch-up the image using the client-side tool

To get your free API key and id, click the button below. You can use these credentials until you complete your integration, and purchase a paid subscription plan only when you’re ready to go.

Your API credentials:

API key :      <== keep this key secret!

API id :     

IMPORTANT: keep your API key safe and secret. This is the authentication used to access all of your images and future billings.

 

Once you have your key and id, you can start making test calls by calling the domain api.malabi.co/test instead of api.malabi.co/v1
Test is limited to 200 images per month, and images returned by test calls will include a watermark.

Backend Integration

Normally, the Malabi background removal API should receive a link to an image that is publicly available online. If however, your images are not stored online (or not publicly available), the API provides a simple way to upload your images (described below).

Start by making a POST call from your backend server to Malabi Background Remover API. This call will include your secret API key, so it is crucial that it will not be sent directly from your client side (otherwise, your secret API key will be visible to all, and others will be able to access your images and use your credits).

The call should look like the example below (see full API Calls documentation).

 

The request can be carried out synchronously or asynchronously. To make an asynchronous call pass the callback_url parameter:

 

In a synchronous call, an HTTP response will be returned after the image processing is done and the result image is ready.

In an asynchronous call, an HTTP response will be returned immediately but the result_image_url will only be valid after the image processing in done (a few seconds), at which point you will receive a POST call to the callback_url you have provided.

The response body (to both types of calls), as well as the callback body, will look like this (see full API Calls documentation for all possible error code and responses):

 

Once you have received a response for a synchronous call or the callback to an asynchronous call, the result_image_url will hold your result image.

The callback_url parameter should point either to a server with a public access (ready to receive POST calls from Malabi) or an AWS Simple Queue Service opened for public ‘SendMessage’. In the later case, Malabi will send a message containing the callback body to the queue.

Here are two diagrams showing the two possible types of flows.

Changing the settings of the result image – background and shadows:

You can control several parameters of the result image by changing the ‘settings’ block in the body of the POST request.

 

To control the shadow – set the ‘shadow’ parameter to:

  • ‘drop’ – a synthetic shadow will be added. (default)
  • ‘none’ – no shadow will be added.
  • If the ‘shadow’ parameter has been set to ‘drop’, use any of the following parameters to modify the appearance of the shadow:

    ‘shadow_shift_x’ – To control how much the shadow is shifted horizontally in respect to the object, set this parameter to a negative value to shift left, or to a positive value to shift right. The default value is 1, and the valid range is between -5 and 5.

    ‘shadow_shift_y’ – To control how much the shadow is shifted vertically in respect to the object, set this parameter to a negative value to shift up, or to a positive value to shift down. The default value is 1, and the valid range is between -5 and 5.

    ‘shadow_opacity’ – To control the opacity of the shadow, set this parameter to a higher value to make the shadow more transparent (and less visible), or to a lower value to make it more opaque. The default value is 35, and the valid range is between 0 and 100.

    ‘shadow_blur’ – To control how blurred the shadow will appear, set this parameter to higher value for a more “fuzzy” shadow, or to a lower value for a sharper shadow. The default value is 5, and the valid range is between 0 and 20.

     

    To control the background of the image – set the ‘background’ parameter to:

  • ‘white’ – to set a white background. (default)
  • ‘color’ – to set the background to any color. If this value is selected, the background_image_color parameter should also be set.
  • ‘transparent’ – to set a transparent background (the result image will be a transparent PNG image)
  • ‘image_stretch’ – to use a given image as the background. The background image will be stretched to the size of the input image (the aspect ratio of the original background image will not be maintained). If this value is selected, the background_image_url parameter should also be set.
  • ‘image_fill’ – to use a given image as the background. The background image will be enlarged, preserving its original aspect ratio, to cover the whole background – if the aspect ratios of the background image and the product image are different, the background image will be truncated. If this value is selected, the background_image_url parameter should also be set.
  • ‘background_image_url’ – To use a given image as the background (after setting the ‘background’ parameter to ‘image_fill’ or ‘image_stretch’), provide the url of the desired background image in this parameter.

    ‘background_image_color’ – To control the color of the background (after setting the ‘background’ parameter to ‘color’), specify the color that you would like to use in this parameter. The value should be a valid hex color code (format: #RRGGBB), e.g. #FF0000 for red, #0000FF for blue, #808080 for grey.

     

    Here is an example of an asynchronous call for a transparent image with no shadow:

     

    Here is an example of a synchronous call for a result image with a teal background and a shadow that is shifted to the left, and a lower transparency level (higher opacity) than the default:

     

    Changing the settings of the result image – brightness, contrast and colors:

    Various enhancements can be made to the appearance of the result image, by improving its brightness and contrast (either manually or automatically), or by adjusting the vividness of its colors. Use any of the following parameters to select which image properties you would like to change (the default value of all of these parameters is 0 for the numeric ones, or false for the Boolean ones):

    ‘brightness’ – Select any value in the range [-50,50] to increase or decrease the brightness of the image. This can be used to solve problems such as poor lighting, or over-exposed images.

    ‘auto_brightness’ – Set the value of this parameter to ‘true’ if you would like the system to automatically correct the brightness of the image. Note that setting this parameter to ‘true’ will override any value set in the ‘brightness’ parameter.

    ‘contrast’ – Select any value in the range [0,50] to increase the contrast of the image.

    ‘auto_contrast’ – Set the value of this parameter to ‘true’ if you would like the system to automatically correct the contrast of the image. Note that setting this parameter to ‘true’ will override any value set in the ‘contrast’ parameter.

    ‘sharpness’ – Select any value in the range [-50,50] to increase or decrease the sharpness of the image. This can be helpful in case the image is out of focus, or is of poor quality.

    ‘saturation’ – Select any value in the range [-50,50] to increase or decrease the saturation of the image. Positive values will increase the intensity of all colors in the image, negative ones will decrease it. Increasing the saturation can help when the image colors are too dull.

    ‘vibrance’ – Select any value in the range [-50,50] to increase or decrease the saturation of the image. Similar to the ‘saturation’ parameter, vibrance also controls the intensity of the colors in the image. However, vibrance only increases the intensity of the weaker colors in the image, and colors that are already intense will be less affected.

    ‘color_temperature’ – Select any value in the range [-50,50] to increase or decrease the color temperature of the image. This parameter is useful for correcting wrong lighting in the image, by making the image warmer (more red hue) or colder (more blue hue).

     

    Here is an example of an API call that generates a result image with automatically corrected brightness and contrast, with strongly saturated colors, and with some sharpening:

     

    Processing images that are not publicly available online:

    The Malabi background removal API provides a simple way to upload your images in the processing call itself. Follow the instruction above, but instead of using the POST method, use the PUT method, to indicate to the API that you are uploading an image. The payload (body) of the call will be a binary representation of the image. The ‘content-type’ header should state the type of the image.

    To make an asynchronous call, add a ‘callback-url’ header (note that we use a hyphen in this case). Uploading the file will be done synchronously, of course, and then the processing itself will be carried out asynchronously.

    Note that using this approach, you will not be able to define the setting of the result image (shadow, background type etc.) in the processing call.

    The call should look like the example below (see full API Calls documentation).

     

    Frontend Integration

    After an image was processed and a response was returned, you can present the result of the automatic processing to your user.

    The user may wish to touch-up the result or change some settings, such as transparency or shadow. For that purpose, we have created a client side JavaScript which can be easily integrated into your website.

    This script holds all of the communication with the Malabi Background Remover API and will handle all outgoing edit calls and incoming edit responses. It will append a div tag and an iframe tag to your document containing the editor along with all required controls.

    You can find an example implementation of the frontend here: https://api.malabi.co/v1/toyExample.html 

    Start by adding the following 3 JavaScript files to your document:

    The first two will load Jquery and Materialize libraries. These are commonly used libraries, which may already be included in your code.

    The third line will load Malabi.min.js.

    Now add a simple a short script calling the malabi.init() function. This function must be called once. You cannot edit any images before it was called. A good practice will be to add it to the $(documet).ready() function (called by Jquery).

    ​The malabi.init() function expects a single object containing your API id (DO NOT pass your API secret key here).

    Now let’s add a call to malabi.edit(). This will open a modal window containing the editor.

    The function expects an image id and an image secret (taken from the response to the POST request). The image secret ensures that no one could view or change your images without your permission.

    The function also takes a third parameter, a callback function to be called after the user has saved a new result. The callback function will receive an image object (like the one in the POST call response).

     

    That’s it – you should now be able to run your code and see the full functionality of the Malabi background removal API.

    Zero Integration Editor

    Malabi also offers a Zero Integration Editor. This option usually suits a system with no UI, but can also prove useful in case your system is closed for UI changes or you are looking for a quick and easy solution.

    Note that with this option the user will be directed to an external website, which you have no control over. Each call for edit will take a bit longer to load, since the JavaScript is reloaded on each request.

    Using the Zero Integration Editor is as easy as structuring a URL with a query holding the information, and passing it to your end user.

    The following parameters can be passed to the Zero Integration Editor:

  • id (mandatory) – the id of the image, returned from the POST or PUT call used to upload the image.
  • secret (mandatory) – the secret of the image, returned from the POST or PUT call used to upload the image.
  • apiId (mandatory) – the Malabi API id assigned to you when you first clicked “Get Key”. Normally, this value should be the same for all of your images.
  • callback (optional) – A URL to be called after the editing process has been completed. It must be URL encoded and cannot be a URL to an AWS simple queue service. It should be a publicly available URL ready to accept a POST call holding an image data (formatted the same way as the other responses and callbacks).
  • onSave (optional) – An optional action to be performed after the editing process has been completed. Valid values are:
    – ‘back’ – go back to the previous browser page
    – ‘showImage’ – display the result
    – ‘download’ – immediately start downloading the result
    – ‘none’ – do nothing
    If the ‘onSave’ parameter is omitted, its value defaults to ‘back’.
  • Other Web Framework Support

    The Malabi background removal editing client uses Materialize framework by default. If your website uses Bootstrap, it is advisable to use the editor’s Bootstrap version. to do so, add “framework”: “bootstrap” to the initialization object and change the scripts loaded by the page.

    You can find an example of the frontend integration with Bootstrap here example with Bootstrap

    Language Localization

    You can change the text in the editing popup window by passing the “local” parameter in the call to Malabi.init().

    The languages currently available are:

    • de – German
    • es – Spanish (Latin America)
    • fr – French
    • it – Italian
    • jp – Japanese
    • ko – Korean
    • po-br – Portuguese (Brazil)
    • ru – Russian
    • zh-ch – Chinese (China)
    • zh-hk – Chinese (Hong-Kong)

    If you would like the pop-up to be displayed in a language that does not appear in the above list, you can create your own localization by passing an object that contains a mapping of the following keys.

    Service Agreement​

    By using the Malabi Background Remover API you accept the terms of its services agreement.
    © Copyright ArtInCam Ltd. (2016). All rights reserved.

    Image Requirements

    Images sent to Malabi as input images must meet the following limitations

    • Image musk either be publicly accessible or located on S3 and accessible to Malabi servers
    • Supported types – jpeg (24 or 32 bit), png (24 or 32 bit)
    • Maximum image size – images larger than 4 Mega-Pixels will be resized to 4 Mega-Pixels
    • Minimum image size – 70 pixels on each dimension

    News and Updates

    July 7th 2019 API now includes advanced Color Adjustment features. New feature set includes Auto Brightness and Contrast, Manual Brightness, Contrast, Vibrance, Color Temperature, Sharpness and Saturation.
    June 20th 2019 PRO and ENTERPRISE level customers can now process images with unlimited size
    May 21st 2019 Introducing the enterprise level security and privacy suite
    April 4th 2019 A new version of AI neural network – for more accurate background removal