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.

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.

Example Error Response

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

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.

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

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.

Response Attributes

image

The Image JSON Object.

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

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
}