LEXI Live API Documentation

Overview

  • Engines - Retrieving available EEG ASR engines.
  • Instances - Retrieving, creating, and deleting LEXI Live Instances
  • Jobs - Retrieving, creating and deleting LEXI jobs (deprecated).
  • Transcripts - Retrieving caption transcripts from LEXI Live jobs
  • Topic Models - Retrieving, creating, editing, and deleting LEXI custom topic models
  • Topic Models - Word entries - Retrieving, creating, editing, and deleting custom topic model word entries
  • Topic Models - Substitution / Blacklist - Retrieving, creating, editing, and deleting custom topic model substitution entries

Denotes an optional parameter.

ASR Engines

The following provides retrieval of available engines.
Resource Description
GET /live/v2/engines

Action

Retrieves a list of EEG ASR Engines available to use. These are the engines supported by LEXI.
In particular, the "name" property will be needed to construct instances and jobs using the engine.

NOTE: No authentication is required for this endpoint.

Instances

The following provides for the creation and retrieval of instances through the LEXI Live API.
Resource Description
GET /live/v2/instances

Action

Retrieves list of LEXI Live instances available to your credential set.

Parameters (Query)
get_history  If set to 1, or omitted, the response will include LEXI job history for each instance. If set to 0, the response will omit LEXI job history. The API will return a BAD REQUEST error for any value other than 1 or 0.
GET /live/v2/instances/:instance_id

Action

Retrieves the specified :instance_id (instance).

Parameters (Path)
:instance_id The instance_id to retrieve.
Parameters (Query)
get_history  If set to 1, or omitted, the response will include LEXI job history for this instance. If set to 0, the response will omit LEXI job history. No other values are supported.
POST /live/v2/instances/:instance_id/turn_on

Action

Activates the specified :instance_id (instance) to start caption service.

Parameters (Path)
:instance_id The instance_id to activate.
Parameters (JSON)

These are optional parameters that are carried with the instance job into the activity reports.

initialization_origin (string)  The origin of the API call. Recommended value: Application/Daemon name.
initialization_reason (string)  The reason of the API call. Recommended values: "User initialized" or "Scheduled Start".
Parameters (Query)
get_history  If set to 1, or omitted, the response will include LEXI job history for this instance. If set to 0, the response will omit LEXI job history. No other values are supported.
POST /live/v2/instances/:instance_id/turn_off

Action

Terminates the specified :instance_id (instance) to cease caption service.

Parameters (Path)
:instance_id The instance_id to terminate.
Parameters (JSON)

These are optional parameters that are carried with the instance job into the activity reports.

termination_origin (string)  The origin of the API call. Recommended value: Application/Daemon name.
termination_reason (string)  The reason of the API call. Recommended values: "User initialized" or "Scheduled End".
Parameters (Query)
get_history  If set to 1, or omitted, the response will include LEXI job history for this instance. If set to 0, the response will omit LEXI job history. No other values are supported.
GET /live/v2/instances/:instance_id/keep_alive

Action

Retrieves the keep-alive status/information of the specified :instance_id (instance), if available.

Parameters (Path)
:instance_id The instance_id that was activated with keep-alive (remained on).
POST /live/v2/instances/:instance_id/keep_alive

Action

If the specified :instance_id (instance) is scheduled to terminate within a specified number of seconds (defaulting to 30 seconds), allow the instance to keep running until the user terminates it through other means.

Parameters (Path)
:instance_id The instance_id to keep-alive (remain on).
Parameters (JSON)

You can optionally specify the keepalive_period. Otherwise, a default keepalive_period of 30 seconds will be used.

keepalive_period (integer)  The number of seconds the keep-alive status is active.
DELETE /live/v2/instances/:instance_id/keep_alive

Action

Removes the keep-alive status/information from the specified :instance_id (instance), if available. This removes the ability to keep the instance alive if previously activated. If the instance does not have keep-alive information, the API returns a BAD REQUEST error.

Parameters (Path)
:instance_id The instance_id that was activated with keep-alive (remained on).
POST /live/v2/instances

Action

Creates a new instance. Returns a JSON-Serialized instance on completion.

