用 Deepgram API 与 Python SDK 完成语音转写：从申请密钥到跑通第一个转写请求

Deepgram 提供的是语音识别服务：把音频信号转成可读文本，并在转写结果之上提供语言处理能力。对需要做课堂讲座实时转录、企业会议记录、客服通话分析或语音助手交互的团队来说，它省掉了自己训练声学模型、搭推理集群这一大块工作。适合的读者是掌握基本 Python 编程技能、希望用几行代码把语音转写接进自己应用的开发者；如果你只是想手工转写一两段录音，用现成的转写网页工具更省事，可以先用 Deepgram 这类在线服务试一下效果，再决定是否走 API 集成。

下面按「拿到凭证 → 装 SDK → 发请求 → 处理结果」的顺序展开，命令和参数都给出可直接照抄的形式。涉及价格、免费额度、可用模型与版本的信息变动频繁，请以 Deepgram 官网当前公布的信息为准。

准备工作

账号与身份认证

第一步是注册开发者账号。注册过程中需要填写基本的个人信息和项目描述，项目描述的作用是让服务方了解你的使用场景，填写时如实写明用途即可，不必刻意包装。

注册完成后登录开发者控制台。首次登录时系统会要求完成身份认证，这是账户安全流程的一部分，认证通过后才能正常使用控制台功能。如果认证环节卡住，先确认注册邮箱可以正常收信，再检查浏览器是否拦截了验证流程所需的跳转。

生成并保管 API 密钥

认证通过后，在控制台导航到「API 密钥」页面，点击「生成新密钥」，系统会自动生成一个新的 API 密钥。这个密钥是调用 Deepgram 服务的唯一凭证，务必妥善保管。

密钥管理上有几条实践值得一开始就做对：

• 不要把密钥硬编码进源码后提交到版本库，改用环境变量或密钥管理服务注入。
• 限制能够访问密钥的人和系统范围，只给真正需要调用接口的服务发放。
• 定期轮换密钥，旧密钥在确认无调用后及时吊销。
• 一旦怀疑泄露，立即在控制台生成新密钥并停用旧的，不要抱着「应该没人看到」的侥幸。

Python 环境

SDK 以 Python 包的形式提供，需要本地有可用的 Python 解释器和 pip。建议在虚拟环境里安装，避免和系统里其他项目的依赖互相干扰：

python -m venv venv
source venv/bin/activate
pip install deepgram

Windows 下激活虚拟环境的命令是 venv\Scripts\activate。安装完成后，把密钥写进环境变量，后续代码从环境变量读取，而不是写在脚本里：

export DEEPGRAM_API_KEY="你的密钥"

Windows PowerShell 下对应的是 $env:DEEPGRAM_API_KEY="你的密钥"。具体安装包名与版本以官网当前文档为准，不同版本之间接口可能有调整。

操作步骤

第一步：初始化客户端

SDK 的入口是一个客户端对象，构造时传入 API 密钥。把密钥从环境变量读出来再传进去，是兼顾可用性与安全性的常见写法：

import os
import deepgram

api_key = os.environ["DEEPGRAM_API_KEY"]
dg_client = deepgram.Deepgram(api_key)

客户端对象创建后可以复用，不必每次请求都重新构造。如果你的应用是多线程或异步服务，注意按 SDK 的线程安全性来安排实例的共享方式。

第二步：选择音频输入方式

SDK 支持多种音频源输入，包括本地文件、远程 URL 和实时流。三种方式对应不同的使用场景：

• 本地文件：适合离线批处理，比如把一批已经录好的会议音频统一转成文字稿。
• 远程 URL：适合音频已经存放在对象存储或 CDN 上的情况，服务端直接拉取，省去本地下载再上传的往返。
• 实时流：适合需要边说边出字的场景，例如课堂实时字幕、语音助手、在线客服的即时转写。

选择哪种输入，取决于音频现在在哪里、以及结果需要多快拿到。批处理场景优先用文件或 URL，交互场景才考虑实时流。

第三步：发起转写请求

对文件或 URL 做转写，调用的是转写方法，传入音频来源即可拿到结果：

