Migration guide: Auto Chapters

This guide walks through the process of upgrading from the deprecated auto_chapters parameter to Summarization under Speech Understanding.

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 — it returns topic summaries with headlines and timestamps in one call, which is what chapters are.

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:

// 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" }
    }
  }
}

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.

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:

Deprecated
Speech Understanding

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'])

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"])

The same change in JavaScript:

Deprecated
Speech Understanding

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);
}

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);
}

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:

{
    "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:

{
  "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 for full rates.

If you also need action items

Alongside Summarization we shipped 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:

{
  "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 for all parameters and options.
Explore the other Speech Understanding models you can request in the same call.
Review the AssemblyAI API Reference for the complete request and response schema.

Models & features

Guides

Migration guide: Auto Chapters

Quick upgrade

What changes

Mapping the per-chapter fields

Side-by-side code comparison

Reading the response

Choosing `summary_type`

Controlling quality with `effort`

Pricing

If you also need action items

Next steps

​Quick upgrade

​What changes

​Mapping the per-chapter fields

​Side-by-side code comparison

​Reading the response

​Choosing summary_type

​Controlling quality with effort

​Pricing

​If you also need action items

​Next steps

Quick upgrade

What changes

Mapping the per-chapter fields

Side-by-side code comparison

Reading the response

Choosing `summary_type`

Controlling quality with `effort`

Pricing

If you also need action items

Next steps