ai-sdk/gladia 语音转录 Provider 完全指南从安装配置到安全演进【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiGladia 是专注于语音转录speech-to-text的 AI 服务商ai-sdk/gladia是 AI SDK 生态中将其转录 API 封装为 TypeScript Provider 的官方包。本文以 packages/gladia/CHANGELOG.md 为主线结合 packages/gladia/README.md 与源码实现系统讲解如何安装、配置并使用 Gladia 转录模型剖析其内部上传 → 发起任务 → 轮询结果的三段式工作流并深入解读 3.0.x 版本中 URL 校验、同源凭证保护等关键安全演进帮助你理解并安全地接入 Gladia 语音转写能力。一、包定位与整体架构ai-sdk/gladia是 AI SDK 众多 Provider 包之一只做一件事将 Gladia 的转录 API 适配为 AI SDK 统一的TranscriptionModelV4接口。从 gladia-provider.ts 源码可见它严格遵循 AI SDK 的 Provider 规范specificationVersion固定为v4仅暴露transcription()以及兼容别名的transcriptionModel一个能力languageModel、embeddingModel、imageModel全部抛出NoSuchModelError明确声明Gladia 不提供语言模型 / 嵌入模型 / 图像模型默认实例gladia与工厂函数createGladia双入口源码入口在 index.ts。整个包的核心类只有一个GladiaTranscriptionModel见 gladia-transcription-model.ts它负责与 Gladia API 的全部交互。从 CHANGELOG 看该包经历了从1.0.0首次加入 transcribe 能力到3.0.39的演进期间随 AI SDK 主版本升级了三次大版本1.x引入转录与语音模型支持并适配 Zod 42.0.0升级到 Provider-V3 规范3.0.0则是一次包含 ESM 迁移、Node 版本提升与多项安全修复的重大重构。二、安装与快速上手安装包发布在 npm 上README 给出的安装命令为npm i ai-sdk/gladia从 package.json 可以看到它的依赖非常精简仅依赖ai-sdk/provider与ai-sdk/provider-utils两个核心库zod作为 peer dependency支持^3.25.76 || ^4.1.8。注意engines字段要求Node.js 22这是 3.0.0 版本提升后的硬性约束CHANGELOG 中7fc6bd6变更最低支持 Node 22支持版本为 22、24、26。创建 Provider 实例两种方式等价// 方式一使用默认实例读取环境变量 GLADIA_API_KEY import { gladia } from ai-sdk/gladia; // 方式二工厂函数自定义配置 import { createGladia } from ai-sdk/gladia; const gladia createGladia({ apiKey: your-api-key, // 可选缺省时读取 GLADIA_API_KEY 环境变量 headers: { custom-header: value }, // 自定义请求头 fetch: customFetch, // 自定义 fetch 实现可用于拦截请求或测试 });从源码看createGladia内部会自动完成三件事通过loadApiKey加载 API key优先使用传入的apiKey否则回退到GLADIA_API_KEY环境变量缺少时报错将 API key 写入x-gladia-key请求头这是 Gladia 的鉴权方式而非常见的Authorization: Bearer通过withUserAgentSuffix在 User-Agent 中追加ai-sdk/gladia/${VERSION}以便服务端识别 SDK 版本。发起一次转录README 给出的最简示例import { gladia } from ai-sdk/gladia; import { transcribe } from ai; const { text } await transcribe({ model: gladia.transcription(), audio: new URL( https://github.com/vercel/ai/raw/refs/heads/main/examples/ai-functions/data/galileo.mp3, ), });注意audio参数既可以传远程 URL也可以传本地音频的Uint8Array或 base64 字符串——这是 1.0.8 版本修复过的关键点见下文实战演进实现细节在doGenerate中对options.audio的类型判断。三、转录模型选项完整参数说明gladia.transcription()返回的模型支持通过providerOptions传入丰富的转录参数。这些参数在 gladia-transcription-model-options.ts 中以 Zod schema 严格定义并在 gladia-api-types.ts 中一一对应到 Gladia API 的 snake_case 字段。下表按功能分组整理语言与识别选项camelCase对应 API 字段类型说明languagelanguagestring指定音频语言iso639-1 格式如zhdetectLanguagedetect_languageboolean自动检测音频语言enableCodeSwitchingenable_code_switchingboolean启用语码切换同一音频含多种语言codeSwitchingConfigcode_switching_config{ languages?: string[] }指定语码切换要考虑的语言自定义词汇与纠错选项对应 API 字段类型说明contextPromptcontext_promptstring上下文提示指导转录模型提升准确率AlphacustomVocabularycustom_vocabularyboolean \| any[]启用自定义词汇或直接传入词汇数组customVocabularyConfigcustom_vocabulary_config对象词汇详细配置vocabulary数组元素可为字符串或含value、intensity、pronunciations、language的对象以及defaultIntensitycustomSpellingcustom_spellingboolean启用自定义拼写AlphacustomSpellingConfigcustom_spelling_config{ spellingDictionary: Recordstring, string[] }拼写字典错误写法 → 正确写法列表说话人与字幕选项对应 API 字段类型说明diarizationdiarizationboolean启用说话人分离diarizationConfigdiarization_config{ numberOfSpeakers?; minSpeakers?; maxSpeakers?; enhanced? }说话人数量范围与增强模式Alphasubtitlessubtitlesboolean生成字幕subtitlesConfigsubtitles_config对象字幕格式[srt,vtt]、最短/最长时长、每行最大字符数、每个字幕最大行数、样式default \| compliance翻译、摘要与后处理选项对应 API 字段类型说明translationtranslationboolean启用翻译BetatranslationConfigtranslation_config{ targetLanguages: string[]; model?: base\|enhanced; matchOriginalUtterances? }目标语言iso639-1、翻译模型、是否对齐原始语句summarizationsummarizationboolean生成摘要BetasummarizationConfigsummarization_config{ type?: general\|bullet_points\|concise }摘要类型moderationmoderationboolean内容审核AlphasentimentAnalysissentiment_analysisboolean情感分析Alphachapterizationchapterizationboolean自动分章AlphanameConsistencyname_consistencyboolean实体命名一致性AlphastructuredDataExtractionstructured_data_extractionboolean结构化数据抽取AlphastructuredDataExtractionConfigstructured_data_extraction_config{ classes: string[] }要抽取的数据类别audioToLlmaudio_to_llmboolean将音频送入 LLM 处理AlphaaudioToLlmConfigaudio_to_llm_config{ prompts: string[] }发送给 LLM 的提示词sentencessentencesboolean启用句子级分段displayModedisplay_modeboolean更改输出显示模式AlphapunctuationEnhancedpunctuation_enhancedboolean增强标点AlphacustomMetadatacustom_metadataRecordstring, any附加自定义元数据callbackcallbackboolean转录完成时回调callbackConfigcallback_config{ url: string; method?: POST\|PUT }回调地址与 HTTP 方法一个综合示例const { text } await transcribe({ model: gladia.transcription(), audio: audioBuffer, // Uint8Array providerOptions: { gladia: { detectLanguage: true, diarization: true, diarizationConfig: { maxSpeakers: 4 }, subtitles: true, subtitlesConfig: { formats: [srt, vtt] }, summarization: true, summarizationConfig: { type: bullet_points }, translation: true, translationConfig: { targetLanguages: [en, zh] }, customVocabularyConfig: { vocabulary: [{ value: Vercel, pronunciations: [ver-sel] }], }, }, }, });这些选项在 gladia-transcription-model.ts 的getArgs方法中被逐项映射为 API 请求体字段未提供的选项一律以undefined省略不会污染请求。四、底层实现转录的三段式工作流GladiaTranscriptionModel.doGenerate完整实现了 Gladia 转录的异步流程值得深入理解源码见 gladia-transcription-model.ts1. 上传音频将音频数据Uint8Array或 base64包装为Blob借助mediaTypeToExtension从媒体类型推导文件扩展名通过postFormDataToApi以 multipart/form-data 上传到POST /v2/upload。响应中的audio_url是 Gladia 侧暂存的音频地址。2. 发起转录任务将audio_url与getArgs解析出的全部选项合并POST /v2/pre-recorded发起转录。响应只包含一个字段result_url结果轮询地址。3. 轮询结果对result_url以 1 秒为间隔轮询pollingInterval 100060 秒超时timeoutMs 60 * 1000。响应状态机有四种queued/processing继续等待done跳出循环error抛出TranscriptionJobFailed错误超时抛出TranscriptionJobPollingTimedOut错误完成后若result为空抛出TranscriptionResultEmpty。最终返回结构包含textfull_transcript全文durationInSecondsmetadata.audio_duration音频时长language检测/指定的语言segmentsutterances映射为{ text, startSecond, endSecond }的语句段数组可配合 diarization 输出逐句时间戳providerMetadata.gladia完整的原始响应体供需要深度数据的场景使用。错误处理方面gladia-error.ts 定义了{ error: { message, code } }的响应结构gladiaFailedResponseHandler统一将 API 错误转为带message的 SDK 错误。五、关键安全演进URL 校验与同源凭证保护CHANGELOG 中 3.0.x 最值得关注的不是功能新增而是凭证泄露风险的系统性修复这是ai-sdk/gladia及多个 Provider 包共用的安全模型升级。1. 响应 URL 凭证泄露问题3.0.0commit aeda373修复前存在一个真实风险Provider 客户端会跟随 API 响应中返回的 URL如轮询地址result_url并在该请求上复用带认证的请求头。由于响应 URL 的主机从未被校验一旦响应被篡改攻击者就能让客户端把长期有效的 API key 发送到任意主机造成凭证外泄。修复方案是给ai-sdk/provider-utils增加isSameOrigin辅助函数ai-sdk/gladia、ai-sdk/black-forest-labs、ai-sdk/fireworks、ai-sdk/replicate、ai-sdk/fal、ai-sdk/google六个包同步更新仅当被跟随的 URL 与 Provider 配置的 API 源同源时才附加凭证跨源请求一律不带凭证。2. 全面 URL 校验3.0.9commit 4be62c13.0.9 进一步加固getFromApi新增validateUrl开关所有 AI SDK Provider 包在每个调用点显式声明信任决策。在 Gladia 中gladia-transcription-model.ts轮询result_url时显式传入了三个关键参数validateUrl: true将 URL 交由fetchWithValidatedRedirects校验拒绝私有地址private/loopback/link-local、多播地址IPv4224.0.0.0/4及文档保留网段IPv4192.0.2.0/24、198.51.100.0/24、203.0.113.0/24IPv62001:db8::/32、3fff::/20并重新校验每次重定向跳转、剥离代理/元数据/cookie 请求头、跨源重定向时丢弃除 User-Agent 外的所有请求头credentialedOrigin: apiOrigin除非 URL 与 Gladia 配置的 API 源同源否则不发送 API key 等调用方请求头trustedOrigin: apiOrigin与开发者配置的 Provider 端点同源的 URL及重定向跳转豁免目标校验保证自托管和 localhost 部署可用其余跳转仍全部校验。同时只有 fetch 规范定义的 301/302/303/307/308 才算有效重定向其他状态码即使带Location头也不会跟随。已知边界CHANGELOG 明确说明该校验仅做字符串/字面量检查不解析 DNS解析后指向私有地址的主机名与 DNS rebinding 攻击不在防护范围内面向不可信 URL 的服务器部署需在网络层额外约束或注入固定的 Nodefetch在连接时固定解析 IP。完整设计见 contributing/secure-url-handling.md。六、3.0.0 重大变更ESM、Node 版本与工作流序列化3.0.0 是一次 breaking change 集中发布从 CHANGELOG 可梳理出四个必须知晓的变更点全面 ESM-onlycommit ef992f8移除所有包包括ai-sdk/gladia的 CommonJS 导出package.json中type: module。使用require()的消费者必须切换到 ESMimport语法。Node 最低版本提升至 22commit 7fc6bd6支持 Node 22 / 24 / 26。Provider 实现模式统一commit 04e9009重命名部分导出的符号旧名称通过废弃别名继续可用。工作流序列化支持commit b3976a2ai-sdk/provider-utils新增serializeModel()辅助函数只提取模型实例中可序列化的属性过滤函数及含函数的对象所有 Provider 模型类新增WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE静态方法使模型能跨工作流步骤边界传递而不报序列化错误。在 gladia-transcription-model.ts 中可以找到这两个静态方法的实现。同时Provider 配置类型中的headers变为可选现有传headers的代码不受影响便于从工作流步骤边界反序列化模型时单独提供认证信息。此外 3.0.5 引入了实验性流式转录支持commit 5c5c0f5覆盖 OpenAIgpt-realtime-whisper与 xAI WebSocket STT 等流式转录模型。3.0.9 还修正了validateDownloadUrl的网段覆盖缺口并统一了 URL 校验与媒体下载共用的防护链路。七、版本演进时间线从 1.0 到 3.0综合 CHANGELOGai-sdk/gladia的完整演进脉络如下版本段关键变更1.0.0-alpha/canary → 1.0.0首次加入transcribe能力cf822aa、为 Provider 注册表增加转录与语音模型支持cb68df0、内部使用 Zod 4d1a034f并修复 Zod 兼容性205077b1.0.x修复无效model参数传入问题、修复experimental_transcribe处理合法Buffer时失败的问题1.0.87948763npm 包排除测试文件、附带源码与文档1.1.0-beta → 2.0.0AI SDK 6 beta升级到 Provider-V3 规范ed329cb新增转录模型 v3 规范21e20c0textEmbeddingModel重命名为embeddingModel旧名保留废弃别名User-Agent 中加入 Provider 版本号2.0.x规范化并导出 Provider 专属的模型选项类型名2.0.19修复与更新 Provider 文档2.0.133.0.0AI SDK 7 预发布ESM-only、Node 22、Provider 实现模式统一、工作流序列化、响应 URL 同源凭证保护3.0.5实验性流式转录支持3.0.9getFromApi全面 URL 校验validateUrl / credentialedOrigin / trustedOrigin八、测试与验证仓库为 gladia 包提供了完整的测试与验证体系packages/gladia单测gladia-transcription-model.test.ts 与 gladia-error.test.ts配合同步快照 gladia-transcription-model.test.ts.snap 断言转录模型与错误处理的输出API 夹具__fixtures__目录下的 gladia-upload.json、gladia-initiate.json、gladia-result.json 分别模拟上传、发起、结果三个阶段的服务端响应真实音频样本transcript-test.mp3 用于端到端转录测试运行方式package.json中定义了pnpm test同时跑 Node 与 Edge 环境、pnpm test:node、pnpm test:edge其中 Edge 配置见 vitest.edge.config.jsNode 配置见 vitest.node.config.js。九、使用建议与注意事项鉴权API key 通过x-gladia-key请求头发送优先通过环境变量GLADIA_API_KEY注入不要硬编码在代码中。异步任务转录不是一次请求完成的SDK 内部已处理轮询1 秒间隔、60 秒超时长音频需预留足够时间可结合abortSignal支持取消。安全模型3.0.x 的 URL 校验默认对响应 URL 生效自托管场景可通过trustedOrigin白名单保持兼容了解其 DNS 层边界必要时在网络层加固。环境要求确保 Node.js 22 且使用 ESM 模块系统。查看详细参数所有转录选项的 Zod 定义与 JSDoc 注释在 gladia-transcription-model-options.tsAPI 字段语义说明在 gladia-api-types.ts是排查参数问题的第一手资料。十、总结ai-sdk/gladia虽然只聚焦转录一个能力却完整展现了 AI SDK Provider 的最佳实践严格遵循ProviderV4/TranscriptionModelV4接口规范、以 Zod 定义类型安全的参数边界、内置异步轮询与超时管理、并通过同源凭证保护与 URL 校验建立可审计的安全基线。理解它的实现与演进既能让你熟练接入 Gladia 语音转写也能为自研 Provider 或排查其他 Provider 的类似问题提供直接参考。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考