Серверный API

Все запросы API - это стандартные HTTP-запросы к URL-адресам стиля REST. Ответы представляют собой или JSON, или изображение (при получении результата).

Аутентификация

API использует стандартную аутентификацию основного доступа HTTP. Все запросы к API должны включать ваши учетные данные API, при этом идентификатор API используется как имя пользователя, а секретный ключ API в качестве пароля. Обратите внимание, что ClippingMagic.js использует только ваш идентификатор API, чтобы не показывать секретный ключ API вашим пользователям.

Безопасность

Все запросы должны производиться через HTTPS, и вы должны аутентифицировать все запросы.

Для успешного выполнения запросов Ваша клиентская библиотека http должна поддерживать указание имени сервера (SNI). Если вы получаете странные ошибки подтверждения, скорее всего, проблема именно в этом.

Внутренний сервер против интерфейса

Обратите внимание, что все операции загрузки и скачивания происходят на внутреннем сервере, но все операции просмотра и редактирования выполняются в Умном редакторе.

Это разделение защищает ваш ключ API, обеспечивая при этом устойчивую работу конечных пользователей на вашем сайте.

Ограничение скорости

Использование API ограничено по скорости с щедрыми надбавками и без жесткого верхнего предела кроме ваших API-кредитов.

Во время нормальной работы конечного пользователя вы вряд ли столкнетесь с каким-либо ограничением скорости, поскольку потребление в таком случае то возрастает, то снижается, с чем сервис хорошо справляется.

Однако для пакетных заданий мы рекомендуем начинать не более, чем с 5 потоков, добавляя по 1 новому потоку каждые 5 минут, пока вы не достигнете желаемого уровня параллелизма. Пожалуйста, свяжитесь с нами перед началом работы, если вам нужно более 100 одновременных потоков.

Если вы направите слишком много запросом, вы начнете получать отклики 429 Too Many Requests. Когда это произойдет, вы должны применить линейную выдержку: при первом таком отклике подождите 5 секунд перед отправлением следующего запроса. При втором последовательном отклике 429 подождите 2*5=10 секунд перед отправлением следующего запроса. При третьем подождите 3*4=15 секунд и т.д.

Счетчик выдержки можно сбросить после успешного запроса, а выдержку нужно применять отдельно для каждого потока (т.е. потоки должны работать независимо друг от друга).

JSON объект ошибки

Мы используем обычные статусы HTTP для указания выполнения или невыполнения запроса API и включаем важную информацию об ошибке в направляемый JSON объект ошибки.

Мы стремимся всегда указывать JSON объект ошибки для любого невыполненного запроса. Однако теоретически всегда возможны внутренние сбои сервера, которые приводят к отклику об ошибке не в формате JSON.

Атрибуты

statusСтатус HTTP отклика, повторяется для оказания помощи в отладке.
codeВнутренний код ошибки Clipping Magic.
messageСообщение об ошибке в понятном для человека формате для помощи в отладке.

Если статус HTTP для вашего запроса равен 200, вы не получите JSON объекта ошибки и можете с уверенностью предположить, что запрос в целом выполнен успешно.

Некоторые клиентские библиотеки HTTP вызывают исключения для статусов HTTP в диапазоне 400-599. Вам нужно будет перехватить эти исключения и обработать их соответствующим образом.

HTTP StatusЗначение
200-299

Успешно выполнено

400-499

Возникла проблема с информацией, предоставленной в запросе (например, отсутствует параметр). Пожалуйста, прочитайте сообщение об ошибке, чтобы узнать, как ее исправить.

500-599

Произошла внутренняя ошибка Clipping Magic. Подождите немного, а затем попробуйте еще раз, и, если проблема не исчезнет, отправьте нам сообщение.

Недавние ошибки API перечислены на странице вашей учетной записи для удобства отладки.

Пример сообщения об ошибке

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

JSON объект изображения

Записи изображений представлены единообразно с помощью объекта JSON, возвращаемого несколькими действиями API.

Атрибуты

id

Уникальный идентификатор изображения. Необходим, чтобы пользователи могли редактировать изображение и скачивать результат.

