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