Parameters (JSON)
name (string) The LEXI Live instance name.
While it is not required that the name be unique within your billing group, it is strongly recommended to avoid operator confusion.
engine (string) The LEXI Live recognition engine to be used. Currently the following choices are available:
  • lexi3 (default)
  • lexiAL
The current list of engines can be retrieved at: /speech-recognition/live/v2/engines
base_model (string) The base language model to use. For US English, use:
  • en-US_BroadbandModel
The current list of models can be retrieved at: /speech-recognition/base_models
custom_model (string)  The custom voice model defined in YOUR EEG Cloud account to use.
diarization_style (string)  The speaker change style to use.
Note - This setting is only available for the LEXI 3.0 engine.
Values to use:
  • COLOR_CHANGE - Change the caption color when the speaker changes.
  • CHEVRON_NEWLINE - Insert a new line that begins with ">>" when the speaker changes.
  • DASH_NEWLINE - Insert a new line that begins with "-" when the speaker changes.
Do not include the diarization_style setting if you do not want speaker change indications to appear in captions.
audio_events (boolean)  Enables identification of audio events in CC output. If not specified, LEXI will enable identification of all event types (i.e., music_events, applause_events, laughter_events).

Values to use:
  • true
  • false
music_events (boolean)  Enables identification of music audio events in CC output. audio_events must be enabled.

Values to use:
  • true
  • false
applause_events (boolean)  Enables identification of applause audio events in CC output. audio_events must be enabled.

Values to use:
  • true
  • false
laughter_events (boolean)  Enables identification of laughter audio events in CC output. audio_events must be enabled.

Values to use:
  • true
  • false
cc_service (string) The caption service to use. *Note - Value must be sent as a string.
Values to use:
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
use_newfor (string)  Engages the "Newfor/Teletext" output mode. If not specified, the default output mode is "608/708".
Please choose in accordance with your caption encoder's "CC Output Format" setting, as well as the international region in which your content will be viewed.
Values to use:
  • true
  • false
teletext_page (string)  The Teletext page number to be used with the "Newfor/Teletext" output mode.
In the format of: [magazine number][page number (tens)][page number (units)]
For example:
  • 801
  • 8FF
newfor_row_ordering (string)  Required when use_newfor is true. A compatibility option that controls the order in which rows are written in Newfor row update commands. The end result for caption viewers should be the same regardless of the value chosen, though some downstream decoders may function better with one ordering over the other.
Values to use:
  • top
  • bottom
display_style (string)  Determines the caption advance style - roll-up ("rollup") or pop-on ("popon"). If not specified, the default output mode is "rollup".
Values to use:
  • rollup
  • popon
all_caps (string)  Whether captions should be rendered in ALL CAPS or sentence case. *Note - Value must be sent as a string.
Values to use:
  • true
  • false
num_rows (string)  The number of caption rows to use in output captions. *Note - Value must be sent as a string.
Values to use:
  • 2
  • 3
  • 4
base_row (string)  The base caption row for display.
*Note - Value must be sent as a string.
Values are 1 (top) through 15 (bottom) for 608/708 and 3 (top) through 22 (bottom) for Newfor/teletext. Please note that the base row will be the maximum of this value and "num_rows"
col_indent (string)  The number of columns to indent from the left-hand side of screen. Columns are numbered 1-32 from left to right.
*Note - Value must be sent as a string.
icapaccesscode (string) The iCap Access Code to use for caption delivery.
*Note - Access Code must be shared with EEGASR / EEG LEXI ASR before LEXI Live service can be used.
timeout (string)  The number of seconds (integer value) of silence allowed before iCap will auto-terminate a job (to reduce billing charges).
*Note - Value must be sent as a string.
Values to use:
  • -1 - No timeout. Jobs will run indefinitely until terminated by user.
  • 1 and higher - Jobs will auto-terminate if audio is not present for a specified period of seconds.
profanity_filter (string)  Engages a basic profanity filter.
*Note - Value must be sent as a string.
Values to use:
  • true
  • false
