tencent cloud

APIs

DokumentasiAPIsVideo on DemandMedia Processing APIsComposeMedia

ComposeMedia

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-09-18 15:59:47

1. API Description

Domain name for API request: vod.intl.tencentcloudapi.com.

This API is used to compose media files to achieve the following effects:

  1. Image rotation: Rotate the video or image by a certain degree, or flip it in a certain direction.
  2. Audio control: Increase or reduce the volume of video and audio, or mute the video.
  3. Screen overlay: Overlay frames from videos and images in sequence, for example, to achieve a Picture-in-Picture effect.
  4. Audio mixing: Mix the sound in video and audio together.
  5. Audio extraction: Extract the audio from the video (visuals are not retained).
  6. Crop: Crop a specified time period from video or audio.
  7. Splicing: Splice videos, audio, and images in chronological order.
  8. Transitions: When stitching multiple videos or images, you can add transition effects between paragraphs.

The muxing format of the composed media can be MP4 (video) or MP3 (audio). If event notification is used, the event notification type is Video Synthesis Completed.

A maximum of 100 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: ComposeMedia.
Version Yes String Common Params. The value used for this API: 2018-07-17.
Region No String Common Params. This parameter is not required.
Tracks.N Yes Array of MediaTrack Input media track list, including multiple track information composed of materials such as video, audio, and images. Among them:
  • The input multiple tracks are aligned with the output media file timeline on the timeline;
  • Materials on different tracks at the same time point on the timeline overlap. Image overlay of videos or images in track order, materials with higher track order are overlaid on top, and audio materials are mixed;
  • Each type of track supports up to 10 video, audio, and image tracks.
  • The total number of media segments placed on all types of tracks supports up to 500.
    		•
    Output Yes ComposeMediaOutput Output media file information.
    SubAppId No Integer VOD application ID. For customers who activate VOD services on or after December 25, 2023, this field must be set to the app ID when accessing resources in VOD applications (whether the default application or a newly created application).
    Canvas No Canvas Canvas used when making video files.
    SessionContext No String Source context, used to pass through user request information. The value of this field will be returned in the ComposeMediaComplete callback. It can contain up to 1000 characters.
    SessionId No String Identification Code for Task Deduplication. If a request with the same identification code has been sent within the past 3 days, an error is returned for the current request. The maximum length is 50 characters. If this is not specified or left empty, deduplication is not performed.

    3. Output Parameters

    Parameter Name Type Description
    TaskId String Task ID for media file production, which can be used to query the status of the production task (task type: MakeMedia).
    RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

    4. Example

    Example1 Crop and stitch two video streams together

    Take the segment from the 2nd second to the 62nd second of 5285485487985271487 and the segment from the 6th second to the 81st second of 5285485487985271488, splice them together, and add a 5-second fade-in and fade-out transition in the middle. Paste an image 5285485487985271489 from the 3rd second to the 18th second of the video at position (20px, 20px) with a width and height of (100px, 100px).

    Input Example

    POST / HTTP/1.1
Host: vod.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ComposeMedia
<Common request parameters>

{
    "Output": {
        "Container": "mp4",
        "FileName": "output"
    },
    "Tracks": [
        {
            "TrackItems": [
                {
                    "StickerItem": {
                        "CoordinateOrigin": "TopLeft",
                        "XPos": "20px",
                        "YPos": "20px",
                        "Height": "100px",
                        "Width": "100px",
                        "StartTime": 3,
                        "Duration": 15,
                        "SourceMedia": "5285485487985271489"
                    },
                    "Type": "Sticker"
                }
            ],
            "Type": "Sticker"
        },
        {
            "TrackItems": [
                {
                    "TransitionItem": {
                        "Duration": 5,
                        "MediaTransitions": [
                            {
                                "Type": "ImageFadeInFadeOut"
                            }
                        ]
                    },
                    "Type": "Transition"
                },
                {
                    "Type": "Video",
                    "VideoItem": {
                        "Duration": 60,
                        "SourceMedia": "5285485487985271487",
                        "SourceMediaStartTime": 2
                    }
                },
                {
                    "Type": "Video",
                    "VideoItem": {
                        "Duration": 75,
                        "SourceMedia": "5285485487985271488",
                        "SourceMediaStartTime": 6
                    }
                }
            ],
            "Type": "Video"
        }
    ]
}

    Output Example

    {
    "Response": {
        "RequestId": "6ca31e3a-6b8e-4b4e-9256-fdc700064ef3",
        "TaskId": "125xxx65-ComposeMedia-bffb15f07530b57bc1aabb01fac74bc2"
    }
}

    Example2 Dubbing a video in VOD

    Eliminate the original audio of 5285485487985271487, use 5285485487985271488 for dubbing from second 5, use seconds 2 to 16 of 5285485487985271489 for dubbing from second 20, and generate a new video on demand.

    Input Example

    POST / HTTP/1.1
