Auto Chapters

Supported regions

US & EU

Generate chapter summaries from your audio transcripts using LLM Gateway. This approach gives you full control over how chapters are created and summarized.

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

Quickstart

Python

JavaScript

1 import requests
2 import time
3 
4 base_url = "https://api.assemblyai.com"
5 headers = {"authorization": "<YOUR_API_KEY>"}
6 
7 # Step 1: Transcribe your audio file
8 audio_url = "https://assembly.ai/wildfires.mp3"
9 
10 data = {
11     "audio_url": audio_url,
12     "speech_models": ["universal-3-pro", "universal-2"],
13     "language_detection": True
14 }
15 
16 response = requests.post(base_url + "/v2/transcript", json=data, headers=headers)
17 transcript_id = response.json()['id']
18 polling_endpoint = base_url + "/v2/transcript/" + transcript_id
19 
20 while True:
21     transcription_result = requests.get(polling_endpoint, headers=headers).json()
22     if transcription_result['status'] == 'completed':
23         break
24     elif transcription_result['status'] == 'error':
25         raise RuntimeError(f"Transcription failed: {transcription_result['error']}")
26     else:
27         time.sleep(3)
28 
29 # Step 2: Get paragraphs from the transcript
30 paragraphs = requests.get(polling_endpoint + '/paragraphs', headers=headers).json()['paragraphs']
31 
32 # Step 3: Combine paragraphs into groups for chapter summaries
33 combined_paragraphs = []
34 step = 2  # Adjust to control chapter length
35 
36 for i in range(0, len(paragraphs), step):
37     paragraph_group = paragraphs[i : i + step]
38     start = paragraph_group[0]['start']
39     end = paragraph_group[-1]['end']
40     text = " ".join(p['text'] for p in paragraph_group)
41     combined_paragraphs.append({"text": text, "start": start, "end": end})
42 
43 # Step 4: Generate chapter summaries with LLM Gateway
44 for chapter in combined_paragraphs:
45     llm_gateway_data = {
46         "model": "claude-sonnet-4-6",
47         "messages": [
48             {"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']}"}
49         ],
50         "max_tokens": 500
51     }
52 
53     response = requests.post(
54         "https://llm-gateway.assemblyai.com/v1/chat/completions",
55         headers=headers,
56         json=llm_gateway_data
57     )
58 
59     result = response.json()["choices"][0]["message"]["content"]
60     print(f"{chapter['start']}-{chapter['end']}: {result}\n")

Example output

1 240-60890: 
2 Headline: Canadian Wildfire Smoke Triggers Air Quality Alerts Across the US
3 Gist: Wildfire smoke affects US air quality
4 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.
5 
6 62270-113214:
7 Headline: Baltimore Air Quality Reaches Unhealthy Levels Due to Particulate Matter
8 Gist: Dangerous particulate matter levels in Baltimore
9 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 or specify a JSON format in your prompt:

1 prompt = """For this section of a transcript, provide the following in JSON format:
2 {
3   "headline": "A single sentence headline",
4   "gist": "A few words summarizing the section",
5   "summary": "A one paragraph summary"
6 }
7 
8 Text: """ + chapter['text']

API reference

Step 1: Transcribe audio

$ 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:

$ curl https://api.assemblyai.com/v2/transcript/YOUR_TRANSCRIPT_ID/paragraphs \
> --header "Authorization: <YOUR_API_KEY>"

Step 3: Generate chapter summaries with LLM Gateway

