LEXI Translate API Documentation

Overview

  • Languages - Retrieve list of languages supported by LEXI Translate
  • Voices - Retrieve list of voices supported by LEXI Voice
  • Instances - Retrieving, creating, and deleting LEXI Translate Instances
  • Transcripts - Retrieving caption files and transcripts from LEXI Translate jobs
  • Models - Retrieving, creating, editing, and deleting Do Not Translate models
  • Glossary Models - Retrieving, creating, editing, and deleting Glossary models
  • Voice Models - Retrieving, creating, editing, and deleting Voice models

Denotes an optional parameter.

Languages

The following provides for the retrieval of the list of supported languages to translate to and from.
Resource Description
GET /live/v2/supported_target_languages

Action

Retrieves list of supported languages for Translate instance's translate_to and Translate Glossary model's target_lang.
Each language is represented by a language code and contains information about its compatibility with 608 captioning standards, display name, and its compatibility with LEXI Translate engines.

GET /live/v2/supported_source_languages

Action

Retrieves list of supported languages for Translate instance's translate_from and Translate Glossary model's source_lang.
Each language is represented by a language code and contains information about its compatibility with 608 captioning standards, display name, and its compatibility with LEXI Translate engines.

Voices

The following provides for the retrieval of the list of supported voices for LEXI Voice.
Resource Description
GET /live/v2/supported_voices

Action

Retrieves list of supported voices for Translate instance's tts_voice.
Each voice is represented by a code for Translate instance's tts_voice and contains information about its accent, gender, and compatible Translate 'translate_to' languages and LEXI Voice engines.

Instances

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

Action

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

get_history  If set to 1, or omitted, the response will include Translate job history for each instance. If set to 0, the response will omit Translate job history. Any other value will return a BAD REQUEST error.
POST /live/v2/instances/

Action

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

Parameters (JSON)
name (string) The LEXI Translate 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 Translate engine.
Currently the following choices are available: google-translate, deepl-translate, xl8-translate.
tts_engine (string)  The LEXI Voice engine.
Currently the following choices are available: google-tts, eleven-labs-tts.
tts_voice (string)  The voice to use with your LEXI Voice engine. For example, use:
  • aria
translate_from (string) The language to translate from. For English, use:
  • en
translate_to (string) The language to translate to. For example, for French:
  • fr
custom_model (string)  The Do Not Translate model defined in your EEG Cloud account to use.
glossary_model (string)  The Glossary model defined in your EEG Cloud account to use.
voice_model (string)  The Voice model defined in your EEG Cloud account to use.
translate_decode_608_service (string) The source caption service to use.
*Note - Must be different than the destination service.
Values to use:
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
cc_service (string) The destination caption service to use.
*Note - Must be different than the source service.
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
tone (string)  Adjust the tone of your translations to formal or informal for languages:
de (German), fr (French), it (Italian), ja (Japanese), es (Spanish), nl (Dutch), pl (Polish), pt (Portuguese Brazilian), and pt-pt (Portuguese European).
Values to use:
  • formal (default)
  • informal
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 Translate 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.

Denotes an optional parameter.

GET /live/v2/instances/:instance_id

Action

Retrieves the specified instance.

Parameters (Path)
:instance_id The instance_id to retrieve.
Parameters (Query)
get_history  If set to 1, or omitted, the response will include Translate job history for this instance. If set to 0, the response will omit Translate job history. No other values are supported.
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 Translate job history for this instance. If set to 0, the response will omit Translate 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 Translate job history for this instance. If set to 0, the response will omit Translate job history. No other values are supported.
DELETE /live/v2/instances/:instance_id

Action

Deletes the specified instance.
*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.
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 Translate job history for this instance. If set to 0, the response will omit Translate 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 Translate job history for this instance. If set to 0, the response will omit Translate job history. No other values are supported.

Denotes an optional parameter.

Transcripts / Caption Files

The following provides for retrieving LEXI Translate transcript caption files through the REST API.
Resource Description
POST /live/v2/instances/:instance_id/assemble_data

Action

Retrieves a caption transcript from a specific LEXI Translate instance.

Parameters (Path)
:instance_id The specific instance_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
  • 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 Translate 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 Translate 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.

Do Not Translate Models

The following provides for the creation and retrieval of Do Not Translate models through the LEXI Translate API.
Resource Description
GET /models

Action

Retrieves a JSON-serialized representation of all Do Not Translate models associated with the billing group.

POST /models

Action

Creates a new Do Not Translate model.

Parameters (JSON)
model_name The name of the model to create.
GET /models/:model_id

Action

Retrieves a JSON-serialized representation of a Do Not Translate model.

