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.

intent

Use this skill when a user asks about installing, configuring, or initializing the Gladia SDK (JS/TS or Python). This includes API key setup, region selection, retry/timeout configuration, WebSocket settings, error handling patterns, choosing between SDK and raw API, or browser-based integration questions. The SDK is the recommended default for all Gladia integrations. do not use this skill if the user is asking about a specific transcription use case (pre-recorded files or live streaming) - start with the relevant use-case skill instead (gladia-pre-recorded-transcription or gladia-live-transcription), which reference back here for setup details.

inputs

Required

• gladia api key: obtain from https://console.gladia.io. pass via apiKey parameter or set environment variable GLADIA_API_KEY. if missing, client initialization fails with 401 error.
• language preference (js/ts or python): determine which sdk to install based on user's stack.

Optional

• region: set via region parameter or GLADIA_REGION env var. valid values: eu-west (default), us-west. affects api endpoint and latency.
• network configuration: http timeout (ms), retry count, websocket timeout for live sessions. see ./references/client-config.md for defaults.
• runtime environment: node.js 20+ or bun (js/ts), python 3.10+ (python). browser environment for js/ts requires esm/iife bundle.
• proxy setup (optional, js only): required if embedding sdk in browser front-end to hide api key server-side.

External Connections

• gladia api: https://api.gladia.io (default, configurable via GLADIA_API_URL or apiUrl parameter). requires outbound https and websocket connectivity.
• npm registry (js/ts install): for @gladiaio/sdk package.
• pypi (python install): for gladiaio-sdk package.

procedure

1. Choose SDK Language and Install

Input: user's project language and runtime.

Action: install appropriate sdk package.

JS/TypeScript (requires node.js 20+, bun, or browser support):

npm install @gladiaio/sdk

Python (requires python 3.10+):

pip install gladiaio-sdk

Output: package installed in node_modules/ or site-packages/. verify with npm list @gladiaio/sdk or pip show gladiaio-sdk.

---

2. Obtain and Store API Key

Input: user's gladia console credentials.

Action: retrieve api key from https://console.gladia.io and store securely.

Output: api key string (format: alphanumeric, ~40 chars). store in environment variable GLADIA_API_KEY or pass directly to client constructor in step 3.

Note: never embed api key in browser-side code; use backend proxy (see decision points).

---

3. Initialize Client

Input: api key, optional region, optional timeout/retry config.

JS/TypeScript:

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

const client = new GladiaClient({
  apiKey: process.env.GLADIA_API_KEY, // or hardcoded for non-public code
  region: "eu-west", // optional, defaults to eu-west
  httpTimeout: 30000, // optional, ms
  httpRetry: { maxRetries: 3, backoff: "exponential" }, // optional
  wsTimeout: 60000, // optional, for live sessions
  wsRetry: { maxRetries: 5 }, // optional
});

Python:

from gladiaio_sdk import GladiaClient

client = GladiaClient(
    api_key=os.getenv("GLADIA_API_KEY"),
    region="eu-west",
    http_timeout=30000,
    http_retry={"max_retries": 3, "backoff": "exponential"},
    ws_timeout=60000,
    ws_retry={"max_retries": 5},
)

Output: client object ready to call sub-clients (preRecorded() / prerecorded(), liveV2() / live(), or async variants in python).

Common Issues: if api key is invalid or missing, client construction succeeds but the first api call returns 401 error.

---

4. Access Sub-Client for Your Use Case

Input: client object from step 3, use case type (pre-recorded or live).

Action: call appropriate sub-client method.

JS/TypeScript:

• Pre-recorded: client.preRecorded()
• Live: client.liveV2()

Python (sync):

• Pre-recorded: client.prerecorded()
• Live: client.live()

Python (async):

• Pre-recorded: client.prerecorded_async()
• Live: client.live_async()

Output: sub-client object (PreRecordedV2Client, LiveV2Client, or async variants). proceed to relevant use-case skill for transcription details.

---

5. Configure Audio Input and Transcription Options (Optional, At This Step)

Input: audio source (local file, url, blob/file, or stream), transcription options (language, model, features).

Action: prepare audio input and options dict/object. for pre-recorded: transcribe(audio, options) auto-uploads local files. for live: startSession(options) sets session config.

Output: audio reference and options ready to pass to sub-client methods. (detailed procedure for this step is in gladia-pre-recorded-transcription or gladia-live-transcription).

---

6. Handle Errors and Retries

Input: potential api/network errors during transcription.

Action: wrap api calls in try-catch (js/ts) or try-except (python).

JS/TypeScript:

try {
  const result = await client.preRecorded().transcribe("./audio.mp3");
} catch (error) {
  if (error.message.includes("401")) {
    console.error("invalid api key");
  } else if (error.message.includes("timeout")) {
    console.error("request timed out, will retry");
  } else {
    console.error("unexpected error:", error);
  }
}

Python:

from gladiaio_sdk import GladiaClient, HttpError

try:
    result = client.prerecorded().transcribe("audio.mp3")
except HttpError as e:
    if e.status_code == 401:
        print("invalid api key")
    elif e.status_code == 429:
        print("rate limited, backoff required")
except TimeoutError:
    print("request timeout, retry manually")
except Exception as e:
    print(f"unexpected error: {e}")

Output: errors caught and logged. sdk automatically retries transient failures (5xx, timeout) up to max retries; non-transient errors (4xx auth, validation) fail immediately.

Note: api rate limits (429) require client-side backoff; sdk does not auto-retry 429.

---

decision points

SDK vs Raw API

if user is building a js/ts or python project then use the SDK (always). sdk handles type safety, retry logic, polling, and audio upload.

