Model selection

The speech_models parameter lets you specify which model to use for transcription. You can provide multiple models in priority order, and our system will automatically route to the best available model based on your request.

speech_models is required

You must include the speech_models parameter in every pre-recorded transcription request. There is no default model. If you omit speech_models, the request will fail.

Model routing behavior: The system attempts to use the models in priority order falling back to the next model when needed. For example, with ["universal-3-pro", "universal-2"], the system will try to use universal-3-pro for languages it supports (English, Spanish, Portuguese, French, German, and Italian), and automatically fall back to Universal for all other languages. This ensures you get the best performing transcription where available while maintaining the widest language coverage.

Recommended model

We recommend Universal-3 Pro for pre-recorded audio transcription. It delivers the highest accuracy and fastest transcription out of the box, with optional prompting for when you need more control. For the broadest language coverage (99 languages), use ["universal-3-pro", "universal-2"] to automatically fall back to Universal-2 for unsupported languages.

Python SDK

JavaScript SDK

API

Name	Parameter	Description	Best for
Universal-3 Pro	`speech_models=['universal-3-pro']`	Our highest accuracy, fastest model. Works great out of the box, with optional prompting for more control.	Highest-accuracy transcription, post-call analytics, meeting notetakers, medical transcription, domain-specific accuracy via prompting
Universal-2	`speech_models=['universal-2']`	Our accurate, cost-effective model with support across 99 languages.	High-volume batch transcription, 99-language coverage, price-sensitive workloads, fallback for unsupported U3 Pro languages

Quickstart

Python

Python SDK

JavaScript

JavaScript SDK

You can change the model by setting the speech_models in the POST request body:

1 import requests
2 import time
3 
4 base_url = "https://api.assemblyai.com"
5 
6 headers = {
7     "authorization": "<YOUR_API_KEY>"
8 }
9 
10 data = {
11     "audio_url": "https://assembly.ai/wildfires.mp3",
12     "speech_models": ["universal-3-pro", "universal-2"],
13     "language_detection": True
14 }
15 
16 url = base_url + "/v2/transcript"
17 response = requests.post(url, json=data, headers=headers)
18 
19 transcript_id = response.json()['id']
20 polling_endpoint = base_url + "/v2/transcript/" + transcript_id
21 
22 while True:
23   transcription_result = requests.get(polling_endpoint, headers=headers).json()
24 
25   if transcription_result['status'] == 'completed':
26     print(transcription_result['text'])
27     break
28 
29   elif transcription_result['status'] == 'error':
30     raise RuntimeError(f"Transcription failed: {transcription_result['error']}")
31 
32   else:
33     time.sleep(3)

Identify the model used

After transcription completes, you can check which model was actually used to process your request by reading the speech_model_used field. This is useful when you provide multiple models in the speech_models array, as the system may fall back to a different model depending on language support.

Python

Python SDK

JavaScript

JavaScript SDK

1 import requests
2 import time
3 
4 base_url = "https://api.assemblyai.com"
5 
6 headers = {
7     "authorization": "<YOUR_API_KEY>"
8 }
9 
10 data = {
11     "audio_url": "https://assembly.ai/wildfires.mp3",
12     "speech_models": ["universal-3-pro", "universal-2"],
13     "language_detection": True
14 }
15 
16 url = base_url + "/v2/transcript"
17 response = requests.post(url, json=data, headers=headers)
18 
19 transcript_id = response.json()['id']
20 polling_endpoint = base_url + "/v2/transcript/" + transcript_id
21 
22 while True:
23   transcription_result = requests.get(polling_endpoint, headers=headers).json()
24 
25   if transcription_result['status'] == 'completed':
26     print(f"Model used: {transcription_result['speech_model_used']}")
27     print(transcription_result['text'])
28     break
29 
30   elif transcription_result['status'] == 'error':
31     raise RuntimeError(f"Transcription failed: {transcription_result['error']}")
32 
33   else:
34     time.sleep(3)

Complete example

Here is the full working code that demonstrates model selection with error handling:

Python

Python SDK

JavaScript

JavaScript SDK

1 import requests
2 import time
3 
4 base_url = "https://api.assemblyai.com"
5 headers = {"authorization": "<YOUR_API_KEY>"}
6 
7 data = {
8     "audio_url": "https://assembly.ai/wildfires.mp3",
9     "speech_models": ["universal-3-pro", "universal-2"],
10     "language_detection": True
11 }
12 
13 response = requests.post(base_url + "/v2/transcript", headers=headers, json=data)
14 
15 if response.status_code != 200:
16     print(f"Error: {response.status_code}, Response: {response.text}")
17     response.raise_for_status()
18 
19 transcript_json = response.json()
20 transcript_id = transcript_json["id"]
21 polling_endpoint = f"{base_url}/v2/transcript/{transcript_id}"
22 
23 while True:
24     transcript = requests.get(polling_endpoint, headers=headers).json()
25     if transcript["status"] == "completed":
26         print(f"Model used: {transcript['speech_model_used']}")
27         print(f"\nTranscript:\n\n{transcript['text']}")
28         break
29     elif transcript["status"] == "error":
30         raise RuntimeError(f"Transcription failed: {transcript['error']}")
31     else:
32         time.sleep(3)

