sdk-integration

Original：🇺🇸 English

Translated

Install and configure the official Gladia SDKs (@gladiaio/sdk for JS/TS, gladiaio-sdk for Python). Use when the user asks about SDK setup, client initialization, API key configuration, choosing between JS and Python, browser usage, retry/timeout settings, error handling, or SDK vs raw API decisions. The SDK is the recommended default for all Gladia integrations.

2installs

Sourcekaramouche/skills

Added on2026-05-20

NPX Install

npx skill4agent add karamouche/skills sdk-integration

SKILL.md Content

View Translation Comparison →

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 (pre-recorded-transcription or live-transcription) instead — those skills reference back here for setup details.

When to Use SDK vs Raw API

Scenario	Approach
Any JS/TS or Python project	SDK — always
Browser app	SDK — JS SDK supports ESM/IIFE bundles
Need custom HTTP client or middleware	SDK first; use `httpHeaders` / `httpTimeout` config. Fall back to raw REST only if SDK config is insufficient
Language without an SDK (Go, Java, etc.)	Raw REST/WebSocket (SDK unavailable)
User explicitly requests raw calls	Raw REST/WebSocket
CI script or one-off curl test	Raw REST is acceptable

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)
../pre-recorded-transcription/SKILL.md -- Pre-recorded transcription options, response structure, and audio intelligence config
../live-transcription/SKILL.md -- Live session config, audio streaming, and WebSocket event handling
../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

Variable	Purpose	Default
`GLADIA_API_KEY`	API key for authentication	—
`GLADIA_API_URL`	Base API URL	`https://api.gladia.io`
`GLADIA_REGION`	Datacenter region	—

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

Method	Purpose
`transcribe(audio, options)`	High-level: upload + create + poll
`uploadFile(audio)`	Upload local file to `/v2/upload`
`create(options)`	Create transcription job
`createAndPoll(options)`	Create + poll until done
`poll(jobId, { interval, timeout })`	Poll until complete
`get(jobId)`	Get job status/results
`delete(jobId)`	Delete job and data
`getFile(jobId)`	Download original audio

Live Client Methods

Method	Purpose
`startSession(options)`	Init session → returns LiveV2Session
`get(sessionId)`	Get completed session results
`delete(sessionId)`	Delete session and data
`getFile(sessionId)`	Download session audio

Live Session Methods

Method	Purpose
`sendAudio(chunk)`	Stream audio bytes to the session
`stopRecording()`	End recording, trigger post-processing
`endSession()`	Force close without post-processing
`getSessionId()`	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

Input	JS/TS	Python
Local file path (string)	Node only	Yes
`Path` object	—	Yes
HTTP(S) URL	Yes	Yes
`File` / `Blob`	Browser	—
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

Aspect	JavaScript/TypeScript	Python
Async model	Promise-based (async only)	Sync + async (separate clients)
Naming	camelCase ( `preRecorded` , `sendAudio` )	snake_case ( `prerecorded` , `send_audio` )
Browser support	Yes (ESM, CJS, IIFE)	No (server only)
Runtime	Node 20+, Bun, browsers	Python 3.10+
Dependencies	0 runtime deps (optional `ws` for Node <22)	httpx, websockets, pyee
Options format	Plain objects (snake_case keys)	Dataclasses or dicts
Untyped API	`transcribeUntyped()` , `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,
)

sdk-integration

NPX Install

Tags

SKILL.md Content

SDK Integration

When to Use

When to Use SDK vs Raw API

References

Installation

JavaScript / TypeScript

Python

Client Initialization

JavaScript/TypeScript

Python

Environment Variables

Client Architecture

Pre-Recorded Client Methods

Live Client Methods

Live Session Methods

Configuration Options

Audio Input Types

Error Handling

JavaScript/TypeScript

Python

Key Differences Between JS and Python

Type Exports

Further Reading