secret

Для редактирования этого изображения в ClippingMagic.js

нужен секретный ключ
resultRevision

Целое число, обозначающее самый последний вариант, которую можно скачать (0 = результат еще не доступен).

Позволяет определить, существует ли более новый результат этого изображения, чем тот, который вы скачали ранее.

originalFilename

Строка, содержащая имя файла, указанное при загрузке исходного изображения.

test

true означает, что это тестовое изображение, которое можно обрабатывать бесплатно, но результат будет с водяным знаком.

false означает, что это рабочее изображение, для обработки которого нужны кредиты, но водяного знака на результате не будет.

Пример

{
  "id" : 2346,
  "secret" : "image_secret1",
  "resultRevision" : 0,
  "originalFilename" : "example_image1.jpg",
  "imageCategoryUser" : "Photo",
  "imageCategoryAi" : "Photo",
  "test" : false
}

Загрузить POST https://clippingmagic.com/api/v1/images

Чтобы загрузить изображение, вы выполняете стандартную загрузку файла HTTP POST. Эту конечную точку нужно вызывать с вашего внутреннего сервера, ее нельзя вызвать из javascript вашей веб-страницы. Помните, что при загрузке двоичных файлов Content-Type должен быть multipart/form-data .

Параметры

Входное изображение должно иметь быть представлено одним из следующих вариантов:

image
Двоичный

Двоичный файл.

image.base64
Строка

Строка в кодировке base64. Строка может иметь размер не более 1 мегабайта.

image.url
Строка

URL-адрес изображения.

Должно быть файлом в формате .bmp, .gif, .jpeg, .png или .tiff.

Максимальный размер загружаемого изображения (= ширина × высота) составляет 33 554 432 пикселя, который уменьшается до 4 194 404 пикселя, если он не переопределен указанным ниже maxPixels. Перед загрузкой предварительно уменьшите свои изображения до последнего или меньшего размера.

test
Логический
true, false

Передайте true, чтобы указать, что это тестовое изображение.

Пропустите код или передайте false для рабочих изображений.

Тестовые изображения можно обрабатывать бесплатно, но на результате будет внедренный водяной знак.

format
Перечисление
json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png

format=json (по умолчанию): результат автоматической обрезки не создается, и возвращается JSON объект изображения. Используйте, когда результат просматривается и может потенциально исправляться человеком с помощью ClippingMagic.js.

format=result генерирует и выбирает результат автоматической обрезки.

format=clipping_path_svg генерирует результат автоматической обрезки и выбирает контур обрезки (SVG).

format=clipping_path_tiff генерирует результат автоматической обрезки и выбирает контур обрезки (TIFF).

format=alpha_mask_png генерирует результат автоматической обрезки и выбирает альфа-маску (PNG). Альфа-маска имеет такой же размер, как и входное изображение. Применение его к входному изображению не дает результата, поскольку Защита края и Очиститель ореола улучшают цвета границ.

id и secret возвращаются в заголовках x-amz-meta-id и x-amz-meta-secret при получении результата не в формате JSON. Обязательно сохраните их, чтобы иметь возможность просмотреть и отредактировать свой результат с помощью ClippingMagic.js. Смотреть все заголовки, входящие в ответ

При получении JSON объекта изображения плата с вашей учетной записи не взимается; вы платите только при скачивании рабочих результатов.

maxPixels
Целое число
1000000 - 26214400

Изменяет максимальный размер изображения (= ширина × высота), используемого при изменении размера изображения после загрузки.

По умолчанию: 4 194 404 пикселя

background.color
#RRGGBB
#0055FF

Пропустите, чтобы использовать прозрачный фон и получить результат в формате PNG.

Включите, чтобы получить непрозрачный фон указанного цвета и результат в формате output.opaqueFileFormat (по умолчанию JPEG).

Обязательно укажите '#'.

Настройте параметры обработки:

processing.mode
Перечисление
auto, photo, graphics, scan

Управляйте режимом обработки, применяемым к вашему изображения.

По умолчанию: auto

processing.autoClip
Логический
true, false

