Generate video chapters

Long videos lose viewers who cannot skip to the section they care about, and search engines cannot index topics buried inside a single timeline. FastPix solves this by generating chapter markers automatically through its in-video AI pipeline, giving each chapter a title, summary, and precise start/end timecodes. Enable chapter detection at upload time or trigger it on an existing mediaId, then retrieve the chapters through the Get Media endpoint or the video.mediaAI.chapters.ready webhook.

Prerequisites

• A FastPix account with an active workspace (Activate your account)
• Your Access Token ID and Secret Key from the FastPix dashboard
• A video or audio file accessible through HTTPS, or an existing mediaId in your workspace
• A webhook endpoint if you want to receive the video.mediaAI.chapters.ready event

How FastPix generates chapters

When you enable chapters: true on a media, FastPix runs multimodal indexing across the visual and auditory tracks, detects topic and scene transitions, and attaches chapter markers to the media. Each chapter includes a sequence number, start and end timecodes, a title, and a short summary.

Generate chapters for new media

Use the create media from URL endpoint to pull a file and enable chapters in one request, or direct upload for files uploaded from a device.

Send a POST request to /on-demand with these fields:

• type: Specify whether the file is video or audio.
• url: The HTTPS URL of the source file.
• chapters: Set to true to enable AI chapter detection.
• accessPolicy: (Optional) public or private.
• maxResolution: (Optional) Rendition cap, for example 1080p.

Request body for uploading from URL

1
{   
2
  "inputs": [   
3
    {   
4
      "type": "video",   
5
      "url": "https://static.fastpix.com/fp-sample-video.mp4"   
6
    }   
7
  ],   
8
  "chapters": true,   
9
  "accessPolicy": "public"  
10
}

Request body for direct upload from a device

For direct uploads, the chapters flag is set inside pushMediaSettings:

1
{  
2
  "corsOrigin": "*",  
3
  "pushMediaSettings": 
4
  {  
5
    "chapters": true,  
6
    "accessPolicy": "public" 
7
  }  
8
}

Generate chapters for existing media

To add chapter markers to a media already in your workspace, call the generate video chapters endpoint.

1. Collect the mediaId of the target media.
2. Send a PATCH request to /on-demand/<mediaId>/chapters, replacing <mediaId> with the media identifier.

Example request body

1
{   
2
  "chapters": true   
3
}

Generate video chapters from the dashboard

For new media

1. Add your media

In the left navigation, go to Video > Media. On the Upload media page, add your video using one of the following methods:

• Upload from device: Drag and drop your file into the upload area, or click Browse to open your device’s file picker. Navigate to the video you want to upload, select it, and click Open.
• Upload using video URL: Paste a public video URL into the Upload using video URL field and click Submit URL.

2. Enable chapter generation in media settings

The Media Settings panel opens. Select Custom settings and set "generateChapters": true in the JSON configuration. For example:

1
{
2
  "pushMediaSettings": {
3
    "generateChapters": true
4
  }
5
}

Click Continue, then click Start upload all media.

For existing media

1. Open the media details page

In the left navigation, go to Video > Media. Select the video you want to process from the media list to open its Media Details page.

2. Generate chapters

In the left navigation of the Media Details page, click AI Chapters under In-Video AI. Click Generate to start the analysis. FastPix analyzes your video and creates chapter markers based on scene and topic changes.

3. Review chapters

When chapter generation completes, review the chapter titles and timecodes in the Chapters panel.

Access the generated chapters

To retrieve chapters for a media, call the Get Media by ID endpoint.

Alternatively, subscribe to the video.mediaAI.chapters.ready webhook event, which triggers when chapter data becomes available. For the full schema and sample payload, see the Video Media AI chapters ready event.

Example event payload

