Deepgram：STT/TTS API，亚 300ms 延迟

为什么需要 Deepgram：通用 ASR 延迟高、后处理靠拼装、语音 Agent 链路长

自建或选用通用 ASR 方案时，三个问题最突出。第一是延迟：多数开源模型或云 ASR 的流式尾字延迟在 1 秒以上，实时字幕、语音对话场景下用户体感明显卡顿；第二是后处理成本：标点、数字规范化、说话人分离、热词纠错这些“转写之后”的工作通常要再串三四个模块，自己实现既费工时又难调好；第三是语音 Agent 的链路：STT→LLM→TTS 三段都要独立对接并控制延迟，任何一个环节慢半拍，整体响应就会超过用户可接受的 1 秒门槛。

Deepgram 把这三件事收进一个托管 API。流式 STT 官方口径尾字延迟低于 300ms；批处理转写通过 smart_format、diarize、utterances 等参数开箱即得规范文本；Voice Agent API 则用一套 WebSocket 会话把「转写→LLM→合成」跑完，官方口径端到端延迟低于 800ms。工程师不再需要关心音频特征提取、端点检测和断句策略——这些由服务端处理，客户端只负责发音频、收文本或播放音频。

与同类工具相比，Deepgram 的气质是“实时优先 + 全栈语音”。AssemblyAI 更强调批处理准确率与内容理解，Azure Speech 更偏企业云生态，Whisper 是可私有化的开源模型——而 Deepgram 在流式低延迟和语音 Agent 一体化上走得最靠前。

安装与环境配置：3 步就绪

第一步，注册拿 Key。访问 console.deepgram.com 用邮箱注册，新账号自动获赠 $200 免费额度。在 Console 的 API Keys 页面创建一把 Key 并复制保存。

第二步，安装官方 Python SDK。包名为 deepgram-sdk，注意不是 deepgram 或 deepgram-ai。

第三步，配置环境变量并验证连通性。用官方示例音频跑一次 REST 批转写，能返回 JSON 即完成验证。

若输出为一段可读的英文访谈文本，说明 Key、网络与模型参数全部正常。注意鉴权头写法是 Authorization: Token <key>，前缀是 Token 而不是 Bearer。

# 1) 安装官方 Python SDKpip install deepgram-sdk # 2) 配置 API Key（去 console.deepgram.com 创建）export DEEPGRAM_API_KEY="你的_API_KEY" # 3) 验证：官方示例音频批转写curl -s -X POST "https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true" \  -H "Authorization: Token $DEEPGRAM_API_KEY" \  -H "Content-Type: application/json" \  -d '{"url": "https://static.deepgram.com/examples/interview-script.mp3"}' \  | jq '.results.channels[0].alternatives[0].transcript'

快速上手：30 分钟跑通转写 + 合成最小闭环

最小闭环的思路：先用 REST 把一段现成音频转成文本，再把文本交给 TTS 合成回语音，验证 STT 与 TTS 两条链路。步骤如下：

1. 在 Console → API Keys 创建 Key，复制到环境变量。

2. 确认 deepgram-sdk 已安装。

3. 新建 transcribe_demo.py，粘贴下方 Python 批转写代码，填入 Key 后运行，观察输出 JSON。

4. 把输入换成自己的音频（支持 mp3/wav/flac/m4a 等格式；REST 也支持传公网 URL 或二进制字节）。

5. 用下方 TTS 命令把一句文本合成 MP3，本地播放验证音质。

6. 进阶：换成 WebSocket 流式接口，边发音频边打印实时识别结果（代码见“核心能力详解”支柱一）。

运行后，results.channels[0].alternatives[0].transcript 即是全文，words 数组带每个词的开始/结束时间戳，可直接生成字幕。随后执行 TTS 验证合成链路：

from deepgram import DeepgramClient, PrerecordedOptions API_KEY = "YOUR_DEEPGRAM_API_KEY" client = DeepgramClient(API_KEY) with open("audio.wav", "rb") as f:    payload = {"buffer": f.read()} # 批转写：识别 + 标点/数字规范化 + 说话人分离options = PrerecordedOptions(    model="nova-3",    smart_format=True,   # 自动加标点、规范化数字日期货币    diarize=True,        # 说话人分离，适合多人会议)res = client.listen.prerecorded.v("1").transcribe_file(payload, options)print(res.to_json(indent=2))

curl -s -X POST "https://api.deepgram.com/v1/speak?model=aura-2-athena-en&encoding=mp3" \  -H "Authorization: Token $DEEPGRAM_API_KEY" \  -H "Content-Type: application/json" \  -d '{"text": "This audio was generated by Deepgram Aura."}' \  -o output.mp3

核心能力详解：4 大支柱

支柱一：WebSocket 流式转写（Streaming STT）。这是 Deepgram 的招牌能力。客户端建立 wss://api.deepgram.com/v1/listen?model=nova-3 长连接后持续发送音频字节，服务端边接收边产出结果。开启 interim_results=true 可拿到边听边出的中间结果（适合实时字幕）；endpointing=300 表示检测到 300ms 静音即判定一句话结束并返回最终结果；vad_events=true 可拿到语音开始/结束事件。若发送的是原始 PCM 数据，必须声明 encoding=linear16&sample_rate=16000&channels=1，否则识别内容会乱码。Python 示例：