Включите (по умолчанию) или отключите автоматическую обрезку при редактировании изображения в веб-приложении.

Отключите, если хотите загружать изображения через API, но потом сделайте произвольную обрезку чего-либо, кроме очевидного переднего плана (если он есть).

По умолчанию: true

processing.autoHair
Логический
true, false

Включить (по умолчанию) или отключить применение автоматической маски для волос.

По умолчанию: true

processing.allowGraphicsMode
Логический
true, false

Включить (по умолчанию) или отключить автоматический выбор графического режима.

Эта настройка не применяется, когда format=json.

По умолчанию: true

processing.allowScanMode
Логический
true, false

Включить (по умолчанию) или отключить автоматический выбор режима сканирования.

Эта настройка не применяется, когда format=json.

По умолчанию: true

Настройте уровни цвета:

colors.auto
Логический
true, false

Автоматически настраивайте уровни цвета для повышения контрастности.

По умолчанию: false

colors.brightness
Целое число
-100 - 100

Отрегулируйте яркость выходного изображения.

По умолчанию: 0

colors.shadows
Целое число
-100 - 100

Отрегулируйте тени выходного изображения. Положительные значения означают более темные тени.

По умолчанию: 0

colors.highlights
Целое число
-100 - 100

Отрегулируйте выделенные участки в выходном изображении. Положительные значения означают более светлые выделения.

По умолчанию: 0

colors.temperature
Целое число
-100 - 100

Отрегулируйте цветовую температуру выходного изображения. Положительные значения означают более теплые цвета.

По умолчанию: 0

colors.saturation
Целое число
-100 - 100

Отрегулируйте насыщенность выходного изображения. Положительные значения означают большую насыщенность.

По умолчанию: 0

Настройте удаление цвета фона, который отражается на переднем плане, например, зеленым экраном:

colorCast.auto
Логический
true, false

Автоматически определяйте цвет фона, который нужно удалить с переднего плана.

По умолчанию: false

colorCast.color
#RRGGBB
#A84400

Заданный вручную цвет фона для удаления с переднего плана.

Пропустите, чтобы он определялся автоматически.

colorCast.foregroundGuard
Число с плавающей запятой
0.0 - 20.0

Чем выше значения, тем меньше удаление цветового блика влияет на оригинальные цвета переднего плана, которые аналогичны цветам отражения, но более насыщены, чем те, которые удаляются.

По умолчанию: 4.0

Настройте баланс белого:

whiteBalance.auto
Логический
true, false

Автоматически определять контрольный цвет, который будет использоваться для балансировки белого.

По умолчанию: false

whiteBalance.color
#RRGGBB
#968386

Установленный вручную цвет баланса белого.

Пропустите, чтобы он определялся автоматически.

Настройте финальные штрихи:

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

Добавьте эффект отбрасываемой тени к результату после обрезки.

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

Добавьте эффект отражения к результату после обрезки.

Настройте параметры края:

edges.corners
Логический
true, false

Используйте (по умолчанию) или отключите Защиту угла.

edges.smoothing
Перечисление
smart, fixed

Используйте smart (по умолчанию) или fixed сглаживание.

edges.smoothingLevel
Число с плавающей запятой
0.0 - 5.0

Настройте объем сглаживания, применяемого к результату.

По умолчанию 1.0

edges.feathering
Перечисление
fixed, auto, local

Используйте auto (по умолчанию), local или fixed размытие.

edges.featheringRadiusPx
Число с плавающей запятой
0.0 - 6.0

Настройте объем размытия, применяемого к результату.

По умолчанию: 1.0

edges.offsetPx
Число с плавающей запятой
0.0 - 10.0

Настройте смещение границы, применяемое к результату.

По умолчанию: 0.0

Подгоните выходные данные к результату

fit.toResult
Логический
true, false

Включите подгонку к результату или выключите (по умолчанию).

Если эта опция выключена, остальные параметры в этом разделе игнорируются.

fit.paddingPercent
Число с плавающей запятой
0.0 - 35.0

Заполнение, применяемое вокруг подогранного результата, в процентах от размера результата.

