Python 语音识别教程：从音频文件到转写文本

过去，要为 Python 应用加入语音识别功能并不容易。Python 开发者必须围绕转写流程本身编写代码，包括音频预处理、特征提取和模型集成。此外，工程团队还要处理底层音频处理、转写质量不佳，以及语音与实时字幕之间的延迟问题。

音频模型和语音识别 SDK 的进步改变了这一现状。

在本 Python 语音识别教程中，你将学习把 ElevenLabs 文本转语音 音频模型集成到 Python 项目中，构建可用于商业场景的转写应用。

摘要

• 商用文本转语音模型提供说话人分离、词级时间戳和关键词提示等基础语音识别模型不具备的功能。
• ElevenAPI 通过 Scribe v2 和 Scribe v2 Realtime，为 Python 代码带来语音识别功能。
• 开发者可在 AI 编程平台中安装 ElevenLabs skills，根据官方 API 文档生成准确的 Python 代码。
• 订阅付费计划用于商业开发前，可免费试用 ElevenLabs API。

本 Python 语音识别教程涵盖的内容

本教程涵盖前提条件、API 集成和高级转写功能，帮助你构建适用于企业场景的 Python 语音识别应用。

近年来，语音识别已日趋成熟，尤其是大语言模型和深度学习神经网络改变了 Python 开发者使用转写 SDK 的方式。许多教程会介绍如何构建基础转写应用，但很少涉及商用产品所需的功能。

我们编写本教程，正是为了填补这一空白。

例如，许多企业级转写解决方案需要以下功能：

• 说话人分离：能够在转写文本中识别并区分不同说话人。
• 时间戳：准确标记每个词说出时对应的小时、分钟和秒数。
• 多语言支持：以较低的词错误率捕捉单个录音或直播流中的多种语言语音。
• 关键词提示：映射品牌、产品名称和技术术语等特殊词汇，避免转写拼写错误。
• 低延迟转写：提供毫秒级文本转语音响应，为实时转写应用提供支持。

注意：本教程不止介绍为业余或个人项目生成简单脚本。它不包含构建在 文本转语音 API 集成之上的应用逻辑，因为这些逻辑因业务而异。

集成 Python 语音识别的前提条件

本教程围绕 ElevenAPI 展开。这是 ElevenLabs 提供的生产级 API，可简化代码中与语音模型的交互。通过 ElevenAPI，你可以使用 Scribe v2 和 Scribe v2 Realtime，它们是我们用于批量和实时转写的领先语音模型。

无需直接访问 ElevenLabs 文本转语音模型，只需通过 API 调用传入音频录音、实时流和参数。随后，音频模型会将音频数据转换为文本。完成后，你可在代码中或通过 webhook 接收转写结果。

开始前，请完成以下准备步骤。

1. 注册 ElevenLabs。
2. 创建 API 密钥。
3. 录制一段对话，并上传至可公开访问的存储空间。

准备就绪后，继续阅读下一部分。

设置环境

集成 ElevenLabs 模型前，先设置 Python 环境以安全存储 ElevenLabs API 密钥。与所有 API 密钥一样，建议将其作为环境变量（托管密钥）存储在 .env 文件中。

ELEVENLABS_API_KEY=<your_api_key_here>

发起 API 调用时，传入该环境变量。这样可避免通过公共网络发起 API 请求时意外泄露 API 密钥。

接下来，在 Python 环境中运行 Bash 命令安装 elevenlabs（ElevenLabs SDK）。该 SDK 可让你访问各种语音模型。这里可选择 Scribe v2 或 Scribe v2 Realtime。

pip install elevenlabs
pip install python-dotenv

还需要安装 python-dotenv，它可让 Python 代码访问存储在 .env 文件中的环境变量。

编写第一个转写脚本

设置好 Python 环境后，就可以使用 ElevenLabs Scribe v2 转写音频文件。

ElevenLabs Scribe v2 是行业领先的语音识别模型，可大规模转写音频文件。即使录音中有明显背景噪声，也能高精度识别音素。要转写音频，请通过 ElevenLabs API 将录音发送至模型，并获取完成的转写文本。

以下 Python 代码片段可将音频文件转换为带时间戳和说话人分离标注的转写文本。

