实时音视频
服务端 API
当前页

合并媒体文件

2026-08-07
GET

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

用户进行 CDN 录制时,会把录制好的媒体文件存放在 CDN 服务器上,用户可以调用本接口将多个媒体文件进行 裁剪合并

目前仅支持合并 MP3/MP4/M3U8 格式的媒体文件。

注意
  • 首次使用本接口之前,请确认是否已经开通 CDN 录制服务。若未开通,请前往 ZEGO 控制台 自助开通,详情请参考 控制台 - 服务配置 - CDN,或联系 ZEGO 技术支持开通。
  • 请联系 ZEGO 技术支持开通合并媒体文件功能,并配置回调地址,媒体文件合并完成后会通过 媒体文件合并完成回调 通知。
  • 使用该功能合并后的录制文件会永久保存,不能通过配置来修改保存天数。若需要删除,可以使用 删除媒体文件 接口进行删除。
调用频率限制
同一个 AppID 下所有房间:20 次/秒

Request

Query Parameters

    Action string必填

    可选值: [MergeMedia]

    接口原型参数

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

    AppId uint32必填

    💡公共参数。应用 Id,由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台 获取。

    SignatureNonce string必填

    💡公共参数。16 位 16 进制随机字符串(8 字节随机数的 hex 编码)。生成算法可参考 签名示例

    Timestamp int64必填

    💡公共参数。当前 Unix 时间戳,单位为秒。生成算法可参考 签名示例,最多允许 10 分钟的误差。

    Signature string必填

    💡公共参数。签名,用于验证请求的合法性。请参考签名机制生成。

    SignatureVersion string必填

    可选值: [2.0]

    默认值: 2.0

    💡公共参数。签名版本号。

    Vendor string必填

    可选值: [Tencent, Huawei]

    可能的取值及对应的 CDN 厂商:

    • Tencent:腾讯云。
    • Huawei:华为云。
    Format string

    默认值: MP4

    合并后的文件格式,默认格式为 MP4。

    • 腾讯云:MP3、MP4、M3U8。

      注意
      使用的 CDN 厂商是“腾讯云”时,如果合并后的文件为 MP3 或 MP4 格式,您需要确保输入源文件的“音频格式”为 AAC-LC 编码,否则合并后的视频文件可能没有声音。
    • 华为云:MP4、M3U8。

    Type string

    可选值: [0, 1]

    默认值: 0

    合并操作类型。

    • 0:默认值,不裁剪,直接合并文件。
    • 1:对媒体文件进行裁剪等操作后,再合并文件。此时 InputFileId[] 参数无效,此时必须传入 HandleMediaArgs.N.FileId 参数。

    该参数取值为 1 时,仅对 Vendor 取值为 Tencent 有效,取值为 Huawei 无效。

    示例: 1
    InputFileId[] string[]

    可选值: >= 1, <= 20

    • Type 取值为 0,此参数有效,且必选。
    • Type 取值为 1,此参数无效。

    要合并的文件 ID 列表,按照文件列表的顺序进行合并。其中:

    示例:InputFileId[]=5285890813221514958&InputFileId[]=5285890813221513290

    HandleMediaArgs object[]

    可选值: >= 1, <= 10

    Type 取值为 1,此参数有效。

    Array[
    FileId string必填

    需要裁剪后、再进行合并的文件 ID 列表,按照字段名中 N 从小到大的顺序进行合并,最多支持合并 10 个文件。

    注意
    N 必须从 0 开始,并依次递增,最大值为 9。不从 0 开始、或跳过某个数字,将无法正确裁剪合并文件。

    例如,HandleMediaArgs.0.FileId=5285890813221514958&HandleMediaArgs.1.FileId=5285890813221513290

    Query 参数名HandleMediaArgs.N.FileId
    StartTime double

    默认值: 0

    HandleMediaArgs.N.FileId 对应的媒体文件开始裁剪的时间偏移量,默认为 0,单位:秒。

    例如,HandleMediaArgs.0.StartTime 对应的是 HandleMediaArgs.0.FileId 这个媒体文件的开始裁剪时间。

    Query 参数名HandleMediaArgs.N.StartTime
    EndTime double

    HandleMediaArgs.N.FileId 对应的媒体文件结束裁剪的时间偏移量,默认为视频文件的结束时间,单位:秒。

    例如,HandleMediaArgs.0.EndTime 对应的是 HandleMediaArgs.0.FileId 这个媒体文件的结束裁剪时间。

    Query 参数名HandleMediaArgs.N.EndTime
    ]
    Query 示例:
    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
    • Vendor 取值为 Tencent,此参数必选。
    • Vendor 取值为 Huawei,此参数非必选,不填则由系统自动生成。

    合并后的媒体文件名称,不包含文件格式。

    使用时,请对该参数内容进行 UrlEncode。

    ExpireTime int32

    默认值: 0

    合并后媒体文件的有效保存时长(单位:小时),即文件过期时间 = 接口请求时间 + 有效保存时长。

    • 取值为 0(默认值):表示文件永久保存不过期。
    • 取值大于 0:超过该时长文件将被删除。
    注意
    • 该字段,仅对 Vendor 取值为 Tencent 时有效。
    • 如果合并媒体文件的任务完成时长,大于其有效保存时长,文件将不会生成,媒体文件合并完成回调 在访问合成后的文件 URL 时会 404。

Responses

成功
Schema
    Code int32

    返回码。
    以下仅列出了接口业务逻辑相关的部分返回码,完整返回码请参考全局返回码

    返回码说明处理建议
    0请求成功。-
    2输入参数错误。-
    3未开通相关权限。请联系 ZEGO 技术支持。
    4CDN 类型不匹配。请检查参数。
    5配置错误。请联系 ZEGO 技术支持。
    6请求过于频繁。请稍后重试。
    7鉴权失败。请检查鉴权参数是否正确。
    1000请求失败。请联系 ZEGO 技术支持。
    41003文件不存在。请确认文件格式、文件 ID 等是否正确。
    Message string

    操作结果描述。

    RequestId string

    请求 ID,由 ZEGO 服务端返回。

    Data object
    响应数据。
    Tencent object
    Vendor 为 Tencent 时返回。
    TaskId string

    制作媒体文件的任务 ID,可以通过该 ID 查询制作任务。

    RequestId string

    唯一请求 ID,由请求参数 Vendor 取值对应的 CDN 厂商(即腾讯云)返回,定位问题时需要提供该次请求的 RequestId。

    Huawei object
    Vendor 为 Huawei 时返回。
    TaskId string

    制作媒体文件的任务 ID,可以通过该 ID 查询制作任务。

    RequestId string

    唯一请求 ID,由请求参数 Vendor 取值对应的 CDN 厂商(即 Huawei)返回,定位问题时需要提供该次请求的 RequestId。

上一篇

删除媒体文件

下一篇

查询媒体文件任务

当前页

返回到顶部