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

POST

/v1/access_token/<api_key>

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.

Caution

To build a secure solution we strongly recommend that you DO NOT call this method directly from any client application as you will expose your api key publicly. We recommend you first obtain an access token from your server and then pass to the client app.

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.

curl -X POST https://api-live.qencode.com/v1/access_token/your_api_key

{
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyjpYXQiOjE2MjgxNTgyNJMsInN1YiI6MTMwLCJleHAiOjE2MjgyNDQ2NjN9.SxS3zLx2CZbZ9ylTpd25kj9el6_4TqqTWUA9RT2iJ9I"
}

Creating a Live Stream

POST

/v1/live-streams

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.

Input Objects Structure

Live stream name can be passed as an optional parameter when a stream is created.

The input format for the stream. Defaults to rtmp. You may explicitly define stream input format but system dynamically changes it to the appropriate value depending on the server URL type you used for ingest.

The output format for the stream. Defaults to hls.

The maximum time transcoder waits for the input stream before it's auto-stopped. Defaults to 120 seconds. In case stream_timeout is specified for a stream and its value is greater 120 seconds, stream in idle or waiting state is billed same way as for live state.

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.

Output Objects Structure

The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

Every live stream will stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

You can specify callback URL (also known as webhook) to receive updates upon each stream status change. See Updating a live stream for more details on how to set up a callback URL for a stream.

The desired format for ingesting the stream. Possible values: 'rtmp', 'webrtc', 'srt'. You may explicitly define stream input format but system dynamically changes it to the appropriate value depending on the server URL type you used for ingest.

The desired format for stream playback. LL-HLS, CMAF and DASH coming soon!

Can be specified as integer or float value of frames per second. Specify 0 to preserve input frame rate. Current maximum supported frame rate is 30.

In order to start recording your stream, you must set enabled parameter to 1. Defaults to 0.

Describes output endpoint, path, credentials and permissions for the destination of the output files created a result of the API request. You can save to multiple destinations by putting all of your destination objects into array.

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

This is a unique identifier that works in together with your Secret Access Key to authenticate API requests for S3 storage.

It consists of 20 alphanumeric characters.

This is the private key that is used to sign API requests for S3 storage.

It consists of 40 characters including letters, numbers, and special characters.

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.

Stream key is used to identify the stream when pushing from a 3rd party client software like OBS.

An array of playback IDs for the stream. Each playback ID has the following attributes:

A unique identifier for the playback of the output. Can be used to automatically build playback_url for different output formats.

A policy that defines the playback behavior of the output. Possible values: 'public', 'authenticated'. Authenticated policy requires a signed token to play the stream. See Signed tokens tutorial for more information.

The date and time when the playback ID was created.

Depending on the output format you choose, the playback URL is used in conjuction with your player to play your video to your viewers.

Contains the domain name of live stream origin. Is only available for streams in Waiting, Launching, Live or Idle states.

Contains the live stream origin URL. Is only available for streams in Waiting, Launching, Live or Idle states.

Live stream name can be passed as an optional parameter when a stream is created.

Whenever a stream is created, a timestamp is recorded for future reference.

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.

Whenever there is a change in the status of a stream, a timestamp is recorded for future reference.

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

GET

/v1/live-streams/<stream_id>

Gets a live stream information.

The stream object along with all of it's attributes, originally created with the /v1/live-streams method. See stream output objects structure.

Output Objects Structure

The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

Every live stream will stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

You can specify callback URL (also known as webhook) to receive updates upon each stream status change. See Updating a live stream for more details on how to set up a callback URL for a stream.

The desired format for stream playback. LL-HLS, CMAF and DASH coming soon!

Can be specified as integer or float value of frames per second. Specify 0 to preserve input frame rate. Current maximum supported frame rate is 30.

In order to start recording your stream, you must set enabled parameter to 1. Defaults to 0.

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

This is a unique identifier that works in together with your Secret Access Key to authenticate API requests for S3 storage.

It consists of 20 alphanumeric characters.

This is the private key that is used to sign API requests for S3 storage.

