文本转语音和语音智能体 API | ElevenLabs Documentation

使用编程智能体快速开始，无需提前注册账户或准备 API 密钥。

将以下内容粘贴到 Claude Code、Cursor 或 Codex 中。它会为你登录或创建账户、创建密钥，并将 SDK 添加到项目中。

Add ElevenLabs to my project: run `npx -y @elevenlabs/cli@latest onboard init` and follow what it prints.

了解其工作原理，或阅读 onboard 命令的源代码，查看它会向智能体提供哪些具体指令。

ElevenLabs 如何运作？

ElevenLabs 提供 AI 语音基础设施，包括文本转语音、语音转文本、语音克隆、语音智能体和生成式音频。可通过 4 种方式使用，分别适合不同用户。

ElevenCreative 是一款无需代码的网页应用，创作者、制作人和编辑可直接在浏览器中生成旁白配音、音乐、配音和工作室项目。

ElevenAgents 是用于设计和运营语音智能体的平台，为非技术用户提供可视化构建器，也为开发者提供完整的编程控制能力。

ElevenAPI 通过 REST 接口提供所有功能，并配有官方 Python 和 TypeScript SDK，开发者可将语音嵌入自己的应用和工作流程。

Reception.ai 是面向中小企业、可直接部署的 AI 电话接待员，可接听电话、预约和通过统一仪表板管理日常运营。

选择适合的路径

ElevenCreative

通过分步指南了解如何使用 ElevenCreative 平台

ElevenAgents

了解如何使用 ElevenLabs 构建、发布和扩展智能体

ElevenAPI

通过示例和教程了解如何集成 ElevenLabs API

概念

音色是生成音频时使用的语音角色。每个音色都有唯一 ID，例如 JBFqnCBsd6RMkjVDRZzb，可在仪表板中选择或在 API 请求中传入。ElevenLabs 维护着一个包含 10,000+ 个音色的声音库。你也可以根据音频录音克隆音色，或根据文字描述生成音色。

模型决定生成音频的质量、延迟和语言覆盖范围。eleven_v4 可在 90+ 种语言中生成最具表现力的输出。eleven_v4_turbo 面向实时使用场景，中位推理延迟约为 100ms。每项功能——语音转文本、音乐、音效——都有专属模型。请参阅该使用哪个模型？进行选择。

定价如何计算？

积分是所有产品共用的消耗单位。文本转语音每输入 1 个字符消耗 1 积分。其他操作按处理音频的秒数计费。积分每月重置，未使用的积分最多可结转 2 个月。完整说明请参阅定价。

如果不想订阅月度套餐，可使用按量付费预存余额。在用完订阅积分后，使用 ElevenLabs 时会从余额中扣除。

为生产环境而构建

ElevenLabs 文本转语音有多快？

Eleven Flash v2.5 的模型推理延迟约为 75ms，Eleven v4 Turbo 的中位延迟约为 100ms。Scribe v2 Realtime 可在约 150ms 内返回部分转录结果。这些数据不包括应用和网络延迟，因此用户实际听到音频所需时间会更长。了解延迟介绍了这些数据的涵盖范围，延迟优化则说明如何降低端到端延迟。

ElevenLabs 如何处理规模扩展？

套餐决定了可同时处理的请求数量。并发限制并非同时进行的对话数量上限：通常，5 的并发限制可支持约 100 路同时音频播放，具体取决于所用音色和使用场景。企业版套餐提供更高的限制。请参阅并发与优先级，了解各套餐的限制和负载测试指导。

企业控制功能

私有部署 可在自己的云账户中运行 ElevenAgents、文本转语音和语音转文本，让文本、音频和转录内容始终留在网络内。
数据驻留 将数据存储在欧盟、印度或新加坡的隔离环境中，而非默认的美国位置。这是企业版功能。
工作区 集中管理计费、共享资源、团队访问权限和 API 密钥。企业版工作区支持通过 SAML 2.0 或 OIDC 使用 SSO，并以 OCSF 架构记录管理操作的审计日志。

生成首段音频

安装 SDK，将 API 密钥设为环境变量，然后通过一次请求将文本转换为 MP3 文件。如需让编程智能体完成此设置，请参阅使用编程智能体设置。

安装 SDK

pip install elevenlabs python-dotenv

设置 API 密钥

创建 API 密钥，并将其添加到项目目录中的 .env 文件：

.env

ELEVENLABS_API_KEY=<your_api_key_here>

生成并保存音频

from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
import os
load_dotenv()
elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)
audio = elevenlabs.text_to_speech.convert(
    text="The first move is what sets everything in motion.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",  # "George" - browse voices at elevenlabs.io/app/voice-library
    model_id="eleven_v4",
    output_format="mp3_44100_128",
)
with open("output.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

使用 python example.py 或 npx tsx example.mts 运行脚本，然后打开 output.mp3。如需通过终端完成相同操作，请使用 ElevenLabs CLI：

elevenlabs text-to-speech convert \
  --voice-id JBFqnCBsd6RMkjVDRZzb \
  --model-id eleven_v4 \
  --text "The first move is what sets everything in motion." \
  --output-format mp3_44100_128 \
  --output output.mp3

ElevenAPI 快速入门更详细地介绍了相同请求，包括 CLI 设置及通过扬声器播放音频。

使用 ElevenAgents 可以构建什么？

ElevenAgents 将语音识别、自选 LLM、文本转语音和轮次管理整合为一个语音智能体，可在仪表板中或通过 SDK 进行配置。

客户支持：为智能体添加知识库，根据自己的文档回答问题。
电话线路：通过原生集成连接 Twilio 号码，处理呼入和呼出电话，或通过 SIP 中继接入现有电话系统。
外呼活动：使用批量呼叫同时拨打大量外呼电话。
网站和应用：使用 widget 嵌入同时支持语音和文本的智能体。

ElevenAgents 快速入门将带你从头到尾构建第一个智能体。

该使用哪个模型？

从使用场景开始。下方每个模型 ID 都是在 API 请求中传入 model_id 的值。

使用场景	推荐模型	模型 ID	原因
实时语音智能体	Eleven v4 Turbo	`eleven_v4_turbo`	中位推理延迟约为 100ms†，提供最具表现力的实时语音效果。如需最低延迟，请使用 `eleven_flash_v2_5`（约 75ms†）。
富有表现力或长篇旁白	Eleven v4	`eleven_v4`	最具表现力的模型，适合有声书和角色旁白配音。每次请求最多 10,000 个字符（约 10 分钟音频）。如需最稳定的长篇输出，请使用 `eleven_multilingual_v2`。
多语言内容	Eleven v4	`eleven_v4`	支持 90+ 种语言，切换语言时仍能保持稳定的音色质量。`eleven_v4_turbo` 可实时支持相同语言。
最低成本	Eleven Flash v2.5	`eleven_flash_v2_5`	API 生成每字符价格低 50%，支持 32 种语言，每次请求最多 40,000 个字符。
批量语音转文本	Scribe v2	`scribe_v2`	支持 90+ 种语言的转录，提供词级时间戳、最多 32 位说话人的说话人分离和关键词提示。临床音频请使用 `scribe_v2_medical`。
实时语音转文本	Scribe v2 Realtime	`scribe_v2_realtime`	以约 150ms† 的延迟流式传输 90+ 种语言的转录结果。