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 the 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 scenario. For example, "720p" and "1080p" for different target resolutions, or "gameA" and "gameB"for different game scenarios.

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 width in the encoding resolution. The value range is 0 to 1920. If left blank or filled in with 0, it will follow the width of the source stream. height Number, the height in the encoding resolution. The value range is 0 to 1920. If left blank or filled in with 0, it will follow the height of the source stream. Note The width and height parameters must be filled at the same time, or both left blank. fps: Number, the video encoding frame rate in fps. The value range is 0 to 60. If left blank or filled in with 0, it will follow the frame rate of the source stream. 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 1920. The value of this parameter must be less than video.width. If left blank or filled in with 0, it will use the value of video.width/2. height Number, the height of the video stream. The value range is 0 to 1920. The value of this parameter must be less than video.height. If left blank or filled in with 0, it will use the value of video.height/2. 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 filled in with 0, it will use 15 as default value. 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 filled in with 0, an appropriate bitrate will be set automatically based on the video.bitrate, resolution and fps of the low-quality stream. bitrate: Video encoding bitrate in Kbps. If the low-quality stream is enabled (simulcastStream is provided), then this field is required and the value must be greater than simulcastStream.bitrate. If the low-quality video stream is not enabled, this field is optional. If not filled in, an appropriate bitrate will be set automatically based on the width, height, and fps values. See the following table: 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 Note When the low-quality stream is not enabled, it is recommended to use the automatically set bitrate. audio: Object, audio transcoding parameters. Includes the following fields: enabled: Boolean, whether to enable audio transcoding. Enabled by default. profile: Number, encoded audio scenarios. 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.