ElevenLabs APIで音声AIエージェント構築

「音声で話しかけると、AIが応答してくれる」——そんなエージェントを自分で作れたら、どれだけ可能性が広がるだろうと考えたことはないだろうか。

実際に構築してみると、ElevenLabsのAPIはそのハードルを驚くほど下げてくれる。テキスト→音声の変換だけでなく、音声クローン、リアルタイムストリーミング、そしてVoice Agentsプラットフォームまで、すべてが統一されたAPIで扱える。この記事では、ElevenLabs APIを使った音声AIエージェントの構築を、コピペ可能なコード例つきで順を追って解説する。

AIエージェントの基本的な設計パターンについては、AIエージェント構築完全ガイドで体系的にまとめているので、あわせて参照してほしい。

まず試したい「5分即効」セットアップ3選

即効テクニック1：基本的なTTS（テキスト→音声）API呼び出し

ElevenLabsのPython SDKを使えば、数行でテキストを音声に変換できる。まずはシンプルなTTSから始めてみよう。

# 動作環境: Python 3.10+, elevenlabs>=1.9.0
# インストール: pip install elevenlabs python-dotenv
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
from elevenlabs import save

load_dotenv()

client = ElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])

# 音声生成（モデル: eleven_flash_v2_5 = 低レイテンシ約75ms）
audio = client.text_to_speech.convert(
    voice_id="pNInz6obpgDQGcFmaJgB",  # Adam（デフォルト音声）
    output_format="mp3_44100_128",
    text="こんにちは。私はAIエージェントです。何かお手伝いできることはありますか？",
    model_id="eleven_flash_v2_5",     # リアルタイム用途に推奨
    voice_settings={
        "stability": 0.5,         # 感情の幅 (0=豊か, 1=安定)
        "similarity_boost": 0.75, # 元の声への忠実度
        "speed": 1.0              # 再生速度
    }
)

save(audio, "output.mp3")
print("音声ファイルを生成しました: output.mp3")

動作環境: Python 3.10+, elevenlabs SDK 1.9.0以上
モデル選択ポイント: リアルタイムエージェントには eleven_flash_v2_5（約75ms）、品質重視なら eleven_turbo_v2_5（250-300ms）が適している。

即効テクニック2：ストリーミング出力でリアルタイム応答

エージェントと会話する場合、生成完了を待ってから再生すると遅延が気になる。ストリーミングを使えば生成と同時に再生できる。

# ストリーミングTTS（生成しながら再生）
# 追加インストール: pip install pyaudio

import pyaudio
from elevenlabs.client import ElevenLabs
from elevenlabs import stream

client = ElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])

def speak_streaming(text: str, voice_id: str = "pNInz6obpgDQGcFmaJgB"):
    """テキストをストリーミングで音声再生する"""
    audio_stream = client.text_to_speech.convert_as_stream(
        voice_id=voice_id,
        text=text,
        model_id="eleven_flash_v2_5",
        output_format="pcm_24000",  # ストリーミング用フォーマット
    )
    # ストリームをリアルタイム再生
    stream(audio_stream)

# 使用例: LLMの応答をリアルタイムで読み上げ
llm_response = "処理が完了しました。結果は次の通りです..."
speak_streaming(llm_response)

即効テクニック3：インスタント音声クローン

自分の声や特定のキャラクター音声を複製して、エージェントに使わせることができる。Starter以上のプランで利用可能。

# インスタント音声クローン（要: Starterプラン以上）
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

from elevenlabs.client import ElevenLabs

client = ElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])

# 音声クローンを作成（サンプル音声ファイルが必要）
voice = client.clone(
    name="MyAgent",
    description="AIエージェント用カスタム音声",
    files=["sample_voice.mp3"],  # 最低1分以上の明瞭な音声サンプル
)

print(f"クローンID: {voice.voice_id}")

# 作成したクローンで音声生成
audio = client.text_to_speech.convert(
    voice_id=voice.voice_id,
    text="このボイスクローンでエージェントが話します",
    model_id="eleven_turbo_v2_5",
)

ElevenLabs APIの全体像：3つのアプローチで考える

ElevenLabsのAPIを使った音声AIエージェント構築には、大きく3つのアプローチがある。

実践：LLMと連携した音声会話エージェントの構築

音声入力→LLM→音声出力のパイプライン

