> ## 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: 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](/docs/speech-understanding/summarization) — 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](/docs/llm-gateway/quickstart), 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`: ```json theme={null} // 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: ```python expandable theme={null} import requests import time base_url = "https://api.assemblyai.com" headers = {"authorization": ""} 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"]) ``` ```python expandable theme={null} import requests import time base_url = "https://api.assemblyai.com" headers = {"authorization": ""} 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: ```javascript theme={null} const data = { audio_url: audioUrl, summarization: true, summary_model: "informative", summary_type: "bullets", }; // ... submit and poll until status is "completed" console.log(transcriptionResult.summary); ``` ```javascript theme={null} 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: ```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": "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: ```json theme={null} { "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](/docs/billing-and-pricing) for full rates. ## If you also need action items Alongside the upgraded 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": "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](/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.