Order Subs (machine translation)
To order subtitles, you'll determine the language IDs of the source and target language(s) for your sub and call the Create Subs endpoint.
Determine language IDs
You can get a full listing of languages by hitting the List all Languages endpoint.
Order Subtitles
Now, order subtitles by hitting the Create Subs endpoint, supplying your media, the source_language
, target_languages
and any other configuration options.
The object that is returned is a standard Sub object (same that is returned from the View Sub).
Getting Subtitles Status
To get the current status of your sub, call the View Sub endpoint and inspect the status
field. When your sub is complete, the status field will be complete
.
{
"id": 123,
"media_file_id": 456,
"external_media_id": "marketing-video-001",
"folder_name": "q1-campaign",
"type": "sub",
"source_language": "en",
"target_language": "es",
"state": "completed",
"asset_url": "https://api.3playmedia.com/v3/subs/123"
}
For Production applications, polling endpoints for status is an anti-pattern, so you'll want to specify a callback_url
in the Create Subs endpoint. Whenever the sub's status changes, we'll ping the callback URL with the following payload:
Downloading your Subtitles
Once your sub is complete (status
= complete
), you can download your subtitles (SRT, VTT, etc... by hitting the View Sub endpoint and inspecting the downloads
key. The response will include a downloads
array with different asset types you can choose from.
GET /subs/123?folder_name=q1-campaign
Response:
{
"data": {
"id": 123,
"status": "completed",
"downloads": [
{
"type": "srt",
"mime_type": "application/x-subrip",
"url": "https://s3.amazonaws.com/bucket/subtitles.srt?signature=...",
"expires_at": "2024-01-01T12:00:00Z"
},
{
"type": "vtt",
"mime_type": "text/vtt",
"url": "https://s3.amazonaws.com/bucket/subtitles.vtt?signature=...",
"expires_at": "2024-01-01T12:00:00Z"
}
]
}
}
Key Implementation Notes
• Duplicate Prevention: Re-posting the same external_media_id
with additional languages will only process new language pairs
• Asset Expiration: S3 signed URLs expire. Re-hit the GET endpoint to refresh download links
• Multi-language Processing: Each target language is processed independently and triggers separate callback notifications
• File Organization: Use folder_name
to organize subs into logical groups
• Media File Reuse: If you've already uploaded a file, use media_file_id
instead of source_url
to avoid re-uploading
Language Support
We'll consistently be adding languages to Subtitles. As of April 2025, the list is is below. If you're interested in another language, please reach out.
ar
- Arabicbe
- Belarusianbg
- Bulgariancs
- Czechda
- Danishde
- Germanel
- Greeken-US
- English (US)en-GB
- English (UK)es-ES
- Spanish (Spain)es-419
- Spanish (Latin America)et
- Estonianfa
- Persianfi
- Finnishfr-CA
- French (Canada)fr-FR
- French (France)he
- Hebrewhi
- Hindihr
- Croatianhu
- Hungarianid
- Indonesianit
- Italianja
- Japaneseko
- Koreanlt
- Lithuanianlv
- Latvianms
- Malaynl
- Dutchno
- Norwegianpl
- Polishpt-BR
- Portuguese (Brazil)pt-PT
- Portuguese (Portugal)ro
- Romanianru
- Russiansk
- Slovaksl
- Sloveniansv
- Swedishta
- Tamilth
- Thaitr
- Turkishuk
- Ukrainianvi
- Vietnamesezh-CN
- Chinese (Simplified)zh-TW
- Chinese (Traditional)
A complete list of supported languages will be available at a dedicated API endpoint in the future.
Error Handling
Common failure scenarios:
- Invalid source_url: Ensure URL is publicly accessible with at least 1 day expiry
- Unsupported language: Verify language codes are supported
- Missing required fields:
name
,source_language
,target_languages
,external_media_id
, andcallback_url
are required - Media processing errors: Check callback notifications for
state: "failed"
with error details
Updated 5 days ago