AI 智能识别图像中的主体，一键去除背景，输出高质量透明 PNG。适用于电商商品图、人像、证照、设计素材等场景。支持异步、同步两种调用方式。
接口返回的链接有效期为 1 小时，请及时下载存储。
鉴权
每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。
X-API-KEY: YOUR_API_KEY 创建抠图任务
/api/tasks/visual/segmentation 请求参数
image_url string 可选 源图像 URL。与 image_file 二选一；如果传入此参数，其他图像源参数必须为空。
sync string | number 可选 是否等待结果就绪并立即返回。0 表示异步返回 task_id，稍后通过 task_id 获取结果；1 表示同步等待结果并立即返回。结果最多保留 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 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。
/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 小时，请及时下载存储。
-
上传图片需符合以下格式、分辨率和大小限制。
格式 分辨率 大小 jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw 最大 4096x4096 最大20MB
# 万物抠图 API
AI 智能识别图像中的主体，一键去除背景，输出高质量透明 PNG。适用于电商商品图、人像、证照、设计素材等场景，支持异步与同步两种调用方式。
> 注意：返回的结果图片链接有效期为 1 小时，请及时下载并存储。
## 接口域名（Base URL）
下文中的所有路径均为相对以下 Base URL 的路径：
```
https://techsz.aoscdn.com
```
## 鉴权（Authentication）
每个请求都必须在请求头中携带你的 API Key：
```http
X-API-KEY: YOUR_API_KEY
```
你可以在 [API Key](https://picwish.cn/my-account?subRoute=api-key) 页面获取或管理 X-API-KEY。
未携带有效 Key 的请求会被拒绝。
## 调用方式（同步 / 异步）
通过创建请求中的 `sync` 参数选择调用方式：
- 异步（`sync=0`，推荐用于大图或批量任务）：创建请求会立即返回一个 `task_id`，随后用该 `task_id` 轮询查询接口，直到处理完成。可避免长连接和超时。
- 同步（`sync=1`）：创建请求会阻塞直到处理完成，并在同一个响应中直接返回结果。更简单，但连接会一直保持到图片处理完成。
两种方式的结果都会保留最多 1 小时。
## 提供原图（image_url 或 image_file）
必须且只能提供一种图片来源，二者互斥：
- `image_url`：可公开访问的原图 URL，作为普通表单字段提交。
- `image_file`：以 `multipart/form-data` 上传的原始图片文件（二进制）。
不要同时传两者。若传了 `image_url`，则 `image_file` 必须为空，反之亦然。
## 接口列表
| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建抠图任务 | POST | /api/tasks/visual/segmentation |
| 查询任务结果（异步） | GET | /api/tasks/visual/segmentation/{task_id} |
## 创建抠图任务
`POST /api/tasks/visual/segmentation`
Content-Type：`multipart/form-data`
### 请求参数
| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| image_url | string | image_url / image_file 二选一 | 原图 URL，与 image_file 互斥。 |
| image_file | file | image_url / image_file 二选一 | 二进制原图（multipart），与 image_url 互斥。 |
| sync | string \| number | 可选 | 0 = 异步（返回 task_id，稍后轮询）；1 = 同步（直接返回结果）。结果保留最多 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` = 透明 PNG（默认）；`jpg` = 白底 JPG（可配合 bg_color）。 |
| bg_color | string | 可选 | 纯色背景十六进制值，如 81d4fa 或 ffffff。仅当 format=jpg 时生效。使用时请保证其它 bg_ 参数为空。 |
| bg_image_file | file | 可选 | 自定义背景图文件。按比例居中缩放铺满，多余部分裁剪。最大 20MB，分辨率不超过 4K。使用时请保证其它 bg_ 参数为空。 |
| bg_image_url | string | 可选 | 自定义背景图 URL，行为与限制同 bg_image_file。使用时请保证其它 bg_ 参数为空。 |
### 返回参数 - 异步（sync=0）
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| status | number | HTTP 风格状态码。200 = 成功，非 200 = 失败。详见 /states。 |
| message | string | 响应信息，成功时通常为 "success"。 |
| data.task_id | string | 任务 ID，用于后续查询结果。 |
### 返回参数 - 同步（sync=1）
直接返回处理完成的任务数据，结构与下方“查询结果”的响应相同。
### 示例
异步，使用图片 URL：
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/segmentation' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'image_url=YOUR_IMAGE_URL'
```
异步，上传图片文件：
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/segmentation' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'image_file=@/path/to/image.jpg'
```
同步（直接返回结果）：
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/segmentation' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_url=YOUR_IMAGE_URL'
```
异步创建响应示例：
```json
{
"status": 200,
"message": "success",
"data": { "task_id": "TASK_ID" }
}
```
## 查询抠图结果
异步请求建议每 **1 秒** 轮询一次结果，本接口最大轮询时长为 **60 秒**；累计轮询超过该时长仍未返回结果，即可视为超时失败。
`GET /api/tasks/visual/segmentation/{task_id}`
异步模式下用于轮询获取结果。
### 路径参数
| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| task_id | string | 必填 | 创建任务时返回的任务 ID。 |
### 返回参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| status | number | HTTP 风格状态码。200 = 成功，非 200 = 失败。详见 /states。 |
| message | string | 响应信息，成功时通常为 "success"。 |
| data.task_id | string | 任务 ID。 |
| data.state | number | 1 = 成功；> 1 = 处理中；< 0 = 失败。详见 /states。 |
| data.progress | number | 进度，100 表示处理完成。 |
| data.image | string | 结果图片 URL（取决于 return_type / output_type / format）。有效期 1 小时。 |
| data.mask | string | 蒙版图片 URL，当输出选项包含蒙版时返回。有效期 1 小时。 |
| data.created_at | string | 任务创建时间（Unix 时间戳字符串）。 |
| data.processed_at | string | 开始处理时间（Unix 时间戳字符串）。 |
| data.completed_at | string | 完成时间（Unix 时间戳字符串）。 |
### 示例
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/segmentation/{task_id}' \
-H 'X-API-KEY: YOUR_API_KEY'
```
完成响应示例：
```json
{
"status": 200,
"message": "success",
"data": {
"task_id": "TASK_ID",
"state": 1,
"progress": 100,
"image": "https://.../result.png",
"completed_at": "1700000000"
}
}
```
## 推荐的异步流程
1. 用 `sync=0` 和一种图片来源（`image_url` 或 `image_file`）POST 到 /api/tasks/visual/segmentation，读取 `data.task_id`。
2. 每隔 1 秒 GET /api/tasks/visual/segmentation/{task_id}。
3. 检查 `data.state`：1 = 完成（读取 `data.image`）；> 1 = 继续轮询；< 0 = 失败。
4. 在 1 小时内下载 `data.image`。
## 使用规范与限制
- 接口返回的链接有效期为 **1 小时**，请及时下载存储。
- 上传图片需符合以下格式、分辨率和大小限制。
| 格式 | 分辨率 | 大小 |
| --- | --- | --- |
| jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw | 最大 4096x4096 | 最大20MB |
## 状态码
任务是否成功，需要结合 HTTP 响应状态码（`status`）和任务状态码（`data.state`）共同判断。
### HTTP 响应状态码
| 状态码 | 说明 |
| --- | --- |
| 200 | 请求成功。 |
| 400 | 客户端参数传递错误。请检查参数是否缺失或值是否正确。 |
| 401 | 认证失败。请检查 X-API-KEY 是否正确或服务是否开通。 |
| 404 | 请求的 URL 或资源不存在。请检查 URL 或 task_id 是否正确。 |
| 413 | 上传的文件超出大小限制。请参见各服务的最大文件限制。 |
| 429 | 请求频率超出 QPS 限制（默认 QPS 为 2）。请放缓请求速率，或联系商务提升 QPS。 |
| 500 | 服务端异常。请反馈给商务或技术对接人员。 |
### 任务状态码（data.state）
1 = 成功；大于 1 = 处理中；小于 0 = 失败。
| 状态码 | 说明 |
| --- | --- |
| -17 | 处理失败，非法提示词。 |
| -16 | 处理失败，使用第三方检测发现违规。 |
| -15 | 处理失败，资源不足。 |
| -14 | 处理失败，输入图片内容不符合要求。 |
| -13 | 处理失败，任务异常被取消。 |
| -11 | 处理失败，结果为空。 |
| -10 | 处理失败，内部检测非法。 |
| -9 | 处理失败，内部程序循环处理失败。 |
| -8 | 处理超时，最长处理时间 180 秒。 |
| -7 | 无效图片文件（如图片损坏、格式不对等）。 |
| -5 | image_url 图片超出大小限制（30MB）。 |
| -3 | 服务器下载图片文件失败，请检查图片 URL 是否可用。 |
| -2 | 处理完成，但上传 OSS 失败。 |
| -1 | 处理失败。 |
| 0 | 排队中，任务正在队列中等待。 |
| 1 | 完成，处理成功。 |
| 2 | 准备中。 |
| 3 | 等待中。 |
| 4 | 处理中，正在进行。 |
| 5 | 内部发布处理中。 |
| 6 | 处理中，内部循环处理中。 |