On this page

Translate audio

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. Where translate captions produces a text track in another language, translate-audio produces a dubbed audio track. See the Translate Audio API referenceAPI for the full endpoint specification. See Mux Robots pricing for unit costs.

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.

Create a `translate-audio` job

curl https://api.mux.com/robots/v0/jobs/translate-audio \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "to_language_code": "es"
    }
  }' \
  -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.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/v0/jobs/translate-audio/{JOB_ID} with the id from the response until the status is completed.

Parameters

Parameter	Type	Description
`asset_id`	string	Required. The Mux asset ID whose audio will be translated.
`to_language_code`	string	Required. BCP 47 target language code (e.g. `es`, `fr`, `ja`). See language support for Mux Robots.
`upload_to_mux`	boolean	Whether to upload the dubbed audio and attach it as a new audio track on the asset. Defaults to `true`.
`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.

Output

The outputs object is included in the job once its status is completed. You'll receive it on the robots.job.translate_audio.completed webhook (recommended), or you can fetch it with GET /robots/v0/jobs/translate-audio/{JOB_ID}. It contains:

Field	Type	Description
`uploaded_track_id`	string	Mux audio track ID of the uploaded dubbed track. Present when `upload_to_mux` is `true`.
`temporary_audio_url`	string	Temporary pre-signed URL to download the dubbed audio file. Expires 7 days after the job completes.
`replaced_tracks`	array of objects	Every track deleted before the new track was created. Absent when nothing was deleted. See Managing existing tracks.

Example response

This is the payload delivered to the robots.job.translate_audio.completed webhook, and the same shape you get from GET /robots/v0/jobs/translate-audio/{JOB_ID}:

{
  "data": {
    "id": "rjob_vwx234",
    "workflow": "translate-audio",
    "status": "completed",
    "units_consumed": 4500,
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "to_language_code": "es",
      "upload_to_mux": true
    },
    "outputs": {
      "uploaded_track_id": "track_es_abc123",
      "temporary_audio_url": "https://storage.googleapis.com/..."
    }
  }
}

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.

Managing existing tracks

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.

The asset's original audio track is never deleted. If it conflicts, the new track isn't added.
Deleted tracks are listed in outputs.replaced_tracks.
A conflict is usually caught when you create the job, which returns a 422. If a conflicting track is added while the job runs, the job errors instead. Neither case is billed.

On this page

Translate audio

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.

Create a `translate-audio` job

curl https://api.mux.com/robots/v0/jobs/translate-audio \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "to_language_code": "es"
    }
  }' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

Parameters

Parameter	Type	Description
`asset_id`	string	Required. The Mux asset ID whose audio will be translated.
`to_language_code`	string	Required. BCP 47 target language code (e.g. `es`, `fr`, `ja`). See language support for Mux Robots.
`upload_to_mux`	boolean	Whether to upload the dubbed audio and attach it as a new audio track on the asset. Defaults to `true`.
`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.

Output

Field	Type	Description
`uploaded_track_id`	string	Mux audio track ID of the uploaded dubbed track. Present when `upload_to_mux` is `true`.
`temporary_audio_url`	string	Temporary pre-signed URL to download the dubbed audio file. Expires 7 days after the job completes.
`replaced_tracks`	array of objects	Every track deleted before the new track was created. Absent when nothing was deleted. See Managing existing tracks.

Example response

This is the payload delivered to the robots.job.translate_audio.completed webhook, and the same shape you get from GET /robots/v0/jobs/translate-audio/{JOB_ID}:

{
  "data": {
    "id": "rjob_vwx234",
    "workflow": "translate-audio",
    "status": "completed",
    "units_consumed": 4500,
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "to_language_code": "es",
      "upload_to_mux": true
    },
    "outputs": {
      "uploaded_track_id": "track_es_abc123",
      "temporary_audio_url": "https://storage.googleapis.com/..."
    }
  }
}

Managing existing tracks

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.

The asset's original audio track is never deleted. If it conflicts, the new track isn't added.
Deleted tracks are listed in outputs.replaced_tracks.
A conflict is usually caught when you create the job, which returns a 422. If a conflicting track is added while the job runs, the job errors instead. Neither case is billed.