Creating API Keys

To create an API key:

1. Sign in to your account and navigate to the Dashboard.
2. Click Create New, enter a name for your new API key, then click Create.

Your API key should be kept secure. It is generally a good practice to create a separate key for each project, so you can remove the key in case of leakage.

The API key is a unique identifier that authenticates your API requests. An API key must be supplied in the API request to use most of XL8's APIs. Please note that you need to be on the Advanced plan or Enterprise plan to create an API key.

Using API Keys

This API Key is used for Bearer Authentication. Simply pass your API key as a bearer token in Authorization header in your API request.

$ curl "https://api.xl8.ai/v1/user" --header "Authorization: Bearer <API_KEY>"

> {"status": 0, "email": "contact@xl8.ai", "first_name": "Contact", "last_name": "XL8", "date_joined": "2019-10-01 00:00:00.000000", "email_notification": true, "user_id": 1, "translated_words": 0, "translated_documents": 0}

Supported Languages

Before requesting a text/file translation, use the /v1/trans/languages API to get a list of supported language pairs. The result contains a dictionary mapping of source language codes to arrays of target language codes.

The API accepts two parameters:

• source_language: Specify this parameter to retrieve a list of target languages. By default, the API returns every source and target language pair.
• realtime_only: Set it to true to retrieve a list of language pairs that support real-time translation.

$ curl -X GET "https://api.xl8.ai/v1/trans/languages"

