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
200	Contents	Caption file as body data
200	Description	Success
200	Contents	{ "CaptionUrl": "Hosted URL" }
400	Description	An error occurred
400	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" }