---
title: "Create a 'generate-chapters' job"
method: POST
path: "/robots/v1/jobs/generate-chapters"
tags: ["Generate Chapters"]
---

# Create a 'generate-chapters' job

`POST /robots/v1/jobs/generate-chapters`

## Request

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

Creates a new job that uses AI to generate chapters for a Mux Video asset. Optional output steering can guide chapter style, granularity, audience, and brand terms without changing the response schema.

## Request body

- CreateGenerateChaptersJobRequest
  - `passthrough` string: Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
  - `parameters` GenerateChaptersJobParameters, required
    - `asset_id` string, required: The Mux asset ID of the video to generate chapters for.
    - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript.
    - `output_language_code` string: BCP 47 language code for the output chapter titles. Auto-detected from the transcript if omitted.
    - `output_steering` GenerateChaptersOutputSteering: Curated output_steering controls for chapter style, granularity, audience, and brand terminology. These controls guide model behavior but do not guarantee exact output.
      - `chapter_style` 'descriptive' | 'punchy' | 'educational' | 'seo' | 'platform_neutral': Best-effort style guidance for generated chapter titles.
      - `chapter_granularity` 'coarse' | 'balanced' | 'fine': Best-effort guidance for how coarse or fine chapter boundaries should be.
      - `audience` string: Intended audience used as best-effort model guidance. Does not change the output schema.
      - `brand_terms` string[]: Preferred brand or domain terms to use when supported by the source content.
    - `update_asset_chapters` boolean: When true, the generated chapters are written back to the Mux asset as a chapters text track once the job completes, making them deliverable with the asset. Overwrites existing chapters: an asset holds a single chapters track, so any chapters track already on the asset is deleted and replaced — including one in a different language, and one you created yourself. Best-effort — a failed write does not fail the job — so check `asset_updates.chapters` in the job outputs for the outcome.

## Response `202`

Job queued

- GenerateChaptersJobResponse
  - `data` GenerateChaptersJob, 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` 'generate-chapters', required
    - `parameters` GenerateChaptersJobParameters, required
      - `asset_id` string, required: The Mux asset ID of the video to generate chapters for.
      - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript.
      - `output_language_code` string: BCP 47 language code for the output chapter titles. Auto-detected from the transcript if omitted.
      - `output_steering` GenerateChaptersOutputSteering: Curated output_steering controls for chapter style, granularity, audience, and brand terminology. These controls guide model behavior but do not guarantee exact output.
        - `chapter_style` 'descriptive' | 'punchy' | 'educational' | 'seo' | 'platform_neutral': Best-effort style guidance for generated chapter titles.
        - `chapter_granularity` 'coarse' | 'balanced' | 'fine': Best-effort guidance for how coarse or fine chapter boundaries should be.
        - `audience` string: Intended audience used as best-effort model guidance. Does not change the output schema.
        - `brand_terms` string[]: Preferred brand or domain terms to use when supported by the source content.
      - `update_asset_chapters` boolean: When true, the generated chapters are written back to the Mux asset as a chapters text track once the job completes, making them deliverable with the asset. Overwrites existing chapters: an asset holds a single chapters track, so any chapters track already on the asset is deleted and replaced — including one in a different language, and one you created yourself. Best-effort — a failed write does not fail the job — so check `asset_updates.chapters` in the job outputs for the outcome.
    - `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'.
      - `chapters` object[], required: Generated chapters, ordered by start time.
        - `start_time` number, required: Chapter start time in seconds. The first chapter always starts at 0.
        - `title` string, required: Concise chapter title.
      - `asset_updates` GenerateChaptersAssetUpdateOutcomes: Recorded best-effort chapters track update outcome. A failed update does not fail the analysis job. Omitted when no outcome was recorded.
        - `chapters` GenerateChaptersAssetUpdate: What happened when the generated chapters were written back to the Mux asset. Present only when update_asset_chapters was true. When status is `failed` and replaced_track_ids is nonempty, deletion succeeded but replacement creation failed, leaving the asset without a chapters track.
          - `status` 'created' | 'failed', required: Outcome of the chapters track write. `created` means the asset now carries these chapters. `failed` means the write was attempted and errored; the chapters in this response are still valid and can be applied manually.
          - `track_id` string: Mux text track ID of the chapters track created on the asset. Present when status is `created`.
          - `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, unsupported asset, missing public or signed playback access, missing or ineligible required captions, or no eligible source matching the explicit caption language.
- `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/generate-chapters/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)