Migration guide: Summarization

This guide walks through the process of upgrading from the deprecated top-level summarization parameter to Summarization under Speech Understanding.

This guide is for existing accounts using the deprecated summarization parameter. If you’re adding summaries for the first time, go straight to the Summarization documentation — none of the legacy parameters below apply to you.

We upgraded Summarization rather than replacing it. It now runs on large language models through our LLM Gateway, which brings three improvements over the deprecated version:

Topic-based summaries instead of one block of text. You get a set of summaries, each covering a distinct topic, rather than a single string for the whole file.
Headlines and timestamps on every summary. Each topic carries its own headline and start/end times, so you can link summaries back to the audio — which also replaces the old headline and gist summary types.
Quality you control. The new effort parameter lets you spend more processing on harder content, in place of the fixed summary_model choice.

Your existing API key and endpoint stay the same. The changes are to the request shape, the response location, and the response structure.

Quick upgrade

Move summarization into speech_understanding.request, drop summary_model, and keep summary_type:

// Before (deprecated)
{
  "audio_url": "https://example.com/audio.mp3",
  "summarization": true,
  "summary_model": "informative",
  "summary_type": "bullets"
}

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

That’s it for the request. But the response moves too — read the summary from speech_understanding.response.summarization instead of the top-level summary field, and expect an array of topic summaries rather than a single string. 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 Summarization	Speech Understanding Summarization	Action required
Where it’s set	Top-level `summarization: true`	`speech_understanding.request.summarization`	Nest the parameter under `speech_understanding.request`
`summarization`	Boolean flag	Object holding the summary options	Replace `true` with an object (`{}` for defaults)
`summary_model`	`informative`, `conversational`, `catchy`	Not a parameter — summaries run on LLMs through the LLM Gateway	Remove `summary_model` from your request
`summary_type`	`bullets`, `bullets_verbose`, `gist`, `headline`, `paragraph`	`bullets` or `paragraph`	Map your existing value to `bullets` or `paragraph` (see the table below)
`effort`	Not supported	`low` (default) or `medium`	New capability (optional) — set `medium` for harder content
Response field	Top-level `summary`	`speech_understanding.response.summarization`	Update your response parsing to read from the new path
Response shape	A single string	An object with `status`, `summary`, `summary_type`, and `effort`	Iterate over `summary`, an array of topic summaries
Per-summary data	None — one summary for the whole file	`headline`, `text`, `start`, and `end` per topic	New capability — use headlines and timestamps to link summaries back to audio
Pricing	Bundled with the deprecated model	$0.03 per hour of audio	Review your cost model

Mapping `summary_type`

Deprecated value	Use instead	Notes
`bullets`	`bullets`	Short, concise bullet-point summaries per topic
`bullets_verbose`	`paragraph`	`paragraph` gives the longer, more detailed output
`paragraph`	`paragraph`	Now returned per topic rather than as one block
`gist`	`bullets`	Use the per-topic `headline` fields for the shortest overview
`headline`	`bullets`	Every topic summary now includes its own `headline`

Side-by-side code comparison

Below is a side-by-side comparison of summarizing a pre-recorded audio file with the deprecated parameter and with Speech Understanding:

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,
    "summarization": True,
    "summary_model": "informative",
    "summary_type": "bullets"
}

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)

print(transcription_result["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": "bullets"
            }
        }
    }
}

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,
  summarization: true,
  summary_model: "informative",
  summary_type: "bullets",
};

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

console.log(transcriptionResult.summary);

const data = {
  audio_url: audioUrl,
  speech_understanding: {
    request: {
      summarization: {
        summary_type: "bullets",
      },
    },
  },
};

// ... 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 one string on the top-level summary field. Speech Understanding returns an object on speech_understanding.response.summarization, with the summaries 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": "bullets",
    "effort": "low"
}

Things to know when updating your response handling:

summary is an array of topic-based summaries, not a single string. If you need one block of text, join the text fields.
start and end are timestamps in milliseconds, so you can link each summary back to the audio.
Each topic carries its own headline, which replaces the deprecated headline and gist summary types.
Check status for success before reading the summaries.

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": "bullets",
        "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

The upgraded Summarization is $0.03 per hour of audio. See Billing and pricing for full rates.

If you also need action items

Alongside the upgraded 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": "bullets" },
      "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: Summarization

Quick upgrade

What changes

Mapping `summary_type`

Side-by-side code comparison

Reading the response

Controlling quality with `effort`

Pricing

If you also need action items

Next steps

​Quick upgrade

​What changes

​Mapping summary_type

​Side-by-side code comparison

​Reading the response

​Controlling quality with effort

​Pricing

​If you also need action items

​Next steps

Quick upgrade

What changes

Mapping `summary_type`

Side-by-side code comparison

Reading the response

Controlling quality with `effort`

Pricing

If you also need action items

Next steps