text-to-speech

ElevenLabs 文本转语音

将文本转换为自然语音——支持 70 多种语言，提供多种模型，可在音质与延迟之间权衡。

**设置：**请参阅安装指南。对于 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_multilingual_v2"
)

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";

const client = new ElevenLabsClient();
const audio = await client.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Hello, welcome to ElevenLabs!",
  modelId: "eleven_multilingual_v2",
});
audio.pipe(createWriteStream("output.mp3"));

cURL

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "Hello!", "model_id": "eleven_multilingual_v2"}' --output output.mp3

模型

模型 ID	语言	延迟	适用场景
eleven_v3	70 多种	标准	最高音质、丰富的情感表现
eleven_multilingual_v2	29 种	标准	高音质、长篇内容
eleven_flash_v2_5	32 种	~75ms	超低延迟、实时场景
eleven_flash_v2	英语	~75ms	仅英语、速度最快
eleven_turbo_v2_5	32 种	~250-300ms	音质与速度均衡
eleven_turbo_v2	英语	~250-300ms	仅英语、均衡表现

语音 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 及更高版本的模型）。
• 说话人增强：通过后期处理提升清晰度和语音相似度。

from elevenlabs import VoiceSettings

audio = client.text_to_speech.convert(
    text="Customize my voice settings.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    voice_settings=VoiceSettings(
        stability=0.5,
        similarity_boost=0.75,
        style=0.5,
        speed=1.0,             # 0.25 to 4.0 (default 1.0)
        use_speaker_boost=True
    )
)

语言指定

指定发音所用的语言：

audio = client.text_to_speech.convert(
    text="Bonjour, comment allez-vous?",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2",
    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",
    apply_text_normalization="on"
)

请求拼接

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

# First request
audio1 = client.text_to_speech.convert(
    text="This is the first part.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    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",
    previous_text="This is the first part."
)

输出格式

格式	描述
mp3_44100_128	MP3 44.1kHz 128kbps（默认）——压缩格式，适用于网站和应用
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_flash_v2_5"  # Ultra-low latency
)

for chunk in audio_stream:
    play_audio(chunk)

WebSocket 流式传输请参阅 references/streaming.md。

错误处理

try:
    audio = client.text_to_speech.convert(
        text="Generate speech",
        voice_id="invalid-voice-id"
    )
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_multilingual_v2"
)
audio = response.parse()
print(f"Characters used: {response.headers.get('x-character-count')}")

参考资料

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