（3873期）gladia-sdk-integration – Gladia 语音 API 官方 SDK 集成

Gladia 语音 API 官方 SDK 集成 Gladia 官方维护的语音转文字 SDK，提供 JS/TS 与 Python 双语言支持，零依赖、类型完备，是构建语音识别应用的首选开发工具。 使用说明 核心用法 本技能涵盖 Gladia 官方 SDK 的安装配置与初始化流程，支持 JavaScript/TypeScript（@gladiaio/sdk）和 Python（gladiaio-sdk）两大主流技术栈。开发者通过创建 GladiaClient 实例并配置 API 密钥、区域等参数，即可快速接入预录语音转写（Pre-Recorded）与实时语音流转写（Live）两大核心能力。 SDK 采用分层架构设计：GladiaClient 作为入口，通过 preRecorded()/prerecorded() 和 liveV2()/live() 方法获取专用客户端，进而调用上传、创建任务、轮询结果、流式发送音频等细粒度操作。Python 额外提供异步客户端（*_async），满足不同运行时模型的需求。 显著优点 官方维护，品质保障：SDK 直接由 Gladia 团队从 OpenAPI 架构生成，确保与 API 更新同步，文档与代码高度一致。 零运行时依赖（JS）：JavaScript SDK 除 Node < 22 的 WebSocket 场景外零依赖，极大减少供应链攻击面与安装体积。 类型安全完备：双语言均导出完整的请求/响应类型定义，支持 IDE 智能提示与编译期检查，降低因字段拼写错误导致的运行时故障。 多环境兼容：JS SDK 支持 Node.js 20+、Bun 及浏览器（ESM/CJS/IIFE），Python SDK 支持 3.10+，覆盖主流部署场景。 智能降级与重试：内置 HTTP/WebSocket 超时、重试机制，并提供详细的配置入口，无需开发者自行实现容错逻辑。 潜在缺点与局限性 语言覆盖有限：仅官方支持 JS/TS 与 Python，Go、Java、Rust 等语言需回退至原生 REST/WebSocket 调用，增加接入成本。 浏览器场景限制：JS SDK 虽支持浏览器，但 API 密钥不可直接暴露于前端代码，需额外搭建后端代理层，架构复杂度上升。 命名风格割裂：JS 采用 camelCase（sendAudio），Python 采用 snakecase（sendaudio），跨语言团队需额外注意一致性。 异步模型差异：JavaScript 强制 Promise 异步，Python 提供同步/异步双轨，初学者易混淆客户端选择。 Node.js 版本门槛：要求 Node 20+，旧项目升级可能带来兼容性风险；Node < 22 进行实时流转写时需手动安装 ws 包，易被忽略导致静默失败。 适合的目标群体 需要快速集成语音识别能力的全栈开发者、后端工程师 构建实时会议字幕、语音客服、播客转写等应用的产品团队 注重类型安全与开发体验的 TypeScript/Python 技术栈团队 已有 Gladia API 使用经验、希望从原生 HTTP 迁移至 SDK 的存量项目 使用风险 密钥泄露风险：浏览器端直接嵌入 API 密钥将导致凭证暴露，必须采用后端代理模式。 WebSocket 依赖遗漏：Node < 22 环境下若未安装 ws 包，实时流转写会静默失败，排查成本较高。 超时配置盲区：默认超时策略可能不适用于大文件上传或长音频场景，需根据业务调整 prerecordedTimeouts/liveTimeouts。 区域选择影响：eu-west 与 us-west 数据隔离，错误配置可能导致延迟升高或合规问题。 版本漂移：SDK 自动同步 API 更新，重大版本升级可能引入破坏性变更，建议锁定版本并关注变更日志。 原始说明 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.