It consists of 40 characters including letters, numbers, and special characters.

Specify 'public-read' value in order to make output video publicly accessible.

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.

Stream key is used to identify the stream when pushing from a 3rd party client software like OBS.

An array of playback IDs for the stream. Each playback ID has the following attributes:

A unique identifier for the playback of the output. Can be used to automatically build playback_url for different output formats.

The date and time when the playback ID was created.

Depending on the output format you choose, the playback URL is used in conjuction with your player to play your video to your viewers.

Contains the domain name of live stream origin. Is only available for streams in Waiting, Launching, Live or Idle states.

Contains the live stream origin URL. Is only available for streams in Waiting, Launching, Live or Idle states.

Live stream name can be passed as an optional parameter when a stream is created.

Whenever a stream is created, a timestamp is recorded for future reference.

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.

Whenever there is a change in the status of a stream, a timestamp is recorded for future reference.

 Request Example 
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

GET

/v1/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:
1. Equality to a Specific Value: The stream object's property must exactly match the value specified (e.g., status.name=live).
2. Null Value Check: To check for null values, use the property name with a value of null (e.g., playback_domain=null).
3. Non-Null Value Check: To check for non-null values, use the property name with a value of notnull (e.g., playback_domain=notnull).

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&params.dvr.enabled=true

This example will return all streams that are currently live and have DVR enabled.

In case no filter specified, contains list of all user live streams.

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

POST

/v1/live-streams/<stream_id>/start

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.

Output Objects Structure

The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

Every live stream will stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

You can specify callback URL (also known as webhook) to receive updates upon each stream status change. See Updating a live stream for more details on how to set up a callback URL for a stream.

The desired format for stream playback. LL-HLS, CMAF and DASH coming soon!

Can be specified as integer or float value of frames per second. Specify 0 to preserve input frame rate. Current maximum supported frame rate is 30.

In order to start recording your stream, you must set enabled parameter to 1. Defaults to 0.

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

This is a unique identifier that works in together with your Secret Access Key to authenticate API requests for S3 storage.

It consists of 20 alphanumeric characters.

This is the private key that is used to sign API requests for S3 storage.

It consists of 40 characters including letters, numbers, and special characters.

Specify 'public-read' value in order to make output video publicly accessible.

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.

Stream key is used to identify the stream when pushing from a 3rd party client software like OBS.

An array of playback IDs for the stream. Each playback ID has the following attributes:

A unique identifier for the playback of the output. Can be used to automatically build playback_url for different output formats.

The date and time when the playback ID was created.

Depending on the output format you choose, the playback URL is used in conjuction with your player to play your video to your viewers.

Contains the domain name of live stream origin. Is only available for streams in Waiting, Launching, Live or Idle states.

Contains the live stream origin URL. Is only available for streams in Waiting, Launching, Live or Idle states.

Live stream name can be passed as an optional parameter when a stream is created.

Whenever a stream is created, a timestamp is recorded for future reference.

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.

Whenever there is a change in the status of a stream, a timestamp is recorded for future reference.

 Request Example 
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": {
      "timestamp": "2021-08-28 17:59:33",
      "name": "waiting"
    },
    "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"
      }
    ],
    "origin_host": "live-df6607d4-8867-4a30-906d-0fed54e58f97.qencode.com",
    "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"
    }
  }
}

Stopping a live stream

POST

/v1/live-streams/<stream_id>/stop

Stops a live stream.

Sends a message to the system so it can free transcoding resources. Calling this method is optional, stream is automatically stopped in case a timeout of 120 seconds is reached when waiting for the input stream.

Updated live stream object.

Output Objects Structure

The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

Every live stream will stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

You can specify callback URL (also known as webhook) to receive updates upon each stream status change. See Updating a live stream for more details on how to set up a callback URL for a stream.

The desired format for stream playback. LL-HLS, CMAF and DASH coming soon!

Can be specified as integer or float value of frames per second. Specify 0 to preserve input frame rate. Current maximum supported frame rate is 30.

In order to start recording your stream, you must set enabled parameter to 1. Defaults to 0.

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