Host: vod.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ComposeMedia
<Common request parameters>

{
    "Output": {
        "Container": "mp4",
        "FileName": "output"
    },
    "Tracks": [
        {
            "TrackItems": [
                {
                    "Type": "Empty",
                    "EmptyItem": {
                        "Duration": 5
                    }
                },
                {
                    "AudioItem": {
                        "SourceMedia": "5285485487985271488",
                        "Duration": 15
                    },
                    "Type": "Audio"
                },
                {
                    "AudioItem": {
                        "Duration": 14,
                        "SourceMedia": "5285485487985271489",
                        "SourceMediaStartTime": 2
                    },
                    "Type": "Audio"
                }
            ],
            "Type": "Audio"
        },
        {
            "TrackItems": [
                {
                    "Type": "Video",
                    "VideoItem": {
                        "SourceMedia": "5285485487985271487",
                        "AudioOperations": [
                            {
                                "VolumeParam": {
                                    "Mute": 1
                                },
                                "Type": "Volume"
                            }
                        ]
                    }
                }
            ],
            "Type": "Video"
        }
    ]
}

    Output Example

    {
    "Response": {
        "RequestId": "6ca31e3a-6b8e-4b4e-9256-fdc700064ef3",
        "TaskId": "125xxx65-ComposeMedia-bffb15f07530b57bc1aabb01fac74bca"
    }
}

    Example3 Use a video as a Picture-in-Picture for another video

    Use the video of 5285485487985271487 as the main picture in Picture-in-Picture. Use the video of 5285485487985271488 as the sub-screen in Picture-in-Picture. The center offset of the sub-screen is 25% of the main picture (i.e., at the bottom-right corner of the main picture), and its width is 30% of the frame.

    Input Example

    POST / HTTP/1.1
Host: vod.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ComposeMedia
<Common request parameters>

{
    "Output": {
        "Container": "mp4",
        "FileName": "output"
    },
    "Tracks": [
        {
            "TrackItems": [
                {
                    "Type": "Video",
                    "VideoItem": {
                        "SourceMedia": "5285485487985271487"
                    }
                }
            ],
            "Type": "Video"
        },
        {
            "TrackItems": [
                {
                    "Type": "Video",
                    "VideoItem": {
                        "CoordinateOrigin": "Center",
                        "Width": "30%",
                        "SourceMedia": "5285485487985271488",
                        "XPos": "25%",
                        "YPos": "25%"
                    }
                }
            ],
            "Type": "Video"
        }
    ]
}

    Output Example

    {
    "Response": {
        "RequestId": "6ca31e3a-6b8e-4b4e-9256-fdc700064ef3",
        "TaskId": "125xxx65-ComposeMedia-bffb15f07530b57bc1aabb01fac74bca"
    }
}

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    FailedOperation Operation failed.
    FailedOperation.InvalidVodUser The VOD service is not activated.
    FailedOperation.UploadCosFail Operation failed: Failed to upload the file to cos.
    InternalError Internal error.
    InternalError.GetFileInfoError Internal error: media file info error.
    InternalError.GetMediaListError Internal error: media list error.
    InvalidParameter Parameter error.
    InvalidParameterValue.ClipDuration Parameter value error: The cropping time period is too long.
    InvalidParameterValue.SessionContextTooLong SessionContext is too long.
    InvalidParameterValue.SessionId Duplicate recognition code. Request deduplicated.
    UnauthorizedOperation Unauthorized operation.
    Topik sebelumnya: EditMediaTopik selanjutnya: RemoveWatermark

    Bantuan dan Dukungan

    Apakah halaman ini membantu?

    masukan

    Search
      Enter keywords to search documentation