Skip to main content

Create streaming key

This method creates a streaming key.

Prototype

  • Method: POST
  • Endpoint: https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/streamkeys

Create a key before streaming to ensure that the media stream is pushed to the correct channel and under the correct host ID.

Important
Keep the created streaming key secure to prevent unauthorized streaming to the channel.

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

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
channelStringRequiredThe Agora channel name. The string length must be less than 64 bytes. The following character sets are supported (89 characters in total):
  • All lowercase English letters (a-z)
  • All uppercase English letters (AZ)
  • Numbers 0-9
  • Space
  • !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,.
You can leave this field empty. A random integer UID will be used to enter the channel, in the format of "GR-xxxx". The specific UID value can be obtained by querying the streaming list or receiving notifications about events.
uidStringRequiredThe host user UID in the Agora channel. Can be a numeric ID or a string ID. For numeric IDs, the value range is from 1 to 232 -1, that is, 4294967295. A greater value will be recognized as a string. For string IDs, the value cannot exceed 255 bytes or be empty. The following character sets are supported (89 characters in total):
  • All lowercase English letters (a-z)
  • All uppercase English letters (AZ)
  • Numbers 0-9
  • Space
  • !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,.
You can leave this field empty or pass in 0. A random integer UID will be used to enter the channel. The specific UID value can be obtained by querying the streaming list or receiving notifications about events.
Important
The channel and uid parameters cannot be empty or 0 at the same time.
Examples of the entered uid values and the actual ID values:
  • "123" - integer UID, 123
  • "0123" - integer UID, 123
  • "4294967295" - integer UID, 4294967295,
  • "4294967296" - string UID, "4294967296",
  • "123abc" - string UID, "123abc".
expiresAfterNumberRequiredThe validity period of the created streaming key in seconds, from the time of creation. If set to 0, the streaming key will always be valid.
Important
To ensure a successful request, do not leave this field empty or set to null.
templateIdStringOptionalThe associated flow configuration template ID. For details, see template API documentation. Do not provide this field if you have not created a configuration template. If not provided, the default configuration will be used.

Request example


_13
curl --request POST \
_13
--url https://api.sd-rtn.com/region/v1/projects/yourActualAppId/rtls/ingress/streamkeys \
_13
--header 'Accept: application/json' \
_13
--header 'Authorization: Basic <Base64EncodedCredentials>' \
_13
--header 'Content-Type: application/json' \
_13
--header 'X-Request-ID: <UniqueRequestID>' \
_13
--data '{
_13
"settings": {
_13
"channel": "shx001",
_13
"uid": "1001",
_13
"expiresAfter": 0
_13
}
_13
}'

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.
dataObjectIncludes the following fields:
  • streamKey: String, the newly created streaming key.
  • channel: String. The name of the Agora channel associated with the streaming key.
  • uid: String, the user UID in the Agora channel associated with the streaming key.
  • expiresAfter: Integer, the validity period of the streaming key from the time of creation, in seconds.
  • createdAt: String, the Unix timestamp for when the streaming key was created, in seconds.

Response example

The following is a response example for a successful request:


_10
{
_10
"status": "success" , "success",
_10
"data"{: {
_10
"streamKey": "2dfMTR****fys",
_10
"channel": "shx001",
_10
"uid": "1001",
_10
"expiresAfter": 0,
_10
"createdAt": "1686820170"
_10
}
_10
}

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