Skip to Content
Mux Docs: Home
Create a 'translate-captions' job
post

Creates a new job that translates captions on a Mux Video asset from one language to another.

Request body params
passthrough
string

Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.

parameters.asset_id
string

The Mux asset ID of the video whose captions will be translated.

parameters.track_id
string

The Mux text track ID of the source caption track to translate. The asset must have a ready text track matching this ID or the request will be rejected.

parameters.to_language_code
string

BCP 47 language code for the translated output (e.g. "es", "ja"). Unless replace_existing_tracks allows replacement, the asset must not already have a text track for this language.

parameters.track_name
string

Name for the translated Mux text track. Defaults to "{Language} (Auto-translated)", e.g. "Spanish (Auto-translated)". Mux requires text track names to be unique on an asset, and an existing track with this name is handled according to replace_existing_tracks.

parameters.upload_to_mux
boolean
(default: true)

Whether to upload the translated VTT and attach it as a text track on the Mux asset. Defaults to true.

parameters.never_translate
array

Best-effort list of terms (brand names, proper nouns) to preserve verbatim in the translated captions. Does not guarantee exact output. Terms must not contain '<' or '>', invisible characters, or characters altered by Unicode normalization.

parameters.replace_existing_tracks
string
Possible values: "fail""replace_all""replace_generated"

What to do when the asset already has a text track in the same language as, or with the same name as, the translated track. Defaults to fail, which rejects the request before any translation is billed. replace_all deletes every such track first. replace_generated deletes only Mux Video auto-generated tracks and rejects if an uploaded track is in the way. Any value other than fail requires upload_to_mux to be true. Existing tracks are matched by language ignoring region subtags, and by name ignoring case, in any status.

post
202
https://api.mux.com/robots/v0/jobs/translate-captions
Request
(application/json)
{
  "parameters": {
    "asset_id": "mux_asset_123abc",
    "track_id": "track_en_abc123",
    "to_language_code": "es",
    "upload_to_mux": true,
    "never_translate": [
      "Mux"
    ],
    "replace_existing_tracks": "fail"
  }
}
Response
(application/json)
{
  "data": {
    "id": "rjob_example123",
    "workflow": "translate-captions",
    "status": "pending",
    "units_consumed": 0,
    "created_at": 1700000000,
    "updated_at": 1700000060,
    "parameters": {
      "asset_id": "mux_asset_123abc",
      "track_id": "track_en_abc123",
      "to_language_code": "es",
      "upload_to_mux": true,
      "never_translate": [
        "Mux"
      ],
      "replace_existing_tracks": "fail"
    }
  }
}