1
{
2
  "type": "video.mediaAI.chapters.ready",
3
  "object": {
4
    "type": "media",
5
    "id": "f081fd53-6a9a-43ae-9d64-9974ef243dbd"
6
  },
7
  "id": "51a61b56-0197-4127-8a61-472e4d3fa59a",
8
  "workspace": {
9
    "name": "BrightCovePlayer-iOS",
10
    "id": "f7a13f50-7f5c-48f4-b7b2-c901dcff61c6"
11
  },
12
  "status": "ready",
13
  "data": {
14
    "isChaptersGenerated": true,
15
    "chapters": [
16
      {
17
        "chapter": "1",
18
        "startTime": "00:00:00",
19
        "endTime": "00:03:59",
20
        "title": "The Circle Challenge Begins",
21
        "summary": "Contestants start stacking items in a circle for a chance to win."
22
      },
23
      {
24
        "chapter": "2",
25
        "startTime": "00:04:00",
26
        "endTime": "00:09:59",
27
        "title": "Tyler's Big Surprise",
28
        "summary": "Tyler attempts to fit various items in the circle, revealing its true size."
29
      },
30
      {
31
        "chapter": "3",
32
        "startTime": "00:10:00",
33
        "endTime": "00:14:59",
34
        "title": "The Soup Kitchen Donation",
35
        "summary": "A soup kitchen team fills the circle with groceries and receives a surprise."
36
      },
37
      {
38
        "chapter": "4",
39
        "startTime": "00:15:00",
40
        "endTime": "00:18:29",
41
        "title": "Helping Families in Need",
42
        "summary": "Families fill the circle with essential items and receive financial support."
43
      },
44
      {
45
        "chapter": "5",
46
        "startTime": "00:18:30",
47
        "endTime": "00:19:54",
48
        "title": "Final Surprises and Wrap-Up",
49
        "summary": "Contestants celebrate their wins and the impact of the donations."
50
      }
51
    ]
52
  },
53
  "createdAt": "2025-11-05T11:52:29.526588692Z",
54
  "attempts": []
55
}

The chapters array contains every chapter FastPix generated for the media. Each entry includes:

• chapter: The sequence number of the chapter within the media.
• title: A short, descriptive title.
• startTime: Start time in hh:mm:ss format.
• endTime: End time in hh:mm:ss format.
• summary: A short description of the chapter’s content.

Use these fields to render chapter markers in a video player, build a table of contents, or power video segmentation in search results.

Limits and considerations

• Make sure the mediaId is correct when calling /on-demand/<mediaId>/chapters, otherwise the request fails.
• accessPolicy and maxResolution are optional but help control playback access and rendition quality.
• Generated chapters are timestamped to the second, so they map directly onto HLS segment boundaries for in-player navigation.
• Auto-generated titles and timecodes can be edited from the InVideo AI tab in the dashboard before you surface them to viewers.

Frequently asked questions

Can I edit or override the auto-generated chapters?

Yes. After FastPix generates chapters, open the InVideo AI tab for the media in the dashboard and edit the title, summary, or timecodes for any chapter. The updated values are returned by the Get Media endpoint.

How long does FastPix take to generate chapters?

Chapter generation runs after transcoding completes and scales with the media duration and audio complexity. Subscribe to the video.mediaAI.chapters.ready webhook event rather than polling so your application reacts the moment the chapters are ready.

How do I render chapter markers in a video player?

Fetch the chapters array from the Get Media endpoint or the video.mediaAI.chapters.ready event, then map each startTime onto the player’s timeline. Most HLS-compatible players accept custom cue points or a WebVTT chapter track that you can build from the startTime, endTime, and title fields.

Can I generate chapters for audio-only videos?

Yes. Set type to audio on the input and enable chapters: true. FastPix runs speech-to-text and topic detection on the audio track to produce the same chapter structure as a video.

What happens if I enable chapters on a media that already has them?

Calling PATCH /on-demand/<mediaId>/chapters with chapters: true regenerates the chapters for the media. The previous chapter set is replaced when the new video.mediaAI.chapters.ready event triggers.

What’s next?

• Add metadata to videos
• Extract thumbnails and images from video
• API reference: Generate video chapters
• API reference: Get media by ID