This is a unique identifier that works in together with your Secret Access Key to authenticate API requests for S3 storage.

It consists of 20 alphanumeric characters.

This is the private key that is used to sign API requests for S3 storage.

It consists of 40 characters including letters, numbers, and special characters.

Specify 'public-read' value in order to make output video publicly accessible.

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.

Stream key is used to identify the stream when pushing from a 3rd party client software like OBS.

An array of playback IDs for the stream. Each playback ID has the following attributes:

A unique identifier for the playback of the output. Can be used to automatically build playback_url for different output formats.

The date and time when the playback ID was created.

Depending on the output format you choose, the playback URL is used in conjuction with your player to play your video to your viewers.

Contains the domain name of live stream origin. Is only available for streams in Waiting, Launching, Live or Idle states.

Contains the live stream origin URL. Is only available for streams in Waiting, Launching, Live or Idle states.

Live stream name can be passed as an optional parameter when a stream is created.

Whenever a stream is created, a timestamp is recorded for future reference.

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.

Whenever there is a change in the status of a stream, a timestamp is recorded for future reference.

 Request Example 
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X POST https://api-live.qencode.com/v1/live-streams/$STREAM_ID/stop

{
  "stream": {
    "id": "12345fcd-7aea-492c-b9eb-b4b0cde0dc7e",
    "server_urls": {
      "rtmp": "rtmp://rtmp-live.qencode.com/qlive"
    },
    "status": {
      "timestamp": "2021-08-28 17:59:34",
      "name": "stopping"
    },
    "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"
    }
  }
}

Updating a live stream

PUT

/v1/live-streams/<stream_id>

Updates a live stream.

You can pass stream params as attributes of JSON object in request data. All params are optional, at least one should be specified.

Updated live stream object.

Input Objects Structure

URL of an endpoint on your server to handle task callbacks.

See Receiving Callbacks.

The output format for the stream. Defaults to hls.

In order to start recording your stream, you must set enabled parameter to 1. Defaults to 0.

Enabling or disabling DVR during streaming is supported.

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

Your access key for S3 bucket, or username for FTP server

Your secret key for S3 bucket, or password for FTP server

Specify 'public-read' value in order to make output video publicly accessible.

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

Specifies a list of referer domains allowed for stream playback. Can be used to limit playback for a certain domain or list of domains. Wildcards in domain names are supported.

Please note, this is not a strong secure solution to control stream access since http referer value can be easily changed.

Specify an empty array to reset the setting. Dynamic changing of allowed referer domains during streaming is not supported and will take an effect during next stream launch.

Output Objects Structure

The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

Every live stream will stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

You can specify callback URL (also known as webhook) to receive updates upon each stream status change. See Updating a live stream for more details on how to set up a callback URL for a stream.

The desired format for stream playback. LL-HLS, CMAF and DASH coming soon!

Can be specified as integer or float value of frames per second. Specify 0 to preserve input frame rate. Current maximum supported frame rate is 30.

In order to start recording your stream, you must set enabled parameter to 1. Defaults to 0.

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

This is a unique identifier that works in together with your Secret Access Key to authenticate API requests for S3 storage.

It consists of 20 alphanumeric characters.

This is the private key that is used to sign API requests for S3 storage.

It consists of 40 characters including letters, numbers, and special characters.

Specify 'public-read' value in order to make output video publicly accessible.

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.

Stream key is used to identify the stream when pushing from a 3rd party client software like OBS.

An array of playback IDs for the stream. Each playback ID has the following attributes:

A unique identifier for the playback of the output. Can be used to automatically build playback_url for different output formats.

The date and time when the playback ID was created.

Depending on the output format you choose, the playback URL is used in conjuction with your player to play your video to your viewers.

Contains the domain name of live stream origin. Is only available for streams in Waiting, Launching, Live or Idle states.

Contains the live stream origin URL. Is only available for streams in Waiting, Launching, Live or Idle states.

Live stream name can be passed as an optional parameter when a stream is created.

Whenever a stream is created, a timestamp is recorded for future reference.

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.

