API Overview

Clipping Magic offers a REST-oriented Web API for automating the uploading of images and downloading of results. You can integrate the Clipping Magic Editor into your website with ClippingMagic.js to let your users remove backgrounds right on your website.

The API is especially useful for websites needing to remove backgrounds from user-provided images, and for eCommerce websites with a staff of graphic designers removing image backgrounds on a flow of images.

To use the API you will need an API Key and some web programming skills.

Theory Of Operation

End User Removes Backgrounds

The typical scenario is that an end-user uploads an image to your site, and you want to enable the user to remove the background from that image as part of your site image workflow. The steps you would normally take are:

  1. Your user uploads an image to your website.

  2. Your backend server passes the image to ClippingMagic.com via the backend API and gets an image id and secret back.

    Your web client cannot upload the image directly to ClippingMagic.com for security reasons.

  3. Your backend server passes the image id and secret to your web client. If you're using AJAX this information can be included in the response to the image upload. Otherwise it can be embedded in the webpage you render in response to the user's image upload.

  4. On your site, let the end-user remove the background with ClippingMagic.js, by having your javascript code invoke the Edit A Single Image workflow with the image id and secret from the previous step.

  5. Upon receiving the result-generated callback from ClippingMagic.js your javascript code notifies your backend to download the result for that image.

  6. Your backend server downloads the result and continues with the subsequent steps in your site-specific workflow.

Internal Staff Removes Backgrounds

The typical scenario is that you have a long list of images that need to be processed, and some staff to process them. The steps you would normally take are:

  1. Upload a batch of images one at a time to ClippingMagic.com via the backend API. Get and store the respective image ids and secrets.

  2. In your internal system, allocate images to workers in suitable batches. Then let each worker remove the backgrounds from a batch with ClippingMagic.js, using the Edit Multiple Images In Sequence workflow with the corresponding image ids and secrets from step 1.

    Typical batch sizes vary between 10 and 100 depending on volume and the particulars of your images.

  3. Upon receiving the result-generated callbacks from ClippingMagic.js notify your backend to download the result for that image.

  4. Rinse and repeat.

Backend vs Frontend

Note that all upload and download operations happen on the backend, but all clipping operations happen in the web client (frontend) using ClippingMagic.js.

This split safeguards your API Key, while enabling a seamless end-user experience on your site.

Details

  • You can use the API in test mode without signing up for a subscription, but in order to use it for real you will need to sign up for an API subscription.
  • Sorry, regular website subscriptions do not come with API access.
  • You can view and edit all images uploaded through the API on the main Clipping Magic website (when logged in as the API user) and vice versa. This can be very useful when debugging, or if you need to review the API image flow.
  • While there is no rate limiting put on the API, please be courteous and do not hit it too hard.
  • Your http client library must support Server Name Indication (SNI) to successfully make requests. If you're getting weird handshake errors, this is most likely it.

Feedback

Is something missing or insufficiently documented? Does your implementation require additional features?

Be sure to let us know and we'll try to sort it out!