Our service Api allows you programmatically create, update and manage captions and transcript data in our system.
In order to authenticate requests, please add ApiKey and ApiSecret parameters to every HTTP request you make (see HTTP header shown below).
// find your api key and secret in your account settings
Request.Headers.Add("ApiKey", "my key");
Request.Headers.Add("ApiSecret", "my secret");
Our Api endpoint base URL is https://live-captions.com/api/lc/
You can find code samples on the bottom of this page or at Github
dotnet add package Live-Captions.Com.Api --version 1.1.0
[HttpPost]
SaveEvent(EventDto eventRequest)
EventRequest object to be posted to this method (at https://live-captions.com/api/lc/SaveEvent) is presented below.
{
EventId: "", //empty for new object creation
EventName : "Test Event 1",
StartDate : "2023-01-01 08:11", //event start date
PublishingPointUrl : "rtmp://mysStreamingServer.com:1935/MyApp/MyStreamKey", //RTMP or HLS
TargetDelay : 15000, //delay between stream and captions in milliseconds
EventTimeZone : "GMT Standard Time", //The time zone identifier, from System.TimeZoneInfo.Id property.
EventWaitTime : 15, //max inactivity in minutes
EventMaxTime : 480, //max duration in minutes
EventLanguage : "en-GB", //in BCP-47 format
UserPhrases : "phrase1;phrase2", //list of user phrases to improve recognition accuracy (separated by ;)
SilenceTimeoutMs: 500, //adjusts how much non-speech audio is allowed within a phrase that's currently being spoken before that phrase is considered done.
}
In either case, success or failure, the response message is returned in the format shown below. If new object is created, the "EntityId" variable will hold new object id, so you can store it in your system. In case of error, the "IsSuccess" variable will have false value and "Message" property will include the error details.
{
isSuccess: true,
entityId: "", //will include event id if new event is created
message: "Event has been successfully saved!"
}
[HttpPost]
SaveRecordedEvent(RecordedEventDto eventRequest)
EventRequest object to be posted to this method (at https://live-captions.com/api/lc/SaveRecordedEvent) is presented below.
{
EventId: "", //empty for new object creation
EventName : "Captions for my yesterday meeting..", //event/media name
StartDate : "2023-01-01 08:11", //optional event/media date
MediaUrl : "https://myserver/myMediaFile.mp4", //video or audio file in common extensions
EventTimeZone : "GMT Standard Time", //optional time zone identifier, from System.TimeZoneInfo.Id property.
EventLanguage : "en-GB", //in BCP-47 format
UserPhrases : "phrase1;phrase2", //optional list of user phrases to improve recognition accuracy (separated by ;)
SilenceTimeoutMs: 500, //adjusts how much non-speech audio is allowed within a phrase that's currently being spoken before that phrase is considered done.
}
In either case, success or failure, the response message is returned in the format shown below. If new object is created, the "EntityId" variable will hold new object id, so you can store it in your system. In case of error, the "IsSuccess" variable will have false value and "Message" property will include the error details.
{
isSuccess: true,
entityId: "", //will include event id if new event is created
message: "Event has been successfully saved!"
}
[HttpPost]
DeleteEvent(string eventId)
In either case, success or failure, the response message is returned in the format shown below.
{
isSuccess: true,
entityId: "",
message: "Event has been successfully deleted!"
}
[HttpPost]
GetLiveCaptions(string eventId, DateTime timestamp, int spanInMilliseconds = 3000)
The result will contain array of objects with text date and duration (in milliseconds). The "timespan" property defines the caption start date to be retrieved from, the "spanInMilliseconds" parameter specifies the number of milliseconds back to be retrieved which might affect number of captions to be displayed in one request.
{
Text: "Caption text1,
TimeStamp: "2023-01-01 08:00.01",
Duration: 1234, //in milliseconds
},
{
Text: "Caption text2,
TimeStamp: "2023-01-01 08:00.02",
Duration: 1234, //in milliseconds
}
[HttpPost]
GetTranscript(string eventId)
The result will contain event's basic data and array of transcript items generated. The "sessionId" parameter might be different if event session has been interrupted and started again.
{
eventId: "event id",
eventName: "Event test 1",
eventTimeZone: "GMT Standard Time",
eventMediaUrl: "https://server/file.mp4"
transcriptItems: [
{
"timeStamp": "2023-03-21T10:12:11.028",
"text": "Caption text 1",
"duration": 1234, //in milliseconds
"sessionId": "3320fafa-1b6f-4b93-93a9-cdc22f14a425"
},
{
"timeStamp": "2023-03-21T10:12:19.095",
"text": "Caption text 2",
"duration": 1234, //in milliseconds
"sessionId": "3320fafa-1b6f-4b93-93a9-cdc22f14a425"
}]
}
[HttpPost]
GetUserAccountInfo()
The result will contain information as presented below.
{
"planType": "BASIC",
"accountCredits": 74,
"lastTopUpDate": "2023-03-21T10:26:58.782Z"
}
[HttpPost]
GetEventStatus(string eventId)
The result will return status codes.
{
UNKNOWN = 0,
IN_PROGRESS = 1,
COMPLETED = 2,
COMPLETED_WITH_ERRORS = 3,
COMPLETED_WITH_WARNINGS = 4
}
[HttpGet]
DownloadTranscript(string eventId, int format = 1)
Format "1" - the result will contain transcript in SRT format.
Format "2" - the result will contain transcript in CSV format.
Format "3" - the result will contain transcript in WebVTT format.
public void CreateLiveEvent()
{
//import Newtonsoft.Json
//set api key and secret
var apiKey = "-----";
var apiSecret = "----";
var responseData = new ResponseDto();
var eventDto = new EventDto
{
EventId = "",
EventName = "Test Event 1",
StartDate = DateTime.Parse("2023-05-01 08:11"),
PublishingPointUrl = "rtmp://mysStreamingServer.com:1935/MyApp/MyStreamKey",
TargetDelay = 15000,
EventTimeZone = "GMT Standard Time",
EventWaitTime = 15,
EventMaxTime = 480,
EventLanguage = "en-GB",
UserPhrases = "",
SilenceTimeoutMs = 500
};
//////make request
using (var client = new HttpClient())
{
//set api credentials in header
client.DefaultRequestHeaders.Add("ApiKey", apiKey);
client.DefaultRequestHeaders.Add("ApiSecret", apiSecret);
//serialize dto object before request
var jsonObject = JsonConvert.SerializeObject(eventDto);
using (var httpContent = new StringContent(jsonObject, Encoding.UTF8, "application/json"))
{
//post request
var response = client.PostAsync("https://live-captions.com/api/lc/SaveEvent", httpContent).Result;
//convert received response into dto
responseData = JsonConvert.DeserializeObject<ResponseDto>(response.Content.ReadAsStringAsync().Result);
///display received data
if (responseData != null && responseData.IsSuccess)
{
Console.WriteLine($"Live event id: {responseData.EntityId}, Message: {responseData.Message}");
}
else
{
Console.WriteLine(responseData?.Message);
}
}
}
Console.ReadLine();
}
public class EventDto
{
public string EventId { get; set; }
public string EventName { get; set; }
public DateTime StartDate { get; set; }
public string PublishingPointUrl { get; set; }
public int TargetDelay { get; set; }
public string EventTimeZone { get; set; }
public int EventWaitTime { get; set; }
public int EventMaxTime { get; set; }
public string EventLanguage { get; set; }
public string UserPhrases { get; set; }
public int SilenceTimeoutMs { get; set; }
}
public class ResponseDto
{
public bool IsSuccess { get; set; }
public string EntityId { get; set; }
public string Message { get; set; }
}
public void OrderClosedCaptions()
{
//import Newtonsoft.Json
//set api key and secret
var apiKey = "-----";
var apiSecret = "----";
var responseData = new ResponseDto();
var eventDto = new RecordedEventDto()
{
EventId = "",
EventName = "Captions for my yesterday meeting..",
StartDate = DateTime.Now,
MediaUrl = "https://myserver/myfile.mp4",
EventTimeZone = "GMT Standard Time",
EventLanguage = "en-GB",
UserPhrases = "",
SilenceTimeoutMs = 500
};
//////make request
using (var client = new HttpClient())
{
//set api credentials in header
client.DefaultRequestHeaders.Add("ApiKey", apiKey);
client.DefaultRequestHeaders.Add("ApiSecret", apiSecret);
//serialize dto object before request
var jsonObject = JsonConvert.SerializeObject(eventDto);
using (var httpContent = new StringContent(jsonObject, Encoding.UTF8, "application/json"))
{
//post request
var response = client.PostAsync("https://live-captions.com/api/lc/SaveRecordedEvent", httpContent).Result;
//convert received response into dto
responseData = JsonConvert.DeserializeObject<ResponseDto>(response.Content.ReadAsStringAsync().Result);
///display received data
if (responseData != null && responseData.IsSuccess)
{
Console.WriteLine($"Event id: {responseData.EntityId}, Message: {responseData.Message}");
}
else
{
Console.WriteLine(responseData?.Message);
}
}
}
Console.ReadLine();
}
public class RecordedEventDto
{
public string EventId { get; set; }
public string EventName { get; set; }
public DateTime StartDate { get; set; }
public string MediaUrl { get; set; }
public string EventTimeZone { get; set; }
public string EventLanguage { get; set; }
public string UserPhrases { get; set; }
public int SilenceTimeoutMs { get; set; }
}
public class ResponseDto
{
public bool IsSuccess { get; set; }
public string EntityId { get; set; }
public string Message { get; set; }
}
public void CheckCCStatus()
{
//set api key and secret
var apiKey = "----";
var apiSecret = "----";
//event id retrieved after creating event
var eventId = "-------";
//////make request
using (var client = new HttpClient())
{
//set api credentials in header
client.DefaultRequestHeaders.Add("ApiKey", apiKey);
client.DefaultRequestHeaders.Add("ApiSecret", apiSecret);
var response = client.PostAsync($"https://live-captions.com/api/lc/GetEventStatus?eventId={eventId}", null).Result;
var status = response.Content.ReadAsStringAsync().Result;
if (status == "1") Console.WriteLine("Status: IN_PROGRESS");
if (status == "2")
{
Console.WriteLine("Status: COMPLETED");
Console.WriteLine($"Ready for download at: https://live-captions.com/api/lc/DownloadTranscript?eventId={eventId}&format=3");
}
if (status == "0") Console.WriteLine("Status: UNKNOWN");
}
Console.ReadLine();
}
$(document).ready(function () {
//catch button click
$(document).delegate(".createEventButton", "click", function () {
createEvent();
});
//call the Api
function createEvent() {
// find your api key and secret in your account settings
var apiKey = "----";
var apiSecret = "---";
//create your object here
var eventRequest = {
EventId: "",
EventName: "Test Event 1",
StartDate: "2023-01-01 08:11",
PublishingPointUrl: "rtmp://mysStreamingServer.com:1935/MyApp/MyStreamKey",
TargetDelay: 15000,
EventTimeZone: "GMT Standard Time",
EventWaitTime: 15,
EventMaxTime: 480,
EventLanguage: "en-GB",
UserPhrases: "",
SilenceTimeoutMs: 500
};
//post
$.ajaxSetup({ cache: false });
$.ajax({
url: 'https://live-captions.com/api/lc/SaveEvent',
type: 'POST',
beforeSend: function (request) {
request.setRequestHeader("ApiKey", apiKey);
request.setRequestHeader("ApiSecret", apiSecret);
},
dataType: 'json',
data: eventRequest,
success: function (data) {
if (!data.isSuccess) {
alert('Error: ' + data.message);
}
else {
alert('Event created, event id: ' + data.entityId);
}
},
error: function (jqXHR, textStatus, errorThrown) {
if (jqXHR.status == 500) {
alert('Internal error: ' + jqXHR.responseText);
} else {
alert('Unexpected error.');
}
}
});
};
});