On this page

Generate chapters

Create timestamped chapters from video content using the Mux Robots API.

Generate timestamped chapters from a video's caption track. This is useful for creating a table of contents for long-form video content, improving navigation, and making video content easier to scan. See the Generate Chapters API referenceAPI for the full endpoint specification. See Mux Robots pricing for unit costs.

Chapter generation uses caption tracks on the asset to understand the video content. Make sure your asset has captions, either auto-generated or manually added, before creating a chapter generation job.

Create a `generate-chapters` job

curl https://api.mux.com/robots/v0/jobs/generate-chapters \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "parameters": {
      "asset_id": "YOUR_ASSET_ID"
    }
  }' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

This request is asynchronous. The POST returns immediately with the job in pending status and does not include results. We strongly recommend listening for the robots.job.generate_chapters.completed webhook — the payload contains the full completed job, so no follow-up API call is needed. If webhooks aren't an option, you can poll GET /robots/v0/jobs/generate-chapters/{JOB_ID} with the id from the response until the status is completed.

Parameters

Parameter	Type	Description
`asset_id`	string	Required. The Mux asset ID of the video.
`language_code`	string	BCP 47 language code of the caption track to analyze (e.g. `en`, `fr`). When omitted, the SDK prefers English if available.
`output_language_code`	string	BCP 47 language code for the output chapter titles. Auto-detected from the transcript if omitted.
`output_steering`	object	Curated controls that guide chapter style, granularity, audience, and brand terminology without changing the output schema. See Output steering.

Output steering

Use output_steering when you want best-effort control over how chapters are generated. These fields guide the workflow but do not guarantee exact output. output_steering replaces the legacy prompt_overrides parameter.

Field	Type	Description
`chapter_style`	string	Preferred style for generated chapter titles. Supported values: `descriptive`, `punchy`, `educational`, `seo`, and `platform_neutral`.
`chapter_granularity`	string	Preferred chapter granularity. Supported values: `coarse`, `balanced`, and `fine`.
`audience`	string	Intended audience used to guide chapter titles and emphasis.
`brand_terms`	array of strings	Preferred brand or domain terms to use when supported by the source content.

{
  "parameters": {
    "asset_id": "YOUR_ASSET_ID",
    "output_steering": {
      "chapter_style": "educational",
      "chapter_granularity": "fine",
      "audience": "home cooks following along step by step",
      "brand_terms": ["Dutch oven", "mirepoix"]
    }
  }
}

Output

The outputs object is included in the job once its status is completed. You'll receive it on the robots.job.generate_chapters.completed webhook (recommended), or you can fetch it with GET /robots/v0/jobs/generate-chapters/{JOB_ID}. It contains:

Field	Type	Description
`chapters`	array	Generated chapters, ordered by start time.
`chapters[].start_time`	number	Chapter start time in seconds. The first chapter always starts at 0.
`chapters[].title`	string	Concise chapter title.

Example response

This is the payload delivered to the robots.job.generate_chapters.completed webhook, and the same shape you get from GET /robots/v0/jobs/generate-chapters/{JOB_ID}:

{
  "data": {
    "id": "rjob_ghi789",
    "workflow": "generate-chapters",
    "status": "completed",
    "units_consumed": 1,
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "output_steering": {
        "chapter_style": "educational",
        "chapter_granularity": "fine",
        "audience": "home cooks following along step by step",
        "brand_terms": ["Dutch oven", "mirepoix"]
      }
    },
    "outputs": {
      "chapters": [
        { "start_time": 0, "title": "Gather your ingredients" },
        { "start_time": 18.5, "title": "Preheat the oven to 375°F" },
        { "start_time": 42.1, "title": "Dice the onions and garlic" },
        { "start_time": 95.3, "title": "Sear the chicken thighs" },
        { "start_time": 158.7, "title": "Deglaze with white wine" },
        { "start_time": 203.4, "title": "Simmer the sauce" },
        { "start_time": 278.9, "title": "Plate and garnish" }
      ]
    }
  }
}

On this page

Generate chapters

Create timestamped chapters from video content using the Mux Robots API.

Create a `generate-chapters` job

curl https://api.mux.com/robots/v0/jobs/generate-chapters \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "parameters": {
      "asset_id": "YOUR_ASSET_ID"
    }
  }' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

Parameters

Parameter	Type	Description
`asset_id`	string	Required. The Mux asset ID of the video.
`language_code`	string	BCP 47 language code of the caption track to analyze (e.g. `en`, `fr`). When omitted, the SDK prefers English if available.
`output_language_code`	string	BCP 47 language code for the output chapter titles. Auto-detected from the transcript if omitted.
`output_steering`	object	Curated controls that guide chapter style, granularity, audience, and brand terminology without changing the output schema. See Output steering.

Output steering

Field	Type	Description
`chapter_style`	string	Preferred style for generated chapter titles. Supported values: `descriptive`, `punchy`, `educational`, `seo`, and `platform_neutral`.
`chapter_granularity`	string	Preferred chapter granularity. Supported values: `coarse`, `balanced`, and `fine`.
`audience`	string	Intended audience used to guide chapter titles and emphasis.
`brand_terms`	array of strings	Preferred brand or domain terms to use when supported by the source content.

{
  "parameters": {
    "asset_id": "YOUR_ASSET_ID",
    "output_steering": {
      "chapter_style": "educational",
      "chapter_granularity": "fine",
      "audience": "home cooks following along step by step",
      "brand_terms": ["Dutch oven", "mirepoix"]
    }
  }
}

Output

Field	Type	Description
`chapters`	array	Generated chapters, ordered by start time.
`chapters[].start_time`	number	Chapter start time in seconds. The first chapter always starts at 0.
`chapters[].title`	string	Concise chapter title.

Example response

This is the payload delivered to the robots.job.generate_chapters.completed webhook, and the same shape you get from GET /robots/v0/jobs/generate-chapters/{JOB_ID}:

{
  "data": {
    "id": "rjob_ghi789",
    "workflow": "generate-chapters",
    "status": "completed",
    "units_consumed": 1,
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "output_steering": {
        "chapter_style": "educational",
        "chapter_granularity": "fine",
        "audience": "home cooks following along step by step",
        "brand_terms": ["Dutch oven", "mirepoix"]
      }
    },
    "outputs": {
      "chapters": [
        { "start_time": 0, "title": "Gather your ingredients" },
        { "start_time": 18.5, "title": "Preheat the oven to 375°F" },
        { "start_time": 42.1, "title": "Dice the onions and garlic" },
        { "start_time": 95.3, "title": "Sear the chicken thighs" },
        { "start_time": 158.7, "title": "Deglaze with white wine" },
        { "start_time": 203.4, "title": "Simmer the sauce" },
        { "start_time": 278.9, "title": "Plate and garnish" }
      ]
    }
  }
}