Gladia Python SDK

1.0.1 · active · verified Thu Apr 16

The Gladia SDK for Python provides a robust interface to Gladia's Speech-to-Text (STT) API, enabling both real-time and pre-recorded audio transcription. It simplifies complex tasks such as audio file uploading, job creation, and result retrieval. The SDK integrates features like speaker diarization, language translation, PII redaction, and custom vocabulary to enhance transcription accuracy and utility. Currently at version 1.0.1, Gladia maintains an active development cycle for its SDKs and underlying API, with a focus on continuous improvement.

Common errors

```
ModuleNotFoundError: No module named 'gladia'
```
cause The Python package name on PyPI is `gladiaio-sdk`, but the top-level module to import is `gladia`.

fix Change your import statement from `import gladiaio_sdk` (or similar) to `from gladia import GladiaClient`.
```
ValueError: GLADIA_API_KEY environment variable not set or is default.
```
cause The Gladia API key was not provided or incorrectly set when initializing the `GladiaClient`.

fix Set the `GLADIA_API_KEY` environment variable (e.g., `export GLADIA_API_KEY="YOUR_KEY"`) before running your script, or pass the API key directly: `GladiaClient(api_key="YOUR_KEY")`.
```
gladia.exceptions.GladiaAPIError: {'status': 400, 'message': 'The provided audio URL is not accessible or invalid.'}
```
cause The `audio_source` provided to the `transcribe` method is either an invalid URL, a local path that doesn't exist or is inaccessible, or points to an unsupported file type. It could also be due to file size/duration limits.

fix Verify that the `audio_source` is a valid, publicly accessible URL (if remote) or a correct path to a supported local file. Check file size and duration against Gladia's API limits.

Warnings

breaking Gladia's API has transitioned from V1 to V2. While the SDK is designed to abstract these changes, users migrating from older API integrations (or SDK versions tied to V1) should consult the official migration guides. V1 API support will be deprecated.
Fix: Ensure you are using the latest `gladiaio-sdk` (version 1.0.0+) which targets API V2. Review Gladia's V1 to V2 migration guides for pre-recorded and live transcription if directly interacting with the API or using an older SDK.
gotcha For real-time (live) transcription, direct exposure of your Gladia API key in client-side applications (e.g., web or mobile frontends) is a security risk. It's best practice to initiate WebSocket sessions via a secure backend service to keep your API key private.
Fix: Implement a backend endpoint to handle the `gladiaClient.liveV2().startSession()` call. This backend will securely generate the WebSocket URL and token, which can then be safely passed to your client-side application for connection.
gotcha A single real-time transcription session has a maximum duration limit of 3 hours. Sessions exceeding this limit will be automatically terminated. For continuous transcription beyond 3 hours, new sessions must be initiated.
Fix: Monitor session duration for long-running real-time applications. Implement logic to gracefully stop the current session and start a new one before reaching the 3-hour limit, ensuring seamless continuity for your users.
gotcha Pre-recorded audio transcription has specific file limits: maximum length of 135 minutes (or 120 minutes for direct YouTube links, 4h15 for enterprise plans) and a maximum file size of 1000 MB. Attempting to transcribe files exceeding these limits will result in an error.
Fix: For audio files exceeding these limits, preprocess them by splitting them into smaller chunks (e.g., around 60 minutes each) before passing them to the SDK for transcription. Ensure your input audio source is valid and accessible.

Install

pip install gladiaio-sdk Install Gladia SDK

Imports

GladiaClient

wrong:

import gladiaio_sdk

correct:

from gladia import GladiaClient

Quickstart

This quickstart demonstrates how to transcribe a pre-recorded audio file or URL using the Gladia Python SDK. It initializes the client with an API key from environment variables and then calls the `transcribe` method, including examples of language configuration and custom vocabulary for enhanced accuracy.

import os
from gladia import GladiaClient

# Ensure GLADIA_API_KEY is set in your environment variables
gladia_api_key = os.environ.get("GLADIA_API_KEY")
if not gladia_api_key:
    raise ValueError("GLADIA_API_KEY environment variable not set. Please set your Gladia API key.")

gladia_client = GladiaClient(api_key=gladia_api_key)

# Replace with your audio file path or a publicly accessible URL
# Example: audio_source = "./path/to/your/audio.wav"
audio_source = "https://gladia.io/sample-audio/podcast_excerpt.mp3"

try:
    print(f"Transcribing audio from: {audio_source}")
    transcription = gladia_client.preRecorded().transcribe(
        audio_source,
        language_config={
            "languages": ["en", "fr"],
            "code_switching": True,
        },
        # Enable custom vocabulary for better accuracy on specific terms
        custom_vocabulary=True,
        custom_vocabulary_config={
            "vocabulary": ["Gladia", "Solaria", "Salesforce"],
        },
    )
    print("Transcription successful!")
    print(f"Full Transcript: {transcription.result.transcription.full_transcript}")
except Exception as e:
    print(f"An error occurred during transcription: {e}")

view raw JSON →