1. Introduction #
The plain X API enables the creation of transcription, translation, subtitling and voiceover jobs and the corresponding export of the final results. These actions can be performed in a step-by-step fashion through the Tasks and Exports routes or they can be performed in a synchronous unified call through the Workflows route.
Unless there’s a reason to do so, it’s recommended to use the Workflows routes.
There’s an interactive Swagger documentation here: https://app.plainx.com/automations/swagger/index.html
#
2. Synchronous Operation – Workflows (Recommended) #
The Workflows route allows performing a processing task in an end-to-end synchronous fashion and get the result immediately as the result of the HTTP call.
Note: Some of the fields in the workflow configuration are optional and not specified in the examples below (e.g., itemTitle, fileName, etc) – Please consult the Swagger documentation to see the complete API models.
2.1 Transcription Workflow Example #
- Description: Upload an mp4 video, request a transcription and download the resulting text file.
curl --max-time 14400 --request POST \
--url https://app.plainx.com/automations/api/v1.0/workflows \
--header 'Authorization: Bearer ' \
--header 'Content-Type: multipart/form-data' \
--form 'workflowConfiguration={"Upload": {"SourceLanguage":"en", "RepositoryId": ""},"Tasks": {"WorkspaceUserIds":[" | "], "Transcription": {"ServiceProvider": "Azure", "ServiceVariant": "US", "SourceLanguage":"en"}}, "Export": {"TaskType": "Transcription", "ResourceType": "Txt"}}' \
--form 'file=@' > out.txt
2.2 Translation Workflow Example #
- Description: Upload an mp4 video, request a transcription and a translation and download the resulting text file.
curl --max-time 14400 --request POST \
--url https://app.plainx.com/automations/api/v1.0/workflows \
--header 'Authorization: Bearer ' \
--header 'Content-Type: multipart/form-data' \
--form 'workflowConfiguration={"Upload": {"SourceLanguage":"en", "RepositoryId": ""},"Tasks": {"WorkspaceUserIds":[" | "], "Translation": {"ServiceProvider": "Azure", "SourceLanguage": "en", "TargetLanguage": "pt-PT", "ServiceVariant": "Default"}}, "Export": {"TaskType": "Translation", "ResourceType": "Txt"}}' \
--form 'file=@' > out.txt
2.3 Translation Workflow with Text Input Example #
- Description: Upload an text, request a translation and download the resulting text file.
curl --max-time 14400 --request POST \
--url https://app.plainx.com/automations/api/v1.0/workflows \
--header 'Authorization: Bearer ' \
--header 'Content-Type: multipart/form-data' \
--form 'workflowConfiguration={"Upload": {"SourceLanguage":"en", "RepositoryId": ""},"Tasks": {"WorkspaceUserIds":[" | "], "Translation": {"ServiceProvider": "Azure", "SourceLanguage": "en", "TargetLanguage": "pt-PT", "ServiceVariant": "Default"}}, "Export": {"TaskType": "Translation", "ResourceType": "Txt"}}' \
--form 'text=This is an example text.' > out.txt
2.4 Subtitling SRT Export Workflow Example #
- Description: Upload an mp4 video, request a transcription, a translation and a subtitling, download the resulting srt file.
curl --max-time 14400 --request POST \
--url https://app.plainx.com/automations/api/v1.0/workflows \
--header 'Authorization: Bearer ' \
--header 'Content-Type: multipart/form-data' \
--form 'workflowConfiguration={"Upload": {"SourceLanguage":"en", "RepositoryId": ""},"Tasks": {"WorkspaceUserIds": [" | "], "Subtitling": { "TargetLanguage": "pt-PT"}}, "Export": {"TaskType": "Subtitling", "ResourceType": "Srt"}}' \
--form 'file=@' > out.srt
2.5 Subtitling Video Export Workflow Example #
- Description: Upload an mp4 video, request a transcription and a subtitling, download the mp4 file with the video with subtitles.
curl --max-time 14400 --request POST \
--url https://app.plainx.com/automations/api/v1.0/workflows \
--header 'Authorization: Bearer ' \
--header 'Content-Type: multipart/form-data' \
--form 'workflowConfiguration={"Upload": {"SourceLanguage":"en", "RepositoryId": ""},"Tasks": {"WorkspaceUserIds": [" | "],"Subtitling": { "TargetLanguage": "en"}}, "Export": {"TaskType": "Subtitling", "ResourceType": "VideoBurned"}}' \
--form 'file=@' > out.mp4
2.6 Voiceover Audio Export Workflow Example #
- Description: Upload an mp4 video, request a transcription and a voiceover, download the wav file with the voiceover audio.
curl --max-time 14400 --request POST \
--url https://app.plainx.com/automations/api/v1.0/workflows \
--header 'Authorization: Bearer ' \
--header 'Content-Type: multipart/form-data' \
--form 'workflowConfiguration={"Upload": {"SourceLanguage":"en", "RepositoryId": ""},"Tasks": {"WorkspaceUserIds":[" | "], "Voiceover": {"SourceLanguage": "en", "Voice": "Sara", "ServiceVariant": "US","ServiceProvider": "Azure","Gender": "Female"}}, "Export": {"TaskType": "Voiceover", "ResourceType": "TranscriptVoiceoverAudio"}}' \
--form 'file=@' > out.wav
2.7 Voiceover Video Export Workflow Example #
- Description: Upload an mp4 video, request a transcription and a voiceover, download the mp4 file with the voiceover video.
curl --max-time 14400 --request POST \
--url https://app.plainx.com/automations/api/v1.0/workflows \
--header 'Authorization: Bearer ' \
--header 'Content-Type: multipart/form-data' \
--form 'workflowConfiguration={"Upload": {"SourceLanguage":"en", "RepositoryId": ""},"Tasks": {"WorkspaceUserIds": [" | "],"Voiceover": {"SourceLanguage": "en", "Voice": "Sara", "ServiceVariant": "US","ServiceProvider": "Azure","Gender": "Female"}}, "Export": {"TaskType": "Voiceover", "ResourceType": "VoiceOverVideo", "AudioMix": {"VideoAudioVolume": 0.2, "VoiceOverAudioVolume": 0.8}}}' \
--form 'file=@' > out.mp4
2.8 Subtitling SRT Export Workflow Example (Different Input Channel) #
- Description: Upload an mp4 video, request a transcription, a translation and a subtitling, download the resulting srt file.
- Use the audio channels 1 and 2 (starts at 0 – so second and third channels) and merge them.
curl --max-time 14400 --request POST \
--url https://app.plainx.com/automations/api/v1.0/workflows \
--header 'Authorization: Bearer ' \
--header 'Content-Type: multipart/form-data' \
--form 'workflowConfiguration={"Upload": {"InputAudioStreams":[1, 2], "SourceLanguage":"en", "RepositoryId": ""},"Tasks": {"WorkspaceUserIds": [" | "], "Subtitling": { "TargetLanguage": "pt-PT"}}, "Export": {"TaskType": "Subtitling", "ResourceType": "Srt"}}' \
--form 'file=@' > out.srt
2.9 Javascript Examples #
2.9.1 Translation and Txt Export Example #
- Description: Upload an mp4 video, audio or text file, request a translation and download the text file.
- Javascript Script: ⚙️ AutomationsApiTextTranslateWorkflow.js
2.9.2 Video Subtitling and SRT Export Example #
- Description: Upload an mp4 video, request a subtitling and download the SRT file.
- Javascript Script: ⚙️ AutomationsApiSubtitleWorkflow.js
3. Step-by-Step Asynchronous Operation – Tasks and Exports #
The Tasks routes allow querying for available services, upload media items, create plain X tasks and check the results of queued tasks. The Exports routes allow creating an export task, check the status and finally get a URL to fetch the exported resource. These routes offer more fine grained control over the process than the Workflows routes – For example, through Tasks you can add tasks to existing media items instead of creating a new media item for each tasks.
Note: Since these routes are more intricate to use, the examples are provided in python.
3.1 Python Examples #
3.1.1 Transcription Task and Export Example #
- Description: Upload an mp4 video, request a transcription and download the text file in the format of segmented blocks with timecodes.
- Python Script: ⚙️ transcription.py
3.1.2 Translation Task and Export Example #
- Description: Upload an mp4 video, request a transcription and a translation, download the text file in the format of segmented blocks with timecodes.
- Python Script: ⚙️ translation.py
3.1.3 Voiceover Task and Export Example #
- Description: Upload an mp4 video, request a transcription, a translation and a voiceover, download the wav file with the voiceover audio.
- Python Script: ⚙️ voiceover.py
3.2 Javascript Examples #
3.1.1 Text Translation and Txt Export Example #
- Description: Upload a text file, request a translation and download the text file.
- Javascript Script: ⚙️ AutomationsApiTextTranslate.js
3.1.2 Video Subtitling and SRT Export Example #
- Description: Upload an mp4 video, request a subtitling and download the SRT file.
- Javascript Script: ⚙️ AutomationsApiSubtitle.js
3.4 Other tasks. #
Note: Many other task and export format combinations are possible. In doubt, reach out to support.
4. Additional Features #
4.1 Language Detection #
To use the language detection feature, the field “SourceLanguage” of the “Upload” configuration must have the value “Detect Language”. Additionally, if any of the fields in the associated tasks is meant to use the detected language, the field corresponding to the language should have the value “Detect Language”.
Example:
In this case the transcription will be done in the detected language. The Subtitling task will be done in the detected language if the detected language is “pt-pt”, otherwise plain X will automatically do a translation from the detected language to “pt-pt” and then do a subtitling in “pt-pt”.
{
"Upload": {
"SourceLanguage": "Detect Language",
"RepositoryId": ""
},
"Tasks": {
"WorkspaceUserIds": [
" | "
],
"Transcription": {
"ServiceProvider": "Azure",
"SourceLanguage": "Detect Language"
},
"Subtitling": {
"TargetLanguage": "pt-PT"
}
},
"Export": {
"TaskType": "Subtitling",
"ResourceType": "Srt"
}
}