Whenever there is a change in the status of a stream, a timestamp is recorded for future reference.

 Request Example 
curl -X PUT 'https://api-live.qencode.com/v1/live-streams/$STREAM_ID' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN' \ 
--data-raw '{"name": "test-stream-update1", "input_format": "webrtc", "output_format": "cmaf", 
"dvr": {
  "enabled": 1,
  "destination": {
    "url": "s3://us-west.s3.qencode.com/bucketname/path/to/dvr_output",
    "key": "ABCDE12345",
    "secret": "ABCDEFGH12345678",
    "permissions": "public-read"
  }
}}'

{
  "stream": {
    "id": "73bfd689-777b-48fb-97f5-ded39b8b0d50",
    "name": "test-stream-update1",
    "quality": "LIVE SD",
    "status": {
      "timestamp": "2021-12-01 17:24:04",
      "name": "stopped"
    },
    "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-10-17 08:09:00",
    "server_urls": {
      "rtmp": "rtmp://rtmp-live.qencode.com/qlive"
    },
    "params": {
      "input_format": "webrtc",
      "output_format": "cmaf",
      "framerate": "30",
      "mode": "auto",
      "callback_url": null,
      "dvr": {
        "enabled": 1,
        "destination": {
          "url": "s3://us-west.s3.qencode.com/bucketname/path/to/dvr_output",
          "key": "ABCDE12345",
          "secret": "ABCDEFGH12345678",
          "permissions": "public-read"
        }
      }
    }
  }
}

Deleting a live stream

DELETE

/v1/live-streams/<stream_id>

Deletes a live stream.

Live stream must be stopped before deleting.

Stream status will be 'deleted' for a successful operation.

Date and time the stream status changed to 'deleted'.

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X DELETE https://api-live.qencode.com/v1/live-streams/$STREAM_ID

{
  "status": {
    "timestamp": "2021-08-28 17:59:34",
    "name": "deleted"
  }
}

Adding a playback ID to a live stream

POST

/v1/live-streams/<stream_id>/playback-ids

Adds a playback ID to a stream

You should pass playback policy as an attribute of JSON object in request data.

You can add multiple playback IDs to a same stream if necessary.

Updated live stream object.

Input Objects Structure

Playback policy should be either 'public' or 'authenticated'.

Public playback IDs does not require any authentication.

Playback IDs with authenticated policy require a JWT token provided in 'auth' param in playback URL query string.

Output Objects Structure

The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

Every live stream will stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

You can specify callback URL (also known as webhook) to receive updates upon each stream status change. See Updating a live stream for more details on how to set up a callback URL for a stream.

The desired format for stream playback. LL-HLS, CMAF and DASH coming soon!

Can be specified as integer or float value of frames per second. Specify 0 to preserve input frame rate. Current maximum supported frame rate is 30.

In order to start recording your stream, you must set enabled parameter to 1. Defaults to 0.

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

This is a unique identifier that works in together with your Secret Access Key to authenticate API requests for S3 storage.

It consists of 20 alphanumeric characters.

This is the private key that is used to sign API requests for S3 storage.

It consists of 40 characters including letters, numbers, and special characters.

Specify 'public-read' value in order to make output video publicly accessible.

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.

Stream key is used to identify the stream when pushing from a 3rd party client software like OBS.

An array of playback IDs for the stream. Each playback ID has the following attributes:

A unique identifier for the playback of the output. Can be used to automatically build playback_url for different output formats.

The date and time when the playback ID was created.

Depending on the output format you choose, the playback URL is used in conjuction with your player to play your video to your viewers.

Contains the domain name of live stream origin. Is only available for streams in Waiting, Launching, Live or Idle states.

Contains the live stream origin URL. Is only available for streams in Waiting, Launching, Live or Idle states.

Live stream name can be passed as an optional parameter when a stream is created.

Whenever a stream is created, a timestamp is recorded for future reference.

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.

Whenever there is a change in the status of a stream, a timestamp is recorded for future reference.

