Deepgram Provider for AI SDKTypeScript语音转写与文本转语音完整指南【免费下载链接】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/aiDeepgram 是 AI SDKVercel AI Toolkit for TypeScript中专注于语音能力的官方 Provider提供基于 Deepgram 云端 API 的**语音转写Speech-to-Text / Transcription与文本转语音Text-to-Speech**两类模型支持。本文将以 packages/deepgram/README.md 为主线结合 content/providers/01-ai-sdk-providers/110-deepgram.mdx 官方文档与packages/deepgram/src源码实现系统讲解其安装、Provider 实例化、transcription 与 speech 的完整用法、全部 providerOptions 参数、模型能力对照以及底层请求如何被组装与校验帮助你直接在 AI SDK 应用中接入高质量语音能力。部署到 Vercel通过 Vercel AI Gateway 可以直接访问 Deepgram以及数百个来自其他 Provider 的模型——无需额外安装包、API Key 或额外成本。安装与版本要求Deepgram Provider 以独立 npm 包ai-sdk/deepgram的形式发布与 AI SDK 主包ai配合使用npm i ai-sdk/deepgram从 packages/deepgram/package.json 可以看到该包的工程约束运行时依赖仅两个工作区包ai-sdk/provider与ai-sdk/provider-utils引擎要求node 22采用 ESM 模块type: module导出路径为dist/index.js可通过./package.json子路径查看版本信息当前仓库中版本为3.1.10遵循 AI SDK v7 的 Provider V4 规范。使用编码 Agent如 Claude Code、Cursor的开发者建议将 AI SDK skill 加入仓库以获取完整开发指引npx skills add vercel/aiProvider 实例默认实例与自定义配置使用默认实例ai-sdk/deepgram直接导出一个开箱即用的默认实例deepgramimport { deepgram } from ai-sdk/deepgram;默认实例内部通过createDeepgram()创建见 deepgram-provider.tsAPI Key 默认从环境变量DEEPGRAM_API_KEY读取。自定义实例 createDeepgram当需要定制行为如自定义 fetch、附加请求头、显式传入 API Key时使用createDeepgramimport { createDeepgram } from ai-sdk/deepgram; const deepgram createDeepgram({ // 自定义设置例如 fetch: customFetch, });可选设置项对应源码DeepgramProviderSettings见 deepgram-provider.ts设置项类型说明apiKeystring通过Authorization请求头发送。默认读取DEEPGRAM_API_KEY环境变量headersRecordstring,string附加到请求中的自定义请求头fetch(input, init) PromiseResponse自定义 fetch 实现默认使用全局fetch。可用于拦截请求或提供测试用的 mock 实现从源码看API Key 并非使用常见的Bearer前缀而是拼装为Token ${apiKey}的authorization头见 deepgram-provider.ts并自动追加ai-sdk/deepgram/${VERSION}的 User-Agent 后缀。所有请求统一发往https://api.deepgram.com转写走/v1/listen语音合成走/v1/speak。DeepgramProvider还实现了 AI SDK 的ProviderV4接口但只提供transcription与speech两类能力调用languageModel、embeddingModel、imageModel等未支持方法会抛出NoSuchModelError例如提示 Deepgram does not provide language models这是 Provider 接口的规范占位。语音转写Transcription基础用法通过deepgram.transcription(modelId)创建转写模型配合 AI SDK 的transcribe()函数使用。音频可以是 URL 或二进制数据Buffer/Uint8Arrayimport { deepgram } from ai-sdk/deepgram; import { transcribe } from ai; const { text } await transcribe({ model: deepgram.transcription(nova-3), audio: new URL( https://github.com/vercel/ai/raw/refs/heads/main/examples/ai-functions/data/galileo.mp3, ), });返回结果中text为完整转写文本。从 deepgram-transcription-model.ts 的返回结构可以确认transcribe()还支持更丰富的返回值segments带startSecond/endSecond的词级时间戳、language检测到的语言需开启语言检测、durationInSeconds音频时长以及完整的response原始信息。开启语言自动检测Deepgram 的detectLanguage开启后会自动识别音频语言返回结果中会附带language字段import { deepgram } from ai-sdk/deepgram; import { transcribe } from ai; const { text, language } await transcribe({ model: deepgram.transcription(nova-3), audio: new URL( https://github.com/vercel/ai/raw/refs/heads/main/examples/ai-functions/data/galileo.mp3, ), providerOptions: { deepgram: { detectLanguage: true, }, }, });转写 providerOptions 完整参数表以下选项通过providerOptions.deepgram传入全部为可选命名采用 camelCase源码中会被映射为 Deepgram API 的 snake_case 查询参数映射逻辑见 deepgram-transcription-model.ts参数 Schema 定义见 deepgram-transcription-model-options.ts参数类型说明映射的上游参数languagestring音频语言代码支持多种 ISO-639-1 / ISO-639-3 代码不指定时默认英语languagedetectLanguageboolean是否启用自动语言检测detect_languagesmartFormatboolean智能格式化将数字、日期、时间等书面化smart_formatpunctuateboolean为转写文本添加标点punctuateparagraphsboolean将转写文本格式化为段落paragraphssummarizev2 \| false是否生成转写摘要v2为最新版本false关闭summarizetopicsboolean是否识别转写内容主题topicsintentsboolean是否识别转写内容意图intentssentimentboolean是否进行情感分析sentimentdetectEntitiesboolean是否检测并标记命名实体detect_entitiesredactstring \| string[]从转写中脱敏的术语或模式支持数组redactreplacestring用于替换被脱敏内容的字符串replacesearchstring在转写中搜索的术语或短语searchkeytermstring用于提升识别准确率的关键词keytermdiarizeboolean是否识别不同说话人。默认false注意 Deepgram 按分钟对说话人分离额外计费diarizeutterancesboolean是否将转写切分为语句段utterancesutterancesuttSplitnumber触发新语句段的静音阈值秒utt_splitfillerWordsboolean是否在转写中保留填充词um、uh 等filler_words例如开启摘要import { transcribe } from ai; import { deepgram, type DeepgramTranscriptionModelOptions, } from ai-sdk/deepgram; import { readFile } from fs/promises; const result await transcribe({ model: deepgram.transcription(nova-3), audio: await readFile(audio.mp3), providerOptions: { deepgram: { summarize: true, } satisfies DeepgramTranscriptionModelOptions, }, });底层请求组装原理转写模型的核心逻辑位于 deepgram-transcription-model.ts参数解析与校验parseProviderOptions用 zod schema 校验providerOptions.deepgram非法值会在编译期/运行期被拦截参数映射camelCase 选项逐一映射为 Deepgram API 的 snake_case 参数如detectLanguage→detect_language连同模型 ID 一起组装进请求体Query 序列化URLSearchParams仅追加非undefined的字段请求发送通过postToApi向https://api.deepgram.com/v1/listen?query发送音频Content-Type使用options.mediaType成功响应用 JSON handler 解析失败响应由deepgramFailedResponseHandler处理响应提取从results.channels[0].alternatives[0]中提取transcript与words词级起止时间从metadata.duration提取音频时长从detected_language提取检测语言。Deepgram 的错误响应结构为{err_code, err_msg, request_id}失败处理时以err_msg作为错误消息抛出见 deepgram-error.ts。文本转语音Text-to-Speech基础用法通过deepgram.speech(familyId)创建语音合成模型配合 AI SDK 的generateSpeech()使用import { deepgram } from ai-sdk/deepgram; import { generateSpeech } from ai; const { audio } await generateSpeech({ model: deepgram.speech(aura-2), voice: helena, text: Hello, welcome to Deepgram!, });语音家族与 voice/language 组合规则speech()的第一个参数是语音家族 IDaura-2当前代或auraAura-1。语音与语言通过generateSpeech的voice与language选项选择——Provider 会将其组合为上游 Deepgram 模型 IDfamily-voice-language语言默认en。例如deepgram.speech(aura-2)voice: thalialanguage: en会解析为上游模型aura-2-thalia-en组合逻辑见 deepgram-speech-model.ts。import { generateSpeech } from ai; import { deepgram } from ai-sdk/deepgram; const result await generateSpeech({ model: deepgram.speech(aura-2), voice: thalia, language: en, text: Hello, world!, });注意完整的语音模型 ID例如deepgram.speech(aura-2-helena-en)仍然可以直接透传使用但官方推荐使用「家族 ID voice/language」的形式因为它与其他语音 Provider 的选音方式保持一致。若使用完整模型 ID 的同时又传入voice或language参数Provider 会发出unsupported类型警告并忽略这些参数因为声音已编码在模型 ID 中见 deepgram-speech-model.ts。语音合成 providerOptions 完整参数表通过providerOptions.deepgram传入Schema 定义见 deepgram-speech-model-options.tsimport { generateSpeech } from ai; import { deepgram, type DeepgramSpeechModelOptions } from ai-sdk/deepgram; const result await generateSpeech({ model: deepgram.speech(aura-2), voice: helena, text: Hello, world!, providerOptions: { deepgram: { encoding: linear16, sampleRate: 24000, } satisfies DeepgramSpeechModelOptions, }, });参数类型说明encodingstring输出音频编码。支持linear16、mulaw、alaw、mp3、opus、flac、aac。可选containerstring输出音频容器格式。支持wav、ogg、none。可选sampleRatenumber输出音频采样率Hz。可用值取决于编码8000、16000、24000、32000、48000。可选bitRatenumber \| string音频码率bps。mp332000或48000opus4000–650000aac4000–192000。可选callbackstringDeepgram 完成合成后回调请求的 URL携带音频。可选callbackMethodPOST \| PUT回调请求的 HTTP 方法。可选mipOptOutboolean是否选择退出 Deepgram 模型改进计划Model Improvement Program。可选tagstring \| string[]为请求打标签便于用量报告中识别。可选输出格式、speed 与其他行为的底层处理源码 deepgram-speech-model.ts 展示了generateSpeech的outputFormat默认mp3是如何被映射为 Deepgram 参数的outputFormatencodingcontainer说明mp3mp3不设置固定 22050 采样率wav/linear16linear16wav采样率可配mulawmulawwav采样率 8000/16000alawalawwav采样率 8000/16000opus/oggopusogg固定 48000 采样率flacflac不设置采样率可配aacaac不设置固定 22050 采样率pcmlinear16none裸音频同时也支持wav_44100、linear16_24000这类「编码_采样率」组合格式的解析。参数冲突校验当providerOptions与outputFormat推导出的参数冲突时Provider 会做兼容性校验并产生unsupported类型警告而非静默出错例如linear16/mulaw/alaw只支持wav或none容器mp3/flac/aac不支持container参数mp3/opus/aac固定采样率不支持sampleRatelinear16/mulaw/alaw/flac不支持bitRate。speed 选项generateSpeech的speed选项会原样透传为 Deepgram 的speed参数。Deepgram 仅接受 0.7–1.5 区间超出范围会被上游以 400 错误拒绝且并非所有语言都支持 speed。instructions 选项Deepgram REST API 不支持 instructions传入时会被忽略并产生警告。响应元数据generateSpeech的返回结果会将 Deepgram 响应头解析为providerMetadata.deepgram包含modelName最终解析的上游模型、modelUuid、additionalModelUuids、charCount计费字符数、breaksApplied、pronunciationsApplied、pronunciationWarnings存在时、requestId见 deepgram-speech-model.ts。模型能力对照语音家族与声音数声音通过voice选项选择完整声音名称与口音列表以 Deepgram TTS 模型文档为准家族可用声音aura-241 个英语、17 个西班牙语、9 个荷兰语、7 个德语、10 个意大利语、5 个日语、2 个法语aura12 个英语Aura-1转写模型能力对照deepgram.transcription()支持以下模型可用 ID 全集见 deepgram-transcription-options.ts各模型还带有-general、-meeting、-phonecall、-medical、-finance、-voicemail、-video、-conversationalai、-drivethru、-automotive、-atc等领域变体模型转写时长词级分段语言检测nova-3含变体✓✓✓✗nova-2含变体✓✓✓✗nova含变体✓✓✓✗enhanced含变体✓✓✓✗base含变体✓✓✓✗上表中「语言检测」列为 ✗ 表示该列对应的是模型自带能力维度语言自动检测仍可通过detectLanguage: true的 providerOptions 开启README 中的官方能力表即如此标注。测试与验证该 Provider 的测试位于 packages/deepgram/src 目录deepgram-transcription-model.test.ts 与对应的 deepgram-transcription.json fixture验证转写请求的查询参数组装与响应解析含transcript、segments、detected_language等字段deepgram-speech-model.test.ts验证语音家族 ID 组合、outputFormat 映射与 providerOptions 冲突警告deepgram-error.test.ts验证错误响应解析。测试运行命令见 package.jsonpnpm test:node # Node 环境测试 pnpm test:edge # Edge 环境测试仓库根目录还提供了可直接运行的完整示例 examples/ai-functions其中包含用于测试的音频样本如galileo.mp3可作为端到端参考。小结通过ai-sdk/deepgram你可以在 AI SDK 应用中用统一的transcribe()/generateSpeech()接口调用 Deepgram 的语音转写与文本转语音能力转写侧支持语言检测、说话人分离、摘要、主题/意图/情感分析、实体检测、脱敏等丰富的智能后处理合成侧支持aura-2/aura两大语音家族、7 种编码与多容器输出、回调与用量标签等。Provider 层在保持接口一致性的同时对 Deepgram 上游参数做了完整映射、合法性校验与警告机制源码deepgram-provider.ts、deepgram-transcription-model.ts、deepgram-speech-model.ts可作为进一步深入与排查问题的可靠依据。【免费下载链接】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），仅供参考