リファレンスライブラリとSDK音声エンジン

Python SDKリファレンス

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

このページでは、Speech Engine Python SDK（elevenlabs）の公開APIについて説明します。

Speech Engineリソースの取得

エンジンIDでSpeechEngineResourceを取得します。返されるオブジェクトでは、サーバーの起動、リクエストの検証、個別セッションの作成を行えます。

from elevenlabs import AsyncElevenLabs
elevenlabs = AsyncElevenLabs()
engine = await elevenlabs.speech_engine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6")

SpeechEngineResource

プロパティ

プロパティ型説明
engine_idstrSpeech EngineのID。

serve

スタンドアロンのWebSocketサーバーを起動します。停止するまでブロックします。

await engine.serve(
    port=3001,
    path="/ws",
    debug=True,
    on_transcript=handle_transcript,
)
パラメータ型デフォルト説明
portint3001リッスンするポート。
pathstrNone接続をこのパスに制限します。Noneの場合はすべて受け入れます。
debugboolFalsestdoutへのデバッグログを有効にします。
disable_authboolFalse受信接続のJWT検証をスキップします。認証の無効化を参照してください。
on_initcallableセッションの初期化時に呼び出されます。
on_transcriptcallableユーザーの文字起こしが届いたときに呼び出されます。
on_closecallable正常に切断されたときに呼び出されます。
on_disconnectcallableWebSocketが予期せず切断されたときに呼び出されます。
on_errorcallableプロトコルまたはWebSocketエラー時に呼び出されます。

認証の無効化

デフォルトでは、serve()はすべての受信接続でX-Elevenlabs-Speech-Engine-Authorizationヘッダーを検証します。サーバーの前段に、受信トラフィックをすでにElevenLabsのみに制限するインフラ層（通常はElevenLabsの送信元範囲に限定したIP許可リスト）がある場合は、disable_auth=Trueを渡してJWT検証をスキップできます。

# 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を出力します。

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が設定されている場合を除く）。

is_valid = engine.verify_request(headers)
パラメータ型説明
headersdictリクエストヘッダーの辞書。

戻り値：bool — リクエストが有効な場合はTrue。

create_session

受け入れたWebSocketをSpeechEngineSessionでラップします。カスタムサーバーとのインテグレーション（例：FastAPI、Starlette、またはWebSocketの手動処理）に使用します。

session = engine.create_session(websocket, debug=True)
session.on("user_transcript", handle_transcript)
await session.run()
パラメータ型デフォルト説明
wsWebSocket受け入れ済みのWebSocket接続。
debugboolFalseデバッグログを有効にします。

戻り値：SpeechEngineSession

SpeechEngineSession

単一のWebSocket接続をラップします。各接続は1つの会話を表します。セッションは文字起こしとライフサイクル変更のイベントを発行し、LLM応答を返送するメソッドを提供します。

新しい文字起こしが届くと、前の文字起こしハンドラーは自動的にキャンセルされ、進行中のLLM呼び出しが中断されます。

プロパティ

プロパティ型説明
conversation_idOptional[str]APIによって割り当てられる会話ID。init後に利用できます。
is_openboolセッションがまだ開いているかどうか。

on

イベントのハンドラーを登録します。チェーン可能なようにセッションを返します。

session.on("user_transcript", handler)

off

以前に登録したハンドラーを削除します。

session.off("user_transcript", handler)

once

一度だけ実行され、自身を削除するハンドラーを登録します。

session.once("init", handler)

send_response

テキスト読み上げ合成のため、LLM応答をSpeech Engine APIに返送します。on_transcriptハンドラー内で呼び出す必要があります。ハンドラー外で呼び出した場合は警告を出力し、送信せずに戻ります。

# 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)
パラメータ型説明
responsestr | 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()で手動でセッションを構築した後の主なエントリーポイントです。

session = engine.create_session(websocket)
session.on("user_transcript", handle_transcript)
await session.run()

close

セッションと基盤となるWebSocket接続を閉じます。

session.close()

コールバック

serve()に渡すキーワード引数です。すべてのコールバックは任意です。ハンドラーには同期関数または非同期（コルーチン）関数を使用できます。

コールバックシグネチャ説明
on_init(conversation_id: str, session) -> None会話IDとともにセッションが初期化されます。
on_transcript(transcript: list, session) -> Noneユーザー音声が文字起こしされます。
on_close(session) -> NoneElevenLabsから正常に切断されます。
on_disconnect(session) -> NoneWebSocketが予期せず切断されます。
on_error(error: Exception, session) -> NoneプロトコルまたはWebSocketエラー。

イベント

コールバックではなくsession.on()を直接使用する場合は、以下のイベント名とハンドラーシグネチャを使用します。

イベントハンドラーシグネチャ
user_transcript(transcript: list[ConversationMessage])
init(conversation_id: str)
close()
disconnected()
error(error: Exception)

型安全に使用できるイベント名定数も用意されています。

from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR
session.on(USER_TRANSCRIPT, handle_transcript)

ConversationMessage

会話履歴内の単一メッセージです。完全な文字起こしは、各ターンでon_transcriptに渡されます。

プロパティ型説明
role"user" | "agent"メッセージの送信者。
contentstrメッセージのテキスト内容。

ワイヤプロトコル

参考として、WebSocket接続を介して交換されるJSONメッセージを示します。SDKはシリアライズとデシリアライズを自動的に処理します。

受信（ElevenLabs APIからデベロッパーサーバーへ）

メッセージタイプフィールド説明
initconversation_id: stringセッションが初期化されます。
user_transcriptuser_transcript: TranscriptMessage[], event_id: numberユーザー音声が文字起こしされます。
pingキープアライブ。SDKはpongで応答します。
close正常な切断。
errormessage: stringAPIからのエラー。

送信（デベロッパーサーバーからElevenLabs APIへ）

メッセージタイプフィールド説明
agent_responsecontent: string, event_id: number, is_final: booleanTTS合成用のLLM応答チャンク。
pongpingへの応答。