speech_models is required

You must include the speech_models parameter in every pre-recorded transcription request. There is no default model. If you omit speech_models, the request will fail.

Recommended model

Python SDK

JavaScript SDK

API

Name	Parameter	Description	Best for
Universal-3 Pro	`speech_models=['universal-3-pro']`	Our highest accuracy, fastest model. Works great out of the box, with optional prompting for more control.	Highest-accuracy transcription, post-call analytics, meeting notetakers, medical transcription, domain-specific accuracy via prompting
Universal-2	`speech_models=['universal-2']`	Our accurate, cost-effective model with support across 99 languages.	High-volume batch transcription, 99-language coverage, price-sensitive workloads, fallback for unsupported U3 Pro languages

Quickstart

Python

Python SDK

JavaScript

JavaScript SDK

You can change the model by setting the speech_models in the POST request body:

1 import requests
2 import time
3 
4 base_url = "https://api.assemblyai.com"
5 
6 headers = {
7     "authorization": "<YOUR_API_KEY>"
8 }
9 
10 data = {
11     "audio_url": "https://assembly.ai/wildfires.mp3",
12     "speech_models": ["universal-3-pro", "universal-2"],
13     "language_detection": True
14 }
15 
16 url = base_url + "/v2/transcript"
17 response = requests.post(url, json=data, headers=headers)
18 
19 transcript_id = response.json()['id']
20 polling_endpoint = base_url + "/v2/transcript/" + transcript_id
21 
22 while True:
23   transcription_result = requests.get(polling_endpoint, headers=headers).json()
24 
25   if transcription_result['status'] == 'completed':
26     print(transcription_result['text'])
27     break
28 
29   elif transcription_result['status'] == 'error':
30     raise RuntimeError(f"Transcription failed: {transcription_result['error']}")
31 
32   else:
33     time.sleep(3)

Identify the model used

Python

Python SDK

JavaScript

JavaScript SDK

1 import requests
2 import time
3 
4 base_url = "https://api.assemblyai.com"
5 
6 headers = {
7     "authorization": "<YOUR_API_KEY>"
8 }
9 
10 data = {
11     "audio_url": "https://assembly.ai/wildfires.mp3",
12     "speech_models": ["universal-3-pro", "universal-2"],
13     "language_detection": True
14 }
15 
16 url = base_url + "/v2/transcript"
17 response = requests.post(url, json=data, headers=headers)
18 
19 transcript_id = response.json()['id']
20 polling_endpoint = base_url + "/v2/transcript/" + transcript_id
21 
22 while True:
23   transcription_result = requests.get(polling_endpoint, headers=headers).json()
24 
25   if transcription_result['status'] == 'completed':
26     print(f"Model used: {transcription_result['speech_model_used']}")
27     print(transcription_result['text'])
28     break
29 
30   elif transcription_result['status'] == 'error':
31     raise RuntimeError(f"Transcription failed: {transcription_result['error']}")
32 
33   else:
34     time.sleep(3)

Complete example

Here is the full working code that demonstrates model selection with error handling:

Python

Python SDK

JavaScript

JavaScript SDK

1 import requests
2 import time
3 
4 base_url = "https://api.assemblyai.com"
5 headers = {"authorization": "<YOUR_API_KEY>"}
6 
7 data = {
8     "audio_url": "https://assembly.ai/wildfires.mp3",
9     "speech_models": ["universal-3-pro", "universal-2"],
10     "language_detection": True
11 }
12 
13 response = requests.post(base_url + "/v2/transcript", headers=headers, json=data)
14 
15 if response.status_code != 200:
16     print(f"Error: {response.status_code}, Response: {response.text}")
17     response.raise_for_status()
18 
19 transcript_json = response.json()
20 transcript_id = transcript_json["id"]
21 polling_endpoint = f"{base_url}/v2/transcript/{transcript_id}"
22 
23 while True:
24     transcript = requests.get(polling_endpoint, headers=headers).json()
25     if transcript["status"] == "completed":
26         print(f"Model used: {transcript['speech_model_used']}")
27         print(f"\nTranscript:\n\n{transcript['text']}")
28         break
29     elif transcript["status"] == "error":
30         raise RuntimeError(f"Transcription failed: {transcript['error']}")
31     else:
32         time.sleep(3)

1	import requests
2	import time
3
4	base_url = "https://api.assemblyai.com"
5
6	headers = {
7	"authorization": "<YOUR_API_KEY>"
8	}
9
10	data = {
11	"audio_url": "https://assembly.ai/wildfires.mp3",
12	"speech_models": ["universal-3-pro", "universal-2"],
13	"language_detection": True
14	}
15
16	url = base_url + "/v2/transcript"
17	response = requests.post(url, json=data, headers=headers)
18
19	transcript_id = response.json()['id']
20	polling_endpoint = base_url + "/v2/transcript/" + transcript_id
21
22	while True:
23	transcription_result = requests.get(polling_endpoint, headers=headers).json()
24
25	if transcription_result['status'] == 'completed':
26	print(transcription_result['text'])
27	break
28
29	elif transcription_result['status'] == 'error':
30	raise RuntimeError(f"Transcription failed: {transcription_result['error']}")
31
32	else:
33	time.sleep(3)