> {"status": 0, "languages": {"da": ["en", "fi", "no", "sv"], "en": ["ar", "cs", "da", "de", "el", "es", "es-419", "fi", "fr", "he", "hu", "id", "it", "ja", "ko", "ms", "my", "my-zawgyi", "nl", "no", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tr", "vi", "zh-Hans", "zh-Hant"], ...}}

$ curl -X GET "https://api.xl8.ai/v1/trans/languages?realtime_only=true"

> {"status": 0, "languages": {"ko": ["en", "ja", "zh-Hans"], "en": ["ar", "cs", "da", "de", "el", "es", "es-419", "fi", "fr", "he", "hu", "id", "it", "ja", "ko", "ms", "nl", "no", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tr", "vi", "zh-Hans", "zh-Hant"], ...}}

Options

Some language pairs provide additional options, such as genre and formality. Use this API to get the lists of supported option values for a given language pair. If the list is empty, it indicates that the language pair does not support the option.

$ curl -X GET "https://api.xl8.ai/v1/trans/languages/options/en/ko"

> {"status": 0, "formality": ["HAPSYO", "HAO", "HAEYO", "HAGAE", "HAE", "HAERA", "OTHER"], "genre": []}

Requesting Translations

Use this API to request a translation for a list of sentences. This API is asynchronous and returns a request_id, with which you can query your request's status and translation results. You can also pass a callback URL if you'd like to be notified when the translation status is updated. This API requires an API key.

$ curl -X POST 'https://api.xl8.ai/v1/trans/request' --header 'Content-Type: application/json' --header 'Authorization: Bearer <API_KEY>' --data-raw '{"source_language": "en", "target_language": "ko", "sentences": ["Accelerate your Translation with XL8.", "We believe that technology is key to building a better, more prosperous world and new efficient business models for all.", "Here is by far the most humane machine translation."]}'

> {"status": 0, "request_id": "4e2d83f8b9aabbccddeeff0123456789"}

Retrieving Translation Results

Use this API to retrieve the status and the translation results after requesting a translation. The result contains status, which will be one of the following values: -1 (initializing), 0 (processing), 1 (successful), 2 (error), or 3 (partial error). If successful, the result will contain the translated sentences in the sentences field.

$ curl -X GET 'https://api.xl8.ai/v1/trans/requests/4e2d83f8b9aabbccddeeff0123456789' --header 'Authorization: Bearer <API_KEY>'

> {"status": 1, "request_id": "4e2d83f8b9aabbccddeeff0123456789", "sentences": ["XL8로 번역을 가속하십시오", "우리는 기술이 더 발전하고 더 번영하는 세계와 모두를 위한 효율적인 새 비즈니스 모델을 만드는 데 핵심이라고 믿습니다", "이게 가장 인간적인 기계 번역입니다"], "download_url": "...", "source_language": "en", "target_language": "ko"}

Real-time Translations

The real-time translation API immediately returns the translated sentences in its result, instead of translating it asynchronously. Not every language pair supports real-time translation, so please refer to /v1/trans/languages?realtime_only=true API's result to see the supported language pairs. It can take up to 2000 characters per request.

$ curl -X POST 'https://api.xl8.ai/v1/trans/request/rt' --header 'Authorization: Bearer <API_KEY>' --header 'Content-Type: application/json' --data-raw '{"source_language": "en", "target_language": "ko", "sentences": ["The quick brown fox jumps over the lazy dog."], "options":{"formality":["HAEYO"]}}'

> {"status": 1, "sentences": ["날쌘 갈색 여우가 게으른 개를 뛰어넘네요"]}

Supported Languages

Before requesting a file translation, use the /v1/trans/languages API to get a list of supported language pairs.

Options

Some language pairs provide additional options, such as genre and formality.

Uploading Files

This API allows you to upload a file to translate before requesting a file translation. It will generate an S3 presigned URL, to which you can upload your file directly. Once the upload is complete, you can pass the resulted key to the file translation API below.

$ curl -X POST "https://api.xl8.ai/v1/file/upload" -H "Content-Type: application/json" -H "Authorization: Bearer <API_KEY>" --data '{"filename": "example.json"}'

> {"status": 0, "presigned_url": {"url": "https://s3.amazonaws.com/public.upload.xl8", "fields": {"key": "prod/your@email.com/2021-11-1/xshyn_example.json", "AWSAccessKeyId": "...", "policy": "...", "signature": "..."}}}

Then upload your file to the presigned URL:

$ curl -X POST "https://s3.amazonaws.com/public.upload.xl8" -F "key=prod/your@email.com/2021-11-1/xshyn_example.json" -F "AWSAccessKeyId=..." -F "policy=..." -F "signature=..." -F "file=@example.json"

Once the upload is complete, pass the generated key as the s3_key parameter to the file translation API.

File Translations

To translate a file, either pass the uploaded key as s3_key parameter, or encode your file to Base64 and include it as encoded_subtitle parameter. You also need to specify the subtitle_type parameter. We support various subtitle formats, such as srt, ttml, and vtt.

$ curl -X POST "https://api.xl8.ai/v1/trans/request/file" --header 'Authorization: Bearer <API_KEY>' --header 'Content-Type: application/json' --data-raw '{"source_language":"en", "target_language":"ko", "subtitle_type":"json", "s3_key":"your/email.com/2021-11-15/cgeyw_example.json", "options":{"formality":["HAEYO"]}}'

> {"status": 0, "request_id": "4e2d83f8b9aabbccddeeff0123456789"}

Retrieving Translated Files

Use this API to download the translated results in subtitle formats you want. It outputs a file in the specified subtitle format, encoded to Base64.

$ curl -X GET "https://api.xl8.ai/v1/trans/requests/file/4e2d83f8b9aabbccddeeff0123456789?subtitle_type=srt" --header "Authorization: Bearer <API_KEY>"

> {"status": 1, "encoded_subtitle": "..."}

Create New Glossary

The glossary feature allows you to specify translations for words and phrases. Prepare a glossary CSV file with three columns (without header): source text, target text, and case sensitivity ("cs" for case-sensitive, "ci" for case-insensitive).

$ curl -X POST "https://api.xl8.ai/v1/glossary" -H "Content-Type: application/json" -H "Authorization: Bearer <API_KEY>" --data '{"name": "en-kr-glossary", "source_language":"en", "target_language":"ko", "s3_path": "prod/your@email.com/2022-3-8/munvj_glossary.csv"}'

> {"status": 0, "glossary_id": 200}

List All Glossaries

Use this API to get the list of glossaries. You will get each glossary's name, source_language, target_language, download_url and glossary_id. Pass glossary_id to the file translation request to apply the given glossary.

$ curl -X GET "https://api.xl8.ai/v1/glossary" --header "Authorization: Bearer <API_KEY>"

> {"status": 0, "glossaries": [{"glossary_id": 200, "name": "en-kr-glossary", "source_language": "en", "target_language": "ko", "download_url": "..."}]}

Use Glossary

To use the glossary in the file translation request, pass the glossary_id parameter.

$ curl -X POST "https://api.xl8.ai/v1/trans/request/file" --header 'Authorization: Bearer <API_KEY>' --header 'Content-Type: application/json' --data-raw '{"glossary_id":"200", "source_language":"en", "target_language":"ko", "subtitle_type":"json", "encoded_subtitle": "..."}'

> {"status": 0, "request_id": "5k2d83f8b9aabb..."}

Supported Languages for Sync

This API retrieves the list of languages supported by Sync.

$ curl -X GET "https://api.xl8.ai/v1/autotemplate/languages" --header 'Authorization: Bearer <API_KEY>'

> {"status": 0, "languages": ["en-US", "ko-KR", "ar-SA", "de-DE", "es-ES", "fr-FR", "it-IT", "ja-JP", "nl-NL", "zh", "zh-TW"]}

Requesting Auto Subtitling

This API creates a request to generate a subtitle of a video via Sync. Before making a request, upload your video and transcript files to /v1/file/upload API. A transcript file is optional.

The API accepts following parameters:

• language: the language of the video to transcribe.
• media_s3_key: the key of the video file you have uploaded.
• transcript_s3_key: (optional) the key of the transcript file you have uploaded.

$ curl -X POST "https://api.xl8.ai/v1/autotemplate/request" --header 'Authorization: Bearer <API_KEY>' --header 'Content-Type: application/json' --data-raw '{"language":"en", "media_s3_key":"prod/your@email.com/2021-11-1/nimou_video.mp4"}'

> {"status": 0, "request_id": "e05aadf8b9aabbccddeeff0123456789"}

Retrieving Status

Use this API to retrieve the status of your auto-subtitling request. The result contains status: -1 (initializing), 0 (processing), 1 (successful), 2 (error), or 3 (partial error).

$ curl -X GET "https://api.xl8.ai/v1/autotemplate/requests/e05aadf8b9aabbccddeeff0123456789" --header "Authorization: Bearer <API_KEY>"

> {"status": 1, "request_id": "e05aadf8b9aabbccddeeff0123456789", "media_filename": "video.mp4", "media_duration": 36.37, "language": "en", "created_at": "2021-11-16T07:06:07.357368Z"}

Downloading Subtitles

Once your Sync request is complete, use this API to download the resulted subtitle. Supported file formats include srt, ttml, vtt, xif, json and more.

$ curl -X GET "https://api.xl8.ai/v1/autotemplate/request/file/srt/e05aadf8b9aabbccddeeff0123456789" --header "Authorization: Bearer <API_KEY>"

> {"status": 0, "encoded_subtitle": "MQ0KMDA6MDA6MDAsMDAwIC0tPiAwMDowMDow..."}

Supported Languages for Dubbing

This API retrieves the list of languages supported in the Dubbing task, and the available voices for each language. The output also contains a URL to sample MP3 audio for each voice.

$ curl -X GET "https://api.xl8.ai/v1/dubbing/languages" --header 'Authorization: Bearer <API_KEY>'

> {"status": 0, "voices": {"en-US": [{"voice_name": "en-US-F001", "display_name": "Female 1", "gender": "Female", "sample_url": "https://static.xl8.ai/voices/en-US/en-US-F001.mp3"}, {"voice_name": "en-US-M001", "display_name": "Male 1", "gender": "Male", "sample_url": "..."}]}}

Request Dubbing

This API creates a request to dub a video using the synchronized subtitle in the requested language. Upload your media and subtitle files first via /v1/file/upload.

The API accepts following parameters:

• language: the language code of your subtitle.
• voice_name: the voice name (e.g. "en-US-F001").
• subtitle_s3_key: the key of subtitle file you have uploaded.
• subtitle_type: the subtitle format (srt, ttml, vtt, etc.).
• media_s3_key: the key of media file you have uploaded.

By default, the synthesized audio will be overlayed on the original audio track. Adjust with original_audio_gain. Set dubbing_type to "dubbing" for synthesized voice only.

$ curl -X POST "https://api.xl8.ai/v1/dubbing/request" --header 'Authorization: Bearer <API_KEY>' --header 'Content-Type: application/json' --data-raw '{"language":"en-US", "voice_name":"en-US-F001", "subtitle_s3_key":"your@email.com/2022-05-18/cgeyw_video.en.srt", "subtitle_type":"srt", "media_s3_key":"your@email.com/2022-05-18/qozkz_video.mp4"}'

> {"status": 0, "request_id": "d720cd43569143b596ea0fce12345678"}

Retrieving Status

Use this API to retrieve the status of your dubbing request. Status values: -1 (initializing), 0 (processing), 1 (successful), 2 (error), or 3 (partial error).

$ curl -X GET "https://api.xl8.ai/v1/dubbing/requests/d720cd43569143b596ea0fce12345678" --header "Authorization: Bearer <API_KEY>"

> {"status": 1, "request_id": "d720cd43569143b596ea0fce12345678", "language": "en-US", "voice_name": "en-US-F001", "dubbing_type": "VoiceOver", "char_count": 183, "result_media_file_name": "cgeyw_video.en.VO.mp4"}

Downloading Results

Call this API to download the results from a successful dubbing request. The output contains links to download the generated audio and media files.

$ curl -X GET "https://api.xl8.ai/v1/dubbing/requests/d720cd43569143b596ea0fce12345678/download" --header "Authorization: Bearer <API_KEY>"

> {"status": 0, "request_id": "d720cd43569143b596ea0fce12345678", "audio_download_url": "https://...", "media_download_url": "https://..."}

Supported Languages for LiveSubs

This API retrieves the list of language pairs supported by Live Subs.

$ curl -X GET "https://api.xl8.ai/v1/e2e/languages" --header 'Authorization: Bearer <API_KEY>'

> {"status": 0, "languages": {"en": ["es-419", "ko"], "ko": ["en"]}}

Requesting Live Translation

This API creates a request to translate a live video stream. Live Subs takes HLS and RTMP sources as inputs, and returns a HLS stream URL with embedded WebVTT subtitles.

The API accepts following parameters:

• source_language: the language code of the source video stream.
• target_languages: a list of language codes in which to add subtitles.
• original_endpoint: the live stream URL (HLS master playlist or RTMP url).
• target_protocol: the protocol of the output stream, "hls" or "rtmp". Default is hls.
• target_endpoint: specify the publish URL of your RTMP server (only when target_protocol is rtmp).
• max_running_time_in_sec: the stream will shut down after specified time. Default is 5 hours.

$ curl -X POST "https://api.xl8.ai/v1/e2e/hlslive/request" --header 'Authorization: Bearer <API_KEY>' --header 'Content-Type: application/json' --data-raw '{"source_language":"en", "target_languages":["ko"], "original_endpoint": "https://foo.bar/live/master.m3u8"}'

> {"status": 0, "request_id": "099f43824a73453faf102e112345678"}

Retrieving Status

Use this API to retrieve the status of your LiveSubs request. Status values: -1 (initializing), 0 (running), 1 (stopped), 2 (error), or 3 (partial error).

$ curl -X GET "https://api.xl8.ai/v1/e2e/hlslive/requests/099f43824a73453faf102e112345678" --header "Authorization: Bearer <API_KEY>"

> {"status": 0, "request_id": "e05aadf8b9aabbccddeeff0123456789", "source_languages": ["en"], "target_languages": ["ko"], "original_endpoint": "https://foo.bar/live/master.m3u8", "target_protocol": "hls", "target_endpoint": "https://static.xl8.ai/hls/example/.../master.m3u8", "total_running_time_in_sec": 552, "max_running_time_in_sec": 18000}

Stopping Stream

Call this API to stop the request once your live event is over. The request will stop automatically if your stream is aborted or reaches the maximum running time.

$ curl -X POST "https://api.xl8.ai/v1/e2e/hlslive/requests/099f43824a73453faf102e112345678/shutdown" --header "Authorization: Bearer <API_KEY>"

> {"status": 0, "request_id": "099f43824a73453faf102e112345678"}