curl -X POST 'https://api-live.qencode.com/v1/live-streams/$STREAM_ID/playback-ids' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN' \ 
--data-raw '{
 "url": "rtmp://a.rtmp.youtube.com/live2",
 "stream_key": "1234-5678-abcd-efgh-3cm6"
}'

{
  "stream": {
      "status": {
          "timestamp": "2023-06-02 13:19:40",
          "name": "created"
      },
      "name": "Stream_N3B47YML",
      "stream_key": "a49c85c5-513a-4cea-8c66-f98e2019aab0",
      "created_at": "2023-06-02 13:19:40",
      "server_urls": {
          "rtmps": "rtmps://rtmp-live.qencode.com/qlive",
          "rtmp": "rtmp://rtmp-live.qencode.com/qlive"
      },
      "params": {
          "input_format": "rtmp",
          "output_format": "hls",
          "framerate": 0,
          "mode": "auto",
          "callback_url": null,
          "dvr": {
              "max_file_duration": 14400,
              "destination": null,
              "enabled": false,
              "stream_source": "auto",
              "format": "mp4"
          }
      },
      "playback_ids": [
          {
              "policy": "public",
              "created": "2023-06-02 13:19:40",
              "id": "Av22X1p8h5",
              "playback_url": "https://play-Av22X1p8h5.qencode.com/qhls/qlive/playlist.m3u8"
          },
          {
              "policy": "authenticated",
              "id": "5yxn1iz6vj4g",
              "playback_url": "https://play-5yxn1iz6vj4g.qencode.com/qhls/qlive/playlist.m3u8",
              "created": "2023-06-02 16:15:54"
          }
      ],
      "id": "92727a3d-5b14-491d-9479-a9269d8e76e1"
  }
}

Removing a playback ID from a live stream

DELETE

/v1/live-streams/<stream_id>/playback-ids/<playback_id>

Removes a playback ID from stream.

Updated live stream object.

Output Objects Structure

The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

Every live stream will stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

You can specify callback URL (also known as webhook) to receive updates upon each stream status change. See Updating a live stream for more details on how to set up a callback URL for a stream.

The desired format for stream playback. LL-HLS, CMAF and DASH coming soon!

Can be specified as integer or float value of frames per second. Specify 0 to preserve input frame rate. Current maximum supported frame rate is 30.

In order to start recording your stream, you must set enabled parameter to 1. Defaults to 0.

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

This is a unique identifier that works in together with your Secret Access Key to authenticate API requests for S3 storage.

It consists of 20 alphanumeric characters.

This is the private key that is used to sign API requests for S3 storage.

It consists of 40 characters including letters, numbers, and special characters.

Specify 'public-read' value in order to make output video publicly accessible.

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.

Stream key is used to identify the stream when pushing from a 3rd party client software like OBS.

An array of playback IDs for the stream. Each playback ID has the following attributes:

A unique identifier for the playback of the output. Can be used to automatically build playback_url for different output formats.

The date and time when the playback ID was created.

Depending on the output format you choose, the playback URL is used in conjuction with your player to play your video to your viewers.

Contains the domain name of live stream origin. Is only available for streams in Waiting, Launching, Live or Idle states.

Contains the live stream origin URL. Is only available for streams in Waiting, Launching, Live or Idle states.

Live stream name can be passed as an optional parameter when a stream is created.

Whenever a stream is created, a timestamp is recorded for future reference.

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.

Whenever there is a change in the status of a stream, a timestamp is recorded for future reference.

curl -X DELETE 'https://api-live.qencode.com/v1/live-streams/$STREAM_ID/playback-ids/$PLAYBACK_ID' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN'

