API 文档

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

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

安全:所有请求必须通过 HTTPS 提出,您必须对所有请求进行身份验证。 您的 http 客户端库必须支持服务器名称指示(SNI)才能成功地提出请求。 如果您得到奇怪的握手错误,则很可能是握手错误。

请尝试

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

JSON 对象错误

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

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

属性

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

错误回应示例

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

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

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

HTTP Status表示
200-299

成功

301-303

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

400-499

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

500-599

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

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 文件上载图象。请注意文件类型必须为multipart/form-data

属性

image

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

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

可选
test

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

响应属性

image

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