---
title: "Create an 'edit-captions' job"
method: POST
path: "/robots/v0/jobs/edit-captions"
tags: ["Edit Captions (v0)"]
deprecated: true
---

# Create an 'edit-captions' job

`POST /robots/v0/jobs/edit-captions`

## Request

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

> **Deprecated.**

Deprecated: use `POST /robots/v1/jobs/edit-captions` instead. Creates a new job that edits an existing Mux text track using static replacements, speaker-label replacements, and optional profanity censoring. Provide at least one of `replacements`, `speaker_replacements`, or `auto_censor_profanity`.

## Request body

- CreateEditCaptionsJobRequestV0
  - `passthrough` string: Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
  - `parameters` EditCaptionsJobParametersV0, required
    - `asset_id` string, required: The Mux asset ID whose existing text track should be edited.
    - `track_id` string, required: The existing ready Mux text track ID to edit and optionally replace.
    - `auto_censor_profanity` object: Optional LLM-driven profanity detection and censorship rules applied to the selected caption track.
      - `detection_method` 'llm': How profanity is detected. Currently only `llm` is supported, which uses an LLM to identify profanity in cue text.
      - `mode` 'blank' | 'remove' | 'mask': Replacement strategy for detected profanity: blank inserts bracketed underscores, remove drops the match, and mask replaces characters with question marks. Defaults to "blank".
      - `always_censor` string[]: Additional words or short phrases that should always be censored even if the model does not detect them.
      - `never_censor` string[]: Words or short phrases that should never be censored even if the model flags them.
    - `replacements` object[]: Optional static word or phrase replacements applied directly to cue text.
      - `find` string, required: Exact word or phrase to replace in cue text.
      - `replace` string, required: Replacement text to insert when a match is found.
      - `case_sensitive` boolean: When true, `find` is matched only with exact case. Defaults to false (case-insensitive matching), so "gonna" also matches "Gonna" and "GONNA".
    - `speaker_replacements` EditCaptionsSpeakerReplacementV0[]: Optional replacements for bracketed speaker labels at the start of caption cues. Values omit the surrounding square brackets, and matching spoken text is not changed.
      - `find` string, required: Existing speaker label without the surrounding square brackets.
      - `replace` string, required: New speaker label without the surrounding square brackets.
    - `upload_to_mux` boolean: Whether to upload the edited VTT back to the Mux asset as a text track. Defaults to true.
    - `replace_existing_tracks` 'replace' | 'fail': What to do with the source track. Defaults to `replace`: the source is deleted and the edited track takes its place under the same name, language and closed-captions setting; no other track is touched, and the source is restored if the edited track can't be added. `fail` deletes nothing and adds the edited track alongside the source, so it requires a `track_name` different from the source's. Either way the request is rejected if a track other than the source already has the edited track's name. `replace` requires `upload_to_mux` to be true.
    - `track_name` string: Name for the edited Mux text track. Defaults to the source track's name. Required and must differ from the source's name when `replace_existing_tracks` is `fail`. Mux requires text track names to be unique on an asset.
    - `delete_original_track` boolean: Deprecated: use `replace_existing_tracks`. When set, the previous behavior applies: the edited track is added as `<source name> (<track_name_suffix>)`, then the source is deleted if this is true. Cannot be combined with `replace_existing_tracks` or `track_name`.
    - `track_name_suffix` string: Deprecated: use `track_name`. Selects the previous naming scheme, appending this suffix to the source track's name (default "edited"). Cannot be combined with `replace_existing_tracks` or `track_name`.

## Response `202`

Caption editing job queued

