Create or reset template
Updated
Creates or resets a Media Gateway flow configuration template.
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 templateId. 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.
Path Parameters
Region for the streaming key or stream. Supported values are na for North America, eu for Europe, ap for Asia except mainland China, and cn for mainland China.
Important
Make sure that:
- The
regionvalue is the same as for the input source stream. - The domain names for setting the
regionparameter and streaming are the same. - The
regionvalue is in lowercase.
na | eu | ap | cnThe 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.
The flow configuration template ID. The value can contain only lowercase letters, uppercase letters, and numbers, and cannot exceed 12 bytes. Set the value according to your business use case. For example, use "720p" and "1080p" for different target resolutions, or "gameA" and "gameB" for different game use cases.
12Pattern^[A-Za-z0-9]+$Example720pHeader Parameters
The UUID (Universally Unique Identifier) of the request. After you pass in this field, the Agora server returns this field in the response header. It is recommended to assign X-Request-ID a value. If omitted, the Agora server automatically generates a UUID and returns it.
6d35d43f-f4c5-4b3a-9df4-8f0d7e1d5f0aRequest Body
application/json
Note
To ensure a successful request, do not set the required fields to null or leave them empty.
Response Body
application/json
application/json
application/json
Response schema
200application/jsonThe request succeeded and created or reset the template.
The status of this request. success means the request succeeds.
401application/jsonThe request failed. A 401 (Unauthorized) response status code means the request is not authorized.
Response Headers
The UUID (Universally Unique Identifier) of the request. The value is in the X-Request-ID response header. If a request error occurs, print the value in the log to troubleshoot the problem.
200Example6d35d43f-f4c5-4b3a-9df4-8f0d7e1d5f0aRequest examples
curl --location -g --request PUT 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/stream-templates/{{templateId}}' \--data '{ "settings": { "transcoding": { "video": { "enabled": true, "codec": "H.264", "width": 1280, "height": 720, "fps": 24, "bitrate": 2200, "simulcastStream": { "width": 960, "height": 540, "fps": 24, "bitrate": 1670 } }, "audio": { "enabled": false, "profile": 3 } }, "jitterBuffer": { "size": 500, "maxSize": 800 } }}'Response example
{ "status": "success"}{ "status": "error", "message": "Describes why the request failed."}{ "status": "error", "message": "Describes why the request failed."}