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 uses API keys and tokens to authenticate requests and manage live streams. You can view and manage the API keys associated with your projects inside of your Qencode Account.

To get started, you first need to acquire an access token in order to authenticate and access the Qencode live streaming API. You will pass this token in Authorization header to all other live streaming API methods described below.

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 will be used to call all other live streaming API methods.

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

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

Creating a Live Stream

POST

/v1/live-streams

Creates a live stream and returns its data.

You can pass optional JSON data containing stream params.

Input Objects Structure

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

Output Objects Structure

Contains all information about the live stream.

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

See possible status values description below.

created	New stream.
starting	System is allocating resources to process live stream.
waiting	Transcoder is ready and waiting for input stream.
live	Stream is live.
idle	Input stream was stopped or interrupted. Transcoder is still ready and waiting for input stream.
stopping	Stream is stopping.
stopped	Stream is stopped.

Timestamp of most recent live stream status change.

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.

Currently only RTMP inputs are supported. WebRTC coming soon!

Currently only HLS outputs are supported. LL-HLS 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.

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.

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

{
  "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.

Contains live stream data. See Output objects structure section of Create stream method description for the details of stream object internal structure.

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-live.qencode.com/v1/live-streams/12345fcd-7aea-492c-b9eb-b4b0cde0dc7e

{
  "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.

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

Input Objects Structure

Optional set of params to filter live streams list response.

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

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.

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

{
  "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.

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

{
  "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.

Updated live stream object.

Input Objects Structure

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

See Receiving Callbacks.

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

{
  "status": "stopping",
  "timestamp": "2021-08-05 14:17:17"
}