Merge Media Files

2026-08-07

GET

https://rtc-api.zego.im/

When performing CDN recording, recorded media files are stored on CDN servers. You can call this API to crop and merge multiple media files.

Currently, only media files in MP3/MP4/M3U8 formats can be merged.

Warning

Before using this API for the first time, confirm that CDN recording has been enabled. If it has not been enabled, go to the ZEGOCLOUD Console to enable it. For details, see Console - Service Configuration - CDN, or contact ZEGOCLOUD Technical Support.
Contact ZEGOCLOUD Technical Support to enable the media file merging feature and configure a callback URL. After media file merging is completed, the Media File Merge Complete Callback will be triggered.
Recording files merged using this feature are permanently retained, and the retention period cannot be changed through configuration. To delete a file, call the Delete Media File API.

Call frequency limit

All rooms under the same AppID: 20 requests/second

Request

Query Parameters

Action stringrequired

Possible values: [MergeMedia]

API prototype parameter

https://rtc-api.zego.im/?Action=MergeMedia

AppId uint32required

💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

SignatureNonce stringrequired

💡Common parameter. A 16-character hexadecimal random string (hex-encoded 8-byte random number). For the generation algorithm, refer to the signature example.

Timestamp int64required

💡Common parameter. Current Unix timestamp in seconds. For the generation algorithm, refer to the signature example. A maximum deviation of 10 minutes is allowed.

Signature stringrequired

💡Common parameter. Signature used to verify the legitimacy of the request. Please refer to the signature mechanism to generate it.

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

💡Public parameter. Signature version number.

Vendor stringrequired

Possible values: [Tencent, Huawei]

Possible values and corresponding CDN vendors:

Tencent: Tencent Cloud.
Huawei: Huawei Cloud.

Format string

Default value: MP4

Format of the merged file. The default format is MP4.

Tencent Cloud: MP3, MP4, M3U8.

Warning
When the CDN vendor is Tencent Cloud and the merged file is in MP3 or MP4 format, ensure that the audio format of the source file is AAC-LC. Otherwise, the merged video file may have no sound.
Huawei Cloud: MP4, M3U8.

Type string

Possible values: [0, 1]

Default value: 0

Merge operation type.

0: Default value. Merge files directly without cropping.
1: Crop or otherwise process media files before merging them. In this case, InputFileId[] is invalid and HandleMediaArgs.N.FileId must be passed.

When this parameter is set to 1, it is valid only when Vendor is Tencent and is invalid when Vendor is Huawei.

Example: 1

InputFileId[] string[]

Possible values: >= 1, <= 20

When Type is 0, this parameter is valid and required.
When Type is 1, this parameter is invalid.

List of file IDs to merge. Files are merged in list order. Specifically:

Tencent Cloud: Pass the FileID returned by the Recording File Generation Callback. A maximum of 10 files can be merged.
Huawei Cloud: Pass the ObsObject returned by the Recording File Generation Callback. A maximum of 20 files can be merged.

Example: InputFileId[]=5285890813221514958&InputFileId[]=5285890813221513290

HandleMediaArgs object[]

Possible values: >= 1, <= 10

This parameter is valid when Type is 1.

Array[

FileId stringrequired

List of file IDs to crop and then merge. Files are merged in ascending order of N in the parameter names. A maximum of 10 files can be merged.

Tencent Cloud: Pass the FileID returned by the Recording File Generation Callback.
Huawei Cloud: Pass the ObsObject returned by the Recording File Generation Callback.

Warning

N must start at 0 and increase continuously, with a maximum value of 9. If N does not start at 0 or a number is skipped, the files cannot be cropped and merged correctly.

For example, HandleMediaArgs.0.FileId=5285890813221514958&HandleMediaArgs.1.FileId=5285890813221513290

Query parameter：HandleMediaArgs.N.FileId

StartTime double

Default value: 0

Start-time offset for cropping the media file corresponding to HandleMediaArgs.N.FileId. The default value is 0, in seconds.

For example, HandleMediaArgs.0.StartTime specifies the start time for cropping the media file identified by HandleMediaArgs.0.FileId.

Query parameter：HandleMediaArgs.N.StartTime

EndTime double

End-time offset for cropping the media file corresponding to HandleMediaArgs.N.FileId. The default value is the end time of the video file, in seconds.

For example, HandleMediaArgs.0.EndTime specifies the end time for cropping the media file identified by HandleMediaArgs.0.FileId.

Query parameter：HandleMediaArgs.N.EndTime

]

Query example:

