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

# Migration guide: Auto Chapters

This guide walks through the process of upgrading from the deprecated `auto_chapters` parameter to [Summarization](/docs/speech-understanding/summarization) under Speech Understanding.

<Note>
  **This guide is for existing accounts using the deprecated `auto_chapters`
  parameter.** If you're adding chapters for the first time, go straight to the
  [Summarization documentation](/docs/speech-understanding/summarization) — it
  returns topic summaries with headlines and timestamps in one call, which is
  what chapters are.
</Note>

We replaced Auto Chapters with Summarization. Both return the transcript split into topic sections with a headline and timestamps per section, so the response shapes line up closely. The changes are to the request shape, the response location, and the fields on each section.

* **Topic sections replace chapters.** You still get the transcript broken into ordered sections with `start`, `end`, and a headline per section.
* **One `text` field per topic.** The deprecated parameter returned three overlapping text fields (`summary`, `gist`, `headline`) per chapter; Summarization returns `text` and `headline`.
* **Quality you control.** The new `effort` parameter lets you spend more processing on harder content — useful for meetings, multilingual audio, or files longer than about 1.5 hours.

Your existing API key and endpoint stay the same.

## Quick upgrade

Replace `auto_chapters: true` with a `speech_understanding.request.summarization` object:

```json theme={null}
// Before (deprecated)
{
  "audio_url": "https://example.com/audio.mp3",
  "auto_chapters": true
}

// After
{
  "audio_url": "https://example.com/audio.mp3",
  "speech_understanding": {
    "request": {
      "summarization": { "summary_type": "paragraph" }
    }
  }
}
```

<Note>
  **That's it for the request.** But the response moves too — read the sections
  from `speech_understanding.response.summarization.summary` instead of the
  top-level `chapters` field. Read on for the full migration details.
</Note>

## What changes

This table covers the key parameter and response field differences. Use it as a migration checklist.

| What                   | Deprecated Auto Chapters                      | Speech Understanding Summarization                    | Action required                                                                            |
| ---------------------- | --------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Where it's set**     | Top-level `auto_chapters: true`               | `speech_understanding.request.summarization`          | Replace `auto_chapters` with a `summarization` object under `speech_understanding.request` |
| **Request shape**      | Boolean flag                                  | Object holding the summary options                    | Pass an object; `{}` uses the defaults                                                     |
| **`summary_type`**     | Not a parameter                               | `bullets` or `paragraph` (defaults to `paragraph`)    | Optional — pick `paragraph` for chapter-style prose or `bullets` for short bullets         |
| **`effort`**           | Not supported                                 | `low` (default) or `medium`                           | New capability (optional) — set `medium` for harder content                                |
| **Response field**     | Top-level `chapters`                          | `speech_understanding.response.summarization.summary` | Update your response parsing to read from the new path                                     |
| **Per-section fields** | `headline`, `gist`, `summary`, `start`, `end` | `headline`, `text`, `start`, `end`                    | Read `text` in place of `summary`; drop `gist` (or fall back to `headline`)                |
| **Pricing**            | Bundled with the deprecated model             | \$0.03 per hour of audio                              | Review your cost model                                                                     |

### Mapping the per-chapter fields

| Deprecated field | Use instead     | Notes                                                        |
| ---------------- | --------------- | ------------------------------------------------------------ |
| `headline`       | `headline`      | Same field, same purpose                                     |
| `summary`        | `text`          | The longer summary body for the section                      |
| `gist`           | `headline`      | No direct equivalent — use `headline` for the short overview |
| `start` / `end`  | `start` / `end` | Same field, milliseconds                                     |

## Side-by-side code comparison