Parameters (Path)
:model_id (string) The ID name of the model to retrieve.
DELETE /models/:model_id

Action

Deletes a Do Not Translate model.
Cannot delete model if it is being used by one or more instances.

Parameters (Path)
:model_id (string) The ID name of the model to delete.
GET /models/:model_id/notranslate

Action

Retrieves the entries of a Do Not Translate model as a .csv or JSON.

Parameters (Path)
:model_id (string) The ID name of the model to retrieve.
Parameters (Query)
download  A boolean (true/false) indicating whether to download the model as a .csv. Defaults to false.
POST /models/:model_id/notranslate

Action

Updates the entries of a Do Not Translate model.

Parameters (Path)
:model_id (string) The ID name of the model to modify.
Parameters (Query)
overwrite  A boolean (true/false) indicating whether to overwrite the existing model. Defaults to false.
Parameters (form-data)
notranslate_file A .csv file of phrases to to update the model.
Patch .csv file Example

This .csv file will add a case-insensitive entry for "MyPhrase0" and a case-sensitive entry for "MyPhrase1": 

MyPhrase0,false
MyPhrase1,true
PATCH /models/:model_id/notranslate

Action

Updates the entries of a Do Not Translate model.

Parameters (Path)
:model_id (string) The ID name of the model to modify.
Parameters (JSON)
patchNoTranslates A dictionary of patch objects to update the model.
Patch Object
Phrase (named) An dictionary of entries to update the model.
phrase The phrase key. It should be the phrase value.
caseSensitive A boolean (true/false) indicating whether the detection of the phrase should be case sensitive.
Example

This JSON will add an entry for "MyPhrase", and delete an existing entry for "OldPhrase":

{
    "patchNoTranslates":{
        "MyPhrase":{
            "word": "MyPhrase",
            "caseSensitive": false
        },
        "OldPhrase": null
    }
}

Denotes an optional parameter.

Glossary Models

The following provides for the creation and retrieval of Glossary models through the LEXI Translate API.
Resource Description
GET /models/v2

Action

Retrieves a JSON-serialized representation of all Glossary models associated with the billing group.

POST /models/v2

Action

Creates a new Glossary model.

Parameters (JSON)
model_name The name of the model to create.
source_lang The source language for translation. This must match the source language for your desired Translate instance (translate_from).
target_lang The target language for translation. This must match the target language for your desired Translate instance (translate_to).
GET /models/v2/:model_id

Action

Retrieves a JSON-serialized representation of a Glossary model.

Parameters (Path)
:model_id (string) The ID name of the model to retrieve.
PUT /models/v2/:model_id

Action

Updates an existing Glossary model and replaces the existing settings.

Parameters (Path)
:model_id (string) The ID name of the model to modify.
Parameters (JSON)
model_name The name of the model to create.
source_lang The source language for translation. This must match the source language for your desired Translate instance (translate_from).
target_lang The target language for translation. This must match the target language for your desired Translate instance (translate_to).
DELETE /models/v2/:model_id

Action

Deletes a Glossary model.
Cannot delete model if it is being used by one or more instances.

Parameters (Path)
:model_id (string) The ID name of the model to delete.
GET /models/v2/:model_id/glossary

Action

Retrieves the entries of a Glossary model as a .csv or JSON.

Parameters (Path)
:model_id (string) The ID name of the model to retrieve.
Parameters (Query)
download  A boolean (true/false) indicating whether to download the model as a .csv. Defaults to false.
POST /models/v2/:model_id/glossary

Action

Updates the entries of a Glossary model.
Cannot update a glossary model if it is in use by an instance (the instance is ON).
Glossaries used with the Google Translate and XL8 Translate engine are case-sensitive and glossaries used with DeepL are case-insensitive.

Parameters (Path)
:model_id (string) The ID name of the model to modify.
Parameters (Query)
overwrite  A boolean (true/false) indicating whether to overwrite the existing model. Defaults to false.
Parameters (form-data)
glossary_file A .csv file of phrases to to update the model.
Patch .csv file Example

This .csv file will add an entry for "Brand Name" to not be translated and an entry for "house" to be translated to "maison": 

Brand Name,
house,maison
PATCH /models/v2/:model_id/glossary

Action

Updates the entries of a Glossary model.

Parameters (Path)
:model_id (string) The ID name of the model to modify.
Parameters (JSON)
glossary A list of patch objects to update the model.
Patch Object
source The source word/phrase that you want to translate from.
target The target word/phrase that you want to translate to. This can be left blank if you want do not want to translate the source word/phrase. This can also be set to null if you want to delete the word/phrase.
Example

This JSON will add an entry for "home", will add an entry for "Brand Name", and delete an existing entry for "parking": 

