For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see For full documentation content, see For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at

Migration guide: Gladia to AssemblyAI

For the complete documentation index, see llms.txt

This guide walks through the process of migrating from Gladia to AssemblyAI for transcribing pre-recorded audio.

Get started

Before we begin, make sure you have an AssemblyAI account and an API key. You can sign up for a free account and get your API key from your dashboard. If you'd prefer to use one of our official SDKs, check our documentation for the full list of available SDKs.

The Gladia documentation uses cURL commands to demonstrate API usage. In this guide, we will use Python code snippets to illustrate the same functionality across both APIs. If you prefer to use cURL, you can find the equivalent commands in the AssemblyAI API Reference.

Side-by-side code comparison

Below is a side-by-side comparison of a basic snippet to transcribe pre-recorded audio with Gladia and AssemblyAI:

import requests
import time

base_url = ""

headers = {
    "x-gladia-key": "<YOUR_API_KEY>"
}

with open("./my-audio.mp3", "rb") as f:
    files = {"audio": ("my-audio.mp3", f, "audio/mp3")}
    response = requests.post(base_url + "/v2/upload",
                            headers=headers,
                            files=files)

upload_url = response.json()["audio_url"]

data = {
    "audio_url": upload_url # You can also use a URL to an audio or video file on the web.
}

url = base_url + "/v2/pre-recorded"
response = requests.post(url, json=data, headers=headers)

transcript_id = response.json()['id'] # You can also use response.json()['result_url'] to get the polling_endpoint directly.
polling_endpoint = url + "/" + transcript_id

while True:
    transcript = requests.get(polling_endpoint, headers=headers).json()

    if transcript['status'] == 'done':
        print(f"Full Transcript: {transcript['result']['transcription']['full_transcript']}")
        break

    elif transcript['status'] == 'error':
        raise RuntimeError(f"Transcription failed: {transcript['error_code']}")

    else:
        time.sleep(3)

import requests
import time

base_url = ""

headers = {
    "authorization": "<YOUR_API_KEY>"
}

with open("./my-audio.mp3", "rb") as f:
  response = requests.post(base_url + "/v2/upload",
                          headers=headers,
                          data=f)

upload_url = response.json()["upload_url"]

data = {
    "audio_url": upload_url, # You can also use a URL to an audio or video file on the web
    "speech_models": ["universal-3-pro", "universal-2"],
    "language_detection": True,
}

url = base_url + "/v2/transcript"
response = requests.post(url, json=data, headers=headers)

transcript_id = response.json()['id']
polling_endpoint = url + "/" + transcript_id

while True:
    transcript = requests.get(polling_endpoint, headers=headers).json()

    if transcript['status'] == 'completed':
        print(f"Full Transcript: {transcript['text']}")
        break

    elif transcript['status'] == 'error':
        raise RuntimeError(f"Transcription failed: {transcript['error']}")

    else:
        time.sleep(3)

Installation and authentication

import requests
import time

base_url = ""

headers = {
    "x-gladia-key": "<YOUR_API_KEY>"
}

import requests
import time

base_url = ""

headers = {
    "authorization": "<YOUR_API_KEY>"
}

When migrating from Gladia to AssemblyAI, you'll first need to handle authentication:

Get your API key from your AssemblyAI dashboard.

Things to know:

• Store your API key securely in an environment variable.
• We support the ability to create multiple API keys and projects to help you track and manage seperate environments.

Gladia uses the x-gladia-key HTTP header for authentication, while AssemblyAI uses the authorization header.

Audio file sources

You can provide either a locally stored audio file or a publicly accessible URL.

# Local Files
with open("./my-audio.mp3", "rb") as f:
    files = {"audio": ("my-audio.mp3", f, "audio/mp3")}
    response = requests.post(base_url + "/v2/upload",
                            headers=headers,
                            files=files)

upload_url = response.json()["audio_url"]

data = {
    "audio_url": upload_url
}

#Public URLs
audio_file = ""

data = {
    "audio_url": audio_file
}

# Local Files
with open("./my-audio.mp3", "rb") as f:
  response = requests.post(base_url + "/v2/upload",
                          headers=headers,
                          data=f)

upload_url = response.json()["upload_url"]

data = {
    "audio_url": upload_url,
    "speech_models": ["universal-3-pro", "universal-2"],
    "language_detection": True,
}

