图片抠像

自动分离图片主体与背景，输出带透明通道（alpha）的抠像结果，含发丝级软边，可直接用于叠加、封面、海报等合成场景。

效果示例

原图	抠像前景（透明）	背景底板（主体处透明）

前景层与背景底板互补——两层叠回去即原图；前景可直接用于叠加合成，背景底板（output_background=true 时返回）可作新背景复用。

创建任务

基本信息

项目	值
请求方法	POST
请求路径	/task/image_matting
Content-Type	application/json
鉴权方式	Authorization 请求头（直接传 API Key）

请求参数（Body）

参数名	类型	必填	默认值	说明
file_id	string	是	—	已上传图片文件的 ID
output_format	string	否	png	透明输出容器，png 或 webp，均含 alpha 通道
high_res	boolean	否	true	是否用 2048 高分辨率推理（默认开，质量最佳；关则 1024，更快省显存）
output_background	boolean	否	false	是否额外输出背景底板（主体处透明的背景层，与前景互补）；开启则响应含 background_file_id

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/image_matting \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "537489015178246", "output_format": "png"}'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "task_type": "image_matting",
    "status": "queued"
  }
}

---

查询任务结果

基本信息

项目	值
请求方法	GET
请求路径	/task/image_matting/{task_id}
鉴权方式	Authorization 请求头（直接传 API Key）

响应参数（output_result）

参数名	类型	说明
file_id	string	抠像结果文件 ID（带 alpha 的透明图）
background_file_id	string	背景底板文件 ID（主体处透明，仅 output_background=true 时返回）

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "file_id": "537489015178248"
    },
    "create_time": "2026-06-21T08:00:00Z",
    "update_time": "2026-06-21T08:00:03Z"
  }
}

错误码

错误码	HTTP 状态码	说明	解决方案
6013	400	file_id 缺失	传入 file_id 参数
6014	400	文件类型与接口不匹配	传入图片文件
6016	400	业务参数非法（output_format / high_res）	检查参数取值范围
6004	404	文件不存在	检查 file_id 是否正确
6502	401	鉴权失败	检查 Authorization 请求头