> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Python SDKリファレンス このページでは、Speech Engine Python SDK（`elevenlabs`）の公開APIについて説明します。 ## Speech Engineリソースの取得 エンジンIDで`SpeechEngineResource`を取得します。返されるオブジェクトでは、サーバーの起動、リクエストの検証、個別セッションの作成を行えます。 ```python from elevenlabs import AsyncElevenLabs elevenlabs = AsyncElevenLabs() engine = await elevenlabs.speech_engine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6") ``` ## SpeechEngineResource ### プロパティ | プロパティ | 型 | 説明 | | ----------- | ----- | ----------------- | | `engine_id` | `str` | Speech EngineのID。 | ### serve スタンドアロンのWebSocketサーバーを起動します。停止するまでブロックします。 ```python await engine.serve( port=3001, path="/ws", debug=True, on_transcript=handle_transcript, ) ``` | パラメータ | 型 | デフォルト | 説明 | | --------------- | ---------- | ------- | ---------------------------------------------------------------- | | `port` | `int` | `3001` | リッスンするポート。 | | `path` | `str` | `None` | 接続をこのパスに制限します。`None`の場合はすべて受け入れます。 | | `debug` | `bool` | `False` | stdoutへのデバッグログを有効にします。 | | `disable_auth` | `bool` | `False` | 受信接続のJWT検証をスキップします。[認証の無効化](#disabling-authentication)を参照してください。 | | `on_init` | `callable` | | セッションの初期化時に呼び出されます。 | | `on_transcript` | `callable` | | ユーザーの文字起こしが届いたときに呼び出されます。 | | `on_close` | `callable` | | 正常に切断されたときに呼び出されます。 | | `on_disconnect` | `callable` | | WebSocketが予期せず切断されたときに呼び出されます。 | | `on_error` | `callable` | | プロトコルまたはWebSocketエラー時に呼び出されます。 | #### 認証の無効化 デフォルトでは、`serve()`はすべての受信接続で`X-Elevenlabs-Speech-Engine-Authorization`ヘッダーを検証します。サーバーの前段に、受信トラフィックをすでにElevenLabsのみに制限するインフラ層（通常は[ElevenLabsの送信元範囲](/docs/ja/eleven-api/resources/ip-allowlisting)に限定したIP許可リスト）がある場合は、`disable_auth=True`を渡してJWT検証をスキップできます。 ```python # No api_key required when disable_auth is True await engine.serve(port=3001, disable_auth=True, on_transcript=on_transcript) # Or directly on SpeechEngineServer from elevenlabs.speech_engine import SpeechEngineServer server = SpeechEngineServer(port=3001, disable_auth=True, on_transcript=on_transcript) await server.serve() ``` 認証を無効にすると、サーバーは到達可能なすべてのクライアントを受け入れ、起動時に`UserWarning`を出力します。 > **Warning** > > `disable_auth=True`は、サーバーの前段にIP許可リスト、カスタムヘッダー値、または同等の > ネットワークレベルの制限がある場合にのみ使用してください。これらがないと、インターネット上の誰でも > セッションを開き、コンピューティングリソースや下流のLLMクォータを消費できます。 ### verify_request 受信リクエストがElevenLabs Speech Engine APIから送信されたものであることを検証します。APIキーのSHA-256ハッシュで署名された有効なJWTが、`X-Elevenlabs-Speech-Engine-Authorization`ヘッダーに含まれているか確認します。 WebSocketのアップグレードを自分で管理する場合にのみ必要です。`serve()`を使用する場合、検証は自動的に処理されます（`disable_auth=True`が設定されている場合を除く）。 ```python is_valid = engine.verify_request(headers) ``` | パラメータ | 型 | 説明 | | --------- | ------ | ------------- | | `headers` | `dict` | リクエストヘッダーの辞書。 | **戻り値：**`bool` — リクエストが有効な場合は`True`。 ### create_session 受け入れたWebSocketを`SpeechEngineSession`でラップします。カスタムサーバーとのインテグレーション（例：FastAPI、Starlette、またはWebSocketの手動処理）に使用します。 ```python session = engine.create_session(websocket, debug=True) session.on("user_transcript", handle_transcript) await session.run() ``` | パラメータ | 型 | デフォルト | 説明 | | ------- | --------- | ------- | ------------------- | | `ws` | WebSocket | | 受け入れ済みのWebSocket接続。 | | `debug` | `bool` | `False` | デバッグログを有効にします。 | **戻り値：**`SpeechEngineSession` ## SpeechEngineSession 単一のWebSocket接続をラップします。各接続は1つの会話を表します。セッションは文字起こしとライフサイクル変更のイベントを発行し、LLM応答を返送するメソッドを提供します。 新しい文字起こしが届くと、前の文字起こしハンドラーは自動的にキャンセルされ、進行中のLLM呼び出しが中断されます。 ### プロパティ | プロパティ | 型 | 説明 | | ----------------- | --------------- | ---------------------------------- | | `conversation_id` | `Optional[str]` | APIによって割り当てられる会話ID。`init`後に利用できます。 | | `is_open` | `bool` | セッションがまだ開いているかどうか。 | ### on イベントのハンドラーを登録します。チェーン可能なようにセッションを返します。 ```python session.on("user_transcript", handler) ``` ### off 以前に登録したハンドラーを削除します。 ```python session.off("user_transcript", handler) ``` ### once 一度だけ実行され、自身を削除するハンドラーを登録します。 ```python session.once("init", handler) ``` ### send_response テキスト読み上げ合成のため、LLM応答をSpeech Engine APIに返送します。`on_transcript`ハンドラー内で呼び出す必要があります。ハンドラー外で呼び出した場合は警告を出力し、送信せずに戻ります。 ```python # String response await session.send_response("Hello, how can I help?") # Streamed response (OpenAI, Anthropic, or Gemini) stream = await openai_client.responses.create(model="gpt-4o", input=messages, stream=True) await session.send_response(stream) ``` | パラメータ | 型 | 説明 | | ---------- | ----------------------- | ----------------------------------------- | | `response` | `str` \| async iterable | 完全な文字列、またはテキストチャンク／LLMストリームイベントの非同期イテラブル。 | SDKは、以下のLLMストリーム形式からテキストを自動検出して抽出します。 | プロバイダー | イベント形式 | | ----------------------- | ------------------------------------------------------------------------------ | | OpenAI Responses API | `{ type: "response.output_text.delta", delta: "text" }` | | OpenAI Chat Completions | `{ choices: [{ delta: { content: "text" } }] }` | | Anthropic Messages API | `{ type: "content_block_delta", delta: { type: "text_delta", text: "text" } }` | | Google Gemini API | `{ candidates: [{ content: { parts: [{ text: "text" }] } }] }` | ### run WebSocketが閉じるまで受信ループを実行します。`create_session()`で手動でセッションを構築した後の主なエントリーポイントです。 ```python session = engine.create_session(websocket) session.on("user_transcript", handle_transcript) await session.run() ``` ### close セッションと基盤となるWebSocket接続を閉じます。 ```python session.close() ``` ## コールバック `serve()`に渡すキーワード引数です。すべてのコールバックは任意です。ハンドラーには同期関数または非同期（コルーチン）関数を使用できます。 | コールバック | シグネチャ | 説明 | | --------------- | ----------------------------------------- | ---------------------- | | `on_init` | `(conversation_id: str, session) -> None` | 会話IDとともにセッションが初期化されます。 | | `on_transcript` | `(transcript: list, session) -> None` | ユーザー音声が文字起こしされます。 | | `on_close` | `(session) -> None` | ElevenLabsから正常に切断されます。 | | `on_disconnect` | `(session) -> None` | WebSocketが予期せず切断されます。 | | `on_error` | `(error: Exception, session) -> None` | プロトコルまたはWebSocketエラー。 | ## イベント コールバックではなく`session.on()`を直接使用する場合は、以下のイベント名とハンドラーシグネチャを使用します。 | イベント | ハンドラーシグネチャ | | ----------------- | ----------------------------------------- | | `user_transcript` | `(transcript: list[ConversationMessage])` | | `init` | `(conversation_id: str)` | | `close` | `()` | | `disconnected` | `()` | | `error` | `(error: Exception)` | 型安全に使用できるイベント名定数も用意されています。 ```python from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR session.on(USER_TRANSCRIPT, handle_transcript) ``` ## ConversationMessage 会話履歴内の単一メッセージです。完全な文字起こしは、各ターンで`on_transcript`に渡されます。 | プロパティ | 型 | 説明 | | --------- | --------------------- | ------------- | | `role` | `"user"` \| `"agent"` | メッセージの送信者。 | | `content` | `str` | メッセージのテキスト内容。 | ## ワイヤプロトコル 参考として、WebSocket接続を介して交換されるJSONメッセージを示します。SDKはシリアライズとデシリアライズを自動的に処理します。 ### 受信（ElevenLabs APIからデベロッパーサーバーへ） | メッセージタイプ | フィールド | 説明 | | ----------------- | ---------------------------------------------------------- | ----------------------- | | `init` | `conversation_id: string` | セッションが初期化されます。 | | `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | ユーザー音声が文字起こしされます。 | | `ping` | | キープアライブ。SDKはpongで応答します。 | | `close` | | 正常な切断。 | | `error` | `message: string` | APIからのエラー。 | ### 送信（デベロッパーサーバーからElevenLabs APIへ） | メッセージタイプ | フィールド | 説明 | | ---------------- | ---------------------------------------------------------- | ----------------- | | `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | TTS合成用のLLM応答チャンク。 | | `pong` | | pingへの応答。 |