StartCloudTranscode

POST

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

Overview

This document describes how to use the server-side API to transcode a specified single input Stream into video Streams with different resolutions, bitrates, and frame rates.

For single-stream transcoding triggered by the "client" based on transcoding templates, please refer to Single-Stream Transcoding; for related "server" callbacks, please refer to Single-Stream Transcoding Started Callback and Single-Stream Transcoding Stopped Callback.

Prerequisites

Before implementing single-stream transcoding, ensure that:

You have created a project in the ZEGOCLOUD Console and applied for a valid AppId and ServerSecret. For details, please refer to Console - Project Information.
You have enabled the "Stream Mixing" service permission in the ZEGOCLOUD Console. For details, please refer to Console - Service Configuration - Stream Mixing, or contact ZEGOCLOUD technical support to enable it.

Rate Limit

100 requests/second

Preset output templates for single-stream transcoding

The parameter configurations for preset templates (TemplateId values 0, 1, 2, 3) are as follows:

Template ID	Resolution (Short Edge)	Bitrate (kbps)	Other Configuration
0 (360P)	360	600	Frame rate: Maintained at the original input Stream frame rate. GOP: Default is 2. Video encoding format: Default is H.264. Audio encoding format: Default is AAC-LC. Preset templates output resolution adaptively based on the short edge, with the long edge scaled proportionally according to the short edge of the transcoding template.
1 (540P)	540	1000
2 (720P)	720	1500
3 (1080P)	1080	2000

Only some parameters in this interface support dynamic updates after starting Stream Mixing. Parameters not marked do not support dynamic updates. For details, please refer to the parameter descriptions in the table below.

Request

Query Parameters

Action stringrequired

Possible values: [StartCloudTranscode]

Interface prototype parameters

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

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.

application/json

Body

required

TaskId stringrequired

Task ID, the unique identifier for the single-stream transcoding task, customized by the developer.

Calling the "Start Cloud Transcoding" interface repeatedly with the same TaskId can directly update the transcoding task information.

UserId stringrequired

User ID of the User initiating the transcoding task, customized by the developer. The User ID for the same TaskId must be consistent, and the User IDs for different TaskId tasks must be different.

Through UserId, you can achieve User attribution for transcoding tasks, meaning only this User can update or stop the transcoding task corresponding to the TaskId. This feature requires contacting ZEGOCLOUD technical support to enable.

Sequence int

Sequence number of the transcoding task, used to ensure ordering. Parameter modifications for the same task need to ensure the sequence number is incremented.

TranscodeInput objectrequired

Input Stream settings for the transcoding task.

StreamId stringrequired

Transcoding input Stream ID, which comes from the RTC service. Only supports numbers, English characters, "-", and "_".

Note

Only one of StreamId or StreamUrl is required. If both StreamId and StreamUrl are specified, StreamUrl takes effect.

StreamUrl stringrequired

Transcoding input Stream URL, supports RTMP protocol.

Note

Only one of StreamId or StreamUrl is required. If both StreamId and StreamUrl are specified, StreamUrl takes effect.

TranscodeOutput object[]required

Output Stream information for the transcoding task.