$ 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.
`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 - Learn more about available models and features
Apply LLM Gateway to pre-recorded audio - General guide for using LLM Gateway with transcripts
Structured Outputs - Constrain responses to a specific JSON schema

Supported regions

US & EU

Generate chapter summaries from your audio transcripts using LLM Gateway. This approach gives you full control over how chapters are created and summarized.

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

Quickstart

Python

JavaScript

1 import requests
2 import time
3 
4 base_url = "https://api.assemblyai.com"
5 headers = {"authorization": "<YOUR_API_KEY>"}
6 
7 # Step 1: Transcribe your audio file
8 audio_url = "https://assembly.ai/wildfires.mp3"
9 
10 data = {
11     "audio_url": audio_url,
12     "speech_models": ["universal-3-pro", "universal-2"],
13     "language_detection": True
14 }
15 
16 response = requests.post(base_url + "/v2/transcript", json=data, headers=headers)
17 transcript_id = response.json()['id']
18 polling_endpoint = base_url + "/v2/transcript/" + transcript_id
19 
20 while True:
21     transcription_result = requests.get(polling_endpoint, headers=headers).json()
22     if transcription_result['status'] == 'completed':
23         break
24     elif transcription_result['status'] == 'error':
25         raise RuntimeError(f"Transcription failed: {transcription_result['error']}")
26     else:
27         time.sleep(3)
28 
29 # Step 2: Get paragraphs from the transcript
30 paragraphs = requests.get(polling_endpoint + '/paragraphs', headers=headers).json()['paragraphs']
31 
32 # Step 3: Combine paragraphs into groups for chapter summaries
33 combined_paragraphs = []
34 step = 2  # Adjust to control chapter length
35 
36 for i in range(0, len(paragraphs), step):
37     paragraph_group = paragraphs[i : i + step]
38     start = paragraph_group[0]['start']
39     end = paragraph_group[-1]['end']
40     text = " ".join(p['text'] for p in paragraph_group)
41     combined_paragraphs.append({"text": text, "start": start, "end": end})
42 
43 # Step 4: Generate chapter summaries with LLM Gateway
44 for chapter in combined_paragraphs:
45     llm_gateway_data = {
46         "model": "claude-sonnet-4-6",
47         "messages": [
48             {"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']}"}
49         ],
50         "max_tokens": 500
51     }
52 
53     response = requests.post(
54         "https://llm-gateway.assemblyai.com/v1/chat/completions",
55         headers=headers,
56         json=llm_gateway_data
57     )
58 
59     result = response.json()["choices"][0]["message"]["content"]
60     print(f"{chapter['start']}-{chapter['end']}: {result}\n")

Example output

1 240-60890: 
2 Headline: Canadian Wildfire Smoke Triggers Air Quality Alerts Across the US
3 Gist: Wildfire smoke affects US air quality
4 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.
5 
6 62270-113214:
7 Headline: Baltimore Air Quality Reaches Unhealthy Levels Due to Particulate Matter
8 Gist: Dangerous particulate matter levels in Baltimore
9 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 or specify a JSON format in your prompt:

1 prompt = """For this section of a transcript, provide the following in JSON format:
2 {
3   "headline": "A single sentence headline",
4   "gist": "A few words summarizing the section",
5   "summary": "A one paragraph summary"
6 }
7 
8 Text: """ + chapter['text']

API reference

Step 1: Transcribe audio

$ 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:

$ curl https://api.assemblyai.com/v2/transcript/YOUR_TRANSCRIPT_ID/paragraphs \
> --header "Authorization: <YOUR_API_KEY>"

Step 3: Generate chapter summaries with LLM Gateway

$ 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.
`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 - Learn more about available models and features
Apply LLM Gateway to pre-recorded audio - General guide for using LLM Gateway with transcripts
Structured Outputs - Constrain responses to a specific JSON schema

1	import requests
2	import time
3
4	base_url = "https://api.assemblyai.com"
5	headers = {"authorization": "<YOUR_API_KEY>"}
6
7	# Step 1: Transcribe your audio file
8	audio_url = "https://assembly.ai/wildfires.mp3"
9
10	data = {
11	"audio_url": audio_url,
12	"speech_models": ["universal-3-pro", "universal-2"],
13	"language_detection": True
14	}
15
16	response = requests.post(base_url + "/v2/transcript", json=data, headers=headers)
17	transcript_id = response.json()['id']
18	polling_endpoint = base_url + "/v2/transcript/" + transcript_id
19
20	while True:
21	transcription_result = requests.get(polling_endpoint, headers=headers).json()
22	if transcription_result['status'] == 'completed':
23	break
24	elif transcription_result['status'] == 'error':
25	raise RuntimeError(f"Transcription failed: {transcription_result['error']}")
26	else:
27	time.sleep(3)
28
29	# Step 2: Get paragraphs from the transcript
30	paragraphs = requests.get(polling_endpoint + '/paragraphs', headers=headers).json()['paragraphs']
31
32	# Step 3: Combine paragraphs into groups for chapter summaries
33	combined_paragraphs = []
34	step = 2 # Adjust to control chapter length
35
36	for i in range(0, len(paragraphs), step):
37	paragraph_group = paragraphs[i : i + step]
38	start = paragraph_group[0]['start']
39	end = paragraph_group[-1]['end']
40	text = " ".join(p['text'] for p in paragraph_group)
41	combined_paragraphs.append({"text": text, "start": start, "end": end})
42
43	# Step 4: Generate chapter summaries with LLM Gateway
44	for chapter in combined_paragraphs:
45	llm_gateway_data = {
46	"model": "claude-sonnet-4-6",
47	"messages": [
48	{"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']}"}
49	],
50	"max_tokens": 500
51	}
52
53	response = requests.post(
54	"https://llm-gateway.assemblyai.com/v1/chat/completions",
55	headers=headers,
56	json=llm_gateway_data
57	)
58
59	result = response.json()["choices"][0]["message"]["content"]
60	print(f"{chapter['start']}-{chapter['end']}: {result}\n")

1	240-60890:
2	Headline: Canadian Wildfire Smoke Triggers Air Quality Alerts Across the US
3	Gist: Wildfire smoke affects US air quality
4	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.
5
6	62270-113214:
7	Headline: Baltimore Air Quality Reaches Unhealthy Levels Due to Particulate Matter
8	Gist: Dangerous particulate matter levels in Baltimore
9	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.

1	prompt = """For this section of a transcript, provide the following in JSON format:
2	{
3	"headline": "A single sentence headline",
4	"gist": "A few words summarizing the section",
5	"summary": "A one paragraph summary"
6	}
7
8	Text: """ + chapter['text']

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

$	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
>	}'