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.
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.
generate-chapters jobcurl 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.
| 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. |
prompt_overrides | object | Override specific sections of the chapter generation prompt. See below. |
Like the summarize workflow, you can override specific parts of the chapter generation prompt to control the AI's behavior.
| Override | Description |
|---|---|
prompt_overrides.task | Replace the high-level instruction for what the AI should do with the transcript. |
prompt_overrides.output_format | Replace the instructions for how the AI should structure its JSON output. |
prompt_overrides.chapter_guidelines | Replace the rules for chapter density and timing (e.g. minimum chapter length, maximum number of chapters). |
prompt_overrides.title_guidelines | Replace the rules for chapter title style (e.g. length, tone, formatting). |
Here's an example that generates chapters for a cooking tutorial, with shorter chapters and action-oriented titles:
{
"parameters": {
"asset_id": "YOUR_ASSET_ID",
"prompt_overrides": {
"chapter_guidelines": "Create a chapter for each distinct step in the recipe. Chapters should be at least 15 seconds long. Aim for one chapter per ingredient or technique introduced.",
"title_guidelines": "Use imperative verb phrases like 'Dice the onions' or 'Preheat the oven'. Keep titles under 40 characters. Do not number the chapters."
}
}
}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. |
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",
"prompt_overrides": {
"chapter_guidelines": "Create a chapter for each distinct step in the recipe. Chapters should be at least 15 seconds long. Aim for one chapter per ingredient or technique introduced.",
"title_guidelines": "Use imperative verb phrases like 'Dice the onions' or 'Preheat the oven'. Keep titles under 40 characters. Do not number the chapters."
}
},
"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" }
]
}
}
}