sdk-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SDK Integration

SDK 集成

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).

用于集成Gladia语音转文本API的官方SDK。两款SDK采用相同设计，均基于Gladia OpenAPI架构生成。

SDK是所有Gladia集成场景的默认选择。 除非有明确的文档说明的特殊原因（见下方决策指南），否则请始终使用SDK。

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.

用户询问Gladia SDK的安装、配置或初始化方法
设置API密钥、区域、重试机制、超时或WebSocket配置
关于SDK架构、客户端方法或类型导出的问题
在JS/TS与Python SDK之间选择，或是在SDK与原生API之间选择
基于浏览器的集成、代理设置或打包格式相关问题
Gladia API响应的错误处理模式

不适用场景： 如果用户询问特定的转录用例（预录制文件或实时流），请先参考相关用例技能（预录制转录或实时转录）——这些技能会在此处引用设置细节。

When to Use SDK vs Raw API

SDK与原生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.

场景	方案
任意JS/TS或Python项目	SDK — 优先使用
浏览器应用	SDK — JS SDK支持ESM/IIFE打包格式
需要自定义HTTP客户端或中间件	优先使用SDK；可配置 `httpHeaders` / `httpTimeout` 。仅当SDK配置无法满足需求时，再切换到原生REST API
无对应SDK的语言（Go、Java等）	使用原生REST/WebSocket（无SDK可用）
用户明确要求原生调用	使用原生REST/WebSocket
CI脚本或一次性curl测试	可接受使用原生REST API

如有疑问，优先使用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

按需查阅以下资源：

./references/sdk-versions.md -- 当前SDK版本（由CI自动同步）
./references/client-config.md -- 完整客户端配置参考（所有选项、默认值、超时设置）
./references/javascript.md -- JS/TS专属模式（浏览器、代理、File/Blob、Node要求）
./references/python.md -- Python专属模式（同步/异步、类型化请求、httpx/websockets）
../pre-recorded-transcription/SKILL.md -- 预录制转录选项、响应结构及音频智能配置
../live-transcription/SKILL.md -- 实时会话配置、音频流及WebSocket事件处理
../troubleshooting/SKILL.md -- 常见错误、注意事项及验证清单

Installation

安装步骤

JavaScript / TypeScript

bash

npm install @gladiaio/sdk

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.

yarn add @gladiaio/sdk


要求Node.js 20+或Bun环境。也可通过ESM/IIFE包在浏览器中运行。

Python

bash

pip install gladiaio-sdk

bash

pip install gladiaio-sdk

or

uv add gladiaio-sdk


Requires Python 3.10+.

uv add gladiaio-sdk


要求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)
});

typescript

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

const client = new GladiaClient({
  apiKey: "your-api-key", // 或设置GLADIA_API_KEY环境变量
  region: "eu-west", // 或设置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
)

python

from gladiaio_sdk import GladiaClient

client = GladiaClient(
    api_key="your-api-key",      # 或设置GLADIA_API_KEY环境变量
    region="eu-west",            # 或设置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	—

变量名	用途	默认值
`GLADIA_API_KEY`	用于身份验证的API密钥	—
`GLADIA_API_URL`	API基础地址	`https://api.gladia.io`
`GLADIA_REGION`	数据中心区域	—

Client Architecture

客户端架构

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

GladiaClient
├── preRecorded()  → PreRecordedV2Client    (JS)
│   prerecorded()  → PreRecordedV2Client    (Python)
│
├── liveV2()       → LiveV2Client           (JS)
│   live()         → LiveV2Client           (Python)
│
└── (Python专属)
    ├── 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

方法	用途
`transcribe(audio, options)`	高阶方法：上传 + 创建任务 + 轮询结果
`uploadFile(audio)`	上传本地文件到 `/v2/upload` 接口
`create(options)`	创建转录任务
`createAndPoll(options)`	创建任务 + 轮询直至完成
`poll(jobId, { interval, timeout })`	轮询任务直至完成
`get(jobId)`	获取任务状态/结果
`delete(jobId)`	删除任务及对应数据
`getFile(jobId)`	下载原始音频文件

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

方法	用途
`startSession(options)`	初始化会话 → 返回LiveV2Session实例
`get(sessionId)`	获取已完成会话的结果
`delete(sessionId)`	删除会话及对应数据
`getFile(sessionId)`	下载会话音频文件

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)

方法	用途
`sendAudio(chunk)`	向会话流式传输音频字节数据
`stopRecording()`	结束录制，触发后处理流程
`endSession()`	强制关闭会话，不触发后处理
`getSessionId()`	异步获取会话ID

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.

核心客户端选项：

apiKey

、

apiUrl

、

region

、

httpTimeout

、

httpRetry

、

wsRetry

、

wsTimeout

、

prerecordedTimeouts

、

liveTimeouts

。

如需查看包含所有选项及默认值的完整配置参考，请见./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

输入类型	JS/TS	Python
本地文件路径（字符串）	仅Node环境	支持
`Path` 对象	—	支持
HTTP(S) URL	支持	支持
`File` / `Blob`	浏览器环境	—
二进制文件对象（ `BinaryIO` ）	—	支持

URL会直接作为

audio_url

参数传递，无需上传。本地文件会自动通过

/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");
  }
}

typescript

try {
  const result = await client.preRecorded().transcribe("./audio.mp3", options);
} catch (error) {
  if (error.message.includes("401")) {
    console.error("无效的API密钥");
  } else if (error.message.includes("timeout")) {
    console.error("请求超时");
  }
}

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.

python

from gladiaio_sdk import GladiaClient

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

Python导出了

HttpError

和

TimeoutError

用于针对性错误处理。

Key Differences Between JS and Python

JS与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

维度	JavaScript/TypeScript	Python
异步模型	基于Promise（仅支持异步）	同步+异步（独立客户端）
命名规范	小驼峰（ `preRecorded` , `sendAudio` ）	下划线命名（ `prerecorded` , `send_audio` ）
浏览器支持	支持（ESM、CJS、IIFE格式）	不支持（仅服务端可用）
运行环境	Node 20+、Bun、浏览器	Python 3.10+
依赖项	0运行时依赖（Node <22版本可选依赖 `ws` ）	httpx、websockets、pyee
选项格式	普通对象（下划线命名键）	数据类或字典
非类型化API	`transcribeUntyped()` , `createUntyped()`	多数方法支持传入字典

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均从主包导出所有请求/响应类型：

typescript

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

python

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

sdk-integration

Original

Translation

SDK Integration

SDK 集成

When to Use

适用场景

When to Use SDK vs Raw API

SDK与原生API的选择

References

参考资源

Installation

安装步骤

JavaScript / TypeScript

JavaScript / TypeScript

or

or

or

or

Python

Python

or

or

Client Initialization

客户端初始化

JavaScript/TypeScript

JavaScript/TypeScript

Python

Python

Environment Variables

环境变量

Client Architecture

客户端架构

Pre-Recorded Client Methods

预录制客户端方法

Live Client Methods

实时客户端方法

Live Session Methods

实时会话方法

Configuration Options

配置选项

Audio Input Types

音频输入类型

Error Handling

错误处理

JavaScript/TypeScript

JavaScript/TypeScript

Python

Python

Key Differences Between JS and Python

JS与Python版本的主要差异

Type Exports

类型导出

Further Reading

延伸阅读