Video Matting

Green-screen-free human video matting: auto-detect the subject in the first frame (or specify it), then cut it out frame by frame, producing a temporally stable WebM/VP9 transparent video with an alpha channel and hair-level soft edges.

Examples

The checkerboard indicates transparent areas (for visualization only). Foreground and background are complementary and reconstruct the original when stacked. The API actually returns a transparent WebM (VP9 / yuva420p) — overlay it with an alpha-aware tool (CapCut / Premiere / After Effects, or ffmpeg overlay). ⚠️ When re-encoding, keep the alpha (VP9 / yuva420p); converting to AV1 or yuv420p drops the alpha channel.

Usage Limits

• Input video duration must be within 10 minutes (10 minutes inclusive). Longer videos are rejected by the server with error code 6019 and no task is created. Trim or compress to within 10 minutes before submitting.

Create Task

Basic Information

Item	Value
Request Method	POST
Request Path	/task/video_matting
Content-Type	application/json
Authentication	Raw API key in the Authorization header

Request Body

Parameter	Type	Required	Default	Description
file_id	string	Yes	-	Uploaded video file ID
target_mode	string	No	auto	First-frame subject selection: auto detects the subject; mask uses mask_file_id
mask_file_id	string	Conditional	-	First-frame binary mask image file ID (required when target_mode=mask)
output_format	string	No	webm	Transparent output container; currently webm (VP9 alpha)
max_size	integer	No	-	Long-edge downscale cap (VRAM/speed); original resolution if omitted
output_background	boolean	No	false	Also output the background video after matting (subject transparent, complementary to the foreground)

Request Example

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"}'

Success Example

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

---

Query Task Result

Basic Information

Item	Value
Request Method	GET
Request Path	/task/video_matting/{task_id}
Authentication	Raw API key in the Authorization header

Output Result (output_result)

Parameter	Type	Description
file_id	string	Transparent matting video file ID (WebM/VP9 with alpha)
background_file_id	string	Background video file ID (returned when output_background=true; subject transparent, complementary to the foreground)

Success Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "file_id": "537489015178248"
    }
  }
}

Error Codes

Error Code	HTTP Status	Description	Resolution
6013	400	Missing file_id or mask_file_id	Provide the required fields
6014	400	File type does not match the task	Upload a video file
6016	400	Invalid business params (target_mode / output_format / max_size / output_background)	Check the parameter ranges
6019	400	Video duration exceeds the 10-minute limit	Trim / compress to within 10 minutes
6004	404	File not found	Verify the file_id
6502	401	Authentication failed	Check the Authorization header