Hosted Smart Editor

The easiest way to integrate the Clipping Magic Smart Editor into your custom workflow.

Integration Steps

Be sure to read the Quick Start first.

  1. Upload an image using the Server API.

  2. Create a Hosted Smart Editor URL and refer your human operator to it, where they clip the images you specified.

  3. After clipping all images, your human operator's browser navigates to the specified Return URL with an HTTP POST containing the relevant information about the clipping session.

If you need a white label solution or a callback for every image clipped, then please see the White Label Smart Editor.

Hosted Smart Editor URL https://clippingmagic.com/api/v1/hosted/[apiId]

You can create a simple URL and have your human operator open it in their browser to have them review and edit one or more of your images.

The Hosted Smart Editor URL supports the following parameters:

images
id1:secret1,id2:secret2,...
123:abc,456:def
Required

The images to clip. A comma-separated list of id:secret pairs. You get these by uploading an image using the Server API.

returnUrl
String
Required

When your human operator has finished clipping, their browser will issue an HTTP POST to this URL. See below for the details.

useStickySettings
Boolean
true, false

If you pass in useStickySettings=true the editor will use the sticky settings currently configured for the user whose API key was used to upload the image.

This lets you configure the base clipping settings once, and then have them apply across all the images you edit.

Read about how to configure the sticky settings

Pre-Crop is not available via the API, but you can configure the Image Size Limit in the API upload call.

locale
String

The display language to use for the editor. Defaults to English if omitted. Valid values are:

CodeDisplay Language
en-US English
de-DE Deutsch (German)
es-ES Español (Spanish)
fr-FR Français (French)
hi-IN हिन्दी (Hindi)
id-ID Indonesia (Indonesian)
it-IT Italiano (Italian)
ja-JP 日本語 (Japanese)
ko-KR 한국어 (Korean)
pl-PL Polski (Polish)
pt-BR Português (Portuguese)
ru-RU Русский (Russian)
th-TH ไทย (Thai)
tr-TR Türkçe (Turkish)
vi-VN Tiếng Việt (Vietnamese)
zh-Hans-CN 简体中文 (Chinese)
zh-Hant-TW 繁體中文 (Chinese)

Modern browsers allow very long URLs, but if you need to support legacy browsers and clip more than 30 images in one session, then you can submit them in a POST instead of using a direct link.

Single Image URL Example


https://clippingmagic.com/api/v1/hosted/123?images=2345:image_secret&returnUrl=https%3A%2F%2Fclippingmagic.com%2Fapi%2FreturnUrlExample

When specifying a single image the editor doesn't have a 'skip' button and doesn't show the number of images remaining to clip.

Multi-Image URL Example


https://clippingmagic.com/api/v1/hosted/123?images=2345:image_secret,2346:image_secret2&returnUrl=https%3A%2F%2Fclippingmagic.com%2Fapi%2FreturnUrlExample

When specifying multiple images the editor has a 'skip' button and shows the number of images remaining to clip.

Return URL

When your human operator has finished clipping, their browser will issue an HTTP POST to the Return URL you specify. That POST will contain a single parameter in its body: clippingMagicJson. When you parse the contents of that parameter, they unpack to a JSON object with information about what images were clipped. You can then download the now available results by using the Download Server API.

event
Enum
editor-exit, error

editor-exit means the clipping session concluded successfully.

error means an error occurred and that error below is populated.

images
[{"id":1,"secret":"secret1"},{"id":2,"secret":"secret2"},{"id":3,"secret":"secret3"},{"id":4,"secret":"secret4"}]
An array with the images provided in the Hosted Smart Editor URL.
clipped
[{"id":1,"secret":"secret1"},{"id":2,"secret":"secret2"}]
An array with the images actually clipped in this session, i.e. the images where the human operator clicked 'Done' in the editor.
skipped
[{"id":3,"secret":"secret3"},{"id":4,"secret":"secret4"}]
An array with the images skipped in this session, i.e. the images where the human operator clicked 'Skip' in the editor.

If event=error, there will be an error member object populated with:

error.status
Integer
HTTP-status-like code. 4xx means a caller error. 5xx means an internal server error.
error.code
Integer
Number that uniquely identifies the error that occurred.
error.message
String
Human-readable error message that describes the error that occurred.

You'll either need to disable any CSRF checks or add the CSRF token to the Return URL for the POST to succeed.

If your human operator closes their browser or you use an unparseable Hosted Smart Editor URL, then your Return URL will not be called.

Success Example clippingMagicJson decodes to:
{
  "event" : "editor-exit",
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret"
  }, {
    "id" : 2346,
    "secret" : "image_secret2"
  } ],
  "clipped" : [ {
    "id" : 2345,
    "secret" : "image_secret"
  }, {
    "id" : 2346,
    "secret" : "image_secret2"
  } ],
  "skipped" : [ ]
}
Test your Return URL
Error Example clippingMagicJson decodes to:
{
  "event" : "error",
  "error" : {
    "status" : 400,
    "code" : 1234,
    "message" : "Example error"
  },
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret"
  }, {
    "id" : 2346,
    "secret" : "image_secret2"
  } ],
  "clipped" : [ ],
  "skipped" : [ {
    "id" : 2345,
    "secret" : "image_secret"
  }, {
    "id" : 2346,
    "secret" : "image_secret2"
  } ]
}
Test your Return URL