All API requests are standard HTTP requests to REST-style URLs. The responses are either JSON, or an image (when fetching the result).
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 Secret as the password. Note that ClippingMagic.js only uses your API Id, to not reveal your API Secret to your users.
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.
Note that all upload and download operations happen on the backend, but all review and editing operations happen in the Smart Editor.
This split safeguards your API Key, while enabling a seamless end-user experience on your site.
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).
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 |
|
|---|---|
| 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. |
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 Status | Meaning |
|---|---|
200-299
|
Success |
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. |
Recent API errors are listed on your account page for your debugging convenience.
Example Error Response
{
"error" : {
"status" : 400,
"code" : 1006,
"message" : "Failed to read the supplied image. "
}
}
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 |
| 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 |
|
Example
{
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
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 when uploading binary files.
|
Parameters |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
The input image must be provided as one of:
Must be a .bmp, .gif, .jpeg, .png, or .tiff file.
The maximum image upload size (= width × height) is 33,554,432 pixels, which gets shrunk to 4,194,404 pixels unless overridden by |
|||||||||||||||
|
test
Boolean true, false
|
Pass in
Omit or pass in Test images are free to process, but the result will have a watermark embedded. |
||||||||||||||
|
format
Enum json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png
|
The Fetching the Image JSON Object doesn't charge your account; you're only charged when downloading production results. |
||||||||||||||
|
maxPixels
Integer 1000000 to 26214400
|
Changes the max image size (= width × height) used when resizing the image after upload. Default: 4,194,404 pixels |
||||||||||||||
|
background.color
#RRGGBB #0055FF
|
Omit to use a transparent background and get a PNG result. Include to get an opaque background of the specified color and an output.opaqueFileFormat result (default JPEG). Be sure to include the '#'. |
||||||||||||||
|
Configure the processing parameters:
|
|||||||||||||||
|
Configure the color levels:
|
|||||||||||||||
|
Configure the removal of a color from the background that is cast on the foreground, such as with a green screen:
|
|||||||||||||||
|
Configure the white balance:
|
|||||||||||||||
|
Configure the finishing touches:
|
|||||||||||||||
|
Configure the edge parameters:
|
|||||||||||||||
|
|||||||||||||||
|
Control the result size and aspect ratio:
|
|||||||||||||||
|
Control the output options:
|
|||||||||||||||
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 Secret
cURL
$ curl "https://clippingmagic.com/api/v1/images" \ -u 123:[secret] \ -F 'image=@example.jpg' \ -F 'test=true'
Assumes 'example.jpg' exists. Replace as appropriate. Line with 'test=true' optional.
Example Response
{
"image" : {
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
}
GET https://clippingmagic.com/api/v1/images/[imageId]
To download a result, you do a standard HTTP GET. A result must have been generated first.
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 no result available, then you will get an error response.
|
Parameters |
|
|---|---|
| imageId |
Baked into the URL
You'll need to insert the |
|
Optional
format |
Fetching the Image JSON Object doesn't charge your account; you're only charged when downloading production results. |
|
Response Headers
When |
|
|---|---|
x-amz-meta-id
Example: 2346
|
Your image's |
x-amz-meta-secret
Example: image_secret1
|
Your image's |
x-amz-meta-resultrevision
Example: 1
|
The Every time a new result is generated this counter is incremented. |
x-amz-meta-width
Example: 3200
(only included for format=result)
|
The width in pixels of the result you're fetching in this request. |
x-amz-meta-height
Example: 2400
(only included for format=result)
|
The height in pixels of the result you're fetching in this request. |
Content-Disposition
Example: attachment; filename*=UTF-8''example_image1_clipped_rev_0.png
|
The result filename, including the extension. |
Try it out
Username = API Id, Password = API Secret
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346" \ -u 123:[secret] \ -LOJ
Example JSON Response
{
"image" : {
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
}
GET https://clippingmagic.com/api/v1/images
To fetch a list of your Image JSON Objects, you do a standard HTTP GET.
|
Parameters |
|
|---|---|
|
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 |
| offset |
The |
Try it out
Username = API Id, Password = API Secret
cURL
$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \ -u 123:[secret]
Example Response
{
"images" : [ {
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}, {
"id" : 2347,
"secret" : "image_secret2",
"resultRevision" : 0,
"originalFilename" : "example_image2.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
} ],
"limit" : 2,
"offset" : 0
}
POST https://clippingmagic.com/api/v1/images/[imageId]/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.
|
Parameters |
|
|---|---|
| imageId |
Baked into the URL
You'll need to insert the |
|
Response Attributes |
|
|---|---|
| image |
The deleted Image JSON Object. |
Try it out
Username = API Id, Password = API Secret
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \ -u 123:[secret] \ -X POST
Example Response
{
"image" : {
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
}
GET https://clippingmagic.com/api/v1/account
Fetch basic information about your account, such as your subscription status and number of credits left.
|
Parameters |
|
|---|---|
| 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 API credits left in your account. 0 if not currently subscribed, or subscribed to a non-API plan. |
Try it out
Username = API Id, Password = API Secret
cURL
$ curl "https://clippingmagic.com/api/v1/account" \ -u 123:[secret]
Example Response
{
"subscriptionPlan" : "none",
"subscriptionState" : "ended",
"credits" : 0
}