> ## Documentation Index
> Fetch the complete documentation index at: https://assemblyai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto Chapters

<AccordionGroup>
  <Accordion title="Supported regions">
    US & EU <br />
  </Accordion>
</AccordionGroup>

Generate chapter summaries from your audio transcripts using [LLM Gateway](/llm-gateway/quickstart). This approach gives you full control over how chapters are created and summarized.

<Note>
  The `auto_chapters` parameter on the transcription API is deprecated. Use LLM Gateway as shown below for more flexible and powerful chapter summaries.
</Note>

## Quickstart

<Tabs groupId="language">
  <Tab language="python" title="Python" default>
    ```python expandable theme={null}
    import requests
    import time

    base_url = "https://api.assemblyai.com"
    headers = {"authorization": "<YOUR_API_KEY>"}

    # Step 1: Transcribe your audio file
    audio_url = "https://assembly.ai/wildfires.mp3"

    data = {
        "audio_url": audio_url,
        "language_detection": True
    }

    response = requests.post(base_url + "/v2/transcript", json=data, headers=headers)
    transcript_id = response.json()['id']
    polling_endpoint = base_url + "/v2/transcript/" + transcript_id

    while True:
        transcription_result = requests.get(polling_endpoint, headers=headers).json()
        if transcription_result['status'] == 'completed':
            break
        elif transcription_result['status'] == 'error':
            raise RuntimeError(f"Transcription failed: {transcription_result['error']}")
        else:
            time.sleep(3)

    # Step 2: Get paragraphs from the transcript
    paragraphs = requests.get(polling_endpoint + '/paragraphs', headers=headers).json()['paragraphs']

    # Step 3: Combine paragraphs into groups for chapter summaries
    combined_paragraphs = []
    step = 2  # Adjust to control chapter length

    for i in range(0, len(paragraphs), step):
        paragraph_group = paragraphs[i : i + step]
        start = paragraph_group[0]['start']
        end = paragraph_group[-1]['end']
        text = " ".join(p['text'] for p in paragraph_group)
        combined_paragraphs.append({"text": text, "start": start, "end": end})

    # Step 4: Generate chapter summaries with LLM Gateway
    for chapter in combined_paragraphs:
        llm_gateway_data = {
            "model": "claude-sonnet-4-6",
            "messages": [
                {"role": "user", "content": f"Provide a brief one-paragraph summary, a one-line gist, and a headline for this section of a transcript.\n\nText: {chapter['text']}"}
            ],
            "max_tokens": 500
        }

        response = requests.post(
            "https://llm-gateway.assemblyai.com/v1/chat/completions",
            headers=headers,
            json=llm_gateway_data
        )

        result = response.json()["choices"][0]["message"]["content"]
        print(f"{chapter['start']}-{chapter['end']}: {result}\n")
    ```
  </Tab>

  <Tab language="javascript" title="JavaScript">
    ```javascript expandable theme={null}
    const baseUrl = "https://api.assemblyai.com";

    const headers = {
      authorization: "<YOUR_API_KEY>",
      "content-type": "application/json",
    };

    // Step 1: Transcribe your audio file
    const audioUrl = "https://assembly.ai/wildfires.mp3";

    const data = {
      audio_url: audioUrl,
      language_detection: true,
    };

    const response = await fetch(`${baseUrl}/v2/transcript`, {
      method: "POST",
      headers,
      body: JSON.stringify(data),
    });

    const { id: transcriptId } = await response.json();
    const pollingEndpoint = `${baseUrl}/v2/transcript/${transcriptId}`;

    let transcriptionResult;
    while (true) {
      const pollingResponse = await fetch(pollingEndpoint, { headers });
      transcriptionResult = await pollingResponse.json();

      if (transcriptionResult.status === "completed") {
        break;
      } else if (transcriptionResult.status === "error") {
        throw new Error(`Transcription failed: ${transcriptionResult.error}`);
      } else {
        await new Promise((resolve) => setTimeout(resolve, 3000));
      }
    }

    // Step 2: Get paragraphs from the transcript
    const paragraphsResponse = await fetch(`${pollingEndpoint}/paragraphs`, {
      headers,
    });
    const { paragraphs } = await paragraphsResponse.json();

    // Step 3: Combine paragraphs into groups for chapter summaries
    const step = 2; // Adjust to control chapter length
    const combinedParagraphs = [];

    for (let i = 0; i < paragraphs.length; i += step) {
      const group = paragraphs.slice(i, i + step);
      combinedParagraphs.push({
        text: group.map((p) => p.text).join(" "),
        start: group[0].start,
        end: group[group.length - 1].end,
      });
    }

    // Step 4: Generate chapter summaries with LLM Gateway
    for (const chapter of combinedParagraphs) {
      const llmGatewayData = {
        model: "claude-sonnet-4-6",
        messages: [
          {
            role: "user",
            content: `Provide a brief one-paragraph summary, a one-line gist, and a headline for this section of a transcript.\n\nText: ${chapter.text}`,
          },
        ],
        max_tokens: 500,
      };

      const result = await fetch(
        "https://llm-gateway.assemblyai.com/v1/chat/completions",
        {
          method: "POST",
          headers,
          body: JSON.stringify(llmGatewayData),
        }
      );

      const resultData = await result.json();
      console.log(
        `${chapter.start}-${chapter.end}: ${resultData.choices[0].message.content}\n`
      );
    }
    ```
  </Tab>