実際のプロジェクトで使った、OpenAI Whisper（STT）＋GPT-4o（LLM）＋ElevenLabs（TTS）を組み合わせたシンプルな音声会話エージェントのコードを示す。

# 音声会話エージェント（STT→LLM→TTS パイプライン）
# インストール: pip install elevenlabs openai pyaudio sounddevice numpy
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

import os
import numpy as np
import sounddevice as sd
import tempfile
import wave
from openai import OpenAI
from elevenlabs.client import ElevenLabs
from elevenlabs import stream

openai_client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
el_client = ElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])

VOICE_ID = "pNInz6obpgDQGcFmaJgB"
SAMPLE_RATE = 16000
DURATION = 5  # 録音秒数

def record_audio(duration: int = DURATION) -> str:
    """マイクから音声を録音してファイルに保存"""
    print(f"録音中... ({duration}秒)")
    audio_data = sd.rec(int(duration * SAMPLE_RATE), samplerate=SAMPLE_RATE,
                        channels=1, dtype=np.int16)
    sd.wait()

    # 一時ファイルに保存
    tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
    with wave.open(tmp.name, 'wb') as wf:
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(SAMPLE_RATE)
        wf.writeframes(audio_data.tobytes())
    return tmp.name

def speech_to_text(audio_file: str) -> str:
    """OpenAI Whisperで音声をテキストに変換"""
    with open(audio_file, "rb") as f:
        result = openai_client.audio.transcriptions.create(
            model="whisper-1",
            file=f,
            language="ja"
        )
    return result.text

def get_llm_response(user_message: str, history: list) -> str:
    """GPT-4oから応答を取得"""
    history.append({"role": "user", "content": user_message})
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "あなたは親切な音声AIアシスタントです。簡潔に答えてください。"},
        ] + history,
    )
    assistant_msg = response.choices[0].message.content
    history.append({"role": "assistant", "content": assistant_msg})
    return assistant_msg

def text_to_speech_stream(text: str):
    """ElevenLabsでテキストをストリーミング音声再生"""
    audio_stream = el_client.text_to_speech.convert_as_stream(
        voice_id=VOICE_ID,
        text=text,
        model_id="eleven_flash_v2_5",
        output_format="pcm_24000",
    )
    stream(audio_stream)

# メインループ
def run_voice_agent():
    history = []
    print("音声エージェント起動。Ctrl+Cで終了。")
    while True:
        try:
            audio_file = record_audio()
            user_text = speech_to_text(audio_file)
            print(f"ユーザー: {user_text}")

            if not user_text.strip():
                continue

            response = get_llm_response(user_text, history)
            print(f"エージェント: {response}")
            text_to_speech_stream(response)
        except KeyboardInterrupt:
            print("終了します")
            break

if __name__ == "__main__":
    run_voice_agent()

動作環境: Python 3.10+, openai>=1.30, elevenlabs>=1.9, sounddevice, pyaudio
注意: 録音時間は固定秒数（DURATION）のため、実用的には音量検出による自動終了を実装することを推奨する。

ElevenLabs Voice Agents APIの活用

ElevenLabsは独自のVoice Agentsプラットフォームも提供しており、WebSocket接続による双方向リアルタイム通信が可能だ。電話統合やブラウザ向けの音声エージェントに特に有用。

# Voice Agents API（WebSocket経由のリアルタイム会話）
# インストール: pip install elevenlabs websockets
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

import asyncio
from elevenlabs.client import AsyncElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

async def run_voice_agent_conversation():
    client = AsyncElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])

    # エージェントIDは事前にElevenLabs管理画面で作成
    AGENT_ID = os.environ["ELEVENLABS_AGENT_ID"]

    conversation = Conversation(
        client=client,
        agent_id=AGENT_ID,
        requires_auth=False,
        audio_interface=DefaultAudioInterface(),
        callback_agent_response=lambda response: print(f"エージェント: {response}"),
        callback_user_transcript=lambda transcript: print(f"ユーザー: {transcript}"),
        callback_agent_response_correction=lambda original, corrected: print(f"修正: {original} → {corrected}"),
    )

    conversation.start_session()
    await asyncio.sleep(30)  # 30秒間会話
    conversation.end_session()

asyncio.run(run_voice_agent_conversation())

ElevenLabsプラン比較：用途別の選び方

音声AIエージェントの規模に合わせてプランを選ぼう。以下は2026年4月時点の情報（最終確認: 2026-04-11）。

