视频抠像

无绿幕人物视频抠像：自动检测首帧主体（或自行指定），逐帧抠出后输出带透明通道（alpha）、时序稳定、发丝级软边的 WebM/VP9 透明视频。

效果示例

原视频

抠像前景（棋盘格＝透明区）

背景视频（主体已抠除）

示例中的棋盘格代表透明区域（仅为可视化展示）。前景与背景互补，叠回即原视频。接口实际产出的是透明 WebM（VP9 / yuva420p），用支持 alpha 的工具（剪映 / Premiere / AE，或 ffmpeg overlay）叠到底层即可。⚠️ 二次转码务必保留 alpha（VP9 / yuva420p）；转成 AV1 或 yuv420p 会丢掉透明通道。

创建任务

基本信息

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

请求参数（Body）

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	—	已上传视频文件的 ID
`target_mode`	`string`	否	`auto`	首帧主体选取方式：`auto` 自动检测主体；`mask` 由 `mask_file_id` 指定
`mask_file_id`	`string`	条件	—	首帧二值 mask 图文件 ID（`target_mode=mask` 时必填）
`output_format`	`string`	否	`webm`	透明输出容器，当前支持 `webm`（VP9 alpha）
`max_size`	`integer`	否	—	长边下采样上限（控显存/加速），不填按原分辨率
`output_background`	`boolean`	否	`false`	是否额外输出抠像后的背景视频（主体处透明，与前景层互补）

请求示例

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

成功响应示例

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

查询任务结果

基本信息

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

响应参数（output_result）

参数名	类型	说明
`file_id`	`string`	透明抠像视频文件 ID（WebM/VP9，带 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"
    }
  }
}

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	`file_id` 或 `mask_file_id` 缺失	补齐必填字段
`6014`	400	文件类型与接口不匹配	传入视频文件
`6016`	400	业务参数非法（`target_mode` / `output_format` / `max_size` / `output_background`）	检查参数取值范围
`6004`	404	文件不存在	检查 `file_id` 是否正确
`6502`	401	鉴权失败	检查 `Authorization` 请求头