Speech Engineクイックスタート | ElevenLabs Documentation

このガイドでは、Speech Engineを使用して音声対応エージェントを構築します。LLMをElevenLabsに接続するサーバーをセットアップし、ブラウザクライアントを接続することで、ユーザーがエージェントと音声で会話できるようにします。

ElevenLabs Speech Engineスキルを使用して、チャットエージェントに音声を追加します。

npx skills add elevenlabs/skills --skill speech-engine

Speech Engineの仕組み

Speech EngineはLLMをElevenLabsに接続し、ユーザーがエージェントに話しかけ、その応答を聞けるようにします。ElevenLabsがスピーチtoテキストとテキスト読み上げを処理し、サーバー側でLLMロジックを提供します。

各WebSocket接続は1つの会話を表します。ユーザーが話すと、ElevenLabsがオーディオを文字起こししてサーバーへ送信します。サーバーはそれをLLMに渡し、応答をストリーミングで返します。ElevenLabsがテキストを音声に変換し、ブラウザで再生します。SDKが接続管理、ターンテイキング、割り込み検出を処理します。

前提条件

このチュートリアルでは、LLMにOpenAIのAPIを使用します。OPENAI_API_KEY環境変数に設定されたOpenAI APIキーが必要です。

サーバーのセットアップ

APIキーを作成

APIに安全にアクセスするために使用するAPIキーは、ダッシュボードで作成できます。

キーは管理されたシークレットとして保存し、好みに応じて .env ファイルを通じた環境変数として、またはアプリの設定で直接SDKに渡してください。

.env

ELEVENLABS_API_KEY=<your_api_key_here>

依存関係をインストール

pip install elevenlabs openai python-dotenv

サーバーを公開

Speech Engineにはパブリックにアクセス可能なURLが必要です。ngrokを使用してローカルサーバーを公開します。サーバーはまだ作成しませんが、次のステップで使用するURLを取得するため、先にngrokを実行しておく必要があります。

ngrok http 3001

転送URL（例：https://abc123.ngrok.io）をコピーします。

Speech Engineインスタンスを作成

SDKを使用してSpeech Engineインスタンスを作成します。WebSocket URLには、ngrok URLに/wsパスを追加して渡します。

import asyncio
from dotenv import load_dotenv
from elevenlabs import AsyncElevenLabs
load_dotenv()
elevenlabs = AsyncElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
async def main():
    engine = await elevenlabs.speech_engine.create(
        name="My Speech Engine",
        speech_engine={
            # Note we use the wss protocol instead of https
            "ws_url": "wss://abc123.ngrok.io/ws",
        },
    )
    print(f"Speech Engine ID: {engine.engine_id}")
if __name__ == "__main__":
    asyncio.run(main())

このスクリプトを実行し、次のステップで使用するSpeech Engine ID（例：seng_8k3m9xr4hjnfg983brhmhkd98n6）をコピーします。

サーバーを作成

以下の内容でserver.pyまたはserver.mtsというファイルを作成します。サーバーをセットアップし、/wsパスにSpeech Engineを接続して、OpenAIで応答を生成します。

import asyncio
import os
from dotenv import load_dotenv
from openai import AsyncOpenAI
from elevenlabs import AsyncElevenLabs
load_dotenv()
# Replace with your Speech Engine ID from step 4
SPEECH_ENGINE_ID = "seng_8k3m9xr4hjnfg983brhmhkd98n6"
openai = AsyncOpenAI(
  api_key=os.getenv("OPENAI_API_KEY"),
)
elevenlabs = AsyncElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)
def on_init(conversation_id, session):
    print(f"Session started: {conversation_id}")
async def on_transcript(transcript, session):
    stream = await openai.responses.create(
        model="gpt-4o",
        instructions="You are a helpful voice assistant. Keep responses concise and conversational.",
        input=[
            {"role": "assistant" if m.role == "agent" else m.role, "content": m.content}
            for m in transcript
        ],
        stream=True,
    )
    await session.send_response(stream)
def on_close(session):
    print(f"Session ended: {session.conversation_id}")
def on_error(err, session):
    print(f"Error: {err}")
async def main():
    engine = await elevenlabs.speech_engine.get(SPEECH_ENGINE_ID)
    await engine.serve(
        port=3001,
        path="/ws",
        debug=True,
        on_init=on_init,
        on_transcript=on_transcript,
        on_close=on_close,
        on_error=on_error,
    )
if __name__ == "__main__":
    asyncio.run(main())

onTranscript / on_transcriptコールバックは、会話履歴全体と現在のセッションを受け取ります。TypeScript SDKは、ユーザーが応答の途中で割り込んだ場合に発火するAbortSignalも提供します。OpenAI呼び出しにsignalを渡すと、割り込み時にLLMリクエストが自動的にキャンセルされます。

sendResponse() / send_response()は、文字列、非同期イテラブル、またはOpenAI、Anthropic、Google Geminiからのストリームを受け取ります。SDKがテキストコンテンツを自動的に抽出します。

上記の例では、ユーザーからの完全な文字起こしがLLMに渡されます。本番環境では、プロンプトインジェクションや操作の試みを防ぐためのガードレールを追加してください。