if user needs custom http client or middleware (e.g., instrumentation, custom logging) then use sdk first; configure via httpHeaders and httpTimeout. fall back to raw rest only if sdk config is insufficient.

if user's language has no official sdk (go, java, rust, c#, etc.) then use raw rest/websocket. see gladia-api-reference for raw endpoint docs.

if user explicitly requests raw http calls or is writing a ci script / curl one-off then raw rest is acceptable. for terminal one-offs, prefer gladia-using-cli if available.

default: when in doubt, use the sdk.

---

API Key Exposure (Browser Context)

if user is embedding sdk in browser-side javascript then do NOT embed api key directly in front-end code. instead, set up a backend proxy: front-end calls your own backend endpoint, which forwards requests to gladia api with the key server-side. see ./references/javascript.md for proxy pattern code.

if api key is accidentally exposed (committed to git, logged, or visible in network tab) then immediately rotate key in console at https://console.gladia.io. revoked keys cannot be used even if copied.

---

Node.js WebSocket Dependency (JS SDK < Node 22)

if user is using node.js < 22 for live sessions (which require websocket) then install the ws peer dependency manually: npm install ws. node.js 22+ has native websocket.

if user runs live session without ws on node < 22 then session fails silently (no error at time of startSession(), error surfaces on first sendAudio()).

---

Python Async in Sync Context

if user calls client.prerecorded_async() or client.live_async() from synchronous code then error: RuntimeError: no running event loop. solution: either (a) use sync client (client.prerecorded(), client.live()), or (b) wrap entire script in asyncio.run().

if user is inside an async def function then use async clients (client.prerecorded_async(), client.live_async()).

---

Region and Endpoint Selection

if user is in europe or latency to us is unacceptable then set region: "eu-west" (default). api endpoint: eu-west datacenter.

if user is in north america or eu latency is too high then set region: "us-west". api endpoint: us-west datacenter.

if user needs to override api url (e.g., reverse proxy, custom deployment) then set apiUrl parameter or GLADIA_API_URL env var. default: https://api.gladia.io.

---

Timeout and Retry Tuning

if user experiences frequent timeout errors on slow networks or large files then increase httpTimeout (default 30000 ms). example: httpTimeout: 120000 for 2-minute timeout.

if user experiences 5xx or transient network errors then sdk auto-retries up to maxRetries times (default 3 for http, 5 for websocket). increase if needed: httpRetry: { maxRetries: 5 }.

if user experiences 429 (rate limit) errors then sdk does not auto-retry 429. implement client-side exponential backoff (wait 1s, 2s, 4s, etc. before retrying). gladia rate limits reset hourly.

---

output contract

Client Initialization Output

• type: GladiaClient object (js/ts and python).
• properties: apiKey, region, apiUrl, httpTimeout, httpRetry, wsTimeout, wsRetry (all set to provided or default values).
• ready to use: sub-client methods (preRecorded(), liveV2(), etc.) callable without error.

Pre-Recorded Sub-Client Methods

Available methods: transcribe(audio, options), uploadFile(audio), create(options), createAndPoll(options), poll(jobId, config), get(jobId), delete(jobId), getFile(jobId).

Live Sub-Client Methods

Available methods: startSession(options) (returns LiveV2Session object), get(sessionId), delete(sessionId), getFile(sessionId).

Live Session Methods

Available methods: sendAudio(chunk), stopRecording(), endSession(), getSessionId().

Type Exports

Both sdks export request/response types:

JS/TypeScript:

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

Python:

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

Environment Variables Set

Variable	Value
GLADIA_API_KEY	api key string (if used)
GLADIA_REGION	eu-west or us-west (if used)
GLADIA_API_URL	https://api.gladia.io or custom

---

outcome signal

success: client object created without error, and user can call sub-client methods.

verification checklist:

1. sdk installed: npm list @gladiaio/sdk (js) or pip show gladiaio-sdk (python) returns package info with version.
2. api key configured: environment variable GLADIA_API_KEY set or passed to client constructor.
3. client instantiation succeeds: const client = new GladiaClient(...) or client = GladiaClient(...) completes without throwing.
4. sub-client accessible: client.preRecorded() (js) or client.prerecorded() (python) returns sub-client object.
5. no 401 error on first api call: if 401 occurs, api key is invalid or missing. retry step 2.
6. region correctly set: check client object property region matches user's choice (default eu-west).
7. timeout/retry config applied: if custom timeouts or retries were specified, verify they are set on client object.

common failure modes and fixes:

• "module not found" or ImportError: sdk not installed. run npm/pip install from step 1.
• 401 unauthorized: api key invalid, expired, or missing. verify key in console and update environment variable.
• timeout errors on live session without ws (node < 22): install npm install ws.
• "preRecorded is not a function" (js) or AttributeError: 'GladiaClient' object has no attribute 'prerecorded' (python): incorrect method name. js uses camelCase (preRecorded, liveV2), python uses snake_case (prerecorded, live).
• promise not awaited (js): forgot await on async call. all js sdk methods return promises.

---

references

• client config reference - full client configuration options, defaults, and timeouts.
• javascript sdk patterns - js/ts-specific guide including browser, proxy, file/blob, and node version notes.
• python sdk patterns - python-specific guide including sync/async, typed requests, and dependency info.
• sdk versions - current sdk versions (auto-synced).
• gladia-pre-recorded-transcription - pre-recorded transcription options, response structure, and audio intelligence config.
• gladia-live-transcription - live session config, audio streaming, and websocket event handling.
• gladia-using-cli - terminal transcription with gladia-cli; cli vs sdk routing.
• gladia-troubleshooting - common errors, gotchas, and verification checklist.
• sdk integration guide - official docs.
• js sdk on npm.
• python sdk on pypi.
• sdk source code.
• code samples.

---

key architecture

Client Structure

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

Audio