Create or reset template

This method creates or resets a flow configuration template.

• Method: PUT
• Endpoint: https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/stream-templates/:templateId

In the template, you can configure transcoding parameters for video or audio streams, as well as parameters for mitigating network latency.

Up to 10 flow configuration templates can be created under an app ID, each with a unique templatedId. Specify the templateId when creating a template; if a template corresponding to this ID already exists, the existing template will be reset with the incoming body data.

There are two ways to use flow configuration templates, which can be used in combination:

• Specify a global template for the app ID: All streaming keys under the app ID will use this template by default.
• Specify a configuration template for a specific streaming key: When using this key to push streams, the specific template will be used.

Note

By default, a template is not set for the app ID. That is, video transcoding is not enabled.

Authentication

• HTTP Basic Authentication

  Every time you send an HTTP request, you must pass in a credential in the Authorization field in the HTTP request header. See RESTful Authentication on how to generate it.

  Basic authentication is a simple authentication scheme built into the HTTP protocol. To use it, send your HTTP requests with an Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password.

  Example: Authorization: Basic ZGVtbzpwQDU1dzByZA==

• HTTP HMAC Authentication

  Every time you send an HTTP request, you must pass in an API key in the Authorization field in the HTTP request header. See RESTful Authentication on how to generate it.

  Example: Authorization: 123

Path parameters

Parameter	Data type	Required/Optional	Description
appId	String	Required	The app ID provided by Agora to each developer. After creating a project in Agora Console, you can get an app ID. The app ID is a unique identifier for a project.
region	String	Required	Create an area for pushing the streaming key. Agora supports creation of stream keys by region. Currently, the following regions are supported: na: North America eu: Europe ap: Asia, except mainland China cn: Mainland China Important Make sure that: The region value is the same as for the input source stream. The domain names for setting the region parameter and streaming are the same. The region value is in lowercase.
templateId	String	Required	The flow configuration template ID. The value can only include the following characters: a-z, A-Z, 0-9, and the length cannot exceed 12 bytes. The value of the flow configuration template ID can be set according to your business use-case. For example, "720p" and "1080p" for different target resolutions, or "gameA" and "gameB"for different game use-cases.

Headers

Header	Data type	Description
X-Request-ID	String	The UUID (Universally Unique Identifier) of the request. After passing in this field, the Agora server will return this field in the response header. It is recommended to assign X-Request-ID a value. If no value is assigned, the Agora server will automatically generate a UUID and pass it in.

Request body

The request body consists of a JSON Object type settings and includes the following fields:

