API 文档

所有 API 请求均为 REST 式样 URL 标准 HTTP 请求。 回应是 JSON 或图像(在提取结果时)。

身份验证

API 使用标准的 HTTP 基本存取身份验证。 所有 API 请求将需要包括您的 API 凭据,将 API Id 用作用户,将 API 键用作密码。 请注意,ClippingMagic.js 仅使用您的 API ID,不向用户披露您的 API 键。

安全

所有请求必须通过 HTTPS 提出,您必须对所有请求进行身份验证。

您的 http 客户端库必须支持服务器名称指示(SNI)才能成功地提出请求。 如果您得到奇怪的握手错误,则很可能是握手错误。

后端与前端

请注意,所有上载和下载操作在后端发生,但裁剪操作使用 ClippingMagic.js 在网络客户端(前端)进行。

该拆分保护您的 API 键,同时启动在您的网站上的终端用户无缝体验。

速率限制

API 使用速率限制宽松,不存在超出您的 API 信用分的硬性上限。

在正常的终端用户驱动型操作过程中,由于该服务一般可轻松应对使用的起伏,您不大可能会遇到任何速率限制。

但我们建议您在批次作业时,最多以 5 个线程开始,每 5 分钟增加 1 个新线程,直至达到想要的并行水平。 如果您需要的并行线程超过 100 个,请在开始前与我们联系。

如果您提交的请求过多,会收到 429 Too Many Requests的回复。 这种情况下您应当应用线性后退:第一次收到此回复时,等待 5 秒钟再提交下一个请求。 连续第二次收到 429 回复时,等待 2*5=10 秒钟再提交下一个请求。 第三次等待 3*5=15 秒钟,依此类推。

您可以在一次成功的请求后,重置后退计数器,并且应当以每个线程为基础,应用后退(即各个线程应当相互独立运作)。

请尝试

所有 API 行动均带有 html 表格/链接示例,您可以在您的浏览器中尝试。如果您已经登记,cURL 范例使用您的 API 凭据,因此您只需将它们粘贴进您的终端并运行。

JSON 对象错误

我们使用传统的 HTTP 状态,表示 API 请求成功或失败,并在返回的 JSON 对象错误中包括重要的错误信息。

我们努力始终为任何有问题的请求返回 JSON 对象错误。 但是,从理论上来说,总是可能出现内部服务器故障,从而导致非 JSON 错误回应。

属性

status回应的 HTTP 状态在此重复,以帮助调试。
codeClipping Magic 内部错误代码。
message人类可读错误消息,旨在帮助调试。

如果您的请求的 HTTP 状态是 200,则不会返回 JSON 对象错误,您可以安全地假设请求总体而言已取得成功。

一些 HTTP 客户端库为 400-599 范围内的 HTTP 状态引发异常。 您将需要捕获这些异常,并适当处理。

HTTP Status表示
200-299

成功

301-303

在下载结果时:您被重定向至实际结果储存地点。 不会返回 JSON 对象错误。 您应当在下载结果时配置您的 HTTP 客户端库,执行重定向。

400-499

请求中提供的信息存在问题(例如,缺少一个参数)。 请查看错误消息,了解如何纠错。

500-599

一直存在 Clipping Magic 内部错误。 请稍候,然后再重新尝试,如果问题依然存在,请发电子邮件给我们。

错误回应示例

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

上载 POST https://clippingmagic.com/api/v1/images

如需上载图像,您使用标准 HTTP POST 文件上载。 此终结点必须从您的后端调用,无法从您的网页的 JavaScript 调用。 请记住内容-类型必须是multipart/form-data

属性

image

上载的图像文件必须是 .bmp、.gif、.jpeg、.png 或 .tiff 文件。

最大图像尺寸是16,777,216像素,图像尺寸缩小为4,194,404像素。 上载之前请预先将您的图像缩小为后一个尺寸或较小的尺寸。

可选
test

填充true表示这是测试图像。 测试图像可免费处理,但结果将带有嵌入水印。

可选
format

