图片智能切边API

免费体验

AI 智能判断图像边缘，可根据选择的增强类型裁剪主体或文档区域、校正方向、增强文字或去除商品图背景。支持异步、同步两种调用方式。

接口返回的链接有效期为 1 小时，请及时下载存储。

鉴权

每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。

X-API-KEY: YOUR_API_KEY

创建图片智能切边任务

POST /api/tasks/visual/correction

请求参数

image_url string 可选

源图像 URL。与 image_file 二选一；如果传入此参数，另一个图像源参数必须为空。

二选一必填

image_file file 可选

源图像文件（二进制）。与 image_url 二选一；如果传入此参数，另一个图像源参数必须为空。

图片上传要求请参看使用规范与限制#4。

sync integer 可选

是否等待结果就绪并立即返回。0 表示异步返回 task_id，稍后通过 task_id 获取结果；1 表示同步等待结果并立即返回。结果最多保留 1 小时。

type integer 可选

智能切边类型。0 = 文档图，仅校正；1 = 文档图，仅增强（默认）；2 = 文档图，校正 + 增强；3 = 物品图，仅校正；4 = 物品图，校正 + 背景去除。

return_type integer 可选

结果返回格式。1 返回图片下载 URL；2 返回 base64 字符串；3 返回二进制流，仅同步接口支持。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

接口返回消息。如果失败，可以参考此参数返回的信息，或携带此参数联系支持人员。

data.task_id string

异步图片智能切边任务 ID。创建任务成功后返回，用于后续查询结果。

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

接口返回消息。如果失败，可以参考此参数返回的信息，或携带此参数联系支持人员。

data.task_id string

图片智能切边任务 ID。

data.created_at string

任务创建时间，Unix 时间戳字符串。

data.processed_at string

任务开始处理时间，Unix 时间戳字符串。

data.completed_at string

任务完成时间，Unix 时间戳字符串。

data.image string

结果图片下载 URL 或 base64 数据，取决于 return_type；URL 结果有效期为 1 小时。

data.progress number

任务处理进度。100 表示处理完成。

data.state number

任务状态码。1 表示处理成功，大于 1 表示处理中，小于 0 表示失败，详见状态码说明。

查询图片智能切边结果

异步请求建议每 1 秒 轮询一次结果，本接口最大轮询时长为 60 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。

GET /api/tasks/visual/correction/{task_id}

路径参数

task_id string 必填

图片智能切边任务 ID。创建异步任务后返回，用于查询任务处理结果。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

接口返回消息。如果失败，可以参考此参数返回的信息，或携带此参数联系支持人员。

data.task_id string

图片智能切边任务 ID。如果任务失败，请携带此 task_id 联系支持人员。

data.created_at string

任务创建时间，Unix 时间戳字符串。

data.processed_at string

任务开始处理时间，Unix 时间戳字符串。

data.completed_at string

任务完成时间，Unix 时间戳字符串。

data.image string

结果图片下载 URL 或 base64 数据，取决于 return_type；URL 结果有效期为 1 小时。

data.progress number

任务处理进度。100 表示处理完成。

data.state number

任务状态码。1 表示处理成功，大于 1 表示处理中，小于 0 表示失败，详见状态码说明。

使用规范与限制

接口返回的结果图片链接有效期为 1 小时，请及时下载并存储。
HTTP status 为 200 表示 HTTP 请求成功，并不一定表示图片任务处理成功，详见状态码说明。
使用 URL 作为参数传递时，请遵守 URL 编码规范，避免参数解析混乱。
上传图片需符合以下格式、分辨率和大小限制。

格式分辨率大小

jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw 最大 4096x4096 最大20MB

格式	分辨率	大小
jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw	最大 4096x4096	最大20MB

响应

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": "1634884056", // 仅在异步轮询结果中存在。
    "processed_at": "1634884056", // 仅在异步轮询结果中存在。
    "completed_at": "1634884056", // 仅在异步轮询结果中存在。
    "image": "https://wxtechsz.oss-cn-shenzhen.aliyuncs.com/tasks/output/segmentation/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // 仅在异步轮询结果中存在。
    "progress": 100, // 仅在异步轮询结果中存在。
    "state": 1 // 仅在异步轮询结果中存在。
  }
}