По умолчанию: 5.0

fit.paddingPixels
Целое число
0 - 250

Заполнение, применяемое вокруг подобранного результата, в пикселях.

Если значение не указано, используется процентное заполнение.

fit.objectSize
Перечисление
small, medium, large

Вы можете указать синтетический размер для вашего объекта. Эта функция полезна для Интернет-магазинов, потому что вы можете дать покупателю приблизительное представление о размере изделия по сравнению с другими изделиями.

По умолчанию: large (= размер результата не меняется)

fit.verticalAlignment
Перечисление
top, middle, bottom

Если присутствует лишнее вертикальное пространство, укажите, как ваш результат должен быть выровнен.

Также применяется для распределения лишнего пространства, возникшего в результате принудительной установки пропорций или целевого размера, см. ниже.

По умолчанию: middle

fit.shadows
Перечисление
ignore, pad, tight

Вы можете игнорировать тени, равномерно применить заливку с обеих сторон, подогнав ее к теням, или вплотную добавить заливку только там, где это необходимо, чтобы не обрезать тень.

По умолчанию: pad

fit.rotationDeg
Число с плавающей запятой
-360.0 - 360.0

Повернуть изображение. Положительные значения - против часовой стрелки.

По умолчанию: 0

Контролируйте размер и пропорции результата:

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

Убедитесь в том, что результат имеет указанные пропорции.

fit.verticalAlignment контролирует, как распределяется избыточное вертикальное пространство.

По умолчанию: не применяется

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

Убедитесь в том, что результат имеет указанный размер.

fit.verticalAlignment контролирует, как распределяется избыточное вертикальное пространство.

По умолчанию: не применяется

result.allowEnlarging
Логический
true, false

Контролирует, может ли результат становиться больше входного изображения.

По умолчанию: false

Контролирует параметры вывода:

output.dpi
Целое число
1 - 4000

Установите информацию о DPI, встроенную в результат.

Информация о DPI не включается, если результат оптимизирован для Интернета.

По умолчанию: 72

output.colorSpace
Перечисление
sRGB, AdobeRGB, AppleRGB, ColorMatchRGB

Установите информацию о цветовом пространстве, встроенную в результат.

Информация о цветовом пространстве не включается, если результат оптимизирован для Интернета.

По умолчанию: sRGB

output.jpegQuality
Целое число
1 - 100

Настройте параметр качества, используемый при создании результата в формате JPEG.

По умолчанию: 75

output.pngOptimization
Перечисление
none, lossless, lossy

Настройте веб-оптимизацию результатов в формате PNG.

По умолчанию: lossless

output.jpegOptimization
Перечисление
none, enabled

Настройте веб-оптимизацию результатов в формате JPEG.

По умолчанию: enabled

output.opaqueFileFormat
Перечисление
jpeg, png

Настройте формат файла для непрозрачных результатов.

По умолчанию: jpeg

Вы можете загрузить изображения в тестовом режиме без подписки. В то же время, хотя для загрузки кредиты не нужны, вам все равно потребуется действующая подписка на API для загрузки через него рабочих изображений.

Попробуйте


Формат: '#RRGGBB'



Формат: '#RRGGBB'

Формат: '#RRGGBB'


Формат: '[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]'
Пример: 30 30 25 0.75

Формат: '[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]'
Пример: 0 200 0.5




Формат: '[width:float, >0]:[height:float, >0]'
Пример: 4:3

Формат: '[width:int, >0] [height:int, >0]'
Пример: 400 300

Имя пользователя = идентификатор API, пароль = секрет API

cURL

$ curl "https://clippingmagic.com/api/v1/images" \
 -u 123:[secret] \ 
 -F 'image=@example.jpg' \ 
 -F 'test=true'

Предполагает существование "example.jpg". При необходимости замените. Строка с 'test=true' необязательна.

Пример отклика