# Public URLs
audio_file = ""

data = {
    "audio_url": audio_file,
    "speech_models": ["universal-3-pro", "universal-2"],
    "language_detection": True,
}

Basic transcription and polling the transcription status

Make a POST request to the /v2/pre-recorded endpoint.

url = base_url + "/v2/pre-recorded"
response = requests.post(url, json=data, headers=headers)

Every few seconds, make a GET request to the /v2/pre-recorded/:transcript_id endpoint until the transcription status is 'done'.

transcript_id = response.json()['id'] # You can also use response.json()['result_url'] to get the polling_endpoint directly.
polling_endpoint = url + "/" + transcript_id

while True:
    transcript = requests.get(polling_endpoint, headers=headers).json()

    if transcript['status'] == 'done':
        print(f"Full Transcript: {transcript['result']['transcription']['full_transcript']}")
        break

    elif transcript['status'] == 'error':
        raise RuntimeError(f"Transcription failed: {transcript['error_code']}")

    else:
        time.sleep(3)

Make a POST request to the /v2/transcript endpoint.

url = base_url + "/v2/transcript"
response = requests.post(url, json=data, headers=headers)

Every few seconds, make a GET request to the /v2/transcript/:transcript_id endpoint until the transcription status is 'completed'.

transcript_id = response.json()['id']
polling_endpoint = url + "/" + transcript_id

while True:
    transcript = requests.get(polling_endpoint, headers=headers).json()

    if transcript['status'] == 'completed':
        print(f"Full Transcript: {transcript['text']}")
        break

    elif transcript['status'] == 'error':
        raise RuntimeError(f"Transcription failed: {transcript['error']}")

    else:
        time.sleep(3)

Note that our APIs possible values for transcription status are queued, processing, completed, and error. Check out the AssemblyAI API Reference for the full list of possible transcription status values. If you'd rather not poll the API, you can use our SDKs which handle polling internally. Alternatively, you can also use webhooks to get notified when your transcript is complete.

Here are helpful things to know when migrating your audio input handling:

• Both AssemblyAI and Gladia allow you the option of uploading a local file or specifying a publicly accessible URL.
• There's no need to specify the audio format to AssemblyAI - it's auto-detected. AssemblyAI accepts almost every audio/video file type: here is a full list of all our supported file types
• For self-hosted or pre-signed URLs (i.e. S3), see our example in this cookbook.

Adding features

data = {
    "audio_url": upload_url,
    "diarization": True,                # Speaker diarization
    "chapterization": True,             # Auto chapter detection
    "named_entity_recognition": True    # Named entity detection
}

# Access speaker labels
for utterance in transcript['result']['transcription']['utterances']:
    print(f"Speaker {utterance['speaker']}: {utterance['text']}")

# Access auto chapters
for chapter in transcript['result']['chapterization']['results']:
    print(f"{chapter['start']} - {chapter['end']}: {chapter['headline']}")

# Access named entities
for entity in transcript['result']['named_entity_recognition']['results']:
    print(entity['text'])
    print(entity['entity_type'])
    print(f"Timestamp: {entity['start']} - {entity['end']}\n")

data = {
    "audio_url": upload_url,
    "speech_models": ["universal-3-pro", "universal-2"],
    "language_detection": True,
    "speaker_labels": True,     # Speaker diarization
    "auto_chapters": True,      # Auto chapter detection
    "entity_detection": True    # Named entity detection
}

# Access speaker labels
for utterance in transcript['utterances']:
    print(f"Speaker {utterance['speaker']}: {utterance['text']}")

# Access auto chapters
for chapter in transcript['chapters']:
    print(f"{chapter['start']} - {chapter['end']}: {chapter['headline']}")

# Access named entities
for entity in transcript['entities']:
    print(entity['text'])
    print(entity['entity_type'])
    print(f"Timestamp: {entity['start']} - {entity['end']}\n")

Key differences:

• Make sure to note any differences in parameters or response structure. If using Speaker Diarization, for example:
  • Parameters: AssemblyAI uses speaker_labels, while Gladia uses diarization.
  • Response: AssemblyAI uses transcript.utterances, while Gladia uses transcript.result.transcription.utterances.
• Make sure to review each API reference for the full list of parameters and response objects.
  • AssemblyAI API Reference
  • Gladia API Reference