Все запросы 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 секунд и т.д.
Счетчик выдержки можно сбросить после успешного запроса, а выдержку нужно применять отдельно для каждого потока (т.е. потоки должны работать независимо друг от друга).
Мы используем обычные статусы 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, возвращаемого несколькими действиями API.
|
Атрибуты |
|
|---|---|
| id |
Уникальный идентификатор изображения. Необходим, чтобы пользователи могли редактировать изображение и скачивать результат. |
| secret |
Для редактирования этого изображения в |
| resultRevision |
Целое число, обозначающее самый последний вариант, которую можно скачать (0 = результат еще не доступен). Позволяет определить, существует ли более новый результат этого изображения, чем тот, который вы скачали ранее. |
| originalFilename |
Строка, содержащая имя файла, указанное при загрузке исходного изображения. |
| test |
|
Пример
{
"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 .
|
Параметры |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Входное изображение должно иметь быть представлено одним из следующих вариантов:
Должно быть файлом в формате .bmp, .gif, .jpeg, .png или .tiff.
Максимальный размер загружаемого изображения (= ширина × высота) составляет 33 554 432 пикселя, который уменьшается до 4 194 404 пикселя, если он не переопределен указанным ниже |
|||||||||||||||
|
test
Логический true, false
|
Передайте
Пропустите код или передайте Тестовые изображения можно обрабатывать бесплатно, но на результате будет внедренный водяной знак. |
||||||||||||||
|
format
Перечисление json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png
|
При получении JSON объекта изображения плата с вашей учетной записи не взимается; вы платите только при скачивании рабочих результатов. |
||||||||||||||
|
maxPixels
Целое число 1000000 - 26214400
|
Изменяет максимальный размер изображения (= ширина × высота), используемого при изменении размера изображения после загрузки. По умолчанию: 4 194 404 пикселя |
||||||||||||||
|
background.color
#RRGGBB #0055FF
|
Пропустите, чтобы использовать прозрачный фон и получить результат в формате PNG. Включите, чтобы получить непрозрачный фон указанного цвета и результат в формате output.opaqueFileFormat (по умолчанию JPEG). Обязательно укажите '#'. |
||||||||||||||
|
Настройте параметры обработки:
|
|||||||||||||||
|
Настройте уровни цвета:
|
|||||||||||||||
|
Настройте удаление цвета фона, который отражается на переднем плане, например, зеленым экраном:
|
|||||||||||||||
|
Настройте баланс белого:
|
|||||||||||||||
|
Настройте финальные штрихи:
|
|||||||||||||||
|
Настройте параметры края:
|
|||||||||||||||
|
Подгоните выходные данные к результату
|
|||||||||||||||
|
Контролируйте размер и пропорции результата:
|
|||||||||||||||
|
Контролирует параметры вывода:
|
|||||||||||||||
Вы можете загрузить изображения в тестовом режиме без подписки. В то же время, хотя для загрузки кредиты не нужны, вам все равно потребуется действующая подписка на API для загрузки через него рабочих изображений.
Попробуйте
Имя пользователя = идентификатор 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
Вам нужно будет вставить значение |
|
Необязательно
format |
При получении JSON объекта изображения плата с вашей учетной записи не взимается; вы платите только при скачивании рабочих результатов. |
|
Заголовки ответа
Когда |
|
|---|---|
x-amz-meta-id
Example: 2346
|
|
x-amz-meta-secret
Example: image_secret1
|
|
x-amz-meta-resultrevision
Example: 1
|
Каждый раз при создании нового результата показатель этого счетчика увеличивается. |
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 |
|
| 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
Вам нужно будет вставить значение |
|
Атрибуты отклика |
|
|---|---|
| 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
}