{
  "stream": {
      "status": {
          "timestamp": "2023-06-02 13:19:40",
          "name": "created"
      },
      "name": "Stream_N3B47YML",
      "stream_key": "a49c85c5-513a-4cea-8c66-f98e2019aab0",
      "created_at": "2023-06-02 13:19:40",
      "server_urls": {
          "rtmps": "rtmps://rtmp-live.qencode.com/qlive",
          "rtmp": "rtmp://rtmp-live.qencode.com/qlive"
      },
      "params": {
          "input_format": "rtmp",
          "output_format": "hls",
          "framerate": 0,
          "mode": "auto",
          "callback_url": null,
          "dvr": {
              "max_file_duration": 14400,
              "destination": null,
              "enabled": false,
              "stream_source": "auto",
              "format": "mp4"
          }
      },
      "playback_ids": [
          {
              "policy": "public",
              "created": "2023-06-02 13:19:40",
              "id": "Av22X1p8h5",
              "playback_url": "https://play-Av22X1p8h5.qencode.com/qhls/qlive/playlist.m3u8"
          }
      ],
      "id": "92727a3d-5b14-491d-9479-a9269d8e76e1"
  }
}

Adding a simulcast target for a live stream

POST

/v1/live-streams/<stream_id>/simulcast-targets

Adds a simulcast target for a stream

You should pass target params as attributes of JSON object in request data.

Updated live stream object.

Input Objects Structure

The re-streaming service RTMP ingest URL.

Stream key used to authenticate against the simulcast target.

Output Objects Structure

The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

Every live stream will stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

You can specify callback URL (also known as webhook) to receive updates upon each stream status change. See Updating a live stream for more details on how to set up a callback URL for a stream.

The desired format for stream playback. LL-HLS, CMAF and DASH coming soon!

Can be specified as integer or float value of frames per second. Specify 0 to preserve input frame rate. Current maximum supported frame rate is 30.

In order to start recording your stream, you must set enabled parameter to 1. Defaults to 0.

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

This is a unique identifier that works in together with your Secret Access Key to authenticate API requests for S3 storage.

It consists of 20 alphanumeric characters.

This is the private key that is used to sign API requests for S3 storage.

It consists of 40 characters including letters, numbers, and special characters.

Specify 'public-read' value in order to make output video publicly accessible.

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.

Stream key is used to identify the stream when pushing from a 3rd party client software like OBS.

An array of playback IDs for the stream. Each playback ID has the following attributes:

A unique identifier for the playback of the output. Can be used to automatically build playback_url for different output formats.

The date and time when the playback ID was created.

Depending on the output format you choose, the playback URL is used in conjuction with your player to play your video to your viewers.

Contains the domain name of live stream origin. Is only available for streams in Waiting, Launching, Live or Idle states.

Contains the live stream origin URL. Is only available for streams in Waiting, Launching, Live or Idle states.

Live stream name can be passed as an optional parameter when a stream is created.

Whenever a stream is created, a timestamp is recorded for future reference.

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.

Whenever there is a change in the status of a stream, a timestamp is recorded for future reference.

curl -X POST 'https://api-live.qencode.com/v1/live-streams/$STREAM_ID/simulcast-targets' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN' \ 
--data-raw '{
 "url": "rtmp://a.rtmp.youtube.com/live2",
 "stream_key": "1234-5678-abcd-efgh-3cm6"
}'

{
  "stream": {
    "id": "73bfd689-777b-48fb-97f5-ded39b8b0d50",
    "name": "test-stream-update1",
    "quality": "LIVE SD",
    "status": {
      "timestamp": "2021-12-01 17:24:04",
      "name": "stopped"
    },
    "server_urls": {
      "rtmp": "rtmp://rtmp-live.qencode.com/qlive"
    },
    "params": {
      "input_format": "webrtc",
      "output_format": "cmaf",
      "framerate": "30",
      "mode": "auto",
      "callback_url": null,
      "dvr": {
        "destination": null,
        "enabled": 0
      }
    },
    "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-10-17 08:09:00",
    "simulcast_targets": [
      {
        "url": "rtmp://a.rtmp.youtube.com/live2",
        "id": "12348fd3-0fc2-4982-8910-d1b06bb917c9",
        "stream_key": "1234-5678-abcd-efgh-3cm6"
      }
    ]
  }
}

Removing a simulcast target from a live stream

DELETE

/v1/live-streams/<stream_id>/simulcast-targets/<target_id>

Removes a simulcast target from stream by its ID.

Updated live stream object.

Output Objects Structure

The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

Every live stream will stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.