vision_positioning (string)  Engages a basic facial and text detector to attempt to keep captions from obscuring faces and Character Generator elements.
*Note - Value must be sent as a string.
Values to use:
  • true
  • false
max_delay (number or string)  Sets the maximum number of seconds between receiving audio input and producing CC output. Higher max_delay values may yield greater recognition accuracy.
Values to use:
  • 0.7 through 4
PUT /live/v2/instances/:instance_id

Action

Updates an existing instance and replaces the existing settings. Returns a JSON-Serialized instance on completion.

Parameters (JSON)

Parameters are identical to the POST request used to create instances (above).

Parameters (Query)
get_history  If set to 1, or omitted, the response will include LEXI job history for this instance. If set to 0, the response will omit LEXI job history. No other values are supported.
PATCH /live/v2/instances/:instance_id

Action

Modifies an existing instance with select settings. Returns a JSON-Serialized instance on completion.

Parameters (JSON)

Parameters are identical to the POST request used to create instances (above).

Parameters (Query)
get_history  If set to 1, or omitted, the response will include LEXI job history for this instance. If set to 0, the response will omit LEXI job history. No other values are supported.
DELETE /live/v2/instances/:instance_id

Action

Deletes the specified :instance_id.
*Note: Instances consume no resources to simply exist, but deleting them can cause you to lose track of transcripts and job/audit history.
Consider renaming an instance to "{Old Name} - Unused" for 30 days before deleting instances entirely.

Parameters (Path)
:instance_id The instance_id to delete.

Denotes an optional parameter.

Jobs

NOTE: The LEXI v1 (Jobs) API is deprecated
Please refer to Instances.
Resource Description
GET /live/v1/jobs

Action

Retrieve a list of recent LEXI Live jobs

Parameters (Query)
limit  The maximum number of records (or page size) to load. If this parameter is used, the response will include additional fields verifying the limit, offset, and total number of available records. Note that in future versions of the API, it is likely that a default limit of 1000 records will be returned if no explicit limit is specified.
GET /live/v1/jobs/:job_id

Action

Retrieves detailed information of the specified :job_id.

Parameters (Path)
:job_id A specific LEXI Live Job Identifier.
POST /live/v1/jobs

Action

Creates a new LEXI Live job and launches it immediately.

Parameters (JSON)
engine (string) The LEXI Live recognition engine to be used. Currently the following choices are available:
  • lexi3 (default)
  • lexiAL
The current list of engines can be retrieved at: /speech-recognition/live/v2/engines
base_model (string) The base language model to use. For US English, use:
  • en-US_BroadbandModel
The current list of models can be retrieved at: speech-recognition/base_models
custom_model (string)  The custom voice model defined in YOUR EEG Cloud account to use.
cc_service (string) The caption service to use. *Note - Value must be sent as a string.
Values to use:
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
all_caps (string)  Whether captions should be rendered in ALL CAPS or sentence case. *Note - Value must be sent as a string.
Values to use:
  • true
  • false
num_rows (string)  The number of rollup caption rows to use in output captions. *Note - Value must be sent as a string.
Values to use:
  • 2
  • 3
  • 4
base_row (string)  The base caption row for display.
*Note - Value must be sent as a string.
Values are 1 (top) through 15 (bottom) for 608/708 and 3 (top) through 22 (bottom) for Newfor/teletext. Please note that the base row will be the maximum of this value and "num_rows"
col_indent (string)  The number of columns to indent from the left-hand side of screen. Columns are numbered 1-32 from left to right.
*Note - Value must be sent as a string.
icapaccesscode (string) The iCap Access Code to use for caption delivery.
*Note - Access Code must be shared with EEGASR / EEG LEXI ASR before LEXI Live service can be used.
timeout (string)  The number of seconds (integer value) of silence allowed before iCap will auto-terminate a job (to reduce billing charges).
*Note - Value must be sent as a string.
Values to use:
  • -1 - No timeout. Jobs will run indefinitely until terminated by user.
  • 1 and higher - Jobs will auto-terminate if audio is not present for a specified period of seconds.
profanity_filter (string)  Engages a basic profanity filter.
*Note - Value must be sent as a string.
Values to use:
  • true
  • false
