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#

ScenarioApproachAny JS/TS or Python projectSDK — alwaysBrowser appSDK — JS SDK supports ESM/IIFE bundlesNeed custom HTTP client or middlewareSDK first; use httpHeaders / httpTimeout config. Fall back to raw REST only if SDK config is insufficientLanguage without an SDK (Go, Java, etc.)Raw REST/WebSocket (SDK unavailable)User explicitly requests raw callsRaw REST/WebSocketCI script or one-off curl testRaw REST is acceptableTerminal one-off with gladia-cli on PATHCLI — see gladia-using-cli

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-using-cli/SKILL.md -- Terminal transcription with gladia-cli; CLI vs SDK routing
• ../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#

bash

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#

bash

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

Requires Python 3.10+.

Client Initialization#

JavaScript/TypeScript#

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#

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#

VariablePurposeDefaultGLADIA_API_KEYAPI key for authentication—GLADIA_API_URLBase API URLhttps://api.gladia.io``GLADIA_REGIONDatacenter region—

Client Architecture#

text

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#

MethodPurposetranscribe(audio, options)High-level: upload + create + polluploadFile(audio)Upload local file to /v2/upload``create(options)Create transcription jobcreateAndPoll(options)Create + poll until donepoll(jobId, { interval, timeout })Poll until completeget(jobId)Get job status/resultsdelete(jobId)Delete job and datagetFile(jobId)Download original audio

Live Client Methods#

MethodPurposestartSession(options)Init session → returns LiveV2Sessionget(sessionId)Get completed session resultsdelete(sessionId)Delete session and datagetFile(sessionId)Download session audio

Live Session Methods#

MethodPurposesendAudio(chunk)Stream audio bytes to the sessionstopRecording()End recording, trigger post-processingendSession()Force close without post-processinggetSessionId()Await session ID (async)

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#

InputJS/TSPythonLocal file path (string)Node onlyYesPath object—YesHTTP(S) URLYesYesFile / BlobBrowser—Binary file object ( BinaryIO)—Yes

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

Error Handling#

JavaScript/TypeScript#

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#

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#

AspectJavaScript/TypeScriptPythonAsync modelPromise-based (async only)Sync + async (separate clients)NamingcamelCase ( preRecorded, sendAudio)snake_case ( prerecorded, send_audio)Browser supportYes (ESM, CJS, IIFE)No (server only)RuntimeNode 20+, Bun, browsersPython 3.10+Dependencies0 runtime deps (optional ws for Node <22)httpx, websockets, pyeeOptions formatPlain objects (snake_case keys)Dataclasses or dictsUntyped APItranscribeUntyped(), createUntyped()Dict accepted on most methods

Type Exports#

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

typescript

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

python

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