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.

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.

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.

Attributes

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

Example Error Response

{
  "error" : {
    "status" : 400,
    "code" : 1006,
    "message" : "Failed to read the supplied image. "
  }
}
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.

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
}

To upload an image, you do a standard HTTP POST file upload.

Keep in mind that the Content-Type has to be multipart/form-data

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.

Arguments

image

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

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

test

Optional

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.

Response Attributes

image
The Image JSON Object.

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
  }
}

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.

format

Optional

By default the result image is returned. However, if you specify format=json, then you'll get the Image JSON Object back instead. 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.

Try it out

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
  }
}

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

Arguments

limit

Optional

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

offset

Optional

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.

Try it out

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
}

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
  }
}

Javascript Error :-(


Please help us fix this issue!