vision_positioning (string)  Engages a basic facial and text detector to attempt to keep captions from obscuring faces and Character Generator elements.
*Note - Value must be sent as a string.
Values to use:
  • true
  • false

Denotes an optional parameter.

Transcripts

The following table provides a quick definition for retrieving LEXI Live transcripts caption files through the REST API.
Resource Description
GET /live/v1/jobs/:job_id/assemble_data

Action

NOTE: This endpoint is deprecated, please use instances and the associated assemble_data endpoint.

Parameters (Path)
:job_id The specific job_id to retrieve the caption transcript for.
Parameters (Query)
file_type  The file type to retrieve.
Values:
  • vtt (default)
  • ttml
  • srt
  • scc
  • smi
  • ecf
  • stl
  • txt
starting_time_code  The starting timecode of the file (if supported by format).
Example:
  • 01:00:00:00 (default)
video_framerate  The video framerate of the timecode of the file (if supported by format).
Example:
  • 24
  • 25
  • 29.97 (default)
  • 30
  • 59.94
  • 23.976
  • 50
  • 60
caption_service  The caption service (if supported by format).
Example:
  • 1 (Default)
  • 2
  • 3
  • 4
  • 5
  • 6
POST /live/v2/instances/:instance_id/assemble_data

Action

Retrieves a caption transcript from a specific LEXI Live instance.

Parameters (Path)
:instance_id The specific job_id to retrieve the caption transcript for.
Parameters (JSON)
icapuser (string) The icapuser retrieved from the instance detail.
Example:
  • s1_caption_data (Default)
  • s2_caption_data
start_time (string) The Unix Epoch start time to retrieve captioning from.
*Note: this is an integer sent as a string value.
end_time (string) The Unix Epoch end time to retrieve captioning from.
*Note: this is an integer sent as a string value.
usertype (string) The user type to query from. For customer use, only "captioner" is permitted.
  • captioner
caption_service  The caption service (if supported by format). Archive data is only available for caption services 1 and 2. NOTE: This parameter is optional for LEXI but REQUIRED for Translate.
Example:
  • s1_caption_data (Default)
  • s2_caption_data
file_type  The file type to retrieve.
Values:
  • vtt (default)
  • ttml
  • srt
  • scc
  • smi
  • ecf
  • stl
  • txt
starting_time_code  The starting timecode of the file (if supported by format).
Example:
  • 01:00:00:00 (default)
video_framerate  The video framerate of the timecode of the file (if supported by format).
Example:
  • 24
  • 25
  • 29.97 (default)
  • 30
  • 59.94
  • 23.976
  • 50
  • 60
POST /live/v2/transcripts/job/:job_id

Action

Starts an asynchronous transcript task for a specific LEXI Live job. Returns a task ID that can be used to poll for status and retrieve the assembled captions when ready.

This is the simplest way to retrieve captions for a single job - the start and end times default to the job's creation and termination timestamps. If the job is still running, the end time is clamped to the current time.

See this guide for a quick introduction to using the transcript endpoints.

Parameters (Path)
:job_id The specific job_id to assemble the caption transcript for.
Parameters (JSON)
start_time (integer)  The Unix Epoch start time to retrieve captioning from. Defaults to the job's creation timestamp if not provided.
end_time (integer)  The Unix Epoch end time to retrieve captioning from. Defaults to the job's termination timestamp if not provided. If the job is still running, this is clamped to the current time.
file_type  The file type to retrieve. Illegal values are set to the default.
Values:
  • vtt (default)
  • ttml
  • srt
  • scc
  • smi
  • ecf
  • stl
  • txt
starting_time_code  The starting timecode of the file (if supported by format). Illegal values are set to the default.
Example:
  • 01:00:00:00 (default)
video_framerate  The video framerate of the timecode of the file (if supported by format). Illegal values are set to the default.
Example:
  • 24
  • 25
  • 29.97 (default)
  • 30
  • 59.94
  • 23.976
  • 50
  • 60
Returns

Returns a JSON object containing a task_id that can be used with the GET endpoint below to check status and retrieve the assembled captions.

POST /live/v2/transcripts/instance/:instance_id

