Theta Video API: Livestream
The flow of setting up a livestream on Theta Video API is as follows:
- Create a Livestream. The created livestream will be at "off" status, and stream server and stream key will be null at this moment. Once a stream is created, it can be re-used for future streaming sessions, i.e. only step 2 & 3 are required.
- List available Edge Ingestors, and then pick an Edge Ingestor's id for step 3.
- Select an Edge Ingestor. When an Edge Ingestor is selected, the stream server and stream key will be available. Streamers can use them to set up OBS. Upon starting the stream source from, say, OBS, the TVA stream's status will automatically turn ON; Upon stopping the stream from OBS, the TVA stream's status will automatically turn OFF.
Create a Livestream
Request:
curl -X POST 'https://api.thetavideoapi.com/stream' \
-H 'x-tva-sa-id: srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'x-tva-sa-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{ "name": "demo" }'
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://api.thetavideoapi.com/stream',
'headers': {
'x-tva-sa-id': 'srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx',
'x-tva-sa-secret': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({"name":"demo"})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Response:
{
"status":"success",
"body":{
"id": "stream_xxxxxxxxxxxxxxxxxxxxxxxxx",
"name": "demo",
"status": "off",
"update_time": "2023-11-08T00:57:02.462Z",
"playback_uri": null,
"player_uri": null
}
}
Each Service Account can create max 3 livestreams. It'll return a 400 error with message "Live stream limit reached - you already have 3/3 streams" when already maxed out.
Retrieve a Livestream
Request:
curl -X GET 'https://api.thetavideoapi.com/stream/stream_xxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'x-tva-sa-id: srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'x-tva-sa-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
var request = require('request');
var options = {
'method': 'GET',
'url': 'https://api.thetavideoapi.com/stream/stream_xxxxxxxxxxxxxxxxxxxxxxxxx',
'headers': {
'x-tva-sa-id': 'srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx',
'x-tva-sa-secret': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Response:
{
"status":"success",
"body":{
"id": "stream_xxxxxxxxxxxxxxxxxxxxxxxxx",
"name": "demo",
"status": "off",
"update_time": "2023-11-08T00:57:02.462Z",
"playback_uri": null,
"player_uri": null,
"stream_server": "rtmp://xxx.xxx.xxx.xxx:1935/live",
"stream_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
- x-tva-sa-id and x-tva-sa-secret are optional in request header.
- stream_server and stream_key are only present in response when an Edge Ingestor is selected using this stream, and when x-tva-sa-id and x-tva-sa-secret are provided.
List Livestreams of a Service Account
Request:
curl -X GET 'https://api.thetavideoapi.com/service_account/srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx/streams' \
-H 'x-tva-sa-id: srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'x-tva-sa-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
var request = require('request');
var options = {
'method': 'GET',
'url': 'https://api.thetavideoapi.com/service_account/srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx/streams',
'headers': {
'x-tva-sa-id': 'srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx',
'x-tva-sa-secret': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Response:
{
"status":"success",
"body":{
"total_count":2,
"streams":[
{
"id": "stream_xxxxxxxxxxxxxxxxxxxxxxxxx",
"service_account_id": "srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx",
"name": "demo",
"status": "off",
"update_time": "2023-11-08T00:57:02.462Z",
"playback_uri": null,
"player_uri": null
},
{
"id": "stream_xxxxxxxxxxxxxxxxxxxxxxxxx",
"service_account_id": "srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx",
"name": "demo1",
"status": "off",
"update_time": "2023-11-22T05:09:58.377Z",
"playback_uri": null,
"player_uri": null
}
]
}
}
Query parameter:
- status: on or off. If not specified, it lists streams of both statuses of the service account.
List Available Edge Ingestors
Request:
curl -X GET 'https://api.thetavideoapi.com/ingestor/filter' \
-H 'x-tva-sa-id: srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'x-tva-sa-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
var request = require('request');
var options = {
'method': 'GET',
'url': 'https://api.thetavideoapi.com/ingestor/filter',
'headers': {
'x-tva-sa-id': 'srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx',
'x-tva-sa-secret': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Response:
{
"status":"success",
"body":{
"total_count":2,
"ingestors":[
{
"id": "0x093D7e6936fbd2e86f72DB6A5060CbC1535A232A",
"ip": "35.226.139.216",
"stream_key": null,
"state": "available",
"stakes": 3000000,
"geo": [ -77.2481, 38.6583 ]
},
{
"id": "0xaCe1F1d6E6284eF39ff55Ed7b5765b659b70Ca9f",
"ip": "35.222.95.104",
"stream_key": null,
"state": "available",
"stakes": 2000000,
"geo": [ -77.4298, 38.7739 ]
}
]
}
In response, Edge Ingestors are sorted by distance from the streamer (API requestor) based on streamer's IP address, nearest first.
Select an Edge Ingestor
Request:
curl -X PUT 'https://api.thetavideoapi.com/ingestor/ingestor_xxxxxxxxxxxxxxxxxxxxxxx/select' \
-H 'x-tva-sa-id: srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'x-tva-sa-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{ "tva_stream": "stream_xxxxxxxxxxxxxxxxxxxxxxxxx" }'
var request = require('request');
var options = {
'method': 'PUT',
'url': 'https://api.thetavideoapi.com/ingestor/ingestor_xxxxxxxxxxxxxxxxxxxxxxx/select',
'headers': {
'x-tva-sa-id': 'srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx',
'x-tva-sa-secret': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({"tva_stream": "stream_xxxxxxxxxxxxxxxxxxxxxxxxx"})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Response:
{
"status":"success",
"body":{
"stream_server": "rtmp://xxx.xxx.xxx.xxx:1935/live",
"stream_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
- Ingestor selection will expire if not used in 5 minutes, i.e. if there's no stream (e.g. from OBS) in 5 minutes after the ingestor is selected, the ingestor will be automatically unselected and become available for selection again.
- The tva_stream value must be a stream id that belongs to the x-tva-sa-id service account, or else it will return a 403 error with message "You are not authorized to select this ingestor"
Unselect Edge Ingestor
Request:
curl -X PUT 'https://api.thetavideoapi.com/ingestor/ingestor_xxxxxxxxxxxxxxxxxxxxxxx/unselect' \
-H 'x-tva-sa-id: srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'x-tva-sa-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{}'
var request = require('request');
var options = {
'method': 'PUT',
'url': 'https://api.thetavideoapi.com/ingestor/ingestor_xxxxxxxxxxxxxxxxxxxxxxx/unselect',
'headers': {
'x-tva-sa-id': 'srvacc_xxxxxxxxxxxxxxxxxxxxxxxxx',
'x-tva-sa-secret': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Response:
{
"status":"success",
"body":{}
}
- The TVA stream used to select the ingestor earlier (and now to be unselected) must belong to the x-tva-sa-id service account, or else it will return a 403 error with message "You are not authorized to unselect this ingestor"
Updated 5 months ago