Parameter	Data type	Required/Optional	Description
transcoding	Object	Optional	Audio and video transcoding parameter configuration. video: Object, video transcoding parameters. Includes the following fields: enabled: Whether to enable video transcoding. Disabled by default. mode: String, the transcoding mode. force(default): Force transcoding. adaptive: Adaptive transcoding: When the source stream has B-frames, transcoding is enabled. When B-frames appear in the first 2 seconds of streaming, transcoding is enabled. When B-frames appear during streaming, transcoding is enabled once they appear. During this transition, the audience will see that the host stops and then immediately resumes streaming. codec: String, the codec format for transcoding. Supported values are H.264 (default) and VP8. width: Number, the encoding height of the main stream, in px. The value range is [0,3840]. If height is not specified or set to 0, the width of the source stream is used. If height has a value other than 0, the "short side fixed, long side adaptive" function is implemented Note If the ABR function is enabled, this field is required. height Number, The encoding height of the main stream, in px. The value range is [0,3840]. If width is not specified or set to 0, the height of the source stream is used. If width has a value other than 0, the "long side fixed, short side adaptive" function is implemented. Note If the ABR function is enabled, this field is required. fps: Number, the video encoding frame rate in fps. The value range is 0 to 60. If not specified or set to 0, the frame rate of the source stream is used. bitrate: Number, the encoding bitrate of the main stream, in Kbps. The value range is [0,20000]. If not specified, the bitrate of the source stream is used. If set to 0, the bitrate recommended by Agora is automatically used based on width and height. For details, see Common video resolutions. info If you enable low-speed streaming (provide the following simulcastStream object), this field is required. If you do not enable low-speed streaming, it is recommended to use the automatically matched bitrate without setting the bitrate yourself. advancedOptions Advanced configuration for video transcoding. pvc: Number, Enable and configure the PVC function. enabled: Boolean, indicates whether to enable PVC. The default value is false. saveBitrateRatio Indicates the bitrate ratio saved by PVC. For example, 20 means saving 20% of the bitrate. info This parameter is effective only when video.bitrate is missing or 0. For the relationship between the two parameters, see PVC and Super Quality configuration. superResolution: Object, enable and configure Super Resolution. enabled: Boolean, indicates whether to enable super image quality. The default value is false. alphaBlending: Number, Indicates the intensity of super quality. The value range is [1, 256]. The larger the value, the higher the intensity. The default value is 128. simulcastStream: Object, video stream configuration. If provided, enable the low-quality stream and specify the transcoding parameters for it. width: Number, the width of the video stream in px. The value range is 0 to 3840. The value of this parameter must be less than video.width. If left blank or set to 0, a value of video.width/2 is used. height Number, the height of the video stream. The value range is 0 to 3840. The value of this parameter must be less than video.height. If left blank or set to 0, a value of video.height/2 is used. fps: Number, the frame rate of the video stream in fps. The value range is 0 to 60. The value of this parameter must be less than or equal to video.fps. If left blank or set to 0, a default value of 15 is used. bitrate: The bitrate of the low-quality video stream, in Kbps. The value of this parameter must be less than video.bitrate. If left blank or set to 0, an appropriate bitrate is set automatically based on the video.bitrate, resolution and fps of the low-quality stream. info When enabling the low-quality stream and specifying low-quality bitrate, you need to specify video.bitrate at the same time. simulcastStreamLayers Array: Layers transcoding parameter configuration for ABR. If specified, ABR function is enabled; if not specified, ABR is disabled. info You can set either simulcastStream or simulcastStreamLayer. If you set both, simulcastStream setting does not take effect. For resolution and bitrate settings for main and ABR streams, recommended values, and viewer subscription settings, refer to Enable adaptive bitrate. id Number Required: Specifies the layer ID. The value range is [1,7]. width Number: Specifies the encoding width of the layer in pixels. If specified, this value must be smaller than the video.width value and must decrease monotonically as the layer ID increases. If not specified or set to 0, height must be specified as a non-zero value to enable the "short side fixed, long side adaptive" behavior. height Number: Specifies the encoding height of the layer in pixels. If specified, this value must be smaller than the video.height value and must decrease monotonically as the layer ID increases. If not specified or set to 0, width must be specified as a non-zero value to enable the "long side fixed, short side adaptive" behavior. fps Number: Specifies the encoding frame rate of the Layer in fps. If specified, the value of this parameter must be smaller than the video.fps value. If not specified or set to 0, the frame rate of the main stream is used. bitrate Number Required: Specifies the encoding bitrate of the layer in Kbps. If specified, the value of this parameter must be smaller than the video.bitrate value and decrease monotonically in the order of layer ID from small to large. audio: Object, audio transcoding parameters. Includes the following fields: enabled: Boolean, whether to enable audio transcoding. Enabled by default. profile: Number, encoded audio use-cases. The default value is 0, which means 48 KHz sampling rate, music encoding, mono, and the maximum encoding rate is 64 Kbps. If you want to set other settings profile, please contact technical support. bitrate: Number, the encoding bitrate in Kbps. If left blank, it is determined by the profile value. The range is 64 to 320.
jitterBuffer	Object	Optional	Network jitter buffer. Only takes effect when video transcoding is enabled. size: Number, the maximum length in ms. The default value is 500, which means that Media Gateway will add 500 ms to the end-to-end delay to reduce lag caused by network jitter. maxSize: Number, the maximum length in ms. The default value is 1000. Make sure that the value of this field is greater than jitterBuffer.size. When jitterBuffer exceeds this value, Media Gateway will enable acceleration until it returns to jitterBuffer.size.

_29

curl --location -g --request PUT 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/stream-templates/{{templateId}}' \

_29

--data '{

_29

"settings": {

_29

"transcoding": {

_29

"video": {

_29

"enabled": true,

_29

"codec": "H.264",

_29

"width": 1280,

_29

"height": 720,

_29

"fps": 24,

_29

"bitrate": 2200,

_29

"simulcastStream": {

_29

"width": 960,

_29

"height": 540,

_29

"fps": 24,

_29

"bitrate": 1670

_29

}

_29

},

_29

"audio": {

_29

"enabled": false,

_29

"profile": 3

_29

}

_29

},

_29

"jitterBuffer": {

_29

"size": 500,

_29

"maxSize": 800

_29

}

_29

}

_29

}'

Headers

Header	Data type	Description
X-Request-ID	String	The UUID (Universally Unique Identifier) of the request. The value is in its X-Request-ID header. If a request error occurs, print the value in the log to troubleshoot the problem. A 401 (Unauthorized) response status code means that there is no such field in the response header.

Response body

For details about possible response status codes, see Response status codes.

If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure.

If the status code is 200, the request succeeds, and the response body includes the following parameters:

Parameter	Type	Description
status	String	The status of this request. success means the request succeeds.

The following is a response example for a successful request:

_3

{

_3

"status": "success"

_3

}

Info

To explore the RESTful API parameters, obtain sample code in various client languages, or test Media Gateway requests, refer to the Postman API reference.

Resolution (width × height, px)	Frame rate (fps)	Bitrate (Kbps)
640 × 360	15	680
640 × 360	30	1030
848 × 480	15	920
848 × 480	30	1400
960 × 540	15	1100
960 × 540	30	1670
1280 × 720	15	1600
1280 × 720	30	2400
1920 × 1080	15	2500
1920 × 1080	30	3780
1920 × 1080	60	5730