Action

Starts an asynchronous transcript task for a LEXI Live instance. Returns a task ID that can be used to poll for status and retrieve the assembled captions when ready.

Use this endpoint when you need to retrieve captions across multiple jobs within an instance, or when you want to specify a custom time range. For single-job transcript retrieval, consider using the simpler job-based endpoint instead.

See this guide for a quick introduction to using the transcript endpoints.

Parameters (Path)
:instance_id The specific instance_id to assemble the caption transcript for.
Parameters (JSON)
start_time (integer) The Unix Epoch start time to retrieve captioning from.
end_time (integer) The Unix Epoch end time to retrieve captioning from.
caption_service (integer)  The caption service (if supported by format). Archive data is available for caption services 1 through 6. Illegal values are set to the default.
Example:
  • 1 (Default)
  • 2
  • 3
  • 4
  • 5
  • 6
file_type  The file type to retrieve. Illegal values are set to the default.
Values:
  • vtt (default)
  • ttml
  • srt
  • scc
  • smi
  • ecf
  • stl
  • txt
starting_time_code  The starting timecode of the file (if supported by format). Illegal values are set to the default.
Example:
  • 01:00:00:00 (default)
video_framerate  The video framerate of the timecode of the file (if supported by format). Illegal values are set to the default.
Example:
  • 24
  • 25
  • 29.97 (default)
  • 30
  • 59.94
  • 23.976
  • 50
  • 60
filename  The filename for the downloaded caption file.
Returns

Returns a JSON object containing a task_id that can be used with the GET endpoint below to check status and retrieve the assembled captions.

GET /live/v2/transcripts/:task_id

Action

Retrieves the status and result of an asynchronous transcript task. While the task is in progress, returns status information with HTTP 202. When complete, returns the assembled caption file directly with HTTP 200.

This endpoint works for both job-based and instance-based transcript requests.

Parameters (Path)
:task_id The task_id returned from the POST request to start assembly.
Parameters (Query) 
download Optional. Default is "true" when the parameter is omitted.
• "true": When the task is complete, the response body is the assembled caption file (streamed directly).
• "false": When the task is complete, the response is JSON with download_url (presigned S3 URL) and metadata.
Note: Using download=true (or omitting the parameter) avoids potential CORS issues with S3 presigned URLs in browser clients.
Response

HTTP 202: Task is still in progress. Response contains status information in JSON format including task_id, status ("pending" or "started"), and other metadata.

HTTP 200 (with download=true or default): Task is complete. Response body contains the assembled caption file content directly. The Content-Type header will be set appropriately for the file type.

HTTP 200 (with download=false): Task is complete. Response contains JSON with a download_url (presigned S3 URL) for the assembled caption file, along with other metadata including expires_in (seconds until URL expires). NOTE: The expiry value may change over time.

Denotes an optional parameter.

Custom Topic Models

The following provides for the creation and retrieval of custom topic models through the LEXI API.
NOTE: Legacy Topic Model endpoints are still supported with URL redirects to the new v3 endpoint.
You must use /v3 endpoints for Topic Models if your client does not follow URL redirects.
Example: POST /models should be changed to POST /models/v3
Resource Description
GET /base_models

Action

Retrieves a list of EEG Base Models available to use. These are the languages supported by LEXI.
In particular, the "base_model_name" property will be needed to construct custom models on top of these base models.

NOTE: No authentication is required for this endpoint.

GET /models/v3

Action

Retrieves list of LEXI your billing account's custom topic models.

GET /models/v3/:model_id

Action

Retrieves the specified :model_id (model).
This is a detailed view that includes all pronunciations and substitutions.

Parameters (Path)
:model_id The model_id of the model to retrieve.
POST /models/v3

Action

Creates a new custom topic model.