You can specify callback URL (also known as webhook) to receive updates upon each stream status change. See Updating a live stream for more details on how to set up a callback URL for a stream.

The desired format for stream playback. LL-HLS, CMAF and DASH coming soon!

Can be specified as integer or float value of frames per second. Specify 0 to preserve input frame rate. Current maximum supported frame rate is 30.

In order to start recording your stream, you must set enabled parameter to 1. Defaults to 0.

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

This is a unique identifier that works in together with your Secret Access Key to authenticate API requests for S3 storage.

It consists of 20 alphanumeric characters.

This is the private key that is used to sign API requests for S3 storage.

It consists of 40 characters including letters, numbers, and special characters.

Specify 'public-read' value in order to make output video publicly accessible.

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.

Stream key is used to identify the stream when pushing from a 3rd party client software like OBS.

An array of playback IDs for the stream. Each playback ID has the following attributes:

A unique identifier for the playback of the output. Can be used to automatically build playback_url for different output formats.

The date and time when the playback ID was created.

Depending on the output format you choose, the playback URL is used in conjuction with your player to play your video to your viewers.

Contains the domain name of live stream origin. Is only available for streams in Waiting, Launching, Live or Idle states.

Contains the live stream origin URL. Is only available for streams in Waiting, Launching, Live or Idle states.

Live stream name can be passed as an optional parameter when a stream is created.

Whenever a stream is created, a timestamp is recorded for future reference.

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.

Whenever there is a change in the status of a stream, a timestamp is recorded for future reference.

curl -X DELETE 'https://api-live.qencode.com/v1/live-streams/$STREAM_ID/simulcast-targets/$TARGET_ID' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN'

{
  "stream": {
    "id": "73bfd689-777b-48fb-97f5-ded39b8b0d50",
    "name": "test-stream-update1",
    "quality": "LIVE SD",
    "status": {
      "timestamp": "2021-12-01 17:24:04",
      "name": "stopped"
    },
    "server_urls": {
      "rtmp": "rtmp://rtmp-live.qencode.com/qlive"
    },
    "params": {
      "input_format": "webrtc",
      "output_format": "cmaf",
      "framerate": "30",
      "mode": "auto",
      "callback_url": null,
      "dvr": {
        "destination": null,
        "enabled": 0
      }
    },
    "playback_ids": [
      {
        "policy": "public",
        "created": "2021-08-28 17:59:33",
        "id": "Av22X1p8h5",
        "playback_url": "https://play-Av22X1p8h5.qencode.com/qhls/qlive/playlist.m3u8"
      }
    ],
    "stream_key": "1234e5b1-dfd7-4daa-8121-bc5c68bbeb37",
    "created_at": "2021-10-17 08:09:00",
    "simulcast_targets": []
  }
}

Input Stream Health

GET

/v1/live-streams/<stream_id>/health

Returns ingest health metrics for a live stream over a specified time range.

Metrics array.

Input Objects Structure

The beginning of the period to query, UTC datetime string, e.g. 2026-02-05 16:00:00. Defaults to 1 hour before the current time.

The end of the period to query, as a UTC datetime string, e.g. 2026-02-05 17:00:00. Defaults to the current time.

When specified, the response returns aggregated data instead of raw samples. Each aggregated sample covers the specified time interval and includes average, minimum, and maximum values for bitrate and framerate metrics, along with total dropped frames per interval. Accepted values: 'auto', '1m', '5m', '1h', '1d', '1w', '1M', 'none'.

When not specified, the endpoint returns raw samples ordered by timestamp descending.

Limits the number of records in the response. Defaults to 1000.

When set to 'true', the endpoint returns all available samples for the stream regardless of time range, ignoring time_from and time_to parameters. By default, the endpoint scopes results to the current or last session. Use this parameter when you need to retrieve the complete history of metrics for a stream.

Defaults to 'false'.

Output Objects Structure

Each object represents a single telemetry sample collected at a specific point in time.

Matches the stream_id used in the request. Constant across all samples in the response.

Returned as a UTC string in YYYY-MM-DD HH:MM:SS format.

