Deepgram Provider for AI SDK（TypeScript）：语音转写与文本转语音完整指南

Deepgram Provider for AI SDK（TypeScript）：语音转写与文本转语音完整指南

【免费下载链接】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

Deepgram 是 AI SDK（Vercel 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/ai

Provider 实例：默认实例与自定义配置

使用默认实例

@ai-sdk/deepgram直接导出一个开箱即用的默认实例deepgram：

import { deepgram } from '@ai-sdk/deepgram';

默认实例内部通过createDeepgram()创建（见 deepgram-provider.ts），API Key 默认从环境变量DEEPGRAM_API_KEY读取。

自定义实例 createDeepgram

当需要定制行为（如自定义 fetch、附加请求头、显式传入 API Key）时，使用createDeepgram：

import { createDeepgram } from '@ai-sdk/deepgram'; const deepgram = createDeepgram({ // 自定义设置，例如： fetch: customFetch, });

可选设置项（对应源码DeepgramProviderSettings，见 deepgram-provider.ts）：

从源码看，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/Uint8Array）：

import { 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）：

例如开启摘要：

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：

1. 参数解析与校验：parseProviderOptions用 zod schema 校验providerOptions.deepgram，非法值会在编译期/运行期被拦截；
2. 参数映射：camelCase 选项逐一映射为 Deepgram API 的 snake_case 参数（如detectLanguage→detect_language），连同模型 ID 一起组装进请求体；
3. Query 序列化：URLSearchParams仅追加非undefined的字段；
4. 请求发送：通过postToApi向https://api.deepgram.com/v1/listen?<query>发送音频（Content-Type使用options.mediaType），成功响应用 JSON handler 解析，失败响应由deepgramFailedResponseHandler处理；
5. 响应提取：从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()的第一个参数是语音家族 ID：aura-2（当前代）或aura（Aura-1）。语音与语言通过generateSpeech的voice与language选项选择——Provider 会将其组合为上游 Deepgram 模型 ID：<family>-<voice>-<language>（语言默认en）。例如deepgram.speech('aura-2')+voice: 'thalia'+language: '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.ts：

import { 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, }, });

输出格式、speed 与其他行为的底层处理

源码 deepgram-speech-model.ts 展示了generateSpeech的outputFormat（默认mp3）是如何被映射为 Deepgram 参数的：

同时也支持"wav_44100"、"linear16_24000"这类「编码_采样率」组合格式的解析。

参数冲突校验：当providerOptions与outputFormat推导出的参数冲突时，Provider 会做兼容性校验并产生unsupported类型警告（而非静默出错），例如：

• linear16/mulaw/alaw只支持wav或none容器；
• mp3/flac/aac不支持container参数；
• mp3/opus/aac固定采样率，不支持sampleRate；
• linear16/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 模型文档为准）：

转写模型能力对照

deepgram.transcription()支持以下模型（可用 ID 全集见 deepgram-transcription-options.ts，各模型还带有-general、-meeting、-phonecall、-medical、-finance、-voicemail、-video、-conversationalai、-drivethru、-automotive、-atc等领域变体）：

上表中「语言检测」列为 ✗ 表示该列对应的是模型自带能力维度，语言自动检测仍可通过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.json）：

pnpm 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