StartCloudTranscode

POST

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

简介

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

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

前提条件

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

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

调用频率限制

100 次/秒

单流转码的预设输出模板

预设模版（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

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

Request

Query Parameters

Action stringrequired

Possible values: [StartCloudTranscode]

接口原型参数

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

AppId uint32required

💡公共参数。AppId，ZEGO 分配的用户唯一凭证。

SignatureNonce stringrequired

💡公共参数。随机字符串。

Timestamp int64required

💡公共参数。Unix 时间戳，单位为秒。最多允许 10 分钟的误差。

Signature stringrequired

💡公共参数。签名，用于验证请求的合法性。

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

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

IsTest string

Possible values: [true, false]

Default value: false

💡公共参数。是否为测试环境。设为 true 表示使用测试环境。2021-11-16 及之前在 ZEGO 控制台创建的项目默认是测试环境，可根据业务需求设置此参数；而之后创建的项目默认是正式环境。

application/json

Body

required

TaskId stringrequired

任务 ID，单流转码任务的唯一标识，由开发者自定义。

重复调用"开始单流转码"接口，传入相同的 TaskId，可以直接更新转码任务信息。

UserId stringrequired

发起转码任务的用户 ID，由开发者自定义。同一个 TaskId 任务的用户 ID 需要一致，不同 TaskId 任务的用户 ID 需要保持不同。

通过 UserId 可以实现转码任务的用户归属，也就是该用户才能更新或者停止对应 TaskId 的转码任务，该功能需要联系 ZEGO 技术支持开通。

Sequence int

转码任务的序列号，用于保证时序，同个任务的参数修改需要保证序列号的递增。

TranscodeInput objectrequired

转码任务的输入流设置。

StreamId stringrequired

转码输入流 ID，该流 ID 来自 RTC 服务，仅支持数字、英文字符和 "-"、"_"。

注意

StreamId 和 StreamUrl 二者取其一即可，若同时填写 StreamId 和 StreamUrl，则 StreamUrl 生效。

StreamUrl stringrequired

转码输入流 URL，支持 RTMP 协议。

注意

StreamId 和 StreamUrl 二者取其一即可，若同时填写 StreamId 和 StreamUrl，则 StreamUrl 生效。

TranscodeOutput object[]required

转码任务的输出流信息。

Array[

StreamId stringrequired

输出流 ID。

默认情况下，转码任务输出至 RTC 或低延迟直播产品。
您也可联系 ZEGO 技术支持，配置转码流输出至 ZEGO 代理的 CDN 直播产品，生效范围为整个 AppId。如果指定流输出至 CDN 直播产品，则必须设置 StreamUrl，不能配置转码默认输出至 ZEGO 代理 CDN。

注意

StreamId 和 StreamUrl 二者取其一即可，若同时填写 StreamId 和 StreamUrl，则 StreamUrl 生效。

StreamUrl stringrequired

仅支持 RTMP 协议，表示转码输出至 CDN 直播服务，观众可以从 CDN 直播拉转码流。

注意

StreamId 和 StreamUrl 二者取其一即可，若同时填写 StreamId 和 StreamUrl，则 StreamUrl 生效。

TemplateId int32required

Possible values: [0, 1, 2, 3, 4]

单流转码输出模板 ID，ZEGO 提供了如下模板：

0：输出分辨率为 360P 转码流
1：输出分辨率为 540P 转码流
2：输出分辨率为 720P 转码流
3：输出分辨率为 1080P 转码流
4：自定义模板。通用模板不能满足需求时，请使用自定义模板设置输出参数

请点击单流转码的预设输出模板，查看具体的预设模板配置参数。

TemplateConfig object

自定义模板配置。

VideoEncId int

Possible values: [0, 1, 2]

Default value: 0

输出流的视频编码格式。

0: 默认值，表示输出流编码格式与输入流编码格保持一致。
1: H264
2: H265

Fps int

视频帧率，取值必须大于或等于 0。

0: 默认值，表示输出流帧率与输入流帧率保持一致。
其他值: 转码流的输出帧率，最大帧率默认限制在 20 fps 以内。如果需要输出更大帧率的流，请联系 ZEGO 技术支持进行配置。

目前暂时不支持输出不同帧率的转码流，各个输出流的帧率设置必须保持一致。

GOP int

Default value: 2

转码输出流的关键帧间隔，取值必须大于 0，默认值为 2，单位：秒。

如果需要自定义，请联系 ZEGO 技术支持开启支持自定义。

ShortEdgeAdaption int

Default value: 0

输出流的分辨率是否按照设置的 Width 作为短边，自适应横竖屏。

0: 默认值，直接按照设置的 Width 和 Height 输出。
1: 按照设置的 Width 作为短边，并按照输入流的分辨率，等比例缩放后自适应横竖屏。

Height int

高，范围为 [0, 3000]，数值必须是 2 的倍数。

0: 默认值，与参数 Width 同时为 0，则表示输出流分辨率与输入流分辨率保持一致。
其他值: 转码流自定义分辨率的高。

🔁支持转码过程中实时更新。再次调用本接口，即可动态更新该参数。

Width int

宽，范围为 [0, 3000]，数值必须是 2 的倍数。

0: 默认值，与参数 Height 同时为 0，则表示输出流分辨率与输入流分辨率保持一致。
其他值: 转码流自定义分辨率的宽。

🔁支持转码过程中实时更新。再次调用本接口，即可动态更新该参数。

VideoBitrate int

Default value: 0

视频码率，取值必须大于或等于 0，单位为 bps。

0: 默认值，表示输出码率与输入流码率保持一致。
其他值: 转码流的输出码率。

🔁支持转码过程中实时更新。再次调用本接口，即可动态更新该参数。

LowBitrateHD int

Default value: 0

是否开启“高清低码”功能。

0: 默认值，不开启。
1: 开启。

目前"高清低码"功能需要联系 ZEGO 技术支持开通权限，且仅在 VideoEncId 取值为 2（H265）时生效。

]

Responses

操作成功

application/json

Schema
Example (from schema)

Schema

Code int32

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

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

Message string

操作结果描述。

RequestId string

请求 ID。

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

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

CURL

Base URL

https://rtc-api.zego.im

统一接入地址（不区分区域）

Parameters

Actionqueryrequired

AppIdqueryrequired

SignatureNoncequeryrequired

Timestampqueryrequired

Signaturequeryrequired

SignatureVersionqueryrequired

IsTestquery

Bodyrequired

Example (from schema)
Example

{
  "TaskId": "2213699902971205739",
  "UserId": "456",
  "Sequence": 0,
  "TranscodeInput": {
    "StreamId": "stream1",
    "StreamUrl": ""
  },
  "TranscodeOutput": [
    {
      "StreamId": "stream3",
      "StreamUrl": "",
      "TemplateId": 4,
      "TemplateConfig": {
        "VideoEncId": 0,
        "Fps": 15,
        "GOP": 2,
        "ShortEdgeAdaption": 0,
        "Height": 720,
        "Width": 1280,
        "VideoBitrate": 0,
        "LowBitrateHD": 0
      }
    }
  ]
}

RESPONSEClear

Click the "Send" button above and see the response here!

StartCloudTranscode

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

简介

前提条件

单流转码的预设输出模板

Request

Query Parameters

Body

Responses​

Responses