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_urlin 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 - Arabic
  • be - Belarusian
  • bg - Bulgarian
  • cs - Czech
  • da - Danish
  • de - German
  • el - Greek
  • en-US - English (US)
  • en-GB - English (UK)
  • es-ES - Spanish (Spain)
  • es-419 - Spanish (Latin America)
  • et - Estonian
  • fa - Persian
  • fi - Finnish
  • fr-CA - French (Canada)
  • fr-FR - French (France)
  • he - Hebrew
  • hi - Hindi
  • hr - Croatian
  • hu - Hungarian
  • id - Indonesian
  • it - Italian
  • ja - Japanese
  • ko - Korean
  • lt - Lithuanian
  • lv - Latvian
  • ms - Malay
  • nl - Dutch
  • no - Norwegian
  • pl - Polish
  • pt-BR - Portuguese (Brazil)
  • pt-PT - Portuguese (Portugal)
  • ro - Romanian
  • ru - Russian
  • sk - Slovak
  • sl - Slovenian
  • sv - Swedish
  • ta - Tamil
  • th - Thai
  • tr - Turkish
  • uk - Ukrainian
  • vi - Vietnamese
  • zh-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, and callback_url are required
  • Media processing errors: Check callback notifications for state: "failed" with error details