Captions API

Live captions in the language being spoken, included with every stream. These endpoints answer 404 until live captions are enabled for your organization.

This page is generated from the OpenAPI specification; the same text is inMarkdown for tools and AI assistants.

Read a customer's caption settings

GET/v1/customers/{customer_ref}/caption-settings

The caption settings new streams for this customer start with. is_default is true when none have been saved.

Path parameters

Name	Type	Description
customer_refrequired	string	Your identifier for the customer.

Response 200

The settings.

Fields

Name	Type	Description
customer_refrequired	string	Your identifier for a customer. 1-128 letters, digits, `.`, `_` or `-`; not `.` or `..`.
settingsrequired	object
settings.spoken_languagerequired	string	`auto`, or the language spoken: one of `ar de en es fr it ja ko pl pt ru tl uk vi zh`.
settings.translation_languagesrequired	array of string	Reserved for translated captions. Empty.
settings.translation_moderequired	string	One of `"on_demand"`, `"always"`.
settings.profanity_maskingrequired	boolean
settings.sung_lyricsrequired	string	Whether sung lyrics are captioned or shown as a music symbol. One of `"music-symbol"`, `"caption"`.
settings.vocabularyrequired	array of string	Up to 100 names and terms the captions should spell right.
settings.retired_source_languages	array of string
is_defaultrequired	boolean	True when nothing has been saved for this customer.
translations_availablerequired	boolean	True when translated captions are priced for the organization, so languages chosen now would be produced.
choicesrequired	object	The languages each field may name, for a form.
choices.spokenrequired	array of object
choices.spoken[].coderequired	string	The language code, e.g. es or zh-Hans.
choices.spoken[].namerequired	string	The language’s name in itself.
choices.spoken[].beta	boolean	True for a translation still in beta.
choices.translationrequired	array of object
choices.translation[].coderequired	string	The language code, e.g. es or zh-Hans.
choices.translation[].namerequired	string	The language’s name in itself.
choices.translation[].beta	boolean	True for a translation still in beta.

Errors

Status	Code	Meaning
400	invalid_customer_ref	The path’s customer reference is not valid.

curl "https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings" \
  -H "Authorization: Bearer $CARDINAL_API_KEY"

import os

import requests

response = requests.get(
    "https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings",
    headers={
        "Authorization": f"Bearer {os.environ['CARDINAL_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.text)

const response = await fetch('https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data = await response.json();
console.log(response.status, data);

const response: Response = await fetch('https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data: unknown = await response.json();
console.log(response.status, data);

<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CARDINAL_API_KEY'),
    ],
    'http_errors' => false,
]);
echo $response->getStatusCode(), ' ', $response->getBody(), PHP_EOL;

require 'json'
require 'net/http'

uri = URI("https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('CARDINAL_API_KEY')}"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.body

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  req, err := http.NewRequest("GET", "https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings", nil)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("CARDINAL_API_KEY"))

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(resp.StatusCode, string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings"))
            .header("Authorization", "Bearer " + System.getenv("CARDINAL_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("CARDINAL_API_KEY"));

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

Save a customer's caption settings

PUT/v1/customers/{customer_ref}/caption-settings

The whole document; a field left out takes its default. New streams for the customer start with these.

Path parameters

Name	Type	Description
customer_refrequired	string	Your identifier for the customer.

Request body

Name	Type	Description
spoken_language	string
translation_languages	array of string
translation_mode	string	One of `"on_demand"`, `"always"`.
profanity_masking	boolean
sung_lyrics	string	One of `"music-symbol"`, `"caption"`.
vocabulary	array of string

Response 200

The settings as saved.

Fields

Name	Type	Description
customer_refrequired	string	Your identifier for a customer. 1-128 letters, digits, `.`, `_` or `-`; not `.` or `..`.
settingsrequired	object
settings.spoken_languagerequired	string	`auto`, or the language spoken: one of `ar de en es fr it ja ko pl pt ru tl uk vi zh`.
settings.translation_languagesrequired	array of string	Reserved for translated captions. Empty.
settings.translation_moderequired	string	One of `"on_demand"`, `"always"`.
settings.profanity_maskingrequired	boolean
settings.sung_lyricsrequired	string	Whether sung lyrics are captioned or shown as a music symbol. One of `"music-symbol"`, `"caption"`.
settings.vocabularyrequired	array of string	Up to 100 names and terms the captions should spell right.
settings.retired_source_languages	array of string
is_defaultrequired	boolean	True when nothing has been saved for this customer.
translations_availablerequired	boolean	True when translated captions are priced for the organization, so languages chosen now would be produced.
choicesrequired	object	The languages each field may name, for a form.
choices.spokenrequired	array of object
choices.spoken[].coderequired	string	The language code, e.g. es or zh-Hans.
choices.spoken[].namerequired	string	The language’s name in itself.
choices.spoken[].beta	boolean	True for a translation still in beta.
choices.translationrequired	array of object
choices.translation[].coderequired	string	The language code, e.g. es or zh-Hans.
choices.translation[].namerequired	string	The language’s name in itself.
choices.translation[].beta	boolean	True for a translation still in beta.

Errors

Status	Code	Meaning
400	invalid_customer_ref	The path’s customer reference is not valid.
400	invalid_body	The body is not JSON.
400	invalid_captions	A setting is not acceptable; `detail` names the field.
409	translations_unavailable	Translated captions are not available to your organization.
413	body_too_large	The document is over 128 KB.

curl -X PUT "https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings" \
  -H "Authorization: Bearer $CARDINAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "spoken_language": "en",
  "profanity_masking": true,
  "vocabulary": [
    "Grace Chapel",
    "Pastor Okafor"
  ]
}'

import os

import requests

response = requests.put(
    "https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings",
    headers={
        "Authorization": f"Bearer {os.environ['CARDINAL_API_KEY']}",
    },
    json={
        "spoken_language": "en",
        "profanity_masking": True,
        "vocabulary": ["Grace Chapel", "Pastor Okafor"],
    },
    timeout=30,
)
print(response.status_code, response.text)

const response = await fetch('https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "spoken_language": "en",
    "profanity_masking": true,
    "vocabulary": [
      "Grace Chapel",
      "Pastor Okafor"
    ]
  }),
});
const data = await response.json();
console.log(response.status, data);