{
    "glossary": [
        {
            "source": "home",
            "target": "maison"
        },
        {
            "source": "Brand Name",
            "target": ""
        },
        {
            "source": "parking",
            "target": null
        }
    ]
}
GET /models/v2/:model_id/glossary/status

Action

Retrieves the global_status of the Glossary model and each individual status for each compatible engine.
Sometimes the glossary model is not available immediately at the time of creation and requires additional time for learning.
Glossary model status:
"READY": Ready to be used with Translate instance
"LOADING": Not ready to be used with Translate instance and requires additional time
"FAILED": Failed to create Glossary model for the compatible engine
"N/A": No Glossary model has been created or is incompatible with the engine

Parameters (Path)
:model_id (string) The ID name of the model to modify.
Example Response

The global_status is only deemed "READY" when all compatible engines are ready for translation: 

{
    "model_status": {
        "deepl_glossary_compatible": true,
        "deepl_glossary_status": "READY",
        "google_glossary_compatible": true,
        "google_glossary_status": "READY",
        "xl8_glossary_compatible": true,
        "xl8_glossary_status": "READY",
        "global_status": "READY",
        "modelID": "example-model-ID"
    }
}

Denotes an optional parameter.

Voice Models

The following provides for the creation and retrieval of Voice models through the LEXI Translate API.
Resource Description
GET /models/voice

Action

Retrieves a JSON-serialized representation of all Voice models associated with the billing group.

POST /models/voice

Action

Creates a new Voice model.

Parameters (JSON)
model_name The name of the model to create.
lang The language for pronunciation. This must match the target language for your desired Translate instance (translate_to).
GET /models/voice/:model_id

Action

Retrieves a JSON-serialized representation of a Voice model.

Parameters (Path)
:model_id (string) The ID name of the model to retrieve.
PUT /models/voice/:model_id

Action

Updates an existing Voice model and replaces the existing settings.

Parameters (Path)
:model_id (string) The ID name of the model to modify.
Parameters (JSON)
model_name The name of the model to create.
lang The language for pronunciation. This must match the target language for your desired Translate instance (translate_to).
DELETE /models/voice/:model_id

Action

Deletes a Voice model.
Cannot delete model if it is being used by one or more instances.

Parameters (Path)
:model_id (string) The ID name of the model to delete.
GET /models/voice/:model_id/pronunciations

Action

Retrieves the pronunciation entries of a Voice model as a .csv or JSON.

Parameters Path)
:model_id (string) The ID name of the model to retrieve.
Parameters (Query)
download  A boolean (true/false) indicating whether to download the model as a .csv. Defaults to false.
POST /models/voice/:model_id/pronunciations

Action

Updates the entries of a Voice model.
Cannot update a Voice model if it is in use by an instance (the instance is ON).
The Voice models are case-sensitive.

Parameters (Path)
:model_id (string) The ID name of the model to modify.
Parameters (Query)
overwrite  A boolean (true/false) indicating whether to overwrite the existing model. Defaults to false.
Parameters (form-data)
voicemodel_file A .csv file of pronunciations to update the model.
Patch .csv file Example

This .csv file will add a case-sensitive entry for "hyperbole" to be pronounced as "hy-PUR-buh-lee" and a case-insensitive entry for "Ai-Media" to be pronounced as "ay-eye mee-dee-uh": 

hyperbole,hy-PUR-buh-lee,True
Ai-Media,ay-eye mee-dee-uh,False
PATCH /models/voice/:model_id/pronunciations

Action

Updates the entries of a Voice model.

Parameters (Path)
:model_id (string) The ID name of the model to modify.
Parameters (JSON)
dictionary A list of patch objects to update the model.
Patch Object
word The word/phrase that you want to define a pronunciation for.
pronunciation The phonetic spelling of how you want that word/phrase to be pronounced. This cannot be left blank, you must specify a pronunciation. This can also be set to null if you want to delete the word/phrase.
case_sensitive  A boolean to only replace when the word casing exactly matches. Default: False.
Example

This JSON will add a case-sensitive entry for "hyperbole", will add a case-insensitive entry for "Ai-Media", and delete an existing entry for "parking": 

  {
    "dictionary": [
        {
            "word": "hyperbole",
            "pronunciation": "hy-PUR-buh-lee",
            "case_sensitive": True
        },
        {
            "word": "Ai-Media",
            "pronunciation": "ay-eye mee-dee-uh",
            "case_sensitive": False
        },
        {
            "word": "parking",
            "pronunciation": null
        }
    ]
}

Denotes an optional parameter.

Base URL for all endpoints on this page: https://eegcloud.tv/translation