Reflects real-time encoder output. The first sample in a session may return 0 before the encoder stabilizes.

When a target bitrate is configured for the stream, this field reflects that value. Otherwise it shows the same value as video_bitrate.

When a target bitrate is configured for the stream, this field reflects that value. Otherwise it shows the same value as audio_bitrate.

Serialized as a string. Reflects measured output from the encoder.

When a target frame rate is configured for the stream, this field reflects that value. Otherwise it shows the same value as framerate

Increases with each sample. Resets when the stream reconnects or restarts. The first sample may show a value close to 1.

May vary during the session for WebRTC streams. A value of 0x0 means no video data is available yet.

Identifies the ingest source, such as WebRTC Client or RTMP Client. Remains consistent within a session.

Remains consistent within a session under normal conditions.

Typically stabilizes after the initial connection phase.

May return 0 briefly at the start of a session before the audio is fully negotiated.

Each object represents a summary of telemetry data collected within a specific time interval.

Available when time_bucket is specified.

The beginning of the time interval this aggregated sample covers, in UTC YYYY-MM-DD HH:MM:SS format.

Shows how many individual telemetry samples were collected within this time interval.

The mean video bitrate calculated across all raw samples in the interval.

The lowest video bitrate value recorded across all raw samples in the interval.

The highest video bitrate value recorded across all raw samples in the interval.

The mean audio bitrate calculated across all raw samples in the interval.

The lowest audio bitrate value recorded across all raw samples in the interval.

The highest audio bitrate value recorded across all raw samples in the interval.

The mean frame rate calculated across all raw samples in the interval.

The lowest frame rate value recorded across all raw samples in the interval.

The highest frame rate value recorded across all raw samples in the interval.

The mean input frame rate calculated across all raw samples in the interval.

The mean video data rate calculated across all raw samples in the interval.

The mean audio data rate calculated across all raw samples in the interval.

The highest time_connected value recorded across all raw samples in the interval.

The resolution value in 'WxH' format, e.g. '1920x1080', recorded within this time interval.

The video codec in use during this time interval.

The audio codec in use during this time interval.

Identifies the type of client used to ingest the stream during this interval.

Shows how many metric samples are included in the current response. Useful for quickly checking how much data was returned without iterating through the metrics array.

When false, each sample represents a single raw measurement. When true, samples have been combined over a time interval.

Returns the resolved bucket size when time_bucket=auto, or null in raw mode.

Returns the number of seconds per bucket when time_bucket=auto. Returns null in raw mode.

Always present in the response. Returns null when no data is available.

The overall count of raw telemetry samples included in the current response, across the entire queried time range.

Contains the following fields calculated across all samples in the response: avg, median, min, max, p10, p90.

Returns the resolution in 'WxH' format, e.g. 1920x1080, taken from the latest sample in the queried time range.

The beginning of the period to query, UTC datetime string, e.g. 2026-02-05 16:00:00. Defaults to 1 hour before the current time.

The end of the period to query, as a UTC datetime string, e.g. 2026-02-05 17:00:00. Defaults to the current time.

curl -X GET 'https://api-live.qencode.com/v1/live-streams/$STREAM_ID/health' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN'

{
  "metrics": [
    "stream_id": "73bfd689-777b-48fb-97f5-ded39b8b0d50",
    "timestamp": "2026-02-05 16:34:25",
    "video_bitrate": 2500000,
    "audio_bitrate": 128000,
    "video_data_rate": 2500000,
    "audio_data_rate": 128000,
    "framerate": 30,
    "input_frame_rate": 30,
    "time_connected": 120,
    "resolution": "1920x1080",
    "encoder": 1,
    "video_codec": "mp4",
    "audio_codec": "mp3",
    "audio_channels": 2,
    "audio_sample_rate": 44100,
    "audio_sample_size": 20, 
    ]
  "count": 1,
  "aggregated": false,
  "time_bucket": null,
  "interval": null,
  "summary": null,
  "time_from": "2021-08-28 17:59:33",
  "time_to": "2021-08-28 17:59:33",
  "limit": 10,
    
}