支柱二：REST 批处理转写与智能后处理。POST /v1/listen 接收公网 URL 或二进制音频，适合离线文件。常用参数：smart_format=true 一次性完成标点、数字、日期、货币、邮箱的格式化；diarize=true 做说话人分离，配合 utterances=true 按话轮切分；keywords=某词:2 对自定义词加权，大幅降低人名、产品名的误识别；profanity_filter=true 过滤敏感词。另支持 callback 参数——服务端转写完成后把结果 POST 到你的回调地址，适合大批量异步处理。

支柱三：Aura 语音合成（TTS）。POST /v1/speak 把文本合成语音，模型名如 aura-2-athena-en、aura-2-zeus-en 等，支持英、中、西、法、德等多语言音色，可调 rate（语速）、volume（音量）、pitch（音高）。输出编码用 encoding 参数指定（mp3/wav/ogg/linear16 等）。WebSocket 版 /v1/speak 支持边合成边下发音频块，显著降低首包延迟，适合实时播报。

支柱四：Voice Agent API（语音 Agent）。client.agent 系列接口把 STT→LLM→TTS 整条链路封装成单路 WebSocket 会话：服务端负责转写、调用你指定的大模型（支持 OpenAI、Anthropic、Gemini 等，通过 persona 配置供应商与系统提示词），再把回复合成语音下发。官方口径语音到语音端到端延迟低于 800ms，比自行串联三段 API 更易守住体验底线，是 IVR 客服、外呼营销、语音助手的直接基础设施。

from deepgram import DeepgramClient, LiveOptions, LiveTranscriptionEvents client = DeepgramClient("YOUR_DEEPGRAM_API_KEY")conn = client.listen.live.v("1") def on_transcript(_self, result, **kwargs):    text = result.channel.alternatives[0].transcript    if text:        print(f"[实时] {text}") conn.on(LiveTranscriptionEvents.Transcript, on_transcript) options = LiveOptions(    model="nova-3", language="zh",    interim_results=True, endpointing=300,)conn.start(options) with open("audio.wav", "rb") as f:    while chunk := f.read(4096):        conn.send(chunk)    conn.finish()

生产部署与监控：从上线到运维

部署方式一：批处理任务走 callback 异步化。不要对每个文件同步等结果。把 callback 参数指向你自己的接收端点，Deepgram 转写完成后向该地址 POST 结果，回调侧做校验与落库；配合指数退避重试应对 5xx 与超时。大批量任务可再通过 GET /v1/usage 系列接口按项目对账分钟数。

部署方式二：流式场景按并发连接水平扩展。每个 WebSocket 连接对应一路实时音频，客户端维护连接池并按业务并发峰值预估规模。鉴权一律走服务端：浏览器或移动端只连你的后端，由后端持有 API Key 并转发音频流，避免密钥泄漏；数据主权敏感场景可咨询企业版区域部署选项。

可观测性。Console 的 Usage 页面按项目聚合每日分钟数与费用，支持设置预算告警；GET /v1/projects/{project_id}/usage/requests 可拉取每次请求的明细（时长、模型、费用）。服务状态查看 status.deepgram.com。常见错误码：401/403 为 Key 无效或权限不足，429 为超限流（指数退避重试），400 多为音频编码或参数不匹配（先检查 encoding/language/model）。

<p class="para-label">避坑清单：</p>

<ul class=“dash-list“><li>API Key 严禁放前端：浏览器直连会暴露密钥且受 CORS 拦截，务必由你的后端持有 Key 并代理转发音频流。</li><li>流式原始 PCM 必须声明 encoding/sample_rate/channels（如 linear16@16000 单声道），漏声明会导致乱码或高延迟；带 WAV 头的文件可省略。</li><li>Python SDK v2→v3 API 不兼容：连接从 client.listen.prerecorded 变为 client.listen.prerecorded.v(”1”)，升级前看迁移文档，别直接复制旧代码。</li><li>$200 免费额度用完后自动转计费，在 Console 提前设置账单告警或硬限额，避免一次批量跑量产生意外费用。</li><li>endpointing 值决定断句节奏：设太小（如 50ms）一句话会被切碎，设太大（如 2000ms）最终结果迟迟不出，实时对话建议 200-500ms。</li></ul>

版本迭代

Deepgram 的产品主线是“更快、更多语言、更全链路”。2022 年 Nova-2 确立了亚 300ms 低延迟与行业领先准确率，2023 年补齐多语言转写与 Aura 语音合成，2024 年推出 Voice Agent API 把语音 Agent 做成开箱产品，2025 年 Aura-2 与 Nova-3 分别升级 TTS 与 STT 的准确率、语言覆盖与速度。

AI 应用场景

常见误区

面试题

参考来源

• webpageDeepgram 官网产品总览、定价与客户案例