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

this skill walks you through installing, configuring, and initializing the official Gladia SDKs for JavaScript/TypeScript (@gladiaio/sdk) and Python (gladiaio-sdk). use it when someone asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling patterns, or whether to use the SDK vs raw API. the SDK is the recommended default for all Gladia integrations because it handles auth, retries, type safety, and WebSocket lifecycle automatically.

inputs

external connections:

• gladia api endpoint: https://api.gladia.io (configurable via GLADIA_API_URL env var or apiUrl param)
• gladia api key: required for auth. obtain from gladia dashboard. pass via GLADIA_API_KEY env var or apiKey parameter in client config
• gladia region: optional, set via GLADIA_REGION env var or region param (values: eu-west, us-west)

environment variables (optional):

• GLADIA_API_KEY: api authentication key
• GLADIA_API_URL: base api endpoint (default: https://api.gladia.io)
• GLADIA_REGION: datacenter region (default: inferred from API URL)

runtime requirements:

• javascript/typescript: node.js 20+ or bun or any modern browser (via esm/iife bundle). for node < 22 with live sessions, add ws peer dependency
• python: python 3.10+

optional peer dependencies:

• javascript (node < 22): ws package for native websocket support
• python: httpx, websockets, pyee (bundled with sdk)

procedure

1. choose your language and install the sdk

inputs: your project language (javascript/typescript or python)

javascript/typescript: run one of:

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

python: run one of:

pip install gladiaio-sdk
uv add gladiaio-sdk

if on node.js < 22 and planning to use live sessions, also run:

npm install ws

outputs: sdk installed in project dependencies. verify by checking node_modules/@gladiaio/sdk (js) or running pip show gladiaio-sdk (python).

2. obtain your api key

inputs: access to gladia dashboard at https://dashboard.gladia.io

go to your gladia account dashboard and generate or copy your api key. store it securely (never commit to version control). you can either set the GLADIA_API_KEY environment variable or pass it directly in client initialization (step 3).

outputs: api key ready for use in client config

3. initialize the gladia client

inputs: api key (from step 2), optional region and timeout settings

javascript/typescript:

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

const client = new GladiaClient({
  apiKey: "your-api-key",  // or omit to read from GLADIA_API_KEY env var
  region: "eu-west",       // optional: eu-west or us-west
  httpTimeout: 30000,      // optional: ms timeout for http requests (default: 30000)
  httpRetry: { maxRetries: 3, backoffMultiplier: 2 }, // optional retry config
});

python (sync):

from gladiaio_sdk import GladiaClient

client = GladiaClient(
    api_key="your-api-key",  # or omit to read from GLADIA_API_KEY env var
    region="eu-west",        # optional: eu-west or us-west
)

python (async):

from gladiaio_sdk import GladiaClient

client = GladiaClient(
    api_key="your-api-key",
    region="eu-west",
)

# then use client.prerecorded_async() or client.live_async()

outputs: client object ready for pre-recorded or live transcription. verify by checking that client is not null and has methods like preRecorded() (js) or prerecorded() (python).

4. access the appropriate sub-client (pre-recorded or live)

inputs: client object from step 3, use case (pre-recorded transcription or live streaming)

for pre-recorded transcription:

// JavaScript/TypeScript
const preRecordedClient = client.preRecorded();

# Python (sync)
pre_recorded_client = client.prerecorded()

# Python (async)
pre_recorded_client = client.prerecorded_async()

for live transcription:

// JavaScript/TypeScript
const liveClient = client.liveV2();

# Python (sync)
live_client = client.live()

# Python (async)
live_client = client.live_async()

outputs: sub-client object (PreRecordedV2Client or LiveV2Client) with methods like transcribe(), startSession(), etc.

5. configure audio input and transcription options (optional)

inputs: audio source (file path, url, or blob/file object), transcription options (language, model, features)

the sdk accepts multiple audio input formats:

• local file path (string or path object): automatically uploaded via /v2/upload
• http(s) url: passed directly as audio_url, no upload
• file/blob (browser only): passed as bytes
• binary file object (python only)

transcription options are passed as a dict or object and include language, model, custom_vocabulary, summarization, chaining, etc. see ./references/client-config.md for full list.

outputs: audio input and options ready for step 6

6. call the appropriate transcription method

inputs: sub-client (from step 4), audio input and options (from step 5)

pre-recorded (high-level, one-liner):

// JavaScript/TypeScript
const result = await client.preRecorded().transcribe("./audio.mp3", {
  language: "en",
  model: "nova-2",
});

# Python (sync)
result = client.prerecorded().transcribe("audio.mp3", {
    "language": "en",
    "model": "nova-2",
})

# Python (async)
result = await client.prerecorded_async().transcribe("audio.mp3", {
    "language": "en",
    "model": "nova-2",
})

pre-recorded (manual: create, poll, get):

// JavaScript/TypeScript
const job = await client.preRecorded().create({
  audio_url: "https://example.com/audio.mp3",
  language: "en",
});
const pollResult = await client.preRecorded().poll(job.id, {
  interval: 1000,  // ms between polls
  timeout: 300000, // max time to wait
});
const finalResult = await client.preRecorded().get(job.id);

live (start session and stream):

// JavaScript/TypeScript
const session = await client.liveV2().startSession({
  language: "en",
  model: "nova-2",
});

// in your audio event loop:
await session.sendAudio(audioChunk); // chunk is bytes/buffer
await session.stopRecording();

// get results:
const results = await client.liveV2().get(session.getSessionId());

outputs: transcription result object (pre-recorded) or session object (live) with transcript, confidence, metadata, etc.

7. handle errors and inspect results

inputs: result or error from step 6

javascript/typescript:

try {
  const result = await client.preRecorded().transcribe("audio.mp3", options);
  console.log(result.transcription); // access transcript
} catch (error) {
  if (error.message.includes("401")) {
    console.error("invalid api key");
  } else if (error.message.includes("timeout")) {
    console.error("request timed out, consider raising httpTimeout");
  } else if (error.message.includes("429")) {
    console.error("rate limit hit, back off and retry");
  } else {
    console.error(`sdk error: ${error.message}`);
  }
}

python:

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

the sdk raises standard exceptions (HttpError, TimeoutError, AuthenticationError) that you can catch. check the exception message for http status codes (401 = invalid key, 429 = rate limit, 500+ = server error).

outputs: either successfully parsed result with transcription, utterances, confidence fields, or caught error logged/handled.

decision points

if using javascript/typescript in a browser (not node.js): use the esm or iife bundle (distributed automatically via npm). do not try to import node-only modules like fs. if you need to send your api key, use a backend proxy that handles auth server-side, not embedded in front-end code. see ./references/javascript.md.

if on node.js < 22 and planning to use live sessions (websocket): install the ws peer dependency: npm install ws. without it, websocket calls will fail silently at runtime.

if using python async clients (prerecorded_async(), live_async()): only call these inside an async def function with an active event loop. if you need synchronous code, use the regular sync clients (prerecorded(), live()).

if you need custom http headers, timeouts, or middleware: use the sdk config options: httpHeaders, httpTimeout, httpRetry for http; wsRetry, wsTimeout for websockets. if the sdk config is insufficient (e.g., you need a custom http agent or middleware), fall back to raw rest/websocket only as a last resort (see "when not to use" section of intent).

if the user is asking about a specific transcription use case (pre-recorded files or live streaming): start with ../pre-recorded-transcription/SKILL.md or ../live-transcription/SKILL.md instead. those skills reference back here for setup details.

if the user is asking about sdk vs raw api: use the sdk unless: (a) the language has no sdk (go, java, rust, etc.), (b) the user explicitly requests raw calls, or (c) it is a one-off ci script or curl test. in all other cases, default to the sdk.

if api key is missing or invalid (401 error): verify the key is set via GLADIA_API_KEY env var or passed in client config. regenerate the key in the dashboard if needed. never hardcode keys in source files.

if the request times out (408 or timeout exception): increase httpTimeout (default 30000 ms) or prerecordedTimeouts.polling (default 600000 ms). check your network connection and the gladia api status page. if timeouts persist, contact gladia support.

if you hit a 429 rate limit error: back off exponentially and retry. the sdk's httpRetry config handles this automatically with configurable backoffMultiplier and maxRetries.

output contract

successful execution produces:

pre-recorded transcription result: a PreRecordedV2Response object (or dict) with fields:

• id: job id (string)
• status: "done" (string)
• transcription: full transcript text (string)
• utterances: array of utterance objects, each with start, end, confidence, speaker, text
• language: detected or provided language code (string)
• duration: audio duration in seconds (number)
• metadata: any custom metadata passed in request

live transcription session result: a LiveV2Session object (or dict) with fields:

• id: session id (string)
• status: "done" (string)
• audio_duration: total audio sent, in seconds (number)
• utterances: array of utterance objects (same structure as pre-recorded)
• metadata: any custom metadata from startSession()

error output: if the operation fails, the sdk raises an exception with:

• error.message: descriptive error string (may include http status code or timeout indicator)
• error.code: optional error code or http status (e.g., 401, 429, 500)

results are returned in-memory (not written to disk). if you need to persist results, save them to your own database or file after step 7.

outcome signal

you know the skill worked when:

1. no errors thrown: the sdk methods execute without throwing 401, timeout, or other exceptions
2. result object received: in pre-recorded mode, you receive a PreRecordedV2Response with a non-null transcription field; in live mode, you receive a session result with utterances array
3. transcript is readable: the transcription field or utterances[].text contains actual speech-to-text output (not empty, not error messages)
4. metadata present: optional fields like language, duration, confidence are populated, confirming the api processed your request
5. no silent failures: if you used javascript, all await keywords are present and the code actually pauses for the api call; in python, no AttributeError on method names like prerecorded() vs pre_recorded()

if initialization succeeds but transcription fails with a 401, regenerate your api key and reinitialize. if timeouts occur, increase the timeout values and retry. if you see "is not a function" or AttributeError, check the exact method name for your language (js uses camelCase like preRecorded(), python uses snake_case like prerecorded()).

---

credits: original from clawhub. enriched for implexa's 6-component skill standard with explicit decision points, edge cases (rate limits, timeouts, auth expiry, node version checks), and input/output contracts.