Below is a side-by-side comparison of generating chapters with the deprecated parameter and with Speech Understanding Summarization:

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

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

    audio_url = "https://assembly.ai/wildfires.mp3"

    data = {
        "audio_url": audio_url,
        "auto_chapters": 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)

    for chapter in transcription_result['chapters']:
        print(f"{chapter['start']} - {chapter['end']}: {chapter['headline']}")
        print(chapter['summary'])
    ```
  </Tab>

  <Tab language="aai" title="Speech Understanding">
    ```python expandable theme={null}
    import requests
    import time

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

    audio_url = "https://assembly.ai/wildfires.mp3"

    data = {
        "audio_url": audio_url,
        "speech_understanding": {
            "request": {
                "summarization": {
                    "summary_type": "paragraph"
                }
            }
        }
    }

    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)

    summarization = transcription_result["speech_understanding"]["response"]["summarization"]

    for topic in summarization["summary"]:
        print(f"{topic['start']} - {topic['end']}: {topic['headline']}")
        print(topic["text"])
    ```
  </Tab>
</Tabs>

The same change in JavaScript:

<Tabs groupId="language">
  <Tab language="deprecated" title="Deprecated">
    ```javascript theme={null}
    const data = {
      audio_url: audioUrl,
      auto_chapters: true,
    };

    // ... submit and poll until status is "completed"

    for (const chapter of transcriptionResult.chapters) {
      console.log(`${chapter.start} - ${chapter.end}: ${chapter.headline}`);
      console.log(chapter.summary);
    }
    ```
  </Tab>

  <Tab language="aai" title="Speech Understanding">
    ```javascript theme={null}
    const data = {
      audio_url: audioUrl,
      speech_understanding: {
        request: {
          summarization: {
            summary_type: "paragraph",
          },
        },
      },
    };

    // ... submit and poll until status is "completed"

    const { summary } = transcriptionResult.speech_understanding.response.summarization;

    for (const topic of summary) {
      console.log(`${topic.start} - ${topic.end}: ${topic.headline}`);
      console.log(topic.text);
    }
    ```
  </Tab>
</Tabs>

## Reading the response

The deprecated parameter returned an array on the top-level `chapters` field. Speech Understanding returns an object on `speech_understanding.response.summarization`, with the sections themselves in the `summary` array:

```plain theme={null}
{
    "status": "success",
    "summary": [
      {
        "start": 240,
        "end": 37100,
        "text": "Smoke from hundreds of Canadian wildfires is causing air quality alerts across the US, turning skylines gray and prompting warnings to stay inside.",
        "headline": "Smoke from Canadian Wildfires Affects US Air Quality"
      },
      {
        "start": 39100,
        "end": 60670,
        "text": "Professor Peter DeCarlo explains that dry conditions and specific weather systems are channeling smoke from Canadian wildfires into the Mid-Atlantic and Northeast regions of the US.",
        "headline": "Weather Systems Channeling Smoke"
      }
    ],
    "summary_type": "paragraph",
    "effort": "low"
}
```

Things to know when updating your response handling:

* `summary` is the array of sections — one per topic, in order. Treat each element as a chapter.
* `start` and `end` are timestamps in milliseconds, so you can link each section back to the audio.
* `text` replaces the deprecated `summary` field on each chapter. There is no separate `gist` — use `headline` for a short overview.
* Check `status` for `success` before reading the summaries.

## Choosing `summary_type`

Summarization takes a `summary_type` of `bullets` or `paragraph`:

* **`paragraph`** produces prose summaries per section. This is closest to what Auto Chapters returned in its `summary` field.
* **`bullets`** produces short bullet-style summaries per section. Reach for this if you're rendering chapter markers in a compact UI.

Either way, every section still carries its own `headline`, `start`, and `end`.

## Controlling quality with `effort`

The new `effort` parameter has no equivalent in the deprecated parameter. It controls how much processing power goes into the summary:

```json theme={null}
{
  "audio_url": "https://example.com/audio.mp3",
  "speech_understanding": {
    "request": {
      "summarization": {
        "summary_type": "paragraph",
        "effort": "medium"
      }
    }
  }
}
```

`low` is the default and is the right choice for most use cases. Reach for `medium` when missed details matter — important meetings, multilingual audio, or long files (roughly 1.5 hours and up).

## Pricing

Summarization is **\$0.03 per hour of audio**. See [Billing and pricing](/docs/billing-and-pricing) for full rates.

## If you also need action items

Alongside Summarization we shipped [Action Items](/docs/speech-understanding/action-items). Add an `action_items` object to the same `speech_understanding` request to get structured follow-ups from meetings and calls — pass `{}` to use the defaults:

```json theme={null}
{
  "audio_url": "https://example.com/audio.mp3",
  "speech_understanding": {
    "request": {
      "summarization": { "summary_type": "paragraph" },
      "action_items": {}
    }
  }
}
```

Read the results from `speech_understanding.response.action_items`. Action Items takes the same `effort` parameter as Summarization, plus `include_decisions` to count decisions made in the audio as action items. Action Items is **\$0.02 per hour of audio**.

## Next steps

* Read the full [Summarization documentation](/docs/speech-understanding/summarization) for all parameters and options.
* Explore the other [Speech Understanding](/docs/speech-understanding/getting-started) models you can request in the same call.
* Review the [AssemblyAI API Reference](/docs/pre-recorded-audio/api-reference/transcripts/submit) for the complete request and response schema.