Parameters (JSON)
model_name (string) The visible name of the model to use in the LEXI Live custom models list.
base_model (string) The ID of the topic model to use as a base model, for example, "en-US_BroadbandModel".
Returns
The modelID to use with requests (note this is modelID, not 'model_id' for historical reasons.
DELETE /models/v3/:model_id

Action

Deletes a custom topic model.

Parameters (Path)
:model_id (string) The ID name of the model to be deleted.
GET /models/v3/:model_id/words

Action

Retrieves the learned word vocabulary of a custom topic model as CSV.

Parameters (Path)
:model_id (string) The ID of the model to be retrieved.

Denotes an optional parameter.

Topic Model Word Entries

Retrieving, creating, editing, and deleting custom topic model word entries
Resource Description
POST /models/v3/:model_id/words?overwrite=:overwrite

Action

Updates the word entries of a custom topic model.

Parameters (Path)
:model_id (string) The ID name of the model to be modified.
overwrite (boolean)  Whether or not to overwrite a custom topic model's words, or to append instead. Default: false.
Values to use:
  • true
  • false
Parameters (form-data)
words_file A direct file-obj of a CSV file containing word information.
words_file CSV File

Do not include a header row. The CSV format is:

Phrase to Display Pronunciation Suggestion(s)
Example
Fred Flintstone Fred Flint Stone, Fred Flind Stone, Fred Flin Stone
Wilma Flintstone Will Ma Flint Stone
PATCH /models/v3/:model_id/words

Action

Updates the word entries of a custom topic model.
Please send all patches at once.

Parameters (Path)
:model_id (string) The ID name of the model to be modified.
Parameters (JSON)
patchWords An array of patch dictionary entries to update the model.
Patch Object
Word (named) An array of Word entries to update the model.
word The word key. It is the intended word, case specific.
sounds_like An array of strings phonetic definitions.
Example

This JSON will add a pronunciation for Fred Flintstone that includes some common mispronunciations, update an existing pronunciation for Wilma Flintstone, and delete an existing pronunciation for Barney Rubble 

{
    "patchWords":{
        "Fred Flintstone":{
            "sounds_like":[
            "Fred Flint Stone",
            "Fred Flind Stone",
            "Fred Flin Stone"
            ],
            "word":"Fred Flintstone"
        },
        "Wilma Flintstone":{
            "sounds_like":[
            "Will Ma Flint Stone"
            ],
            "word":"Wilma Flintstone"
        },
        "Barney Rubble": null
    }
}

Denotes an optional parameter.

Topic Model Substitutions and Blacklist Entries

Retrieving, creating, editing, and deleting custom topic model substitution entries.
Resource Description
GET /models/v3/:model_id/substitutions

Action

Retrieves the substitutions of a custom topic model as JSON.

Parameters (Path)
:model_id (string) The ID of the model to be retrieved.
POST /models/v3/:model_id/substitutions?overwrite=:overwrite

Action

Set/append substitution/blacklist words entries for a custom topic model.

Parameters (Path)
:model_id (string) The ID name of the model to be modified.
overwrite (boolean)  Whether or not to overwrite a custom topic model's substitutions, or to append instead.
Values to use:
  • true
  • false
Parameters (form-data)
substitution_file A direct file-obj of a CSV file containing substitution information.
substitution_file CSV File

Do not include a header row. The CSV format is:

Phrase to remove from captions Phrase to use instead Case Sensitive (*optional)
Example

This JSON will add a substitution for "BadWord"

BadWord GoodWord True
BadWord2 GoodWord2 False
CensorWord ****
PATCH /models/v3/:model_id/substitutions

Action

Updates the substitution/blacklist words entries of a custom topic models.

Parameters (Path)
:model_id (string) The ID name of the model to be modified.
Parameters (JSON)
patchSubstitutions An array of patch dictionary entries to update the model.
Patch Object
Word (named) An array of Substitution entries to update the model.
word The word key. It should be the word to remove from captions.
substitution The substitution that should appear in the captions.
caseSensitive  Boolean to only replace when the word casing exactly matches.
Example

This JSON will add a substitution for "BadWord", and delete an existing substitution for "OldBadWord" 

{
    "patchSubstitutions":{
        "BadWord":{
            "word":"BadWord",
            "substitution":"GoodWord"
        },
        "OldBadWord":null
    }
}

Denotes an optional parameter.

Base URL for all endpoints on this page: https://eegcloud.tv/speech-recognition