Live Streaming API
How to authenticate
All live streaming API methods, except /v1/access_token, require a bearer-type Authorization header containing an access token. To acquire an access token you should call /v1/access_token API method described below.
Passing Authorization header with cURL:
curl -X $HTTP_METHOD -H "Authorization: Bearer $ACCESS_TOKEN" https://api-live.qencode.com/v1/$OBJECT
All requests must be made over HTTPS.
Getting Access Token
Qencode requires API keys to generate access tokens that are used to authenticate all of your live stream requests. To get an access_token, you must provide your API key in the authorization header of the request.
You can view and manage the API keys associated with your projects inside of your Qencode Account.
Access token is valid for 24 hours.
For live-streaming, an API key is assigned to each Project created in your Qencode account. After logging into your account, you can manage your API keys on the Live Streaming Projects page, as well as track the usage of each Project on the Statistics page.
After API key authentication is complete, you will receive this session based token, which can be used to call all other live streaming API methods.
Replace the 'your_api_key' value below with your API key. You can find you API key in your Live Streaming Project within your account.
curl -X POST https://api-live.qencode.com/v1/access_token/your_api_key
Token returned should be passed in Authorization header to all other live streaming API methods described below
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyjpYXQiOjE2MjgxNTgyNJMsInN1YiI6MTMwLCJleHAiOjE2MjgyNDQ2NjN9.SxS3zLx2CZbZ9ylTpd25kj9el6_4TqqTWUA9RT2iJ9I"
}
Creating a Live Stream
You can use your access token to create a live stream, and receive all the information you need to start streaming and playback.
You can pass optional JSON data containing stream params.
The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.
The fully qualified domain name for the live stream playback.
You should create a domain for playback first using the content delivery API or Content Delivery section in the portal UI.
Specifies the output url path to a folder in your bucket.
Example: s3://example.com/bucket/video-files/.
Supported storage prefixes are:
- s3:// - for any S3-compatible storage (Qencode, AWS, GCS, DigitalOcean, etc.)
- b2:// - for Backblaze B2
- azblob:// - for Azure Blob Storage
- ftp:// or ftps:// - for any FTP server
- sftp:// - for any FTP over SSH server
For S3 only. Specifies object access permissions. For AWS possible values are: 'private', 'public-read', 'authenticated-read', 'bucket-owner-read' and others described in Access Control List Overview. Default value is 'private'.
Specify 'public-read' value in order to make output video publicly accessible.
Only for AWS S3. Specifies storage class for the output. You can specify REDUCED_REDUNDANCY value in order to lower your storage costs for noncritical, reproducible data. See Reduced redundancy storage description.
Possible values: 'original', 'transcoded' or 'auto' (default).
- original - system tries to record the original ingested stream
- transcoded - records the highest available transcoded resolution
- auto - in this mode system will try to record original stream but will switch to transcoded in case of any incompatibility of incoming stream and recording container
Only applies to to transcoded stream source. Ignored in case stream_source param is set to 'original'.
Possible values: 'highest', 'lowest', '240p', '480p', '720p', '1080p', '1440p', '4k', 'all'. By default the highest transcoded resolution is recorded.
In case the highest transcoded resolution is lower than the specified one, system tries to record the closest one.
You can also record all transcoded streams by specifying 'all' as value for resolution.
Possible values: 'mp4' (default), 'ts' or 'hls'.
Use 'ts' for better compatibility if you want to record the original ingested stream instead of transcoded one.
You can also specify a list of output formats, e.g. ['mp4', 'hls'].
Specifies maximum duration of a recorded video file.
In case the stream lasts longer than max_file_duration seconds, system creates another video file and starts transfer of the recorded one to destination specified.
Max value - 21600 seconds (6 hrs). Defaults to 14400 (4 hrs).
Contains the list of server URLs available for ingest. Server URL needs to be set when streaming through third-party client software like OBS.
Available types of server URLs:
- rtmp
- webrtc
- srt
You only can use one URL at a time.
RTMP url is always available. You need to call start API method for the stream before you can see WebRTC and SRT URLs.
See possible status values description below.
created | A new stream has just been created. |
starting | Allocating transcoding resources to process live streaming. |
waiting | Transcoder is ready and waiting for input stream. |
launching | Input stream is being transcoded, but waiting for output stream to begin playback. |
live | The stream is currently live. |
idle | Input stream was stopped. Transcoder is ready and waiting for input stream. |
stopping | The live stream is stopping. |
stopped | The live stream has stopped. |
curl -X POST 'https://api-live.qencode.com/v1/live-streams' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '{"name": "test-stream-name", "input_format": "rtmp", "output_format": "hls"}'
{
"stream": {
"id": "12345fcd-7aea-492c-b9eb-b4b0cde0dc7e",
"server_urls": {
"rtmp": "rtmp://rtmp-live.qencode.com/qlive"
},
"status": {
"timestamp": "2021-08-28 17:59:33",
"name": "created"
},
"name": "test-stream-name",
"playback_ids": [
{
"policy": "public",
"created": "2021-08-28 17:59:33",
"id": "Av22X1p8h5",
"playback_url": "https://play-Av22X1p8h5.qencode.com/qhls/qlive/playlist.m3u8"
}
],
"created_at": "2021-08-28 17:59:33",
"stream_key": "12345be3-7590-4efa-b476-d99e7757b8c4",
"params": {
"output_format": "hls",
"callback_url": null,
"framerate": 0,
"mode": "auto",
"input_format": "rtmp"
}
}
}
Getting a Live Stream Data
Gets a live stream information.
Specifies the output url path to a folder in your bucket.
Example: s3://example.com/bucket/video-files/.
Supported storage prefixes are:
- s3:// - for any S3-compatible storage (Qencode, AWS, GCS, DigitalOcean, etc.)
- b2:// - for Backblaze B2
- azblob:// - for Azure Blob Storage
- ftp:// or ftps:// - for any FTP server
- sftp:// - for any FTP over SSH server
For S3 only. Specifies object access permissions. For AWS possible values are: 'private', 'public-read', 'authenticated-read', 'bucket-owner-read' and others described in Access Control List Overview. Default value is 'private'.
Specify 'public-read' value in order to make output video publicly accessible.
Only for AWS S3. Specifies storage class for the output. You can specify REDUCED_REDUNDANCY value in order to lower your storage costs for noncritical, reproducible data. See Reduced redundancy storage description.
Possible values: 'original', 'transcoded' or 'auto' (default).
- original - system tries to record the original ingested stream
- transcoded - records the highest available transcoded resolution
- auto - in this mode system will try to record original stream but will switch to transcoded in case of any incompatibility of incoming stream and recording container
Only applies to to transcoded stream source. Ignored in case stream_source param is set to 'original'.
Possible values: 'highest', 'lowest', '240p', '480p', '720p', '1080p', '1440p', '4k', 'all'. By default the highest transcoded resolution is recorded.
In case the highest transcoded resolution is lower than the specified one, system tries to record the closest one.
You can also record all transcoded streams by specifying 'all' as value for resolution.
Possible values: 'mp4' (default), 'ts' or 'hls'.
Use 'ts' for better compatibility if you want to record the original ingested stream instead of transcoded one.
You can also specify a list of output formats, e.g. ['mp4', 'hls'].
Specifies maximum duration of a recorded video file.
In case the stream lasts longer than max_file_duration seconds, system creates another video file and starts transfer of the recorded one to destination specified.
Max value - 21600 seconds (6 hrs). Defaults to 14400 (4 hrs).
Contains the list of server URLs available for ingest. Server URL needs to be set when streaming through third-party client software like OBS.
Available types of server URLs:
- rtmp
- webrtc
- srt
You only can use one URL at a time.
RTMP url is always available. You need to call start API method for the stream before you can see WebRTC and SRT URLs.
See possible status values description below.
created | A new stream has just been created. |
starting | Allocating transcoding resources to process live streaming. |
waiting | Transcoder is ready and waiting for input stream. |
launching | Input stream is being transcoded, but waiting for output stream to begin playback. |
live | The stream is currently live. |
idle | Input stream was stopped. Transcoder is ready and waiting for input stream. |
stopping | The live stream is stopping. |
stopped | The live stream has stopped. |
curl -H "Authorization: Bearer $ACCESS_TOKEN"
-X GET https://api-live.qencode.com/v1/live-streams/12345fcd-7aea-492c-b9eb-b4b0cde0dc7e
{
"stream": {
"id": "12345fcd-7aea-492c-b9eb-b4b0cde0dc7e",
"server_urls": {
"rtmp": "rtmp://rtmp-live.qencode.com/qlive"
},
"status": {
"timestamp": "2021-08-28 17:59:33",
"name": "created"
},
"name": "test-stream-name",
"playback_ids": [
{
"policy": "public",
"created": "2021-08-28 17:59:33",
"id": "Av22X1p8h5",
"playback_url": "https://play-Av22X1p8h5.qencode.com/qhls/qlive/playlist.m3u8"
}
],
"created_at": "2021-08-28 17:59:33",
"stream_key": "12345be3-7590-4efa-b476-d99e7757b8c4",
"params": {
"output_format": "hls",
"callback_url": null,
"framerate": 0,
"mode": "auto",
"input_format": "rtmp"
}
}
}
Listing Live Streams
Gets a list of user live streams.
You can optionally pass a filter object. It enables filtering of streams by specifying properties of the objects within the stream as query string parameters, including support for nested object properties. This allows for a flexible querying of complex data structures, accommodating conditions on both top-level and nested attributes.
Filtering Method Details
-
Nested Property Support: The method accepts keys for filtering in a dot-separated format within the query string (e.g.,
params.dvr.enabled=true
) to specify nested object properties. This allows for deep filtering into nested stream data structures. -
Flexible Value Comparison: The method supports filtering based on three types of value comparisons in the query string:
-
Equality to a Specific Value: The stream object's property must exactly match the value specified (e.g.,
status.name=live
). -
Null Value Check: To check for null values, use the property name with a value of
null
(e.g.,playback_domain=null
). -
Non-Null Value Check: To check for non-null values, use the property name with a value of
notnull
(e.g.,playback_domain=notnull
).
-
Equality to a Specific Value: The stream object's property must exactly match the value specified (e.g.,
Note: All conditions specified in the query string are united using the AND operator, meaning that a stream must meet all specified conditions to be included in the result.
Filtering Examples
Example 1:
Query String: ?playback_domain=notnull
In this example, the result will contain all streams that have a playback_domain
.
Example 2:
Query String: ?status.name=live¶ms.dvr.enabled=true
This example will return all streams that are currently live and have DVR enabled.
curl -H "Authorization: Bearer $ACCESS_TOKEN"
-X GET https://api-live.qencode.com/v1/live-streams
{
"streams": [
{
"id": "7297653f-5a79-4c58-9dbd-972141822b59",
...
},
{
"id": "e09066ca-b200-4b67-bf37-122137f31f8a",
...
}
...
]
}
Starting a live stream
Prepares system for live stream ingest.
Sends a message to the system so it can allocate a transcoder for the stream.
You must call this method when starting a stream with WebRTC or SRT input. WebRTC and SRT Server URLs are returned in server_urls array in stream data.
For RTMP input format calling this method is optional, but helps to minimize the time for stream to get live.
Updated live stream object.
Specifies the output url path to a folder in your bucket.
Example: s3://example.com/bucket/video-files/.
Supported storage prefixes are:
- s3:// - for any S3-compatible storage (Qencode, AWS, GCS, DigitalOcean, etc.)
- b2:// - for Backblaze B2
- azblob:// - for Azure Blob Storage
- ftp:// or ftps:// - for any FTP server
- sftp:// - for any FTP over SSH server
For S3 only. Specifies object access permissions. For AWS possible values are: 'private', 'public-read', 'authenticated-read', 'bucket-owner-read' and others described in Access Control List Overview. Default value is 'private'.
Specify 'public-read' value in order to make output video publicly accessible.
Only for AWS S3. Specifies storage class for the output. You can specify REDUCED_REDUNDANCY value in order to lower your storage costs for noncritical, reproducible data. See Reduced redundancy storage description.
Possible values: 'original', 'transcoded' or 'auto' (default).
- original - system tries to record the original ingested stream
- transcoded - records the highest available transcoded resolution
- auto - in this mode system will try to record original stream but will switch to transcoded in case of any incompatibility of incoming stream and recording container
Only applies to to transcoded stream source. Ignored in case stream_source param is set to 'original'.
Possible values: 'highest', 'lowest', '240p', '480p', '720p', '1080p', '1440p', '4k', 'all'. By default the highest transcoded resolution is recorded.
In case the highest transcoded resolution is lower than the specified one, system tries to record the closest one.
You can also record all transcoded streams by specifying 'all' as value for resolution.
Possible values: 'mp4' (default), 'ts' or 'hls'.
Use 'ts' for better compatibility if you want to record the original ingested stream instead of transcoded one.
You can also specify a list of output formats, e.g. ['mp4', 'hls'].
Specifies maximum duration of a recorded video file.
In case the stream lasts longer than max_file_duration seconds, system creates another video file and starts transfer of the recorded one to destination specified.
Max value - 21600 seconds (6 hrs). Defaults to 14400 (4 hrs).
Contains the list of server URLs available for ingest. Server URL needs to be set when streaming through third-party client software like OBS.
Available types of server URLs:
- rtmp
- webrtc
- srt
You only can use one URL at a time.
RTMP url is always available. You need to call start API method for the stream before you can see WebRTC and SRT URLs.
See possible status values description below.
created | A new stream has just been created. |
starting | Allocating transcoding resources to process live streaming. |
waiting | Transcoder is ready and waiting for input stream. |
launching | Input stream is being transcoded, but waiting for output stream to begin playback. |
live | The stream is currently live. |
idle | Input stream was stopped. Transcoder is ready and waiting for input stream. |
stopping | The live stream is stopping. |
stopped | The live stream has stopped. |
curl -H "Authorization: Bearer $ACCESS_TOKEN"
-X POST https://api-live.qencode.com/v1/live-streams/$STREAM_ID/start
{
"stream": {
"id": "12345fcd-7aea-492c-b9eb-b4b0cde0dc7e",
"server_urls": {
"rtmp": "rtmp://rtmp-live.qencode.com/qlive",
"webrtc": "wss://live-df6607d4-8867-4a30-906d-0fed54e58f97.qencode.com:3334/qlive/534ce5b1-dfd7-4daa-8121-bc5c68bbeb37?direction=send&transport=tcp",
"srt": "srt://live-df6607d4-8867-4a30-906d-0fed54e58f97.qencode.com:9999?streamid=534ce5b1-dfd7-4daa-8121-bc5c68bbeb37"
},
"status