Translate and dub the spoken audio of a video into another language with the Mux Robots API. Use dubbed audio to reach viewers in more languages.
Translate the spoken audio of a Mux asset into another language and automatically attach the result as a new audio track, so viewers can switch languages from the player's audio menu. Download matching captions for the dubbed audio as WebVTT, or attach them to the asset as a subtitle track. See the Translate Audio API referenceAPI for the full endpoint specification. See Mux Robots pricing for unit costs.
Check the shared workflow prerequisites before creating a job.
Audio translation requires an asset with an audio track. A translate-audio job is rejected if the asset has no audio. By default, it's also rejected if the asset already has an audio track in the target language, or with the same name as the new track. See Managing existing tracks.
translate-audio jobcurl https://api.mux.com/robots/v1/jobs/translate-audio \
-H "Content-Type: application/json" \
-X POST \
-d '{
"parameters": {
"asset_id": "YOUR_ASSET_ID",
"output_language_code": "es",
"replace_existing_tracks": "fail",
"captions": {
"upload_to_mux": true,
"replace_existing_tracks": "fail"
}
}
}' \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}This request is asynchronous. The POST returns immediately with the job in pending status and does not include results. We strongly recommend listening for the robots.v1.job.translate_audio.completed webhook: the payload contains the full completed job, so no follow-up API call is needed. If webhooks aren't an option, you can poll GET /robots/v1/jobs/translate-audio/{JOB_ID} with the id from the response until the status is completed.
The captions use the translated transcript that produces the dubbed voice, so they follow what the dubbed audio says. An existing source caption track isn't required. To translate an existing caption track separately, use translate captions.
Set captions.upload_to_mux to true to attach the captions as a subtitle track, as in the request above. It defaults to false. The audio and caption upload settings are independent: you can attach either track, both, or neither. The WebVTT download is available when caption retrieval succeeds, regardless of either upload setting.
Caption retrieval and attachment failures don't fail an otherwise successful dubbing job. If you requested caption upload and outputs.caption_track_id is absent, the subtitle track wasn't attached. outputs.temporary_vtt_url is still available when caption retrieval succeeded.
translate-audio supports the 86 languages listed in language support for Mux Robots. Pass a BCP 47 language tag such as es (Spanish) or yue (Cantonese). Known ISO 639-3 aliases are also accepted.
Dubbing uses the base language. Region and script subtags are retained on the Mux track, but do not select a regional dialect. For example, pt-BR produces Portuguese audio and a track tagged pt-br. An unsupported target language can cause a job to error after it has been queued.
| Parameter | Type | Description |
|---|---|---|
asset_id | string | Required. The Mux asset ID whose audio will be translated. |
output_language_code | string | Required. BCP 47 target language tag (e.g. es, fr, ja). See Supported languages. |
upload_to_mux | boolean | Whether to upload the dubbed audio and attach it as a new audio track on the asset. Defaults to true. Must be false for clips, audio-only assets, and VOD assets generated from live streams; the job returns downloadable audio without adding a track. Video-only assets cannot be translated because they have no audio, regardless of this setting. |
replace_existing_tracks | string | What to do when the asset already has a conflicting audio track: fail (the default), replace_all, or replace_generated (which behaves as fail for audio). See Managing existing tracks. |
track_name | string | Name for the dubbed audio track. Defaults to "{Language} (Auto-dubbed)", e.g. "Spanish (Auto-dubbed)". An existing track with this name is handled by replace_existing_tracks. |
captions | object | Optional subtitle attachment settings. Omitting this object disables caption upload. See Captions for dubbed audio. |
captions.upload_to_mux | boolean | Whether to attach the dub's translated WebVTT as a subtitle track. Defaults to false, independently of the audio upload_to_mux setting. |
captions.track_name | string | Name for the subtitle track. Defaults to "{Language} (dub)", e.g. "Spanish (dub)". Independent of the audio track_name. |
captions.replace_existing_tracks | string | Subtitle conflict policy: fail (the default), replace_all, or replace_generated. A caption conflict prevents subtitle attachment without failing the dub. See Caption tracks. |
The outputs object is included in the job once its status is completed. You'll receive it on the robots.v1.job.translate_audio.completed webhook (recommended), or you can fetch it with GET /robots/v1/jobs/translate-audio/{JOB_ID}. It contains:
| Field | Type | Description |
|---|---|---|
track_id | string | Mux audio track ID of the newly created dubbed track. Present when upload_to_mux is true. |
temporary_audio_url | string | Temporary pre-signed URL to download the dubbed audio in FLAC format (audio/flac). Expires 7 days after the job completes. |
replaced_track_ids | array of strings | IDs of audio tracks deleted before the dubbed audio track was created. Absent when nothing was deleted. See Managing existing tracks. |
temporary_vtt_url | string | Temporary download URL for the dub's translated WebVTT. Present when caption retrieval succeeds, regardless of upload settings. Expires after 7 days. |
caption_track_id | string | Mux subtitle track ID when caption upload succeeds. Omitted when upload wasn't requested or failed. The track may still be preparing after Mux accepts it. |
replaced_caption_track_ids | array of strings | IDs of subtitle tracks deleted during caption replacement, including when creating the replacement fails. Absent when nothing was deleted. |
Dubbed audio downloads use FLAC (audio/flac). Ensure you handle FLAC when processing temporary_audio_url.
This example uses a five-minute asset, consuming 350,000 units. It is the job delivered in the robots.v1.job.translate_audio.completed webhook's data field and returned by GET /robots/v1/jobs/translate-audio/{JOB_ID}:
{
"data": {
"id": "rjob_vwx234",
"workflow": "translate-audio",
"status": "completed",
"units_consumed": 350000,
"created_at": 1746403200,
"updated_at": 1746403260,
"parameters": {
"asset_id": "YOUR_ASSET_ID",
"output_language_code": "es",
"upload_to_mux": true,
"replace_existing_tracks": "fail",
"captions": {
"upload_to_mux": true,
"replace_existing_tracks": "fail"
}
},
"outputs": {
"track_id": "track_es_abc123",
"temporary_audio_url": "https://storage.googleapis.com/.../audio.flac",
"temporary_vtt_url": "https://storage.googleapis.com/.../subtitles.vtt",
"caption_track_id": "track_es_subtitles_abc123"
}
}
}When upload_to_mux is true (the default), the dubbed audio is attached to your asset as a new audio track. Viewers can select the new language from the player's audio menu. See add alternate audio tracks for more on multi-language audio.
Use replace_existing_tracks to control what happens when the asset already has an audio track in the target language (ignoring region, so es matches es-MX) or with the same name as the new track.
| Value | Behavior |
|---|---|
fail (default) | Nothing is deleted, and the new track isn't added. |
replace_all | Conflicting tracks are deleted, then the new track is added. |
Audio tracks are never auto-generated by Mux Video, so replace_generated behaves as fail.
outputs.replaced_track_ids.422. If a conflicting track is added while the job runs, the job errors instead. Neither case is billed.Use captions.replace_existing_tracks to manage subtitle tracks independently of audio tracks. Caption conflicts match the target language ignoring region, or the track name ignoring case.
| Value | Behavior |
|---|---|
fail (default) | Existing tracks are kept. A conflict skips subtitle attachment; the dubbed audio still completes. |
replace_all | Conflicting subtitle or same-name text tracks are deleted before the dubbed captions are added. |
replace_generated | Only conflicting tracks auto-generated by Mux Video are deleted. If an uploaded track conflicts, subtitle attachment is skipped. |
Tracks created by earlier Robots jobs count as uploaded, so replacing one requires replace_all. Either deleting policy requires captions.upload_to_mux: true. The root audio replacement policy doesn't authorize caption deletion.
Deleted subtitle track IDs appear in outputs.replaced_caption_track_ids, including when the replacement upload fails.