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 \x3C 22 without the ws peer dependency: the JS SDK requires the ws package for WebSocket on Node \x3C 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