Image Matting

Automatically separate the subject from the background and output a cutout with a transparent alpha channel and hair-level soft edges, ready for compositing, covers, and posters.

Examples

Original	Foreground (transparent)	Background plate (subject transparent)

The foreground layer and background plate are complementary — stacking them reconstructs the original. The foreground is ready for compositing; the background plate (returned when output_background=true) can be reused as a new background.

Create Task

Basic Information

Item	Value
Request Method	POST
Request Path	/task/image_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 image file ID
output_format	string	No	png	Transparent output container, png or webp, both with alpha
high_res	boolean	No	true	Use 2048 high-resolution inference (on by default, best quality; off = 1024, faster)
output_background	boolean	No	false	Also output the background plate (background layer with the subject area transparent, complementary to the foreground); when on, the response includes background_file_id

Request Example

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

Success Example

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

---

Query Task Result

Basic Information

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

Output Result (output_result)

Parameter	Type	Description
file_id	string	Cutout result file ID (transparent image with alpha)
background_file_id	string	Background plate file ID (subject area transparent; returned only when output_background=true)

Success Example

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

Error Codes

Error Code	HTTP Status	Description	Resolution
6013	400	Missing file_id	Pass the file_id field
6014	400	File type does not match the task	Upload an image file
6016	400	Invalid business params (output_format / high_res)	Check the parameter ranges
6004	404	File not found	Verify the file_id
6502	401	Authentication failed	Check the Authorization header