{
  "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]

Чтобы скачать результат, нужно выполнить стандартный HTTP GET. Сначала нужно создать результат.

Тестовые результаты скачиваются бесплатно, но на них имеется водяной знак. Для скачивания рабочих результатов нужен один кредит при первой загрузке; повторные скачивания бесплатны.

Если результата не существует, вы получите в ответ сообщение об ошибке.

Параметры

imageId

Встроено в URL

Вам нужно будет вставить значение id, которое было возвращено в вызове Upload.

Необязательно
format

format=result (по умолчанию) извлекает итоговое изображение.

format=clipping_path_svg вместо этого извлекает контур обрезки (SVG).

format=clipping_path_tiff вместо этого извлекает контур обрезки (TIFF).

format=alpha_mask_png вместо этого извлекает альфа-маску (PNG).

format=json вместо этого извлекает объект JSON изображения. Полезно, если вы хотите проверить версию результата или если вы потеряли секрет изображения.

При получении JSON объекта изображения плата с вашей учетной записи не взимается; вы платите только при скачивании рабочих результатов.

Заголовки ответа

Когда format не равен json, мы предоставляем сведения о ключе в этих заголовках HTTP-ответов

x-amz-meta-id
Example: 2346

id вашего изображения.

x-amz-meta-secret
Example: image_secret1

secret вашего изображения.

x-amz-meta-resultrevision
Example: 1

resultRevision, который вы извлекаете этим запросом.

Каждый раз при создании нового результата показатель этого счетчика увеличивается.

x-amz-meta-width
Example: 3200
(включается только для format=result).

Ширина в пикселях результата, который вы извлекаете этим запросом.

x-amz-meta-height
Example: 2400
(включается только для format=result).

Высота в пикселях результата, который вы извлекаете этим запросом.

Content-Disposition
Example: attachment; filename*=UTF-8''example_image1_clipped_rev_0.png

Имя файла результата, включая расширение.

Имя пользователя = идентификатор API, пароль = секрет API

cURL

$ curl "https://clippingmagic.com/api/v1/images/2346" \
 -u 123:[secret] \ 
 -LOJ

Пример ответа JSON

{
  "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

Для получения списка объектов JSON вашего изображения выполните стандартный HTTP GET.

Параметры

Необязательно
limit

Количество извлекаемых записей. По умолчанию равно 20 (Минимум 1, максимум 100).

Необязательно
offset

Смещение для использования в списке записей (по умолчанию 0).

Атрибуты отклика

images

Массив объектов JSON изображения.

limit

limit, фактически использованный при создании результата.

offset

offset, фактически использованный при создании результата.

Имя пользователя = идентификатор API, пароль = секрет API

cURL

$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \
 -u 123:[secret]

Пример отклика

{
  "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

Чтобы удалить изображение, отправьте стандартный HTTP POST на URL-адрес для его удаления.

Это небольшое отклонение от стандартной практики REST, чтобы справиться с тем, что многие клиентские библиотеки HTTP не поддерживают команду HTTP DELETE, и при этом избежать путаницы из-за наличия нескольких способов выполнения одного и того же действия.

Параметры

imageId

Встроено в URL

Вам нужно будет вставить значение id, которое было возвращено в вызове Upload.

Атрибуты отклика

image

Объект JSON удаленного изображения.

Попробуйте

Имя пользователя = идентификатор API, пароль = секрет API

cURL

$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \
 -u 123:[secret] \ 
 -X POST

Пример отклика

{
  "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

Извлеките основную информацию о вашей учетной записи, такую как статус вашей подписки и количество оставшихся кредитов.

Параметры

Отсутствуют.

Атрибуты отклика

subscriptionPlan

План, на который вы в настоящее время подписаны, или 'отсутствует'.

subscriptionState

Состояние вашей текущей подписки ('активна' или 'просрочена') или 'закончилась', если вы не подписаны.

credits

Количество кредитов API на вашей учетной записи. Если вы в настоящее время не подписаны или подписаны не на план API, то 0.

Имя пользователя = идентификатор API, пароль = секрет API

cURL

$ curl "https://clippingmagic.com/api/v1/account" \
 -u 123:[secret]

Пример отклика

{
  "subscriptionPlan" : "none",
  "subscriptionState" : "ended",
  "credits" : 0
}