response = dg_client.transcribe_audio("音频文件路径或音频 URL")
print(response)

这一步是整个流程里最短的一段代码，但真正决定结果质量的是音频本身：采样率过低、背景噪声过大、多人抢话的录音，转写准确率都会下降。在接入业务之前，先用几段真实场景的音频跑一遍，确认效果能接受，再决定是否上线。

第四步：读取并处理返回结果

转写返回的是一个结构化结果，而不是一段纯字符串。实际使用时通常需要从结果里取出转录文本，再交给下游做检索、摘要或分析。建议先把返回结构打印出来看清楚字段层级，再写取值代码，避免凭猜测写字段名：

response = dg_client.transcribe_audio("音频文件路径或音频 URL")
print(response)

如果要把结果落库或送入检索系统，注意保留时间戳等定位信息，只存纯文本会丢掉「这句话出现在第几分几秒」的能力，后续做字幕或录音回放定位时还得重新转写一遍。

第五步：按场景调整参数

SDK 支持多种自定义选项和设置，可以根据实际需求调整参数。常见的调整方向包括语言与方言的选择、是否启用额外的语言处理能力等。参数的具体名称、取值范围和默认值随 SDK 版本变化，写代码前对照官网当前文档确认，不要照抄旧版本示例里的参数名。

调整参数时建议一次只改一项，用同一段音频对比前后结果，这样才能判断是哪一项设置带来了变化。同时改三四个参数再对比，出了问题很难定位原因。

一个完整示例

下面是一个从读取密钥到打印转写结果的最小可运行脚本。把音频文件路径换成你自己的文件，或者直接换成一段可公开访问的音频 URL：

import os
import deepgram

# 1. 从环境变量读取密钥
api_key = os.environ["DEEPGRAM_API_KEY"]

# 2. 初始化客户端
dg_client = deepgram.Deepgram(api_key)

# 3. 指定音频来源：本地文件路径或远程 URL
audio_source = "meeting-sample.wav"

# 4. 发起转写
response = dg_client.transcribe_audio(audio_source)

# 5. 输出结果
print(response)

运行前确认三件事：环境变量已经设置、音频文件路径正确、虚拟环境已激活。运行后如果拿到的是结构化结果而不是报错，说明凭证和网络链路都是通的，接下来就可以把这段逻辑封装成函数，接入你自己的业务流程。

封装时建议把「读取密钥」「构造客户端」「发起转写」「解析结果」拆成独立的部分。密钥读取和客户端构造在应用启动时做一次，转写和解析按请求调用，这样既避免重复初始化，也方便在测试时替换音频来源。

注意事项

密钥安全

API 密钥是访问服务的唯一凭证，泄露的后果是别人可以用你的账户额度调用接口。除了前面提到的环境变量、访问限制和定期轮换之外，还要注意日志：调试时打印请求对象可能把密钥一并打进日志文件，上线前检查一遍日志里是否出现了密钥字符串。

音频质量决定结果上限

语音识别引擎负责把音频信号转成文本，但输入音频的质量决定了它能做到多好。远场录音、强噪声环境、多人重叠说话都会拉低准确率。如果业务场景本身噪声较大，先考虑在采集端改善，而不是指望换模型解决。

实时流与批处理的取舍

实时流能边录边出字，但实现复杂度高于文件转写：需要处理连接维持、分片发送、断线重连和结果拼接。如果业务对延迟没有硬性要求，先用文件或 URL 转写把流程跑通，再评估是否值得为实时性付出这部分工程成本。

价格与配额以官网为准

计费方式、免费额度、并发限制、可用模型和语言覆盖范围都属于会调整的信息，本文不给出具体数字。上线前到官网核对当前的定价页和配额说明，按自己的音频时长和并发量估算成本，避免按过时信息做预算。

结果需要人工兜底

转写结果用于会议记录、客服分析这类内部场景时，通常可以直接使用；如果用于对外发布、合同条款或任何有法律效力的文本，应当安排人工校对。语音识别在专有名词、人名、数字和口音较重的内容上更容易出错，这些恰恰是正式文本里最不能错的地方。