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 錯誤：{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"使用的字元數：{response.headers.get('x-character-count')}")

參考資料

• 安裝指南
• 串流音訊
• 語音設定