Array[

StreamId stringrequired

Output Stream ID.

By default, the transcoding task outputs to RTC or low-latency live streaming products.
You can also contact ZEGOCLOUD technical support to configure the transcoding Stream output to the ZEGOCLOUD-proxied CDN live streaming product, with the scope taking effect for the entire AppId. If a Stream is specified to output to the CDN live streaming product, StreamUrl must be set, and the default transcoding output to ZEGOCLOUD-proxied CDN cannot be configured.

Note

Only one of StreamId or StreamUrl is required. If both StreamId and StreamUrl are specified, StreamUrl takes effect.

StreamUrl stringrequired

Only supports RTMP protocol, indicating transcoding output to the CDN live streaming service. Audiences can pull the transcoded Stream from the CDN live streaming.

Note

Only one of StreamId or StreamUrl is required. If both StreamId and StreamUrl are specified, StreamUrl takes effect.

TemplateId int32required

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

Single-stream transcoding output template ID. ZEGOCLOUD provides the following templates:

0: Output 360P transcoded Stream
1: Output 540P transcoded Stream
2: Output 720P transcoded Stream
3: Output 1080P transcoded Stream
4: Custom template. When the general template does not meet your requirements, please use the custom template to set output parameters

Please click Preset output templates for single-stream transcoding to view specific preset template configuration parameters.

TemplateConfig object

Custom template configuration.

VideoEncId int

Possible values: [0, 1, 2]

Default value: 0

Video encoding format of the output Stream.

0: Default value, indicating the output Stream encoding format is consistent with the input Stream encoding format.
1: H264
2: H265

Fps int

Video frame rate, must be greater than or equal to 0.

0: Default value, indicating the output Stream frame rate is consistent with the input Stream frame rate.
Other values: Output frame rate of the transcoded Stream. The maximum frame rate is limited to 20 fps by default. If you need to output a Stream with a higher frame rate, please contact ZEGOCLOUD technical support for configuration.

Currently, outputting transcoded Streams with different frame rates is not supported. The frame rate settings for all output Streams must be consistent.

GOP int

Default value: 2

Keyframe interval of the transcoded output Stream, must be greater than 0, default value is 2, unit: seconds.

If you need to customize it, please contact ZEGOCLOUD technical support to enable custom support.

ShortEdgeAdaption int

Default value: 0

Whether the output Stream resolution uses the set Width as the short edge and adapts to landscape or portrait orientation.

0: Default value, output directly according to the set Width and Height.
1: Use the set Width as the short edge, and adapt to landscape or portrait orientation by scaling proportionally according to the input Stream resolution.

Height int

Height, range is [0, 3000], the value must be a multiple of 2.

0: Default value. When both this parameter and Width are 0, it indicates the output Stream resolution is consistent with the input Stream resolution.
Other values: The height of the transcoded Stream's custom resolution.

🔁Supports real-time updates during transcoding. Call this interface again to dynamically update this parameter.

Width int

Width, range is [0, 3000], the value must be a multiple of 2.

0: Default value. When both this parameter and Height are 0, it indicates the output Stream resolution is consistent with the input Stream resolution.
Other values: The width of the transcoded Stream's custom resolution.

🔁Supports real-time updates during transcoding. Call this interface again to dynamically update this parameter.

VideoBitrate int

Default value: 0

Video bitrate, must be greater than or equal to 0, unit is bps.

0: Default value, indicating the output bitrate is consistent with the input Stream bitrate.
Other values: Output bitrate of the transcoded Stream.

🔁Supports real-time updates during transcoding. Call this interface again to dynamically update this parameter.

LowBitrateHD int

Default value: 0

Whether to enable the "HD Low Bitrate" feature.

0: Default value, not enabled.
1: Enabled.

Currently, the "HD Low Bitrate" feature requires contacting ZEGOCLOUD technical support to enable permission, and it only takes effect when VideoEncId is set to 2 (H265).

]

Responses

Operation succeeded

application/json

Schema
Example (from schema)

Schema

Code int32

The following only lists some return codes related to the interface's business logic. For complete return codes, please refer to Global Return Codes.

Return Code	Description	Suggested Action
110200002	Input parameter error.	Please handle according to the Message information.
110200150	The input Stream for single-stream transcoding does not exist.	Please confirm whether the input StreamId or StreamUrl exists.
110200151	Single-stream transcoding task failed.	Please retry, or contact ZEGOCLOUD technical support for assistance.

Message string

Description of the operation result.

RequestId string

Request ID.

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

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

StartCloudTranscode

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

Overview

Prerequisites

Preset output templates for single-stream transcoding

Request

Query Parameters

Body

Responses​

Responses