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 到 4.0（默认 1.0）
        use_speaker_boost=True
    )
)

语言选择

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

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

文本规范化

控制数字、日期和缩写如何转换为口语。例如，“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"
)

请求拼接

当在多个请求中生成长音频时，音频可能在边界处出现爆音、不自然的停顿或音调变化。请求拼接通过让每个请求知道其前后内容来解决此问题：

# 第一个请求
audio1 = client.text_to_speech.convert(
    text="This is the first part.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    next_text="And this continues the story."
)

# 第二个请求，使用前文上下文
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"  # 超低延迟
)

for chunk in audio_stream:
    play_audio(chunk)

参见references/streaming.md了解WebSocket流式传输。

错误处理

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')}")

参考

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