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.

warning
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.
Arguments

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.

Returns

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.

Request Example

Replace the 'your_api_key' value below with your API key. You can find you API key in your <a href="https://portal.qencode.com/project/live_projects">Live Streaming Project within your account.</a>

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

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

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.

Returns

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
Attributes
Live stream name can be passed as an optional parameter when a stream is created.
Output Objects Structure
Attributes
The stream object contains all the attributes of your live stream, including like id, stream_key, playback_id, status, origin and more.
Attributes
Live stream name can be passed as an optional parameter when a stream is created.
Attributes
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. WebRTC and SRT coming soon!
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.
Attributes

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.
Whenever a stream is created, a timestamp is recorded for future reference.
Stream key is used to identify the stream when pushing from a 3rd party client software like OBS.
Defines the URL for stream playback.
Contains the URL for stream playback.
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.
Request Example
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"}'
Response Example
{
  "stream": {
    "status": {
      "timestamp": "2021-08-28 17:59:33",
      "name": "created"
    },
    "name": "test-stream-name",
    "playback_id": "12345074-42f2-4291-be78-b2b0bdd7a73b",
    "playback_url": "https://play-12345074-42f2-4291-be78-b2b0bdd7a73b.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"
    },
    "id": "12345fcd-7aea-492c-b9eb-b4b0cde0dc7e"
  }
}

Getting a Live Stream Data

GET
/v1/live-streams/<stream_id>

Gets a live stream information.

Returns
Contains live stream data. section of Create stream method description for the details of stream object internal structure.
Request Example
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-live.qencode.com/v1/live-streams/12345fcd-7aea-492c-b9eb-b4b0cde0dc7e
Response Example
{
  "stream": {
    "status": {
      "timestamp": "2021-08-28 17:59:33",
      "name": "created"
    },
    "name": "test-stream-name",
    "playback_id": "12345074-42f2-4291-be78-b2b0bdd7a73b",
    "playback_url": "https://play-12345074-42f2-4291-be78-b2b0bdd7a73b.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"
    },
    "id": "12345fcd-7aea-492c-b9eb-b4b0cde0dc7e"
  }
}

Listing Live Streams

GET
/v1/live-streams

Gets a list of user live streams.

Returns
In case no filter specified, contains list of all user live streams.
Input Objects Structure
Attributes
Optional set of params to filter live streams list response.
Request Example
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-live.qencode.com/v1/live-streams
Response Example
{
  "streams": [
    {
      "id": "7297653f-5a79-4c58-9dbd-972141822b59",
      ...

    },
    {
      "id": "e09066ca-b200-4b67-bf37-122137f31f8a",
      ...
    }
    ...
  ]
}

Starting a live stream

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

Starts a live stream.

Sends a message to the system so it can allocate a transcoder for the stream. Calling this method is optional, but helps to minimize the time for stream to get live.

Returns

Updated live stream object.

Request Example
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X POST https://api-live.qencode.com/v1/live-streams/$STREAM_ID/start
Response Example
{
  "status": "starting",
  "timestamp": "2021-08-05 14:17:17"
}

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 300 seconds is reached when waiting for the input stream.

Returns

Updated live stream object.

Request Example
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X POST https://api-live.qencode.com/v1/live-streams/$STREAM_ID/stop
Response Example
{
  "status": "stopping",
  "timestamp": "2021-08-05 14:17:17"
}

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.

Returns

Updated live stream object.

Input Objects Structure
Attributes

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

See Receiving Callbacks.

Request Example
curl -H "Authorization: Bearer $ACCESS_TOKEN" \ 
 -X PUT https://api-live.qencode.com/v1/live-streams/$STREAM_ID
Response Example
{
  "status": "stopping",
  "timestamp": "2021-08-05 14:17:17"
}