# 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 <ApiRefLink href="/docs/api-reference/robots/generate-chapters">Generate Chapters API reference</ApiRefLink> for the full endpoint specification. See [Mux Robots pricing](/docs/pricing/overview#mux-robots-pricing) for unit costs.

<Callout type="info">
  Chapter generation uses caption tracks on the asset to understand the video content. Make sure your asset has captions, either [auto-generated](/docs/guides/add-autogenerated-captions-and-use-transcripts) or [manually added](/docs/guides/add-subtitles-to-your-videos), before creating a chapter generation job.
</Callout>

## Create a `generate-chapters` job

```bash
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}
```

<Callout type="info">
  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](/docs/guides/robots#webhooks)** — 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`.
</Callout>

## 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). |

### 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. |

```json
{
  "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`](/docs/guides/robots#webhooks) 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`](/docs/guides/robots#webhooks) webhook, and the same shape you get from `GET /robots/v0/jobs/generate-chapters/{JOB_ID}`:

```json
{
  "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" }
      ]
    }
  }
}
```