---
title: "Create a 'translate-captions' job"
method: POST
path: "/robots/v1/jobs/translate-captions"
tags: ["Translate Captions"]
---

# Create a 'translate-captions' job

`POST /robots/v1/jobs/translate-captions`

## Request

- Base URL: `https://api.mux.com`
- URL: `https://api.mux.com/robots/v1/jobs/translate-captions`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

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

## Request body

- CreateTranslateCaptionsJobRequest
  - `passthrough` string: Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
  - `parameters` TranslateCaptionsJobParameters, required
    - `asset_id` string, required: The Mux asset ID of the video whose captions will be translated.
    - `track_id` string, required: Mux text track ID of the source captions. Must identify a ready subtitle track, or the single ready legacy text transcript without subtitle metadata on an audio-only asset. A missing or unready source is rejected.
    - `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`.
    - `upload_to_mux` boolean: Whether to upload the translated VTT and attach it as a text track on the Mux asset. Defaults to true.
    - `never_translate` string[]: 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.
    - `replace_existing_tracks` '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.
    - `output_language_code` string, required: 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.

## Response `202`

Job queued

- TranslateCaptionsJobResponse
  - `data` TranslateCaptionsJob, required
    - `id` string, required: Unique job identifier.
    - `passthrough` string: Arbitrary string supplied at creation, returned as-is.
    - `units_consumed` integer, required: Number of Mux AI units consumed by this job.
    - `directive` JobDirectiveContext: The directive run that dispatched this job. Absent for jobs created via direct API POST.
      - `id` string, required: ID of the directive that dispatched this job.
      - `run_id` string, required: ID of the specific directive run that dispatched this job.
    - `created_at` integer, required: Unix timestamp (seconds) when the job was created.
    - `updated_at` integer, required: Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state).
    - `workflow` 'translate-captions', required
    - `parameters` TranslateCaptionsJobParameters, required
      - `asset_id` string, required: The Mux asset ID of the video whose captions will be translated.
      - `track_id` string, required: Mux text track ID of the source captions. Must identify a ready subtitle track, or the single ready legacy text transcript without subtitle metadata on an audio-only asset. A missing or unready source is rejected.
      - `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`.
      - `upload_to_mux` boolean: Whether to upload the translated VTT and attach it as a text track on the Mux asset. Defaults to true.
      - `never_translate` string[]: 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.
      - `replace_existing_tracks` '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.
      - `output_language_code` string, required: 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.
    - `status` 'pending' | 'processing' | 'completed' | 'errored' | 'cancelled', required: Current job status.
    - `errors` JobError[]: Error details. Present when status is 'errored'.
      - `type` string, required: Stable public error category identifier.
      - `message` string, required: Human-readable public error message.
      - `retryable` boolean: Whether retrying this job may resolve the error.
    - `resources` Resources: Related Mux resources linked to this job.
      - `assets` SlimlineAsset[], required: Mux assets associated with this job.
        - `id` string, required: Mux asset ID.
        - `meta` object: Mux asset metadata, if available.
          - `title` string: Asset title from Mux metadata.
          - `creator_id` string: Creator identifier from Mux metadata.
          - `external_id` string: External identifier from Mux metadata.
        - `passthrough` string: Passthrough string from the Mux asset.
        - `_links` object, required: Hypermedia links for the asset.
          - `self` object, required
            - `href` string, required: URL to the Mux asset resource.
    - `outputs` object: Workflow results. Present when status is 'completed'.
      - `temporary_vtt_url` string: Temporary pre-signed URL to download the translated VTT file, including when upload_to_mux is false. Expires 7 days after the job completes.
      - `never_translate_terms_preserved` boolean: Present when never_translate terms were supplied. False when at least one term was not preserved verbatim in the translated captions. Preservation is best-effort: verified, not guaranteed.
      - `track_id` string: Mux text track ID of the newly created translated captions, distinct from the source parameters.track_id. Present when upload_to_mux is true.
      - `replaced_track_ids` string[]: IDs of tracks deleted during replacement. Omitted when no deletions were recorded; historical jobs may lack this information.

## Other responses

- `400`: Malformed JSON request body.
- `401`: Missing or invalid Mux credentials
- `403`: The access token lacks robots:write (insufficient_scope), or Robots access is inactive or suspended. A free-plan workflow or unit limit can also prevent creation. For insufficient_scope, use credentials with the required permission. If using an API access token, create a replacement token with that permission. Enabling Robots for an organization does not grant token permissions.
- `409`: Resource conflict. See the error type and messages for details.
- `422`: Asset not found or errored, missing public or signed playback access, missing or ineligible caption source, invalid translation parameters, or an existing track blocked by replace_existing_tracks.
- `500`: Server error

## Changes

- **2026-10-23** `ed6cb570d60c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/muxinc/apis/mux-api/changes/robots/v1/jobs/translate-captions/post.md)

---

[API](https://skmtc.dev/muxinc/apis/mux-api.md) - [All operations](https://skmtc.dev/muxinc/apis/mux-api/llms.txt) - [OpenAPI document](https://skmtc.dev/muxinc/apis/mux-api/revisions/75b4251a1d96?raw)