EEG iCap Translate REST API Documentation

EEG iCap Translate REST API Documentation v2.0

Overview

The goal of this REST API is to provide an alternative way to manage your iCap Translate resources with EEG. The current API endpoint's root URI is:

https://eegcloud.tv/translation

When accessing the REST API, you will be prompted to authenticate your credentials using your administrator account via HTTP Basic Authentication.
Please note that the current service expects you to POST data in JSON format.

The current version offers the following resources:

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

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 iCap Translate engines.

Authentication:

Basic (username:password)

GET Parameters

None

Query Parameters

None
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 iCap Translate engines.

Authentication:

Basic (username:password)

GET Parameters

None

Query Parameters

None

Instances

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

Action

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

Authentication:

Basic (username:password)

GET Parameters

None

Query Parameters

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.

Authentication:

Basic (username:password)

POST Parameters (JSON)

name (string) The iCap 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 iCap Translate engine.
Currently the following choices are available: google-translate, deepl-translate.
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.
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
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). 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 iCap 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.

Authentication:

Basic (username:password)

GET Parameters

:instance_id The instance_id to retrieve.

Query Parameters

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.

PUT Parameters (JSON)

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

Query Parameters

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.

PATCH Parameters (JSON)

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

Query Parameters

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.

Authentication:

Basic (username:password)

DELETE Parameters

: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.

POST Parameters

:instance_id The instance_id to activate.

POST 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".

Query Parameters

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.

Authentication:

Basic (username:password)

POST Parameters

:instance_id The instance_id to terminate.

POST 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".

Query Parameters

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 iCap 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 iCap Translate instance.

Authentication:

Basic (username:password)

POST Parameters

:instance_id The specific instance_id to retrieve the caption transcript for.

POST 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

Denotes an optional parameter.

Do Not Translate Models

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

Action

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

Authentication:

Basic (username:password)

GET Parameters

None
POST /models

Action

Creates a new Do Not Translate model.

Authentication:

Basic (username:password)

POST 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.

Authentication:

Basic (username:password)

GET Parameters

: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.

Authentication:

Basic (username:password)

DELETE Parameters

: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.

Authentication:

Basic (username:password)

GET Parameters

:model_id (string) The ID name of the model to retrieve.

GET Parameters (JSON)

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.

Authentication:

Basic (username:password)

POST Parameters

:model_id (string) The ID name of the model to modify.

POST Parameters (JSON)

overwrite  A boolean (true/false) indicating whether to overwrite the existing model. Defaults to false.

POST Parameters (file)

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.

Authentication:

Basic (username:password)

PATCH Parameters

:model_id (string) The ID name of the model to modify.

PATCH 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 iCap Translate API.
Resource Description
GET /models/v2

Action

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

Authentication:

Basic (username:password)

GET Parameters

None
POST /models/v2

Action

Creates a new Glossary model.

Authentication:

Basic (username:password)

POST 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.

Authentication:

Basic (username:password)

GET Parameters

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

Action

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

Authentication:

Basic (username:password)

DELETE Parameters

: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.

Authentication:

Basic (username:password)

GET Parameters

:model_id (string) The ID name of the model to retrieve.

GET Parameters (JSON)

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 engine are case-sensitive and glossaries used with DeepL are case-insensitive.

Authentication:

Basic (username:password)

POST Parameters

:model_id (string) The ID name of the model to modify.

POST Parameters (JSON)

overwrite  A boolean (true/false) indicating whether to overwrite the existing model. Defaults to false.

POST Parameters (file)

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.

Authentication:

Basic (username:password)

PATCH Parameters

:model_id (string) The ID name of the model to modify.

PATCH 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

Authentication:

Basic (username:password)

GET Parameters

: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",
        "global_status": "READY",
        "google_glossary_compatible": true,
        "google_glossary_status": "READY",
        "modelID": "example-model-ID"
    }
}

Denotes an optional parameter.

Copyright © 2013-2024 EEG Enterprises, Inc. All Rights Reserved.