AI抠图 API 文档

说明

此云端 API 使用智能显著目标检测（SOD），提供自动化、高精度的AI抠图服务。为获得最佳速度，建议源图片小于 5 MB。

🥥 重要说明

数据保留：输出图片 URL 和 Alpha 蒙版仅保留 1 天，请及时下载保存。
频率限制：默认限制为 2 QPS。如需更高并发，请联系销售或商务团队。

版本历史

4.0 | 发布日期: 2025-03-20
4.0.1 | 发布日期: 2026-07-01 (新增多结果输出支持)

输入图片要求

图片格式	分辨率	文件大小
jpg, jpeg, bmp, png, webp, bitmap, avif, tiff, heic, heif	Integer between [4096~4096]	不超过 10MB（含）

🥥 重要说明

输出 URL 将在 24 小时后过期。
默认限制为 2 QPS。如需提高并发限制，请联系我们。

请求 URL

🥥 https://coco-openapi.yezisheji.com/api/v1/segment/submit
https://coco-openapi.yezisheji.com/api/v1/segment/task_info

请求方法与示例

# 创建任务

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/submit' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_file=@/path/of/image.jpg'

# 查询任务

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/task_info' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'task_id={YOUR_TASK_ID}'

鉴权与权限

使用服务前需申请 API Key，获取方式请联系商务或销售团队。
API 鉴权：通过 HTTP Header 传递密钥，请安全保存 API Key，防止凭据泄露。

构造请求

1、图片AI抠图

POST /api/v1/segment/submit

请求参数:

参数名	类型	默认值	可选值	说明
image_url	String	None	-	需要移除背景的图片 URL（与 image_file 互斥）。
image_file	String($binary)	None	-	本地图片文件（与 image_url 互斥）。
rsz_w	int	None	Integer between [0~4096]	大于 0 时，按 rsz_w 指定宽度等比缩放返回图片。
rsz_h	int	None	Integer between [0~4096]	大于 0 时，按 rsz_h 指定高度等比缩放返回图片。
crop_object	int	None	0、1	设为 1 时，裁剪到图片主体区域。
multi_result	int	None	0、1	是否返回多个抠图结果。按返回结果数量计费，通常不超过 5 个。
sync	int	0	0、1	0 为异步模式，立即返回 task_id 并通过 task_info 查询；1 等待完成后返回结果。
output_type	int	1	1、2、3	返回图片与蒙版。 1 仅返回图片。 2 返回图片和蒙版。 3 仅返回蒙版。
output_format	String	png	jpeg、png	返回图片格式。 png：透明背景。 jpeg：默认白色背景，可用 bg_color 指定颜色。
bg_color	String	None	Hexadecimal color string starting with "#"	纯色背景，仅在 output_format 为 jpeg 时生效，例如 "#FFFFFF"、"#000000"。
output_mask_format	String	jpeg	jpeg、png	返回蒙版图片的格式。
timeout	int	10	1-60	API 等待处理的超时时间（秒），仅在 sync=1 时生效。

注意：同时设置 rsz_w 和 rsz_h 时，将按指定尺寸缩放且不保持原宽高比；启用 crop_object 时也不会保持原宽高比。

# 异步模式响应示例 (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcadf7b3b99f4447f9ddce"
    },
    "status": 200,
    "timestamp": 1744512855,
    "trace_id": "ae173819-6fb5-4e88-a587-ff654f2de9bf",
    "message": "ok"
}

# 同步模式响应示例 (sync=1)

JSON|

{
    "data": {
        "created_at": 1744513021,
        "completed_at": 1744513022,
        "image": "{image oss url}",
        "mask": "{mask oss url}"
    },
    "status": 200,
    "timestamp": 1744513022,
    "trace_id": "3a2a0b4a-8b4a-4034-865a-8a5ebcc7e93c",
    "message": "ok"
}

2、图片AI抠图

POST /api/v1/segment/submit

请求参数:

# 异步模式响应示例 (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcaec66b4a4af9c824fcd2",
        "created_at": 1744513062,
        "completed_at": 1744513063,
        "status": 2,
        "mask": "{mask oss url}",
        "image": "{image oss url}",
        "result_cnt": 2,
        "results": [
            {
                "task_id": "{task_id_1}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            },
            {
                "task_id": "{task_id_2}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            }
        ]
    },
    "status": 200,
    "timestamp": 1744513180,
    "trace_id": "952a636e-3a9d-4e72-b470-681c61fcd763",
    "message": "ok"
}

参数名	类型	说明
result_cnt	Number	multi_result=1 时返回的结果数量

参数名	类型	默认值	可选值	说明
task_id	String	None	Valid Task ID	AI抠图 API 返回的 task_id，仅用于 sync=0 异步模式。

3、用量配额查询

GET /api/v1/segment/quota

请求参数: 无

# 响应示例

Plain Text|

{
    "data": {
        "used_tasks": 888,
        "remaining_tasks": 88888
    },
    "status": 200,
    "timestamp": 1778555905,
    "trace_id": "b9d83cd6-f220-436f-ac30-52fcd8d5b30a",
    "message": "ok"
}

响应参数

参数名	类型	说明
image	String	AI抠图后图片的 URL
mask	String($binary)	蒙版图片 URL
results	Array	multi_result=1 时的结果数组
result_cnt	Number	multi_result=1 时返回的结果数量
status	String	data.status 任务状态： 2 已完成 1 处理中 -1 失败 -2 超时
used_tasks	Number	已使用的抠图任务数量
remaining_tasks	Number	剩余可用抠图任务数量

状态码

HTTP 响应状态码

HTTP 响应状态码	说明
200	请求成功。
400	客户端参数错误，请检查缺失或无效值。
401	鉴权失败，请检查 X-API-KEY 和服务开通状态。
404	请求的 URL 或资源不存在。
412	上传的图片 URL 或文件校验失败。
413	上传文件超过大小限制。
429	请求频率超过 QPS 限制，请降低频率或联系商务支持。
500	服务器异常，请联系商务或技术支持。