获取 API 密钥

服务器 API

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

身份验证

API 使用标准的 HTTP 基本存取身份验证。 所有 API 请求需要包括您的 API 凭据（用户为 API ID，密码为 API 秘钥）。 请注意，ClippingMagic.js 仅使用您的 API ID，以免向用户披露您的 API 秘钥。

安全

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

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

后端与前端

请注意，所有上载和下载操作在后端发生，但所有审阅和编辑操作都在智能编辑器中进行。

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

速率限制

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

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

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

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

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

JSON 对象错误

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

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

属性
status回应的 HTTP 状态在此重复，以帮助调试。
codeClipping Magic internal error code.
message人类可读错误消息，旨在帮助调试。

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

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

HTTP Status表示
200-299

成功
400-499

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

500-599

There's been a Clipping Magic internal error. 请稍候，然后再重新尝试，如果问题依然存在，请发电子邮件给我们。

为了便于调试，您的账户页面上列出了最近的 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 调用。 请记住，内容-类型在上载二元文件时必须为multipart/form-data。

参数

输入图像必须以下列格式之一提供：

image
二进制

二进制文件。

image.base64
字符串

Base64 编码字符串。 字符串大小不得超过 100 万像素。

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会生成自动剪切结果，并提取 Alpha 蒙板（PNG）。 Alpha 蒙板与输入图像大小相同。 由于边缘防护和光环清理器会改善边界颜色，将其应用于输入图像不会为您取得结果。

提取非 JSON 结果时，id和secret会在 x-amz-meta-id 和 x-amz-meta-secret 标头中返回。 请确保存储这些信息，以便使用 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

在 Web 应用中编辑图像时启用（默认）或禁用自动剪切。

在希望通过 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 至 10.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 信息。

如果结果经过 Web 优化，则不包含 DPI 信息。

默认：72

output.colorSpace
枚举
sRGB、AdobeRGB、AppleRGB、ColorMatchRGB

设定嵌入结果的颜色空间信息。

如果结果经过 Web 优化，则不包含颜色空间信息。

默认：sRGB

output.jpegQuality
整数
1 至 100

生成 JPEG 结果时配置使用的质量设置。

默认：75

output.pngOptimization
枚举
none、lossless、lossy

配置 PNG 结果的 Web 优化。

默认：lossless

output.jpegOptimization
枚举
none、enabled

配置 JPEG 结果的 Web 优化。

默认：enabled

output.opaqueFileFormat
枚举
jpeg、png

配置为不透明结果使用的文件格式。

默认：jpeg

您可以无需订阅在测试模式中上载图像。 但是，即使上载无需使用信用分，您仍然需要有有效的 API 订阅，才能通过 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 ID，密码 = 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 数值。

可选
format

format=result（默认）提取结果图像。

format=clipping_path_svg则会提取剪切路径（SVG）。

format=clipping_path_tiff则会提取剪切路径（TIFF）。

format=alpha_mask_png会提取 alpha 蒙板（PNG）。

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

提取 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 ID，密码 = 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 ID，密码 = 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

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

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

参数
imageId

内置进 URL

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

响应属性
image

删除的 JSON 对象图像。

请尝试

用户名 = API ID，密码 = 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 ID，密码 = API 密钥

cURL

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

响应范例

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