Server API

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

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

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

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",
  "imageCategoryUser" : "Photo",
  "imageCategoryAi" : "Photo",
  "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 when uploading binary files.

Parameters

The input image must be provided as one of:

image
Binary

A binary file.

image.base64
String

A base64-encoded string. The string can be at most 1 megabyte in size.

image.url
String

A URL to fetch.

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 maxPixels below. Please pre-shrink your images to the latter size or smaller before uploading.

test
Boolean
true, false

Pass in true to indicate that this is a test image.

Omit or pass in false for production images.

Test images are free to process, but the result will have a watermark embedded.

format
Enum
json, result, clipping_path_svg, alpha_mask_png

format=json (default): no Auto-Clip result is generated and the Image JSON object is returned. Use this when there's a human operator reviewing and potentially touching up the result using ClippingMagic.js.

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

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

format=alpha_mask_png generates the Auto-Clip result and fetches the Alpha Mask (PNG). The Alpha Mask has the same size as the input image. Applying it to the input image does not get you the result, as the Edge Guard and Halo Scrubber improve the boundary colors.

The id and secret are returned in the x-amz-meta-id and x-amz-meta-secret headers when fetching a non-JSON result. Be sure to store these so you can review and edit your result using ClippingMagic.js. See all headers included in the response

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.

Be sure to include the '#'.

Configure the processing parameters:

processing.mode
Enum
auto, photo, graphics, scan

Control the processing mode used for your image.

Default: auto

processing.autoClip
Boolean
true, false

Enable (default) or disable Auto-Clip when editing the image in the web app.

Disable if want to upload images via the API, but then do free-form clipping of something other than the obvious foreground (if any).

Default: true

processing.autoHair
Boolean
true, false

Enable (default) or disable the application of an automatic hair mask.

Default: true

processing.allowGraphicsMode
Boolean
true, false

Enable (default) or disable the automatic selection of Graphics Mode.

This setting does not apply when format=json.

Default: true

processing.allowScanMode
Boolean
true, false

Enable (default) or disable the automatic selection of Scan Mode.

This setting does not apply when format=json.

Default: true

Configure the color levels:

colors.auto
Boolean
true, false

Automatically adjust the color levels to enhance contrast.

Default: false

colors.brightness
Integer
-100 to 100

Adjust the brightness of the output image.

Default: 0

colors.shadows
Integer
-100 to 100

Adjust the shadows of the output image. Positive values mean darker shadows.

Default: 0

colors.highlights
Integer
-100 to 100

Adjust the highlights of the output image. Positive values mean lighter highlights.

Default: 0

colors.temperature
Integer
-100 to 100

Adjust the color temperature of the output image. Positive values mean warmer colors.

Default: 0

colors.saturation
Integer
-100 to 100

Adjust the saturation of the output image. Positive values mean more saturation.

Default: 0

Configure the removal of a color from the background that is cast on the foreground, such as with a green screen:

colorCast.auto
Boolean
true, false

Automatically determine the background color to remove from the foreground.

Default: false

colorCast.color
#RRGGBB
#A84400

The manually-specified background color to remove from the foreground.

Omit to detect automatically.

colorCast.foregroundGuard
Float
0.0 to 20.0

Larger values reduce the impact of color cast removal on genuine foreground colors that are similar to the cast color but more saturated than those being removed.

Default: 4.0

Configure the white balance:

whiteBalance.auto
Boolean
true, false

Automatically determine the reference color to use to perform white balancing.

Default: false

whiteBalance.color
#RRGGBB
#968386

The manually-specified white balance color.

Omit to detect automatically.

Configure the finishing touches:

effects.dropShadow
[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]
30 30 25 0.75

Add a drop shadow effect to the clipped result.

effects.reflection
[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]
0 200 0.5

Add a reflection effect to the clipped result.

Configure the edge parameters:

edges.corners
Boolean
true, false

Use (default) or disable the Corner Guard.

edges.smoothing
Enum
smart, fixed

Use smart (default) or fixed smoothing.

edges.smoothingLevel
Float
0.0 to 5.0