サーバーを起動

python server.py

クライアントのセットアップ

クライアントSDKをインストール

React

JavaScript

npm install @elevenlabs/react

トークンエンドポイントを作成

会話トークンを生成するサーバーサイドエンドポイントを追加します。これによりAPIキーをブラウザに公開せず、最高のオーディオ品質を実現するWebRTCを使用できます。

import os
from dotenv import load_dotenv
from flask import Flask, jsonify
from elevenlabs import ElevenLabs
load_dotenv()
app = Flask(__name__)
elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
@app.route("/api/token")
def get_token():
    # Replace with your Speech Engine ID from step 4 of the server setup
    speech_engine_id = "seng_8k3m9xr4hjnfg983brhmhkd98n6"
    response = elevenlabs.conversational_ai.conversations.get_webrtc_token(
        agent_id=speech_engine_id,
    )
    return jsonify(token=response.token)
if __name__ == "__main__":
    app.run(port=3002)

会話UIを構築

サーバーから会話トークンを取得し、それを使用してセッションを開始します。

React

JavaScript

App.tsx

import { useConversation } from "@elevenlabs/react";
import { useCallback } from "react";
async function getToken(): Promise<string> {
  const response = await fetch("/api/token");
  if (!response.ok) {
    throw Error("Failed to get conversation token");
  }
  const data = await response.json();
  return data.token;
}
export default function App() {
  const conversation = useConversation({
    onConnect: () => console.log("Connected"),
    onDisconnect: () => console.log("Disconnected"),
    onError: (error: Error) => console.error("Error:", error),
  });
  const startConversation = useCallback(async () => {
    await navigator.mediaDevices.getUserMedia({ audio: true });
    const token = await getToken();
    await conversation.startSession({ conversationToken: token });
  }, [conversation]);
  const stopConversation = useCallback(async () => {
    await conversation.endSession();
  }, [conversation]);
  return (
    <div>
      <p>Status: {conversation.status}</p>
      <button onClick={startConversation} disabled={conversation.status === "connected"}>
        Start conversation
      </button>
      <button onClick={stopConversation} disabled={conversation.status !== "connected"}>
        End conversation
      </button>
    </div>
  );
}

試してみる

次の3つのプロセスが実行されていることを確認してください。

ngrok - ポート3001へ転送
Speech Engineサーバー - python server.pyまたはnpx tsx server.mts
トークンサーバー - npx tsx token-server.mtsまたはpython token_server.py

ブラウザでクライアントアプリケーションを開き、Start conversationをクリックします。求められたらマイクへのアクセスを許可してから、話しかけてください。スピーカーからエージェントの応答が聞こえます。

サーバーでdebug: trueを有効にしている場合は、受信した文字起こしと送信した応答がコンソールに記録されます。

セッションイベント

イベント	TypeScriptコールバック	Pythonコールバック	説明
`user_transcript`	`onTranscript`	`on_transcript`	ユーザーの音声が文字起こしされました。会話履歴全体と中断シグナルが含まれます。
`init`	`onInit`	`on_init`	会話IDでセッションが初期化されました。
`close`	`onClose`	`on_close`	ElevenLabsから正常に切断されました。
`disconnected`	`onDisconnect`	`on_disconnect`	WebSocketが予期せず切断されました。
`error`	`onError`	`on_error`	プロトコルまたはWebSocketのエラー。

最初のエージェントメッセージを設定

デフォルトでは、エージェントはユーザーが最初に話すのを待ちます。会話の開始時にエージェントがユーザーに挨拶するようにするには、セッション開始時にクライアントのoverridesオプションで最初のメッセージを設定します。

エージェントが先に話せるようにするには、クライアントからこの設定を行えるようSpeech Engineリソースを更新する必要があります。

engine = await elevenlabs.speech_engine.update(
    speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
    overrides={
      "first_message": True,
    },
)

次に、クライアントSDKで最初のメッセージを設定します。

React

JavaScript

conversation.startSession({
  conversationToken: token,
  overrides: {
    agent: {
      firstMessage: "Hello! How can I help you today?",
    },
  },
});

最初のメッセージは、接続が確立されるとすぐにエージェントによって発話されます。サーバーのonTranscriptコールバックはトリガーされず、すべてElevenLabs側で処理されます。

最大会話時間を設定

デフォルトでは、会話は600秒（10分）で終了します。Speech Engineは最大7,200秒（2時間）の会話をサポートしています。より長い会話を許可するには、より大きいmax_duration_secondsでSpeech Engineリソースを更新します。

engine = await elevenlabs.speech_engine.update(
    speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
    conversation={
        "max_duration_seconds": 7200,
    },
)

ダッシュボードでも設定できます。Speech Engineを開き、Advancedタブに移動して、Conversational behaviorのMax conversation durationを設定します。

次のステップ

JavaScript SDKリファレンス

JavaScript SDKのクラス、メソッド、イベント。

Python SDKリファレンス

Python SDKのクラス、メソッド、イベント。

APIリファレンス

Speech Engineのすべてのパラメーターと応答形式を確認します。

Next.jsサンプルアプリ

完全なSpeech Engineクイックスタートアプリをローカルで実行します。