HandleMediaArgs.0.FileId=5576678019238910395&
HandleMediaArgs.0.StartTime=0.5&
HandleMediaArgs.0.EndTime=10.5&
HandleMediaArgs.1.FileId=5576678019238910395&
HandleMediaArgs.1.StartTime=10&
HandleMediaArgs.1.EndTime=15

HandleMediaArgs.0.FileId=5576678019238910395&
HandleMediaArgs.0.StartTime=0.5&
HandleMediaArgs.0.EndTime=10.5&
HandleMediaArgs.1.FileId=5576678019238910395&
HandleMediaArgs.1.StartTime=10&
HandleMediaArgs.1.EndTime=15

OutputFileName string

When Vendor is Tencent, this parameter is required.
When Vendor is Huawei, this parameter is optional. If it is not specified, the system automatically generates a name.

Name of the merged media file, excluding the file format.

URL-encode the value of this parameter before passing it.

ExpireTime int32

Default value: 0

Valid retention period of the merged media file, in hours. File expiration time = API request time + valid retention period.

0 (default): The file is permanently retained and does not expire.
Greater than 0: The file is deleted after the specified period.

Warning

This field is valid only when Vendor is Tencent.
If the media file merging task takes longer to complete than the specified retention period, the file will not be generated, and accessing the merged file URL provided by the Media File Merge Complete Callback will return 404.

Responses

Success

application/json

Schema
Example (from schema)
Example

Schema

Code int32

Return code.
The following table lists only the return codes related to the business logic of this API. For the complete list, see Global Return Codes.

Return Code	Description	Suggested Action
0	Request succeeded.	-
2	Invalid input parameter.	-
3	Required permission has not been enabled.	Contact ZEGOCLOUD Technical Support.
4	CDN type mismatch.	Check the parameters.
5	Configuration error.	Contact ZEGOCLOUD Technical Support.
6	Requests are too frequent.	Try again later.
7	Authentication failed.	Check whether the authentication parameters are correct.
1000	Request failed.	Contact ZEGOCLOUD Technical Support.
41003	File does not exist.	Check whether the file format and file ID are correct.

Message string

Description of the operation result.

RequestId string

Request ID returned by the ZEGOCLOUD server.

Data object

Response data.

Tencent object

Returned when Vendor is Tencent.

TaskId string

Task ID for producing the media file. You can use this ID to query the production task.

RequestId string

Unique request ID returned by the CDN vendor corresponding to Vendor, namely Tencent Cloud. Provide this RequestId when troubleshooting.

Huawei object

Returned when Vendor is Huawei.

TaskId string

Task ID for producing the media file. You can use this ID to query the production task.

RequestId string

Unique request ID returned by the CDN vendor corresponding to Vendor, namely Huawei Cloud. Provide this RequestId when troubleshooting.

{
  "Code": 0,
  "Message": "success",
  "RequestId": "3574501647605445341",
  "Data": {
    "Tencent": {
      "TaskId": "1400341231-EditMedia-0d8b6f0a5c457f5722e6b27796ce1f2ctt0",
      "RequestId": "07f0bdbc-6a52-4ef9-ba7b-e96d6c81d6c3"
    },
    "Huawei": {
      "TaskId": "112037345",
      "RequestId": "7a690e874857106ccfa5bed198cdsd79"
    }
  }
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "3574501647605445341",
  "Data": {
    "Tencent": {
      "TaskId": "1400341231-EditMedia-0d8b6f0a5c457f5722e6b27796ce1f2ctt0",
      "RequestId": "07f0bdbc-6a52-4ef9-ba7b-e96d6c81d6c3"
    },
    "Huawei": {
      "TaskId": "112037345",
      "RequestId": "7a690e874857106ccfa5bed198cdsd79"
    }
  }
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "3574501647605445341",
  "Data": {
    "Tencent": {
      "TaskId": "1400341231-EditMedia-0d8b6f0a5c457f5722e6b27796ce1f2ctt0",
      "RequestId": "07f0bdbc-6a52-4ef9-ba7b-e96d6c81d6c3"
    },
    "Huawei": {
      "RequestId": "7a690e874857106ccfa5bed198cdsd79",
      "TaskId": "112037345"
    }
  }
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "3574501647605445341",
  "Data": {
    "Tencent": {
      "TaskId": "1400341231-EditMedia-0d8b6f0a5c457f5722e6b27796ce1f2ctt0",
      "RequestId": "07f0bdbc-6a52-4ef9-ba7b-e96d6c81d6c3"
    },
    "Huawei": {
      "RequestId": "7a690e874857106ccfa5bed198cdsd79",
      "TaskId": "112037345"
    }
  }
}

Merge Media Files

https://rtc-api.zego.im/

Request

Query Parameters

Responses​

Responses