Skip to main content

Create or reset template

This method creates or resets a flow configuration template.

Prototype

  • 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.

Request parameters

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

ParameterData typeRequired/OptionalDescription
appIdStringRequiredThe 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.
regionStringRequiredCreate 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.
templateIdStringRequiredThe 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

HeaderData typeDescription
X-Request-IDStringThe 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:

ParameterData typeRequired/OptionalDescription
transcodingObjectOptionalAudio 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 × 36015680
        640 × 360301030
        848 × 48015920
        848 × 480301400
        960 × 540151100
        960 × 540301670
        1280 × 720151600
        1280 × 720302400
        1920 × 1080152500
        1920 × 1080303780
        1920 × 1080605730
        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.
jitterBufferObjectOptionalNetwork 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.

Request example


_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
}'

Response parameters

Headers

HeaderData typeDescription
X-Request-IDStringThe 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:

ParameterTypeDescription
statusStringThe status of this request. success means the request succeeds.

Response example

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.

vundefined