const response: Response = await fetch('https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "spoken_language": "en",
    "profanity_masking": true,
    "vocabulary": [
      "Grace Chapel",
      "Pastor Okafor"
    ]
  }),
});
const data: unknown = await response.json();
console.log(response.status, data);

<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client();
$response = $client->request('PUT', 'https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CARDINAL_API_KEY'),
    ],
    'json' => [
        'spoken_language' => 'en',
        'profanity_masking' => true,
        'vocabulary' => ['Grace Chapel', 'Pastor Okafor'],
    ],
    'http_errors' => false,
]);
echo $response->getStatusCode(), ' ', $response->getBody(), PHP_EOL;

require 'json'
require 'net/http'

uri = URI("https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings")
request = Net::HTTP::Put.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('CARDINAL_API_KEY')}"
request['Content-Type'] = 'application/json'
request.body = JSON.generate({
  "spoken_language" => "en",
  "profanity_masking" => true,
  "vocabulary" => ["Grace Chapel", "Pastor Okafor"]
})

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.body

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
  "strings"
)

func main() {
  req, err := http.NewRequest("PUT", "https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings", strings.NewReader(`{
  "spoken_language": "en",
  "profanity_masking": true,
  "vocabulary": [
    "Grace Chapel",
    "Pastor Okafor"
  ]
}`))
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("CARDINAL_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(resp.StatusCode, string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings"))
            .header("Authorization", "Bearer " + System.getenv("CARDINAL_API_KEY"))
            .header("Content-Type", "application/json")
            .method("PUT", HttpRequest.BodyPublishers.ofString("{\"spoken_language\":\"en\",\"profanity_masking\":true,\"vocabulary\":[\"Grace Chapel\",\"Pastor Okafor\"]}"))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("PUT"), "https://api.cardinalstreaming.com/v1/customers/grace-chapel/caption-settings");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("CARDINAL_API_KEY"));
request.Content = new StringContent("{\"spoken_language\":\"en\",\"profanity_masking\":true,\"vocabulary\":[\"Grace Chapel\",\"Pastor Okafor\"]}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

Read a stream's captions status

GET/v1/streams/{playback_id}/captions

Whether captions are being produced for a stream right now, and how far behind the video they are.

Path parameters

Name	Type	Description
playback_idrequired	string	The stream’s `playback_id`.

Response 200

The status.

Fields

Name	Type	Description
statusrequired	string	`delayed` when captions are more than 15 seconds behind the video. One of `"waiting"`, `"running"`, `"delayed"`, `"unavailable"`, `"ended"`.
lag_secondsrequired	number or null
source_language	string
translation_mode	string
translations_availablerequired	boolean
languagesrequired	array of object
languages[].langrequired	string
languages[].namerequired	string
languages[].kindrequired	string	One of `"source"`, `"translation"`.
languages[].beta	boolean
languages[].producingrequired	boolean

Errors

Status	Code	Meaning
404	not_found	No such stream in your organization.

curl "https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/captions" \
  -H "Authorization: Bearer $CARDINAL_API_KEY"

import os

import requests

response = requests.get(
    "https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/captions",
    headers={
        "Authorization": f"Bearer {os.environ['CARDINAL_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.text)

const response = await fetch('https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/captions', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data = await response.json();
console.log(response.status, data);

const response: Response = await fetch('https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/captions', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data: unknown = await response.json();
console.log(response.status, data);

<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/captions', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CARDINAL_API_KEY'),
    ],
    'http_errors' => false,
]);
echo $response->getStatusCode(), ' ', $response->getBody(), PHP_EOL;

require 'json'
require 'net/http'

uri = URI("https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/captions")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('CARDINAL_API_KEY')}"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.body

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  req, err := http.NewRequest("GET", "https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/captions", nil)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("CARDINAL_API_KEY"))

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(resp.StatusCode, string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/captions"))
            .header("Authorization", "Bearer " + System.getenv("CARDINAL_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/captions");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("CARDINAL_API_KEY"));

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");