SDK Integration

Official SDKs for integrating Gladia's speech-to-text API. Both SDKs share the same design and are generated from the Gladia OpenAPI schema.

> The SDK is the default for all Gladia integrations. Always use the SDK unless there is a specific, documented reason not to (see decision guide below).

When to Use

• User asks about installing, configuring, or initializing the Gladia SDK
• Setting up API key, region, retry, timeout, or WebSocket configuration
• Questions about SDK architecture, client methods, or type exports
• Choosing between JS/TS and Python SDK, or between SDK and raw API
• Browser-based integration, proxy setup, or bundle format questions
• Error handling patterns for Gladia API responses

When NOT to use: If the user is asking about a specific transcription use case (pre-recorded files or live streaming), start with the relevant use-case skill (gladia-pre-recorded-transcription or gladia-live-transcription) instead — those skills reference back here for setup details.

When to Use SDK vs Raw API

When in doubt, use the SDK.

References

Consult these resources as needed:

• ./references/sdk-versions.md -- Current SDK versions (auto-synced by CI)
• ./references/client-config.md -- Full client configuration reference (all options, defaults, timeouts)
• ./references/javascript.md -- JS/TS-specific patterns (browser, proxy, File/Blob, Node requirements)
• ./references/python.md -- Python-specific patterns (sync/async, typed requests, httpx/websockets)
• ../gladia-pre-recorded-transcription/SKILL.md -- Pre-recorded transcription options, response structure, and audio intelligence config
• ../gladia-live-transcription/SKILL.md -- Live session config, audio streaming, and WebSocket event handling
• ../gladia-troubleshooting/SKILL.md -- Common errors, gotchas, and verification checklist

Installation

JavaScript / TypeScript

npm install @gladiaio/sdk
# or
bun add @gladiaio/sdk
# or
yarn add @gladiaio/sdk

Requires Node.js 20+ or Bun. Also works in browsers via ESM/IIFE bundles.

Python

pip install gladiaio-sdk
# or
uv add gladiaio-sdk

Requires Python 3.10+.

Client Initialization

JavaScript/TypeScript

import { GladiaClient } from "@gladiaio/sdk";

const client = new GladiaClient({
  apiKey: "your-api-key", // or set GLADIA_API_KEY env var
  region: "eu-west", // or set GLADIA_REGION (eu-west | us-west)
});

Python

from gladiaio_sdk import GladiaClient

client = GladiaClient(
    api_key="your-api-key",      # or set GLADIA_API_KEY env var
    region="eu-west",            # or set GLADIA_REGION
)

Environment Variables

Client Architecture

GladiaClient
├── preRecorded()  → PreRecordedV2Client    (JS)
│   prerecorded()  → PreRecordedV2Client    (Python)
│
├── liveV2()       → LiveV2Client           (JS)
│   live()         → LiveV2Client           (Python)
│
└── (Python only)
    ├── prerecorded_async() → AsyncPreRecordedV2Client
    └── live_async()        → AsyncLiveV2Client

Pre-Recorded Client Methods

Live Client Methods

Live Session Methods

Configuration Options

Key client options: apiKey, apiUrl, region, httpTimeout, httpRetry, wsRetry, wsTimeout, prerecordedTimeouts, liveTimeouts.

For the full config reference with all options and defaults, see ./references/client-config.md.

Audio Input Types

URLs are passed directly as audio_url without upload. Local files are automatically uploaded via /v2/upload.

Error Handling

JavaScript/TypeScript

try {
  const result = await client.preRecorded().transcribe("./audio.mp3", options);
} catch (error) {
  if (error.message.includes("401")) {
    console.error("Invalid API key");
  } else if (error.message.includes("timeout")) {
    console.error("Request timed out");
  }
}

Python

from gladiaio_sdk import GladiaClient

try:
    result = client.prerecorded().transcribe("audio.mp3", options)
except Exception as e:
    print(f"Error: {e}")

Python exports HttpError and TimeoutError for specific error handling.

Key Differences Between JS and Python

Type Exports

Both SDKs export all request/response types from the main package:

import type {
  LiveV2InitRequest,
  LiveV2WebSocketMessage,
  PreRecordedV2Response,
  PreRecordedV2TranscriptionOptions,
} from "@gladiaio/sdk";

from gladiaio_sdk import (
    LiveV2InitRequest,
    LiveV2WebSocketMessage,
    LiveV2LanguageConfig,
    LiveV2MessagesConfig,
    PreRecordedV2Response,
)

Common Mistakes

• Wrong sub-client method name between JS and Python: JS uses client.preRecorded() and client.liveV2(); Python uses client.prerecorded() and client.live(). Mixing the naming conventions causes "is not a function" / AttributeError at runtime.
• Forgetting await in JavaScript: every JS SDK method returns a Promise. Omitting await on transcribe(), startSession(), etc. lets the operation run silently in the background with no result or error surfaced to your code.
• API key exposed in browser-side code: never embed the API key directly in front-end JavaScript — it becomes publicly readable. Use a backend proxy that forwards requests with the key server-side. See ./references/javascript.md for the proxy pattern.
• Node.js < 22 without the ws peer dependency: the JS SDK requires the ws package for WebSocket on Node < 22, which lacks a native WebSocket. Without it, live sessions fail silently. Fix: npm install ws.
• Python async client in sync context: client.live_async() and client.prerecorded_async() cannot be called from synchronous code — they require an active event loop. Use the sync client (client.live(), client.prerecorded()) unless you are inside an async def.

Further Reading

• SDK integration guide
• JS SDK on npm
• Python SDK on PyPI
• SDK source code
• Code samples