</Tabs>

### Example output

```plain theme={null}
240-60890: 
Headline: Canadian Wildfire Smoke Triggers Air Quality Alerts Across the US
Gist: Wildfire smoke affects US air quality
Summary: Smoke from hundreds of wildfires in Canada is causing hazy conditions and air quality alerts in multiple states. Peter DeCarlo, an environmental health expert from Johns Hopkins University, explains that dry conditions and specific weather patterns are channeling the smoke southward, affecting the mid-Atlantic and Northeast regions.

62270-113214:
Headline: Baltimore Air Quality Reaches Unhealthy Levels Due to Particulate Matter
Gist: Dangerous particulate matter levels in Baltimore
Summary: The air quality in Baltimore has reached unhealthy levels due to high concentrations of particulate matter. These microscopic particles can affect respiratory, cardiovascular, and neurological systems, measuring 150 micrograms per cubic meter—10 times higher than the annual average.
```

## Customize your chapters

You can adjust the chapter generation by modifying the `step` variable to control how many paragraphs are grouped into each chapter, and by customizing the prompt.

### Structured chapter output

For a more structured output, use [Structured Outputs](/llm-gateway/structured-outputs) or specify a JSON format in your prompt:

```python theme={null}
prompt = """For this section of a transcript, provide the following in JSON format:
{
  "headline": "A single sentence headline",
  "gist": "A few words summarizing the section",
  "summary": "A one paragraph summary"
}

Text: """ + chapter['text']
```

## API reference

### Step 1: Transcribe audio

```bash theme={null}
curl https://api.assemblyai.com/v2/transcript \
--header "Authorization: <YOUR_API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "audio_url": "YOUR_AUDIO_URL"
}'
```

### Step 2: Get paragraphs

Once the transcript is complete, fetch the paragraphs:

```bash theme={null}
curl https://api.assemblyai.com/v2/transcript/YOUR_TRANSCRIPT_ID/paragraphs \
--header "Authorization: <YOUR_API_KEY>"
```

### Step 3: Generate chapter summaries with LLM Gateway

```bash theme={null}
curl https://llm-gateway.assemblyai.com/v1/chat/completions \
--header "Authorization: <YOUR_API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "user", "content": "Provide a brief summary, gist, and headline for this section.\n\nText: YOUR_PARAGRAPH_TEXT"}
  ],
  "max_tokens": 500
}'
```

| Key          | Type   | Description                                                                             |
| ------------ | ------ | --------------------------------------------------------------------------------------- |
| `model`      | string | The LLM model to use. See [available models](/llm-gateway/quickstart#available-models). |
| `messages`   | array  | The messages to send to the model, including your prompt and paragraph text.            |
| `max_tokens` | number | Maximum number of tokens in the response.                                               |

## Next steps

* [LLM Gateway Overview](/llm-gateway/quickstart) - Learn more about available models and features
* [Apply LLM Gateway to pre-recorded audio](/llm-gateway/apply-llms-to-audio-files) - General guide for using LLM Gateway with transcripts
* [Structured Outputs](/llm-gateway/structured-outputs) - Constrain responses to a specific JSON schema