API Documentation

All API requests are standard HTTP requests to REST-style URLs. The responses are either JSON, or an image (when fetching the result).

Authentication

The API uses standard HTTP basic access authentication. All requests to the API will need to include your API Credentials, with the API Id as the user and API Key as the password. Note that ClippingMagic.js only uses your API Id, to not reveal your API Key to your users.

Security

All requests must be made over HTTPS, and you must authenticate all requests.

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.

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.

Rate Limiting

Usage of the API is rate limited with generous allowances and no hard upper bound beyond your API credits.

During normal end-user-driven operation you are unlikely to run into any rate limiting as usage then tends to ebb and flow in a way that the service handles gracefully.

However, for batch jobs we recommend starting out with at most 5 threads, adding 1 new thread every 5 minutes until you have reached the desired level of parallelism. Please reach out before starting if you need more than 100 concurrent threads.

If you submit too many requests you will start getting 429 Too Many Requests responses. When this happens you should apply linear back off: on the first such response, wait 5 seconds until submitting the next request. On the second consecutive 429 response, wait 2*5=10 seconds until submitting the next request. On the third wait 3*5=15 seconds, etc.

You can reset the back off counter after a successful request, and you should apply the back off on a per-thread basis (i.e. the threads should operate independently of each other).

Try it out

All API actions come with html form / link examples you can try out right in your browser. The cURL examples use your API Credentials if you've signed up, so you can just copy-paste them into your terminal and run them.

Error JSON Object

We use conventional HTTP statuses to indicate success or failure of an API request, and include important error information in the returned Error JSON Object.

We strive to always return an Error JSON Object with any problematic request. However, it is always theoretically possible to have internal server failures that lead to a non-JSON error response.

Attributes

statusThe HTTP status of the response, repeated here to help with debugging.
codeClipping Magic internal error code.
messageHuman-readable error message, intended to be helpful in debugging.

If the HTTP status for your request is 200 then no Error JSON Object will be returned, and you can safely assume that the request broadly speaking succeeded.

Some HTTP Client libraries raise exceptions for HTTP statuses in the 400-599 range. You will need to catch those exceptions and handle them appropriately.

HTTP StatusMeaning
200-299

Success

301-303

When downloading results: you're being redirected to the actual result storage location. No Error JSON Object will be returned. You should configure your HTTP Client Library to follow redirects when downloading results.

400-499

There's a problem with the information provided in the request (e.g. a parameter was missing). Please review the error message to figure out how to fix it.

500-599

There's been a Clipping Magic-internal error. Wait a moment then try again, and if the problem persists please email us.

Example Error Response

{
  "error" : {
    "status" : 400,
    "code" : 1006,
    "message" : "Failed to read the supplied image. "
  }
}

Image JSON Object

Image records are represented in a uniform way with a JSON Object, returned by several of the API actions.

Attributes

id

Unique identifier for the image. Needed to let users edit the image and to download its result.

secret

The secret key needed to edit this image with ClippingMagic.js

resultRevision

Integer indicating the most recent revision available for download (0 = no result available yet).

Allows you to determine if there's a newer result available for this image than you've previously downloaded.

originalFilename

A string containing the filename provided when uploading the original image.

test

true means this is a test image which is free to process but the result will have a watermark.

false means this is a production image which costs credits to process, but the result will not have a watermark.

Example

{
  "id" : 2345,
  "secret" : "image_secret",
  "resultRevision" : 0,
  "originalFilename" : "image.jpg",
  "test" : false
}

Upload POST https://clippingmagic.com/api/v1/images

To upload an image, you do a standard HTTP POST file upload. This endpoint must be called from your backend, it cannot be called from your web page's javascript. Keep in mind that the Content-Type has to be multipart/form-data

Attributes

image

The image file to upload. Must be a .bmp, .gif, .jpeg, .png, or .tiff file.

The maximum image size is 16,777,216 pixels, which gets shrunk to 4,194,404 pixels. Please pre-shrink your images to the latter size or smaller before uploading.

Optional
test

Pass in true to indicate that this is a test image. Test images are free to process, but the result will have a watermark embedded.

Optional
format

By default no Auto-Clip result is generated and the Image JSON object is returned. This is the typical mode of operation when having a human operator review and potentially touch up the clip using ClippingMagic.js