# example.py
import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2", # Model to use
    tag_audio_events=True, # Tag audio events like laughter, applause, etc.
    language_code="eng", # Language of the audio file. If set to None, the model will detect the language automatically.
    diarize=True, # Whether to annotate who is speaking
)

print(transcription)

该代码会加载提供所需功能的必要库，并将声明的环境变量载入程序环境。

然后，它使用环境变量中存储的 API 密钥创建 ElevenLabs 客户端。接着下载音频文件并将其转换为二进制数据。

获取原始音频数据后，将其连同多个参数一起发送到 ElevenLabs API。

• model_id 表示要使用的文本转语音模型。由于传入的是音频文件，Scribe v2 是最佳选择。
• tag_audio_events 可用于标注笑声、脚步声和其他背景噪声等非语音片段。
• language_code 表示录音文件中对话的语言。设为 None 时，模型会自动检测语言。
• diarize 表示 是否希望模型根据声纹识别并区分不同说话人。

最后，运行代码，即可在终端中看到转写后的音频文本。

在 Python 中进行流式语音识别

以上示例介绍了适用于预录文件的批量转写。不过，ElevenLabs 还提供可用于构建流式语音识别的 API。不同于批处理，此模式会实时运行语音识别，在对话进行时生成转写文本。

为此，可使用 WebSocket API 将 Python 代码连接至 Scribe v2 Realtime 模型。

Scribe v2 Realtime 采用流式优先架构，转写延迟低于 150 ms。你可以使用 Scribe v2 Realtime 构建会议 智能体、无障碍工具和语音激活自动化等应用。模型会在处理音频流时返回部分转写文本。只有当代码自动或手动提交某个音频片段时，才会返回最终转写文本。

可根据音频来源和应用类型，在服务端或客户端将语音识别与 ElevenLabs API 集成。

• 客户端流式传输 可直接从麦克风或通过手动分块的音频流进行传输。
• 服务端流式传输 可将来自 URL 或音频源的音频数据路由至语音模型。

客户端和服务端流式传输均支持异步 workflow。无需持续轮询 API，可使用 WebSocket 处理结果。在代码中，需要创建用于接收部分和最终转写文本的处理程序。

进阶功能：说话人分离、时间戳和自定义词汇

除了 自动语音识别，ElevenLabs 文本转语音模型还支持说话人分离、时间戳 和自定义词汇。

• 说话人分离：只有批量转写支持 说话人分离。设置 diarize 参数即可启用此功能。不过，批量转写中的多声道转写模式不支持说话人分离。
• 时间戳：进行批量转写时，可选择词级或字符级时间戳。为此，请在使用 convert 方法时设置 timestamps_granularity 参数。
• 自定义词汇：实时和批量转写 都支持关键词提示。此功能会引导模型优先转写列表中指定的关键词。Scribe v2 Realtime 最多支持 50 个关键词，Scribe v2 最多支持 1,000 个关键词。

在 AI 编程助手中使用 ElevenLabs skill

AI 编程助手可加快开发速度。如果你使用 Claude Code、Cursor、Codex 或类似的 AI 编程工具，可在编程环境中添加 ElevenLabs skills。

只需在平台终端中运行以下命令：

 npx skills add elevenlabs/skills --skill speech-to-text 

AI 编程智能体会从 ElevenLabs 的 GitHub 仓库 下载文本转语音 skill，并将其安装到本地 skill 目录。这样便可根据 ElevenLabs 官方文档自动生成 Python 语音识别代码，无需从头编写完整的 API 集成。

安装后，只需用自然语言描述所需功能，即可生成 Python 语音识别代码。编程助手会根据描述，使用文本转语音 skill 和正确的模型及参数自动生成代码。

例如，在 Codex 中输入“创建一个支持说话人分离和词级时间戳转写的 Python 语音识别代码片段”，即可获得与下方类似的代码片段。

使用 ElevenAPI 开始进行语音识别

ElevenAPI 可让你访问高级文本转语音模型，在 Python 中构建语音识别应用。

使用 ElevenAPI，无需从头编写可能拖慢产品创新的集成代码。你可以改用提供满足商业级需求的文本转语音服务的 SDK，例如关键词提示、说话人分离和时间戳。

立即获取 ElevenLabs API 密钥，并查看我们的 官方文档，了解 API 的工作原理。

常见问题