text-to-speech

ElevenLabs Text-to-Speech

テキストから自然な音声を生成します。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

eleven_v3 モデルとデフォルトの音声を使って、テキストをすぐに再生するには say を使用します。

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	エージェントやインタラクティブアプリ向けのリアルタイム v4 品質（Text to Dialogue 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）	音声のステレオ位置。左端から右端まで指定できます

有効なフィルタープリセット、環境、バックグラウンドノイズの ID は、カタログエンドポイント（GET /v1/audio-effects/catalog）で一覧表示できます。

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,
    )
)

リバーブと 0 以外の 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（デフォルト）- 圧縮形式で、ウェブやアプリに適しています
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	Raw PCM 16kHz - リアルタイム処理に使用します
pcm_22050	Raw PCM 22.05kHz
pcm_24000	Raw PCM 24kHz - ストリーミングに適したバランスです
pcm_44100	Raw PCM 44.1kHz（Pro+）- CD 品質です
pcm_48000	Raw 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')}")

リファレンス

• インストールガイド
• 音声のストリーミング
• 音声設定