抠图（Background Matting）

自动识别图像主体，移除背景，返回透明底图。

基本信息

项目	值
接口路径	POST /image/matting
所需 Scope	matting 或 *

| 任务类型 | 异步，返回 taskId |

---

请求参数

{
  "requestId": "可选，调用方自定义唯一 ID",
  "url": "图像公开 HTTPS URL（必填）",
  "crop": false,
  "padding": 20
}

参数说明

参数	类型	必填	默认值	说明
requestId	string	否	null	调用方请求 ID
url	string	是	—	待处理图像的公开 HTTPS URL
crop	boolean	否	false	是否裁剪到主体最小边界框
padding	integer	否	20	裁剪时在主体周围保留的像素边距（≥0，crop=true 时生效）

URL 要求：必须是可公开访问的 HTTPS URL；localhost、内网地址或需要认证的 URL 会被拒绝。

---

请求示例

最简请求（不裁剪）：

curl -s -X POST \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product-photo.jpg"
  }' \
  "https://magiqsight.com/openapi/v1/image/matting"

裁剪到主体（带边距）：

curl -s -X POST \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product-photo.jpg",
    "crop": true,
    "padding": 10
  }' \
  "https://magiqsight.com/openapi/v1/image/matting"

---

响应示例

提交成功：

{
  "code": 0,
  "msg": null,
  "data": {
    "requestId": null,
    "taskId": "img-matt789xyz"
  }
}

---

获取结果

任务成功（status: 1）后，imageUrls 中的图像为透明底（PNG 格式）。

详见异步任务文档。

---

常见问题

Q：输出格式是什么？
A：抠图结果为带 Alpha 通道的 PNG，背景区域完全透明。

Q：crop=true 与 crop=false 有何区别？
A：crop=false（默认）保持原始尺寸，背景变透明；crop=true 会裁剪到主体最小边界框，尺寸更小，适合用于合成或展示。

Q：图像中有多个主体怎么处理？
A：当前版本以整体画面的前景主体为准，不支持单独选定某一目标。