JavaScript SDKリファレンス

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

Speech Engineリソースを取得する

エンジンIDでSpeechEngineResourceを取得します。返されるオブジェクトには、既存のHTTPサーバーへの接続、スタンドアロンサーバーの起動、個別セッションの作成を行うメソッドが含まれます。

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const elevenlabs = new ElevenLabsClient();
const engine = await elevenlabs.speechEngine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6");

SpeechEngineResource

プロパティ

attach

既存のNode.js HTTPサーバーに接続し、指定されたパスでSpeech Engine接続の受け付けを開始します。すでにHTTPサーバー（Express、Fastify、または通常のhttp.createServer()など）があり、既存のルートと並行してSpeech Engineを追加する場合に使用します。

WebSocketアップグレード、パスルーティング、リクエスト検証を自動的に処理します。close()メソッドにより、HTTPサーバーに影響を与えずに接続の受け付けを停止できるSpeechEngineAttachmentを返します。

const attachment = engine.attach(httpServer, "/ws", {
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});

クライアントから直接使用できるショートカットもあり、get()とattach()を1回の呼び出しにまとめられます。

await elevenlabs.speechEngine.attach("seng_8k3m9xr4hjnfg983brhmhkd98n6", httpServer, "/ws", {
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});

verifyRequest

受信リクエストがElevenLabs Speech Engine APIから送信されたことを検証します。X-Elevenlabs-Speech-Engine-Authorizationヘッダーに含まれる、APIキーのSHA-256ハッシュで署名された有効なJWTを確認します。

WebSocketアップグレードを自分で管理する場合にのみ必要です。attach()またはSpeechEngineServerを使用する場合、検証は自動的に処理されます。

const isValid = await engine.verifyRequest(req);

戻り値： Promise<boolean> — リクエストが有効な場合はtrue。

createSession

受け付けたWebSocketをSpeechEngineSessionでラップします。カスタムサーバーとの統合や、WebSocketを手動で処理する場合に使用します。

const session = engine.createSession(ws, { debug: true });
session.on("user_transcript", (transcript, signal) => {
  /* ... */
});

戻り値： SpeechEngineSession

SpeechEngineServer

既存のHTTPサーバーを必要とせず、Speech Engine接続を受け付けるスタンドアロンWebSocketサーバーです。サーバーの用途がSpeech Engine接続の処理のみである場合に使用します。

既存のHTTPサーバー（Express、Fastifyなど）と統合する場合は、代わりにengine.attach()を使用してください。

import { SpeechEngine } from "@elevenlabs/elevenlabs-js";
const server = new SpeechEngine.Server({
  port: 3001,
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});
server.start();

コンストラクターオプション

start

設定したポートでスタンドアロンWebSocketサーバーを起動します。disableAuth: trueを設定していない限り、設定済みのAPIキーを使用してElevenLabs APIに対して各受信接続を検証します。

server.start();

stop

WebSocketサーバーを停止し、すべてのアクティブな接続を閉じます。

await server.stop();

handleConnection

サーバーのコールバックを接続した状態で、既存のWebSocketをSpeechEngineSessionでラップします。独自のWebSocketサーバーを管理し、個別の接続をラップする場合に使用します。

const session = server.handleConnection(ws);

戻り値： SpeechEngineSession

SpeechEngineSession

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

新しい文字起こしが届くと、前の文字起こしハンドラーの中断シグナルが発火し、進行中のLLM呼び出しを中断します。

プロパティ

on

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

session.on("user_transcript", (transcript, signal) => {
  /* ... */
});

off

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

session.off("user_transcript", listener);

once

一度だけ発火し、その後自身を削除するハンドラーを登録します。

session.once("init", (conversationId) => {
  /* ... */
});

sendResponse

テキスト読み上げ合成用のLLMレスポンスをSpeech Engine APIに返送します。onTranscriptハンドラー内で呼び出す必要があります。ハンドラー外で呼び出すと警告が発行され、送信せずに戻ります。

// String response
session.sendResponse("Hello, how can I help?");
// Streamed response (OpenAI, Anthropic, or Gemini)
const stream = await openai.responses.create(
  { model: "gpt-4o", input: messages, stream: true },
  { signal }
);
session.sendResponse(stream);

SDKは、以下のLLMストリーム形式からテキストを自動検出して抽出します。

close

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

session.close();

SpeechEngineAttachment

engine.attach()によって返されます。接続先のHTTPサーバーには影響を与えず、WebSocketサーバーのライフサイクルを制御します。

close

新しい接続の受け付けを停止し、HTTPサーバーからアップグレードリスナーを削除して、基盤となるWebSocketサーバーを閉じます。

await attachment.close();

コールバック

attach()またはSpeechEngineServerに渡すコールバックオブジェクトです。すべてのコールバックは任意です。

onTranscriptハンドラーは、ユーザーがレスポンスの途中で割り込んだときに発火するAbortSignalを受け取ります。

認証を無効にする

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

// Standalone — no apiKey required when disableAuth is true
new SpeechEngine.Server({ port: 3001, disableAuth: true, onTranscript }).start();
// Or on attach
elevenlabs.speechEngine.attach("seng_8k3m9xr4hjnfg983brhmhkd98n6", httpServer, "/ws", {
  disableAuth: true,
  onTranscript,
});

認証を無効にすると、サーバーは到達可能なすべてのクライアントを受け入れ、起動時にconsole.warnを出力します。

イベント

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

型安全に使用するためのイベント名定数を利用できます。

import { SpeechEngine } from "@elevenlabs/elevenlabs-js";
session.on(SpeechEngine.USER_TRANSCRIPT, (transcript, signal) => {
  /* ... */
});

TranscriptMessage

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

ワイヤープロトコル

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

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

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