Get Caption¶
Get the caption file for a job. The job must have completed transcription before a caption can be downloaded.
HTTP Method
-
GET
/api/job/get_caption
¶
Query String Parameters — Required
Name | Details | |
---|---|---|
v | Description | The version of the API to use |
Allowed Values | 1 | |
Example | v=1 |
|
api_token | Description | The API token used for this session |
Allowed Values | Hex String | |
Example | api_token=7ca5dc5c7cce449fb0fff719307e8f5f |
|
job_id | Description | The ID of the job |
Allowed Values | Hex String | |
Example | job_id=64bea283eff6475ea6596027a6ba0929 |
|
caption_format | Description | The format of the caption file to return |
Allowed Values | Caption Format Enumeration | |
Example | caption_format=SRT |
Query String Parameters — Optional
Name | Details | |
---|---|---|
build_url | Rather than returning the file, return a permanent URL to the
file. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | build_url=true |
|
audio_description | Select Audio Description Caption |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | audio_description=true |
|
mixed | **Requires audio_description parameter**
Mixes together the audio description transcript into the caption transcript |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | mixed=true |
|
caption_words_min | Minimum number of words allowed in a caption. |
|
Allowed Values | Integer | |
Default Value | 1 | |
Example | caption_words_min=3 |
|
caption_by_sentence | When true, puts each sentence into its own caption. When
false, more than one sentence may appear in a single
caption. |
|
Allowed Values | Boolean | |
Default Value | true | |
Example | caption_by_sentence=false |
|
characters_per_caption_line | Maximum number of characters to be displayed on each
caption line. |
|
Allowed Values | Integer | |
Default Value | 42 | |
Example | characters_per_caption_line=30 |
|
dfxp_header | Allows you to specify a custom header for your DFXP
caption file. The header should be the entire contents of
the header including the opening and closing tags. Ignored if caption_format does not equal DFXP. |
|
Allowed Values | XML String | |
Default Value | “” | |
Example | dfxp_header=<head></head> |
|
disallow_dangling | Will prevent captions from having the last word in a sentence
start a new line. Last words will ALWAYS be kept on the same
line, even if it breaks the characters_per_caption_line option. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | disallow_dangling=true |
|
display_effects_speaker_as | Determines what speaker name should used for sound effects. |
|
Allowed Values | String | |
Default Value | Effects | |
Example | display_effects_speaker_as=Sound |
|
display_speaker_id | Determines the way speakers are identified in the captions.
Choose "no" to not display speaker identities at all:
">> example"
Choose "number" to display only the speaker number:
">> Speaker 1: example"
Choose "name" to display the speaker name:
">> John Doe: example".
If you choose "name", the speaker number will be displayed
if the name is not available. |
|
Allowed Values | Speaker ID Enumeration | |
Default Value | name | |
Example | display_speaker_id=number |
|
iwp_name | The named version of element list to generate the transcript from.
If not specified, the transcript will be generated from the
latest version. |
|
Allowed Values | String | |
Default Value | “” | |
Example | iwp_name=MECHANICAL |
|
elementlist_version | The version of element list to generate the captions from.
If not specified, the caption will be generated from the
latest version. |
|
Allowed Values | ISO 8601 Date String | |
Default Value | “” | |
Example | elementlist_version=2014-07-31T12:35:52.324389 |
|
emit_speaker_change_tokens_as | Determine what characters to use to denote speaker changes. |
|
Allowed Values | String | |
Default Value | “>>” | |
Example | emit_speaker_change_tokens_as=-- |
|
force_case | Force the contents of the captions to be all UPPER or
lower case. If blank, the case of the captions is not
changed. |
|
Allowed Values | Case Enumeration | |
Default Value | “” | |
Example | force_case=lower |
|
include_dfxp_metadata | When true, and the caption format requested is DFXP,
the jobs name, ID and language will be added to the DFXP
metadata header. When false, these data are omitted from
the header.
Ignored if caption_format does not equal DFXP. |
|
Allowed Values | Boolean | |
Default Value | true | |
Example | include_dfxp_metadata=false |
|
layout_target_caption_length_ms | Captions generated will, on average, be this duration. However,
they may vary significantly based on other parameters you set. |
|
Allowed Values | Integer | |
Default Value | 5000 | |
Example | layout_target_caption_length_ms=4000 |
|
line_break_on_sentence | Inserts a line break in between sentences that are in
the same caption. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | line_break_on_sentence=true |
|
line_ending_format | Determine the end of line (EOL) character to use for the
captions. |
|
Allowed Values | Line Ending Enumeration | |
Default Value | “UNIX” | |
Example | line_ending_format=OSX |
|
lines_per_caption | Number of lines to be displayed for each caption. |
|
Allowed Values | Integer | |
Default Value | 2 | |
Example | lines_per_caption=3 |
|
mask_profanity | Replace profanity with asterisks. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | mask_profanity=true |
|
maximum_caption_duration | No captions longer than this (in milliseconds) will be
produced. If not specified, there is no maximum. |
|
Allowed Values | Integer | |
Default Value | None (no maximum) | |
Example | maximum_caption_duration=10000 |
|
merge_gap_interval | Captions with a gap between them that is smaller than
this (in milliseconds) will have their start and/or
end times changed so there is no time gap between the captions. |
|
Allowed Values | Integer | |
Default Value | 1000 | |
Example | merge_gap_interval=1500 |
|
minimum_caption_length_ms | Extends the duration of short captions to the this minimum
length. Additional time is taken from later caption blocks
to meet this minimum time. |
|
Allowed Values | Integer | |
Default Value | None (no minimum) | |
Example | minimum_caption_length_ms=1500 |
|
minimum_gap_between_captions_ms | Adds a minimum time between captions such as there will
always be some time between captions where no text is
displayed. When captions are very close together, time
will be removed from the caption duration to make the gap. |
|
Allowed Values | Integer | |
Default Value | None (no minimum) | |
Example | minimum_gap_between_captions_ms=100 |
|
qt_seamless | Does not put time gaps of any kind between caption blocks.
Ignored if caption_format does not equal QT. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | qt_seamless=true |
|
remove_disfluencies | Remove verbal disfluencies from the generated transcript.
Common disfluencies such as "um" and "ah" are removed while
maintaining appropriate punctuation. |
|
Allowed Values | Boolean | |
Default Value | true | |
Example | remove_disfluencies=false |
|
remove_sounds_list | A list of sounds to not show in the caption. This is a
JSON style list, and should look like ["MUSIC", "LAUGH"].
Ignored if remove_sound_references is true. |
|
Allowed Values | Sound Tag Enumeration | |
Default Value | [] | |
Example | remove_sounds_list=["MUSIC","LAUGH"] |
|
remove_sound_references | Remove ALL non-verbal sound and noise references from the
generated transcript. Sounds and unidentified noises are
depicted in the caption as [SOUND], [COUGH] and [NOISE].
If this parameter is set, these identifiers are omitted
from the caption. |
|
Allowed Values | Boolean | |
Default Value | true | |
Example | remove_sound_references=false |
|
replace_slang | Replace common slang terms from the generated transcript.
Common replacements are "want to" for "wanna", "going to"
for "gonna", etc. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | replace_slang=true |
|
silence_max_ms | If there is a interval of silence in the middle of a sentence
longer than this, then the caption will be split. |
|
Allowed Values | Integer | |
Default Value | 2000 | |
Example | silence_max_ms=1000 |
|
single_speaker_per_caption | When true, puts each speaker into its own caption. When false,
more than one speaker may appear in a single caption. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | single_speaker_per_caption=true |
|
sound_boundaries | Specifies the characters to surround sound references with.
The default will generate sound references that look like
this: [MUSIC]. |
|
Allowed Values | Character Tuple | |
Default Value | (‘[‘,’]’) | |
Example | sound_boundaries=('{','}') |
|
sound_threshold | Sound references that are longer than this threshold will
be made their own caption entirely, and will not have any
text included with them. If not set, Sound references will
be included back to back with text no matter the duration of
the sound. |
|
Allowed Values | Integer | |
Default Value | None | |
Example | sound_threshold=5000 |
|
sound_tokens_by_caption | If true, all sound references will always be in their own
caption. If false, more than one sound reference may
appear in a single caption. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | sound_tokens_by_caption=true |
|
sound_tokens_by_line | If true, all sound references will always be in their own
line. If false, more than one sound reference may appear
in a single line. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | sound_tokens_by_line=true |
|
sound_tokens_by_caption_list | If non-empty, the specified sound references will always
be in their own caption. If empty, more than one
sound reference may appear in a single caption.
Ignored if sound_tokens_by_caption is true. |
|
Allowed Values | Sound Tag Enumeration | |
Default Value | [“BLANK_AUDIO”,”MUSIC”] | |
Example | sound_tokens_by_caption_list=[] |
|
sound_tokens_by_line_list | If non-empty, the specified sound references will always
be in their own line. If empty, more than one
sound reference may appear in a single line.
Ignored if sound_tokens_by_line is true. |
|
Allowed Values | Sound Tag Enumeration | |
Default Value | [“BLANK_AUDIO”,”MUSIC] | |
Example | sound_tokens_by_line_list=["NOISE"] |
|
speaker_on_new_line | If true, a speaker change will cause a new caption to be
made. If false, multiple speakers may appear in a single
caption. |
|
Allowed Values | Boolean | |
Default Value | true | |
Example | speaker_on_new_line=false |
|
srt_format | If the caption format is SRT, determines what the caption
blocks will look like. The default, prints caption blocks
that look like this:
1:
00:00:06,060 --> 00:00:16,060
This is the caption text.
You can alter the caption block by re-arranging or removing
the substitution string values, shown enclosed in braces "{}"
in the default value below. Substitution strings may used
more than once if desired. Any text that is not a substitution
string will be displayed as written. To add new lines, include
a \n. Note, you may need to escape the \n with an extra
backslash when encoding the request. |
|
Allowed Values | String | |
Default Value | {caption_number:d}\n{start_hour:02d}:
{start_minute:02d}:{start_second:02d},
{start_millisecond:03d} -->{end_hour:02d}:
{end_minute:02d}:{end_second:02d},
{end_millisecond:03d}\n{caption_text}\n\n |
|
Example | srt_format=... |
|
strip_square_brackets | Removes all square brackets like '[' or ']' from captions.
By default square brackets surround sound references like
'[MUSIC]', but they may exist as part of the caption text as well. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | strip_square_brackets=true |
|
utf8_mark | Adds a utf8 bytemark to the beginning of the caption. This
should only be used if the system you are loading the caption
files into needs a byte marker. The vast majority of systems
do not. |
|
Allowed Values | Boolean | |
Default Value | false | |
Example | utf8_mark=true |
|
replace_english_spelling | Replaces English spelling with location accurate spelling
i.e. Color --> Colour |
|
Allowed Values | String | |
Default Value | A --> American
B --> British
Z --> British ize
U --> Australian
C --> Canadian |
|
Example | replace_english_spelling=B |
Responses
Returns requested caption file as body data, or if build_url was set to true returns caption URL.
HTTP Code | Details | |
---|---|---|
200 | Description | Success |
Contents | Caption file as body data
|
|
200 | Description | Success |
Contents | {
"CaptionUrl": "Hosted URL"
}
|
|
400 | Description | An error occurred |
Contents | Error description (see Error Format for details) |
Example Requests
GET /api/job/get_caption?v=1&api_token=7ca5dc5c7cce449fb0fff719307e8f5f
&job_id=64bea283eff6475ea6596027a6ba0929&caption_format=SRT HTTP/1.1
Host: api.cielo24.com
Example Response
HTTP/1.1 200 OK
Content-Type: text/plain
1
00:02:17,440 --> 00:02:20,375
Some text on first line.
2
00:02:20,476 --> 00:02:22,501
More text on second line.
HTTP/1.1 200 OK
Content-Type: application/json
{ "CaptionUrl": "http://domain.com/path/file.srt" }