format=result instead generates and fetches the Auto-Clip result.

format=clipping_path_svg instead generates the Auto-Clip result and fetches the Clipping Path (SVG).

format=alpha_mask_png instead generates the Auto-Clip result and fetches the Alpha Mask (PNG).

The id and secret are returned in the x-amz-meta-id and x-amz-meta-secret headers when fetching a non-JSON result.

Fetching the Image JSON Object doesn't charge your account; you're only charged when downloading production results.

You can upload images in test mode without a subscription. However, even though uploads do not cost credits, you still need a valid API subscription to upload production images via the API.

Try it out

Username = API Id, Password = API Key

cURL

$ curl https://clippingmagic.com/api/v1/images \
 -u 123:[secret] \ 
 -F image=@example.jpg

Assumes 'example.jpg' exists. Replace as appropriate.

Example Response

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

Download GET https://clippingmagic.com/api/v1/images/[image_id]

To download a result, you do a standard HTTP GET. A result must have been generated first. Typically this is done by letting your end user clip the image on your site using ClippingMagic.js

Test results are free to download, but include a watermark. Production results cost one credit to download the first time they're downloaded; repeat downloads are free.

If there is a result available, you will be redirected to it (results are stored on Amazon S3), so be sure your client library is configured to follow redirects.

The x-amz-meta-resultrevision response header indicates the resultRevision of the downloaded result, and the Content-Disposition header indicates the result filename including the extension: .jpeg for results with opaque backgrounds, .png for results with transparent backgrounds.

If there is no result available, then you will get an error response.

Arguments

image_id

Baked into the URL

You'll need to insert the id value that was returned in the Upload call.

Optional
format

By default the result image is returned.

format=clipping_path_svg instead fetches the Clipping Path (SVG).

format=alpha_mask_png instead fetches the Alpha Mask (PNG).

format=json instead fetches the Image JSON Object. Useful if you want to check on the resultRevision, or if you lost the image secret.

Fetching the Image JSON Object doesn't charge your account; you're only charged when downloading production results.

Username = API Id, Password = API Key

cURL

$ curl https://clippingmagic.com/api/v1/images/2345 \
 -u 123:[secret] \ 
 -LOJ

Example JSON Response

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

List GET https://clippingmagic.com/api/v1/images

To fetch a list of your Image JSON Objects, you do a standard HTTP GET.

Arguments

Optional
limit

Number of records to fetch. Defaults to 20 (Min 1, max 100).

Optional
offset

Offset to use in the list of records (defaults to 0).

Response Attributes

images

An array of Image JSON Objects.

limit

The limit actually used when producing the result.

offset

The offset actually used when producing the result.

Username = API Id, Password = API Key

cURL

$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \
 -u 123:[secret]

Example Response

{
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }, {
    "id" : 2346,
    "secret" : "image_secret2",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  } ],
  "limit" : 2,
  "offset" : 0
}

Delete POST https://clippingmagic.com/api/v1/images/[image_id]/delete

To delete an image, you do a standard HTTP POST to its delete-URL.

This is a slight deviation from standard REST practice to handle the reality that a lot of HTTP client libraries don't support the HTTP DELETE verb, while avoiding the mess of having multiple ways of doing the same thing.

Arguments

image_id

Baked into the URL

You'll need to insert the id value that was returned in the Upload call.

Response Attributes

image

The deleted Image JSON Object.

Try it out

Username = API Id, Password = API Key

cURL

$ curl https://clippingmagic.com/api/v1/images/2345/delete \
 -u 123:[secret] \ 
 -X POST

Example Response

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

Account GET https://clippingmagic.com/api/v1/account

Fetch basic information about your account, such as your subscription status and number of credits left.

Arguments

None

Response Attributes

subscriptionPlan

The subscription plan you're currently subscribed to, or 'none'.

subscriptionState

The state of your current subscription ('active' or 'pastDue') or 'ended' if not subscribed.

credits

The number of credits left in your account. 0 if not currently subscribed.

Username = API Id, Password = API Key

cURL

$ curl "https://clippingmagic.com/api/v1/account" \
 -u 123:[secret]

Example Response

{
  "subscriptionPlan" : "none",
  "subscriptionState" : "ended",
  "credits" : 0
}