- EditCaptionsJobResponseV0
  - `data` EditCaptionsJobV0, 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` JobDirectiveContextV0: 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` 'edit-captions', required
    - `parameters` EditCaptionsJobParametersV0, required
      - `asset_id` string, required: The Mux asset ID whose existing text track should be edited.
      - `track_id` string, required: The existing ready Mux text track ID to edit and optionally replace.
      - `auto_censor_profanity` object: Optional LLM-driven profanity detection and censorship rules applied to the selected caption track.
        - `detection_method` 'llm': How profanity is detected. Currently only `llm` is supported, which uses an LLM to identify profanity in cue text.
        - `mode` 'blank' | 'remove' | 'mask': Replacement strategy for detected profanity: blank inserts bracketed underscores, remove drops the match, and mask replaces characters with question marks. Defaults to "blank".
        - `always_censor` string[]: Additional words or short phrases that should always be censored even if the model does not detect them.
        - `never_censor` string[]: Words or short phrases that should never be censored even if the model flags them.
      - `replacements` object[]: Optional static word or phrase replacements applied directly to cue text.
        - `find` string, required: Exact word or phrase to replace in cue text.
        - `replace` string, required: Replacement text to insert when a match is found.
        - `case_sensitive` boolean: When true, `find` is matched only with exact case. Defaults to false (case-insensitive matching), so "gonna" also matches "Gonna" and "GONNA".
      - `speaker_replacements` EditCaptionsSpeakerReplacementV0[]: Optional replacements for bracketed speaker labels at the start of caption cues. Values omit the surrounding square brackets, and matching spoken text is not changed.
        - `find` string, required: Existing speaker label without the surrounding square brackets.
        - `replace` string, required: New speaker label without the surrounding square brackets.
      - `upload_to_mux` boolean: Whether to upload the edited VTT back to the Mux asset as a text track. Defaults to true.
      - `replace_existing_tracks` 'replace' | 'fail': What to do with the source track. Defaults to `replace`: the source is deleted and the edited track takes its place under the same name, language and closed-captions setting; no other track is touched, and the source is restored if the edited track can't be added. `fail` deletes nothing and adds the edited track alongside the source, so it requires a `track_name` different from the source's. Either way the request is rejected if a track other than the source already has the edited track's name. `replace` requires `upload_to_mux` to be true.
      - `track_name` string: Name for the edited Mux text track. Defaults to the source track's name. Required and must differ from the source's name when `replace_existing_tracks` is `fail`. Mux requires text track names to be unique on an asset.
      - `delete_original_track` boolean: Deprecated: use `replace_existing_tracks`. When set, the previous behavior applies: the edited track is added as `<source name> (<track_name_suffix>)`, then the source is deleted if this is true. Cannot be combined with `replace_existing_tracks` or `track_name`.
      - `track_name_suffix` string: Deprecated: use `track_name`. Selects the previous naming scheme, appending this suffix to the source track's name (default "edited"). Cannot be combined with `replace_existing_tracks` or `track_name`.
    - `status` 'pending' | 'processing' | 'completed' | 'errored' | 'cancelled', required: Current job status.
    - `errors` JobErrorV0[]: 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` ResourcesV0: Related Mux resources linked to this job.
      - `assets` SlimlineAssetV0[], 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` EditCaptionsJobOutputsV0: Workflow results. Present when status is 'completed'.
      - `total_replacement_count` integer, required: Total count of cue text replacements applied across all edit operations.
      - `uploaded_track_id` string: Mux text track ID for the uploaded edited captions. Present when upload_to_mux is true and the upload succeeds.
      - `temporary_vtt_url` string: Temporary pre-signed URL for downloading the edited VTT file. Expires 7 days after the job completes.
      - `replaced_tracks` ReplacedTrackV0[]: Every track deleted before the new track was created. Present when `replace_existing_tracks` was a deleting policy and at least one track was removed.
        - `id` string, required: Mux track ID of the deleted track.
        - `type` 'text' | 'audio': Mux track type of the deleted track.
        - `name` string: Name of the deleted track.
        - `language_code` string: Language code of the deleted track.
        - `text_source` string: Mux `text_source` of the deleted track, e.g. `uploaded` or `generated_vod`. Absent for audio tracks.
        - `passthrough` string: `passthrough` value the deleted track carried, if any.

## Other responses

- `400`: Malformed or missing JSON request body, or invalid request parameters
- `401`: Missing or invalid Mux credentials
- `403`: Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.
- `409`: A job with the same workflow and parameters is already pending or processing for this environment.
- `422`: Asset not found, no public or signed playback ID, the requested text track is not ready, or another track already has the edited track's name
- `500`: Server error

## Changes

- **2026-10-26** `151835caff06`: 1 info
  - endpoint deprecated
- **2026-10-19** `7e2e5079412d`: 3 info
  - api operation id `create-edit-captions-job` removed and replaced with `create-edit-captions-job-v0`
  - api tag `Edit Captions (v0)` added
  - api tag `Edit Captions` removed
- **2026-10-08** `296f0b01bb84`: 1 breaking, 14 info
  - request body became required
  - the `replace_existing_tracks` request property default value `replace` was added
  - added the optional property `error/messages` to the response with the `400` status
  - added the optional property `error/messages` to the response with the `401` status
  - …11 more
- **2026-10-02** `90f16ccd8b65`: 11 info
  - added the new optional request property `parameters/replace_existing_tracks`
  - added the new optional request property `parameters/track_name`
  - the `delete_original_track` request property default value `true` was removed
  - request property `parameters/delete_original_track` deprecated
  - …7 more
- **2026-09-17** `68a2dd0743bf`: 3 info
  - added the new optional request property `parameters/speaker_replacements`
  - added the non-success response with the status `409`
  - added the optional property `data/parameters/speaker_replacements` to the response with the `202` status

[Operation history](https://skmtc.dev/muxinc/apis/mux-api/changes/robots/v0/jobs/edit-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)