万物抠图API

免费体验

AI 智能识别图像中的主体，一键去除背景，输出高质量透明 PNG。适用于电商商品图、人像、证照、设计素材等场景。支持异步、同步两种调用方式。

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

鉴权

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

X-API-KEY: YOUR_API_KEY

创建抠图任务

POST /api/tasks/visual/segmentation

请求参数

image_url string 可选

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

二选一必填
image_file file 可选

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

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

sync string | number 可选

是否等待结果就绪并立即返回。 结果最多保留 1 小时。

  • 0：异步返回 task_id，稍后通过 task_id 获取结果；
  • 1：同步等待结果并立即返回。
type string 可选

前景类型。不填时自动识别（默认）。

  • person：人物；
  • object：物体；
  • stamp：印章。
return_type number 可选

结果返回形式。

  • 1：图片下载 URL；
  • 2：base64 字符串；
  • 3：二进制流（当前仅同步接口支持）。
output_type number 可选

图片返回选项。

  • 1：同时返回图片和蒙版；
  • 2：只返回图片（默认）；
  • 3：只返回蒙版。
crop number 可选

是否裁剪至目标边缘。

  • 0：返回原始图像大小（默认）；
  • 1：裁剪至目标边缘。
format string 可选

结果图片格式。

  • png：透明背景图片（默认）；
  • jpg：白色背景图片，可配合 bg_color 设置背景色。
bg_color string 可选

添加纯色背景，传入十六进制颜色值，如 81d4fa 或 ffffff。仅当 format=jpg 时生效；使用时请确保其他 bg_ 参数为空。

bg_image_file file 可选

添加背景图片（二进制文件）。背景图会居中等比缩放直至铺满画布，多余边缘自动裁剪。限制：文件大小不超过 20MB，分辨率不超过 4K；使用时请确保其他 bg_ 参数为空。

bg_image_url string 可选

添加背景图片 URL。背景图会居中等比缩放直至铺满画布，多余边缘自动裁剪。限制：文件大小不超过 20MB，分辨率不超过 4K；使用时请确保其他 bg_ 参数为空。

返回参数

status number

HTTP 响应状态码，详见 状态码说明。

  • 200：请求成功；
  • 非 200：请求失败。
message string

接口返回消息。成功时通常为 success。

data.task_id string

异步抠图任务 ID。创建任务成功后返回，用于后续查询抠图结果。

status number

HTTP 响应状态码，详见 状态码说明。

  • 200：请求成功；
  • 非 200：请求失败。
message string

接口返回消息。成功时通常为 success。

data.task_id string

抠图任务 ID。

data.created_at string

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

data.processed_at string

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

data.completed_at string

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

data.image string

抠图结果图片 URL。是否返回受 return_type、output_type、format 等参数影响；链接有效期为 1 小时。

data.mask string

蒙版图片 URL。仅在返回蒙版的输出选项下返回；链接有效期为 1 小时。

data.progress number

任务处理进度。

  • 100：处理完成。
data.state number

任务状态码，详见 状态码说明。

  • 1：处理成功；
  • > 1：处理中；
  • < 0：失败。

查询抠图结果

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

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

路径参数

task_id string 必填

抠图任务 ID。创建异步抠图任务后返回，用于查询任务处理结果。

返回参数

status number

HTTP 响应状态码，详见 状态码说明。

  • 200：请求成功；
  • 非 200：请求失败。
message string

接口返回消息。成功时通常为 success。

data.task_id string

抠图任务 ID。

data.created_at string

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

data.processed_at string

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

data.completed_at string

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

data.image string

抠图结果图片 URL。是否返回受 return_type、output_type、format 等参数影响；链接有效期为 1 小时。

data.mask string

蒙版图片 URL。仅在返回蒙版的输出选项下返回；链接有效期为 1 小时。

data.progress number

任务处理进度。

  • 100：处理完成。
data.state number

任务状态码，详见 状态码说明。

  • 1：处理成功；
  • > 1：处理中；
  • < 0：失败。

使用规范与限制

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

  2. 上传图片需符合以下格式、分辨率和大小限制。

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