Composite After Video Matting

POSThttps://api.newportai.com/api/async/image_matting_composite_video

The Composite After Video Matting API provides advanced video portrait compositing services. It allows you to take the results of a portrait matting process and seamlessly integrate the subject into a new background—whether it be an image, another video, or a solid color.

First, use the Video Matting API to obtain the mattingAlphaFileUrl.
Submit a POST request to this API with the alpha channel and background details to obtain a taskId.
Submit a POST request to the Polling API to retrieve the final compositeFileUrl.
Configure a Callback URL to receive results automatically on completion.

Request Headers

Content-Type string Required

Enum: application/json

Authorization string Required

Bearer authentication token. Example: Bearer {{APIKey}}.

Request Body Parameters

srcFileUrl string Required

The URL of the original source video file.

mattingAlphaFileUrl string Required

The URL of the alpha channel (mask) file, typically retrieved from a previous Video Matting task.

backgroundType string Required

The type of background to apply. Enum: image, video, or color.

backgroundFileUrl string Optional

The URL of the background image or video file. Required if backgroundType is image or video.

backgroundColor string Optional

The hex or name of the background color. Required if backgroundType is color.

bitRate string Optional

Specifies the bitrate for the generated video (e.g., 16m, 500k).

x integer Optional

The horizontal (x) coordinate for overlay positioning when backgroundType is image.

y integer Optional

The vertical (y) coordinate for overlay positioning when backgroundType is image.

Response

code integer

Returns 0 for success, or a specific error code.

message string

Returns "success" or a descriptive error message.

data object

taskId string

The unique identifier for the task. Use this ID with the Polling API to retrieve the generated output.

Errors

10192Illegal param

Polling

Use the Polling API to retrieve the processing results.

Callback

Alternatively, you can enable Callback to receive task results automatically upon completion.

0Task Completed

123456789101112131415{
  "code": 0,
  "message": "success",
  "data": {
    "task": {
      "taskId": "09f426f4bd9e4aa3bd5742f8cf998f02",
      "status": 3,
      "taskType": "image_matting_composite_video",
      "reason": ""
    },
    "mattingResult": {
      "compositeFileUrl": "https://dreamface-resource-aigc.oss-us-east-1.aliyuncs.com/apiDocsAdmin/2025-4-1744805988229-compositeFileUrl.mp4"
    }
  }
}

Request

cURL

123456789curl -X POST 'https://api.newportai.com/api/async/image_matting_composite_video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{APIKey}}' \
  -d '{
    "srcFileUrl": "https://d2t5pyzt5qvy2d.cloudfront.net/api/static_resource/prod/default/mq0MSmKgPGQQsxS9UovqH.mp4",
    "mattingAlphaFileUrl": "https://dreamface-resource-aigc.oss-us-east-1.aliyuncs.com/apiDocsAdmin/2025-4-1744805292668-videoMatting_mattingAlphaFileUrl.mp4",
    "backgroundColor": "232d84",
    "backgroundType": "color"
  }'

0Successful

1234567{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "32da4d099e51496d20fd83f49bbe985d"
  }
}