默认无自动剪切结果生成,返回图像 JSON 对象。 这是在有真人操作者查看并可能使用 ClippingMagic.js 对剪切进行润色的情况下的典型模式。

format=result会生成并提取自动剪切结果。

format=clipping_path_svg会生成自动剪切结果,并提取剪切路径(SVG)。

format=alpha_mask_png会生成自动剪切结果,并提取 alpha 蒙板(PNG)。

提取非 JSON 结果时,idsecret会在 x-amz-meta-idx-amz-meta-secret 标头中返回。

提取 JSON 对象图像不会向您的账户收费;只有在下载生产结果时才会向您收费。

您可以无需订阅在测试模式中上载图像。 但是,即使上载无需使用信用分,您仍然需要有有效的 API 订阅,才能通过 API 上载生产图像。

请尝试

Username = API Id, Password = API Key

cURL

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

假设‘example.jpg’存在。根据需要取代。

响应范例

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

下载 GET https://clippingmagic.com/api/v1/images/[image_id]

如需下载结果,您执行标准 HTTP GET。 必须已经先生成结果。 通常,这是通过让您的终端用户使用 ClippingMagic.js 在您的网站上裁剪图像来完成的。

测试结果可免费下载,但包括水印。 首次下载生产结果需要一个信用分;重复下载免费。

如果有结果,您将能够被重定向至该结果(结果储存在 Amazon S3 上),因此核实您的客户端库被配置为执行重定向。

x-amz-meta-resultrevision 响应标头表示下载结果的 resultRevision,标头Content-Disposition表示结果文件名,包括扩展名:.jpeg(用于带不透明背景结果)、.png(用于带透明背景结果)。

如果没有可用的结果,您会获得错误响应。

参数

image_id

内置进 URL

您将需要插入在上载呼叫中返回的 id 数值。

可选
format

结果图像默认返回。

format=clipping_path_svg会提取剪切路径(SVG)。

format=alpha_mask_png会提取 alpha 蒙板(PNG)。

format=json会提取 JSON 对象图像。 在您希望在 resultRevision 上查看或者您丢失了图像密钥时会有帮助。

提取 JSON 对象图像不会向您的账户收费;只有在下载生产结果时才会向您收费。

Username = API Id, Password = API Key

cURL

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

JSON 响应范例

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

列表 GET https://clippingmagic.com/api/v1/images

如需提取您的 JSON 对象图像列表,您执行标准 HTTP GET。

参数

可选
limit

提取的记录数目。默认值为 20(最小 1,最大 100)。

可选
offset

在记录列表中使用的偏移(默认值为 0)。

响应属性

images

JSON 对象图像阵列。

limit

生成结果时实际使用的limit

offset

生成结果时实际使用的offset

Username = API Id, Password = API Key

cURL

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

响应范例

{
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }, {
    "id" : 2346,
    "secret" : "image_secret2",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  } ],
  "limit" : 2,
  "offset" : 0
}

删除 POST https://clippingmagic.com/api/v1/images/[image_id]/delete

如需删除图像,您对图像的删除-URL 执行标准 HTTP POST。

这是略微偏离标准 REST 方法的做法,用于应对很多 HTTP 客户端库不支持 HTTP DELETE 动词的现实状况,同时避免用多种方法做同一件事的混乱局面。

参数

image_id

内置进 URL

您将需要插入在上载呼叫中返回的 id 数值。

响应属性

image

删除的 JSON 对象图像。

请尝试

Username = API Id, Password = API Key

cURL

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

响应范例

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

账户 GET https://clippingmagic.com/api/v1/account

获取关于您的账户的基本信息,如您的订阅状态和剩余信用分数。

参数

响应属性

subscriptionPlan

您目前已订阅的计划,或 '无'。

subscriptionState

您目前的订阅状态('活跃' 或 '过期'),或者在无订阅的情况下为 '终止'。

credits

您账户中的剩余信用分数。当前无订阅则为 0。

Username = API Id, Password = API Key

cURL

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

响应范例

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