Configure the amount of smoothing applied to the result.

Default 1.0

edges.feathering
Enum
fixed, auto, local

Use auto (default), local, or fixed feathering.

edges.featheringRadiusPx
Float
0.0 to 6.0

Configure the amount of feathering applied to the result.

Default: 1.0

edges.offsetPx
Float
0.0 to 10.0

Configure the boundary offset applied to the result.

Default: 0.0

Fit the output to the result

fit.toResult
Boolean
true, false

Turn fit to result on or off (default).

If it's off the rest of the parameters in this section are effectively ignored.

fit.paddingPercent
Float
0.0 to 35.0

The padding to apply around the fitted result, as a percentage of the result size.

Default: 5.0

fit.paddingPixels
Integer
0 to 250

The padding in pixels to apply around the fitted result.

If not specified, a percent padding is used instead.

fit.objectSize
Enum
small, medium, large

You can specify a synthetic size for your object. This is useful for eCommerce where you may want to give the shopper a rough sense of the size of the product relative to other products.

Default: large (= the result is not resized)

fit.verticalAlignment
Enum
top, middle, bottom

Specify how your result should be aligned if there's excess vertical space.

Also applies when distributing excess space due to aspect ratio or target size enforcement, see below.

Default: middle

fit.shadows
Enum
ignore, pad, tight

You can ignore the shadows, pad evenly on both sides to fit the shadows, or tightly to only add padding where it's needed to not cut off the shadow.

Default: pad

fit.rotationDeg
Float
-360.0 to 360.0

Rotate the image. Positive values are counterclockwise.

Default: 0

Control the result size and aspect ratio:

result.aspectRatio
[width:float, >0]:[height:float, >0]
4:3

Ensure that the result has the provided aspect ratio.

fit.verticalAlignment controls how excess vertical space is distributed.

Default: not applied

result.targetSize
[width:int, >0] [height:int, >0]
400 300

Ensure that the result has the provided size.

fit.verticalAlignment controls how excess vertical space is distributed.

Default: not applied

result.allowEnlarging
Boolean
true, false

Controls if the result is allowed to become larger than the input image or not.

Default: false

Control the output options:

output.dpi
Integer
1 to 4000

Set the DPI information embedded in the result.

DPI information is not included if the result is web optimized.

Default: 72

output.colorSpace
Enum
sRGB, AdobeRGB, AppleRGB, ColorMatchRGB

Set the color space information embedded in the result.

Color space information is not included if the result is web optimized.

Default: sRGB

output.jpegQuality
Integer
1 to 100

Configure the quality setting used when producing a JPEG result.

Default: 75

output.pngOptimization
Enum
none, lossless, lossy

Configure web optimization of PNG results.

Default: lossless

output.jpegOptimization
Enum
none, enabled

Configure web optimization of JPEG results.

Default: enabled

output.opaqueFileFormat
Enum
jpeg, png

Configure the file format to use for opaque results.

Default: jpeg

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


Format: '#RRGGBB'



Format: '#RRGGBB'

Format: '#RRGGBB'


Format: '[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]'
Example: 30 30 25 0.75

Format: '[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]'
Example: 0 200 0.5




Format: '[width:float, >0]:[height:float, >0]'
Example: 4:3

Format: '[width:int, >0] [height:int, >0]'
Example: 400 300

Username = API Id, Password = API Key

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" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }
}

Download 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 id value that was returned in the Upload call.

Optional
format

format=result (default) fetches the result image.

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.

Response Headers

When format isn't json we provide key information in these HTTP response headers

x-amz-meta-id
Example: 2345

Your image's id.

x-amz-meta-secret
Example: image_secret

Your image's secret.

x-amz-meta-resultrevision
Example: 1

The resultRevision you're fetching in this request.

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''image_clipped_rev_0.png

The result filename, including the extension.

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",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "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.

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 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",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }, {
    "id" : 2346,
    "secret" : "image_secret2",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  } ],
  "limit" : 2,
  "offset" : 0
}

Delete 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 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",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "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.

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