音声AIエージェントを本番運用するなら、プロフェッショナル音声クローンが使えるCreator（$22/月）以上を検討しよう。

【要注意】よくある失敗パターンと回避策

失敗1：レイテンシを考慮せずモデルを選ぶ

❌ 品質を優先して eleven_multilingual_v2 をリアルタイム会話に使う
⭕ レイテンシ要件に応じてモデルを使い分ける

なぜ重要か: 会話型エージェントでは300ms以上の遅延は体験を著しく損なう。リアルタイム会話には eleven_flash_v2_5（約75ms）を使い、品質重視のナレーションなどには eleven_multilingual_v2 を使う。

失敗2：APIキーをコードにハードコードする

❌ client = ElevenLabs(api_key="sk_...") と直接書く
⭕ 環境変数 os.environ["ELEVENLABS_API_KEY"] か .env ファイルから読む

なぜ重要か: APIキーがGitHubにpushされると、ボットに即座にスキャンされ不正利用される。必ず環境変数で管理する。

失敗3：ストリーミングなしでリアルタイム会話を実装する

❌ 音声ファイル全体の生成を待ってから再生する
⭕ convert_as_stream() でストリーミング再生する

なぜ重要か: テキストが長い場合、非ストリーミングでは体感レイテンシが秒単位になる。ストリーミングを使えば最初の音節が生成された時点で再生が始まる。

失敗4：エラーハンドリングが不十分

❌ API呼び出しをtry-exceptなしで実装する
⭕ レート制限（429）・認証エラー（401）・クォータ超過（402）を個別に処理する

# エラーハンドリングの実装例
from elevenlabs.client import ElevenLabs
from elevenlabs.core.api_error import ApiError
import time

def safe_tts(client: ElevenLabs, text: str, voice_id: str, max_retries: int = 3):
    """レート制限対応のTTS呼び出し"""
    for attempt in range(max_retries):
        try:
            return client.text_to_speech.convert(
                voice_id=voice_id,
                text=text,
                model_id="eleven_flash_v2_5",
            )
        except ApiError as e:
            if e.status_code == 429:  # レート制限
                wait = 2 ** attempt   # 指数バックオフ
                print(f"レート制限。{wait}秒後にリトライ...")
                time.sleep(wait)
            elif e.status_code == 401:
                raise ValueError("APIキーが無効です") from e
            else:
                raise
    raise RuntimeError("最大リトライ回数を超えました")

セキュリティと運用ルール

• APIキー管理: 環境変数 or AWS Secrets Manager / GCP Secret Manager を使う。ローカル開発は .env ファイル（.gitignoreに追加済みか確認）
• 音声クローン利用規約: 他人の声を本人同意なくクローンすることは利用規約違反・法的リスクがある
• コスト管理: ElevenLabsダッシュボードで月次クレジット使用量アラートを設定する。長文テキストを処理する場合、事前に文字数を確認してクレジット残量をチェックする
• ログの匿名化: 音声変換のリクエストテキストにPII（個人情報）が含まれる場合、ログに残す前にマスキングを行う

参考・出典

• ElevenLabs Text to Speech API Reference — ElevenLabs公式ドキュメント（参照日: 2026-04-11）
• ElevenLabs API Pricing — ElevenLabs公式（参照日: 2026-04-11）
• ElevenLabs Documentation Overview — ElevenLabs公式（参照日: 2026-04-11）
• ElevenLabs Cheat Sheet (2026) — WebFuse（参照日: 2026-04-11）

まとめ：今日から始める3つのアクション

1. 今日やること: ElevenLabs無料プランに登録してAPIキーを取得。記事内の基本TTSコードをコピペして動かしてみる（所要10分）
2. 今週中: STT→LLM→TTS パイプラインのコードを自分の用途向けにカスタマイズし、テスト環境で会話の流れを確認する
3. 今月中: 用途に合ったプランを選択し、エラーハンドリングとコスト管理を実装した上で本番環境に展開する

あわせて読みたい:

• AIエージェント構築完全ガイド — エージェント設計パターンの基礎から応用まで
• Langfuse AIエージェント可観測性ガイド — 音声エージェントの監視・評価方法

AIエージェントの導入・開発支援についてのご相談は株式会社Uravation（お問い合わせ）からお気軽にどうぞ。

この記事はAIgent Lab編集部がお届けしました。