开始单流转码

更新时间：2025-04-15 17:17

1 简介

本文介绍如何调用服务端 API 接口，将指定的单路输入流，输出为不同分辨率、码率及帧率的视频流。

“客户端”基于转码模板触发的单流转码介绍，请参考单流转码；“服务端”的相关回调，请参考单流转码开始回调和单流转码停止回调。

2 前提条件

在实现单流转码之前，请确保：

已在 ZEGO 控制台创建项目，并申请有效的 AppId 和 ServerSecret，详情请参考控制台 - 项目信息。
已在 ZEGO 控制台自助接入服务开通“混流”服务权限，详情请参考控制台 - 服务配置 - 混流，或联系 ZEGO 技术支持开通。

3 接口原型

请求方法：POST
使用 POST 请求方法传递参数时：
- Body 中的参数直接传 JsonObject 格式即可，无需序列化为 String 格式。
- Headers 中，设置 “Content-type” 为 “application/json”。

请求地址：https://rtc-api.zego.im/?Action=StartCloudTranscode
传输协议：HTTPS
调用频率限制：100 次/秒

4 请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式中的 “2.1 公共请求参数”。

此接口中只有部分参数在开始混流后支持动态更新，未标注的则不支持动态更新，详情请参考下表中的参数描述。

名称	类型	必填	描述
TaskId	String	是	任务 ID，单流转码任务的唯一标识，由开发者自定义。重复调用“开始单流转码”接口，传入相同的 TaskId，可以直接更新转码任务信息。
UserId	String	是	发起转码任务的用户 ID，由开发者自定义。同一个 TaskId 任务的用户 ID 需要一致，不同 TaskId 任务的用户 ID 需要保持不同。通过 UserId 可以实现转码任务的用户归属，也就是该用户才能更新或者停止对应 TaskId 的转码任务，该功能需要联系 ZEGO 技术支持开通。
TranscodeInput	Object	是	转码任务的输入流设置。
StreamId	String	是	转码输入流 ID，该流 ID 来自 RTC 服务，仅支持数字、英文字符和 "-"、"_"。 StreamId 和 StreamUrl 二者取其一即可，若同时填写 StreamId 和 StreamUrl，则 StreamUrl 生效。
StreamUrl	String	是	转码输入流 URL，支持 RTMP 协议。 StreamId 和 StreamUrl 二者取其一即可，若同时填写 StreamId 和 StreamUrl，则 StreamUrl 生效。
TranscodeOutput	Array of Object	是	转码任务的输出流信息。
StreamId	String	是	输出流 ID。默认情况下，转码任务输出至 RTC 或低延迟直播产品。您也可联系 ZEGO 技术支持，配置转码流输出至 ZEGO 代理的 CDN 直播产品，生效范围为整个 AppId。如果指定流输出至 CDN 直播产品，则必须设置 StreamUrl，不能配置转码默认输出至 ZEGO 代理 CDN。 StreamId 和 StreamUrl 二者取其一即可，若填写了 StreamId，则 StreamUrl 不生效。
StreamUrl	String	是	仅支持 RTMP 协议，表示转码输出至 CDN 直播服务，观众可以从 CDN 直播拉转码流。 StreamId 和 StreamUrl 二者取其一即可，若填写了 StreamId，则 StreamUrl 不生效。
TemplateId	Int	是	单流转码输出模板 ID，ZEGO 提供了如下模板： 0：输出分辨率为 360P 转码流。 1：输出分辨率为 540P 转码流。 2：输出分辨率为 720P 转码流。 3：输出分辨率为 1080P 转码流。 4：自定义模板。通用模板不能满足需求时，请使用自定义模板设置输出参数。请点击单流转码的预设输出模板，查看具体的预设模板配置参数。
TemplateConfig	Object	否	自定义设置输出流的视频参数，TemplateId 取值为 4 时，该参数必填。
VideoEncId	Int	否	输出流的视频编码格式。 0：默认值，表示输出流编码格式与输入流编码格保持一致。 1：H264。 2：H265。
Fps	Int	否	视频帧率，取值必须大于或等于 0。 0：默认值，表示输出流帧率与输入流帧率保持一致。其他值：转码流的输出帧率，最大帧率默认限制在 20 fps 以内。如果需要输出更大帧率的流，请联系 ZEGO 技术支持进行配置。目前暂时不支持输出不同帧率的转码流，各个输出流的帧率设置必须保持一致。
GOP	Int	否	转码输出流的关键帧间隔，取值必须大于 0，默认值为 2，单位：秒。如果需要自定义，请联系 ZEGO 技术支持开启支持自定义。
ShortEdgeAdaption	Int	否	输出流的分辨率是否按照设置的 Width 作为短边，自适应横竖屏。 0：默认值，直接按照设置的 Width 和 Height 输出。 1：按照设置的 Width 作为短边，并按照输入流的分辨率，等比例缩放后自适应横竖屏。
Width	Int	否	宽，范围为 [0, 3000]，数值必须是 2 的倍数。 0：默认值，与参数 Height 同时为 0，则表示输出流分辨率与输入流分辨率保持一致。其他值：转码流自定义分辨率的宽。支持转码过程中实时更新。再次调用本接口，即可动态更新该参数。
Height	Int	否	高，范围为 [0, 3000]，数值必须是 2 的倍数。 0：默认值，与参数 Width 同时为 0，则表示输出流分辨率与输入流分辨率保持一致。其他值：转码流自定义分辨率的高。支持转码过程中实时更新。再次调用本接口，即可动态更新该参数。
VideoBitrate	Int	否	视频码率，取值必须大于或等于 0，单位为 bps。 0：默认值，表示输出码率与输入流码率保持一致。其他值：转码流的输出码率。
LowBitrateHD	Int	否	是否开启“高清低码”功能。 0：默认值，不开启。 1：开启。目前“高清低码”功能需要联系 ZEGO 技术支持开通权限，且仅在 VideoEncId 取值为 3（H265）时生效。
Sequence	Int	否	转码任务的序列号，用于保证时序，同个任务的参数修改需要保证序列号的递增。

单流转码的预设输出模板

预设模版（TemplateId 取值为 0、1、2、3）的各项参数配置如下：

模版 ID	分辨率（短边）	码率（kbps）	其他配置
0（360P）	360	600	帧率：保持为原始输入流帧率。 GOP：默认为 2。视频编码格式：默认为 H.264。音频编码格式：默认为 AAC-LC。预设模板按照短边自适应输出分辨率，根据转码模板的短边自适应输出长边。
1（540P）	540	1000
2（720P）	720	1500
3（1080P）	1080	2000

5 请求示例

请求 URL

https://rtc-api.zego.im/?Action=StartCloudTranscode
&<公共请求参数>

请求消息体

{
    "TaskId": "2213699902971205739",
    "UserId": "456",
    "TranscodeInput": {
        "StreamId": "stream1"
    },
    "TranscodeOutput": [
        {
            "StreamId": "stream3",
            "TemplateId": 3
        }
    ]
}

6 响应参数

参数	类型	描述
Code	Number	返回码。
Message	String	操作结果描述。
RequestId	String	请求 ID。

7 响应示例

{
    "Code": 0,
    "Message": "success",
    "RequestId": "8472822294336370476"
}

8 返回码

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

返回码	说明	处理建议
110200002	输入参数错误。	请参考 Message 信息处理。
110200150	单流转码的输入流不存在。	请确认输入流 StreamId 或 StreamUrl 是否存在。
110200151	单流转码任务失败。	请重试，或联系 ZEGO 技术支持处理。