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

# Create an 'edit-captions' job

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

Creates a new job that edits an existing Mux text track using static replacements and optional profanity censoring. Provide at least one of `replacements` or `auto_censor_profanity`.

## Request body

- CreateEditCaptionsJobRequest
  - `passthrough` string — Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
  - `parameters` EditCaptionsJobParameters, 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".
    - `upload_to_mux` boolean — Whether to upload the edited VTT back to the Mux asset as a new text track. Defaults to true.
    - `delete_original_track` boolean — Whether to delete the original source text track after the edited track upload succeeds. Has effect only when upload_to_mux is true. Defaults to true.
    - `track_name_suffix` string — Optional suffix appended to the uploaded replacement track name. Defaults to "edited".

## Response `202`

Caption editing job queued

- EditCaptionsJobResponse
  - `data` EditCaptionsJob, 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.
    - `created_at` integer, required — Unix timestamp (seconds) when the job was created.
    - `updated_at` integer, required — Unix timestamp (seconds) when the job was last updated.
    - `workflow` 'edit-captions', required
    - `parameters` EditCaptionsJobParameters, 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".
      - `upload_to_mux` boolean — Whether to upload the edited VTT back to the Mux asset as a new text track. Defaults to true.
      - `delete_original_track` boolean — Whether to delete the original source text track after the edited track upload succeeds. Has effect only when upload_to_mux is true. Defaults to true.
      - `track_name_suffix` string — Optional suffix appended to the uploaded replacement track name. Defaults to "edited".
    - `status` 'pending' | 'processing' | 'completed' | 'errored' | 'cancelled', required — Current job status.
    - `outputs` EditCaptionsJobOutputs — 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.
    - `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.

## Other responses

- `400` — Validation error
- `401` — Missing Mux credentials
- `403` — Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.
- `422` — Asset not found, no playback ID, or the requested text track is not ready
- `500` — Server error

---

[API](https://skmtc.net/muxinc/apis/mux-api.md) · [All operations](https://skmtc.net/muxinc/apis/mux-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/muxinc/mux-api/versions/34a65dce0f31/schema)