Getting started

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.

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.

Identifying the Model Used in Your Request

The API returns a field called speech_model_used that tells you which specific model was actually used to process your request.

NameParameterDescription
Universal-3 Prospeech_models=['universal-3-pro']Our highest accuracy model with fine-tuning support and customization via prompting.
Universal-2speech_models=['universal-2']Our highly accurate, fastest performing model with support across 99 languages.

Quickstart

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

1import requests
2import time
3
4base_url = "https://api.assemblyai.com"
5
6headers = {
7    "authorization": "<YOUR_API_KEY>"
8}
9
10data = {
11    "audio_url": "https://assembly.ai/wildfires.mp3",
12    "speech_models": ["universal-3-pro", "universal-2"],
13    "language_detection": True
14}
15
16url = base_url + "/v2/transcript"
17response = requests.post(url, json=data, headers=headers)
18
19transcript_id = response.json()['id']
20polling_endpoint = base_url + "/v2/transcript/" + transcript_id
21
22while 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.

1import requests
2import time
3
4base_url = "https://api.assemblyai.com"
5
6headers = {
7    "authorization": "<YOUR_API_KEY>"
8}
9
10data = {
11    "audio_url": "https://assembly.ai/wildfires.mp3",
12    "speech_models": ["universal-3-pro", "universal-2"],
13    "language_detection": True
14}
15
16url = base_url + "/v2/transcript"
17response = requests.post(url, json=data, headers=headers)
18
19transcript_id = response.json()['id']
20polling_endpoint = base_url + "/v2/transcript/" + transcript_id
21
22while 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:

1import requests
2import time
3
4base_url = "https://api.assemblyai.com"
5headers = {"authorization": "<YOUR_API_KEY>"}
6
7data = {
8    "audio_url": "https://assembly.ai/wildfires.mp3",
9    "speech_models": ["universal-3-pro", "universal-2"],
10    "language_detection": True
11}
12
13response = requests.post(base_url + "/v2/transcript", headers=headers, json=data)
14
15if response.status_code != 200:
16    print(f"Error: {response.status_code}, Response: {response.text}")
17    response.raise_for_status()
18
19transcript_json = response.json()
20transcript_id = transcript_json["id"]
21polling_endpoint = f"{base_url}/v2/transcript/{transcript_id}"
22
23while 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)