text-to-speech

ElevenLabs 文本转语音

将文本转换为自然语音——支持 90 多种语言，并提供多种模型，可在音质与延迟之间权衡。示例默认使用最新且音质最高的模型 eleven_v4。

**在编写任何代码之前进行设置：**如果此项目尚未设置 ELEVENLABS_API_KEY，请先在应用文件夹中运行 npx -y @elevenlabs/cli@latest onboard init，并按照输出的说明操作：它会为用户登录并为项目存储密钥，因此无需任何人手动复制密钥。否则，请参阅安装指南。对于 JavaScript，请仅使用 @elevenlabs/* 包。

快速入门

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

audio = client.text_to_speech.convert(
    text="Hello, welcome to ElevenLabs!",
    voice_id="JBFqnCBsd6RMkjVDRZzb",  # George
    model_id="eleven_v4"
)

with open("output.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createWriteStream } from "fs";
import { Readable } from "stream";

const client = new ElevenLabsClient();
const audio = await client.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Hello, welcome to ElevenLabs!",
  modelId: "eleven_v4",
});
// convert() returns a web ReadableStream — bridge it to a Node stream to write to disk
Readable.fromWeb(audio).pipe(createWriteStream("output.mp3"));

CLI

使用 say 立即播放文本，并使用默认语音和 eleven_v3 模型：

elevenlabs say "Hello!"

当其他命令生成输入内容时，可将文本通过管道传递给 say：

echo "The build finished successfully." | elevenlabs say

需要直接设置请求参数时，请使用 API 命令：

elevenlabs text-to-speech convert --voice-id JBFqnCBsd6RMkjVDRZzb \
  --text "Hello!" --model-id eleven_v4 --output output.mp3

CLI 会自动从环境中读取 ELEVENLABS_API_KEY。

模型

模型 ID	语言	延迟	适用场景
eleven_v4	90+	标准	**默认。**音质最高、情感表现丰富、支持音频标签、语音克隆准确度高
eleven_v4_turbo	90+	~100ms	为 Agent 和交互式应用提供实时 v4 音质（通过 文本转对话 WebSocket）
eleven_flash_v2_5	32	~75ms	延迟最低、成本最低，支持 stream-input WebSocket
eleven_flash_v2	英语	~75ms	仅支持英语，延迟最低
eleven_multilingual_v2	29	标准	上一代模型；生成超长内容时最稳定
eleven_v3	70+	标准	上一代富有表现力的模型

eleven_turbo_v2_5 和 eleven_turbo_v2 已被 Flash 模型取代（输出相同，延迟更低）——请改用 eleven_flash_v2_5 / eleven_flash_v2。

**Eleven v4 说明：**仅支持 stability 和 similarity_boost 语音设置（不支持 style 或 speed），不支持 SSML，也不能用于 stream-input TTS WebSocket。可通过 [whispers]、[laughs]、[sarcastic] 等音频标签直接控制语音输出。

语音 ID

使用预设语音，或在控制面板中创建自定义语音。

热门语音：

• JBFqnCBsd6RMkjVDRZzb - George（男性，叙述风格）
• EXAVITQu4vr4xnSDxMaL - Sarah（女性，轻柔）
• onwK4e9ZLuTAKqWW03F9 - Daniel（男性，权威）
• XB0fDUnXU5powFXDhCwa - Charlotte（女性，对话风格）

voices = client.voices.get_all()
for voice in voices.voices:
    print(f"{voice.voice_id}: {voice.name}")

语音设置

微调语音效果：

• 稳定性：语音保持一致的程度。值越低，情感表现和变化越丰富，但听起来可能不稳定。值越高，输出越平稳、可预测。
• 相似度增强：与原始语音样本的匹配程度。值越高，听起来越像原声，但可能会放大音频瑕疵。
• 风格：强化语音独特的风格特征（v2/v3 模型；Eleven v4 不支持）。
• 语速：语速倍率（v2/v3 模型；Eleven v4 不支持）。
• 说话人增强：通过后期处理提升清晰度和语音相似度。

from elevenlabs import VoiceSettings

audio = client.text_to_speech.convert(
    text="Customize my voice settings.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v4",
    voice_settings=VoiceSettings(
        stability=0.5,          # Lower = more expressive, higher = more consistent
        similarity_boost=0.75,  # Higher = closer to the reference voice
    )
)

语言选择

对于支持强制指定语言的模型，可使用 language_code 指导发音和文本规范化。不支持的语言代码会被忽略，且 eleven_multilingual_v2 不支持 language_code。

audio = client.text_to_speech.convert(
    text="Bonjour, comment allez-vous?",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v4",
    language_code="fr"  # ISO 639-1 code
)

文本规范化

控制数字、日期和缩写如何转换为口语。例如，"01/15/2026" 会转换为 "January fifteenth, twenty twenty-six"：

• "auto"（默认）：由模型根据上下文决定
• "on"：始终进行规范化（适用于希望语音自然的情况）
• "off"：按字面读出（适用于希望读作 "zero one slash one five..." 的情况）

audio = client.text_to_speech.convert(
    text="Call 1-800-555-0123 on 01/15/2026",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v4",
    apply_text_normalization="on"
)

音频效果

使用 audio_effects，通过滤镜预设、感知距离、混响环境、循环播放的背景噪声和立体声声像来处理生成的音频。效果不会改变请求费用。

字段	范围	说明
filter_preset_id	目录 ID	为声音着色的滤镜，例如 phone 或 old_radio
distance	0-1（默认值为 0）	说话者听起来距离麦克风有多远
environment_id	目录 ID	混响环境，例如 small_room 或 hall
send_level	0-1（默认值为 1）	人声输入混响的程度；设为 0 可关闭混响
background_noise_id	目录 ID	在人声下循环播放的背景噪声，例如 cafe 或 keyboard
pan	-1 至 1（默认值为 0）	人声的立体声位置，从最左到最右

通过目录端点（GET /v1/audio-effects/catalog）列出有效的滤镜预设、环境和背景噪声 ID：

from elevenlabs import EffectsSpecInput

catalog = client.audio_effects.get_catalog()
for environment in catalog.environments:
    print(f"{environment.environment_id}: {environment.name}")

audio = client.text_to_speech.convert(
    text="Welcome to the concert hall.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v4",
    audio_effects=EffectsSpecInput(
        environment_id="hall",
        distance=0.3,
        pan=-0.5,
    )
)

混响和非零的 pan 会生成立体声音频，因此不支持 ulaw_*、alaw_* 和 pcm_* 输出格式。未知的效果 ID 会返回 404 错误。

请求拼接

分多次请求生成长音频时，音频片段的边界处可能会出现爆音、不自然的停顿或音调变化。请求拼接可让每个请求了解其前后内容，从而解决此问题：

# First request
audio1 = client.text_to_speech.convert(
    text="This is the first part.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v4",
    next_text="And this continues the story."
)

# Second request using previous context
audio2 = client.text_to_speech.convert(
    text="And this continues the story.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v4",
    previous_text="This is the first part."
)

输出格式

格式	说明
mp3_44100_128	MP3 44.1kHz 128kbps（默认值）——压缩格式，适用于 Web/应用
mp3_44100_192	MP3 44.1kHz 192kbps（Creator+）——更高音质的压缩格式
mp3_44100_64	MP3 44.1kHz 64kbps——音质较低，文件更小
mp3_22050_32	MP3 22.05kHz 32kbps——体积最小的 MP3 文件
pcm_16000	原始 PCM 16kHz——用于实时处理
pcm_22050	原始 PCM 22.05kHz
pcm_24000	原始 PCM 24kHz——适合流式传输，音质和效率均衡
pcm_44100	原始 PCM 44.1kHz（Pro+）——CD 音质
pcm_48000	原始 PCM 48kHz（Pro+）——最高音质
ulaw_8000	μ-law 8kHz——电话系统标准格式（Twilio、电话通信）
alaw_8000	A-law 8kHz——电话通信格式（μ-law 的替代格式）
opus_48000_64	Opus 48kHz 64kbps——高效的流式传输编解码器
wav_44100	WAV 44.1kHz——带标头的未压缩格式

流式传输

使用 stream 方法接收生成过程中的音频块：

audio_stream = client.text_to_speech.stream(
    text="This text will be streamed as audio.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v4"
)

for chunk in audio_stream:
    play_audio(chunk)

对于延迟最为重要的实时应用，可通过 Text to Dialogue WebSocket 使用 eleven_v4_turbo（约 100ms），或通过 HTTP 流式传输或 stream-input WebSocket 使用 eleven_flash_v2_5（约 75ms）。请参阅 references/streaming.md。

错误处理

try:
    audio = client.text_to_speech.convert(
        text="Generate speech",
        voice_id="invalid-voice-id",
        model_id="eleven_v4"
    )
except Exception as e:
    print(f"API error: {e}")

常见错误：

• 401：API 密钥无效
• 422：参数无效（检查 voice_id、model_id）
• 429：超出速率限制

跟踪费用

通过响应标头（x-character-count、request-id）监控字符用量：

response = client.text_to_speech.convert.with_raw_response(
    text="Hello!", voice_id="JBFqnCBsd6RMkjVDRZzb", model_id="eleven_v4"
)
audio = response.parse()
print(f"Characters used: {response.headers.get('x-character-count')}")

参考资料

• 安装指南
• 音频流式传输
• 声音设置