> 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.

# JavaScript SDKリファレンス

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

## Speech Engineリソースを取得する

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

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();
const engine = await elevenlabs.speechEngine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6");
```

## SpeechEngineResource

### プロパティ

| プロパティ      | 型        | 説明                |
| ---------- | -------- | ----------------- |
| `engineId` | `string` | Speech EngineのID。 |

### attach

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

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

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

| パラメーター       | 型                       | 説明                                     |
| ------------ | ----------------------- | -------------------------------------- |
| `httpServer` | `http.Server`           | 接続先のNode.js HTTPサーバー。                  |
| `path`       | `string`                | WebSocketアップグレードを処理するURLパス。            |
| `handler`    | `SpeechEngineCallbacks` | コールバックオブジェクト（[コールバック](#callbacks)を参照）。 |

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

```typescript
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`を使用する場合、検証は自動的に処理されます。

```typescript
const isValid = await engine.verifyRequest(req);
```

| パラメーター | 型                                                              | 説明                 |
| ------ | -------------------------------------------------------------- | ------------------ |
| `req`  | `{ headers: Record<string, string \| string[] \| undefined> }` | 受信HTTPリクエストオブジェクト。 |

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

### createSession

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

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

| パラメーター          | 型         | デフォルト   | 説明                |
| --------------- | --------- | ------- | ----------------- |
| `ws`            | WebSocket |         | 受け付けたWebSocket接続。 |
| `options.debug` | `boolean` | `false` | デバッグログを有効にします。    |

**戻り値：** `SpeechEngineSession`

## SpeechEngineServer

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

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

```typescript
import { SpeechEngine } from "@elevenlabs/elevenlabs-js";

const server = new SpeechEngine.Server({
  port: 3001,
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});

server.start();
```

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

| パラメーター     | 型                       | デフォルト  | 説明                                                                                                                               |
| ---------- | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `port`     | `number`                | `3001` | リッスンするポート。                                                                                                                       |
| `apiKey`   | `string`                |        | 接続の検証に使用するElevenLabs APIキー。`ELEVENLABS_API_KEY`環境変数にフォールバックします。`disableAuth`が`true`の場合は不要です。                                     |
| `engineId` | `string`                |        | Speech Engine ID。リソース経由で作成した場合は自動的に設定されます。                                                                                       |
| ...        | `SpeechEngineCallbacks` |        | すべてのコールバックオプション（`onInit`、`onTranscript`、`onClose`、`onDisconnect`、`onError`、`debug`、`disableAuth`）。[コールバック](#callbacks)を参照してください。 |

### start

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

```typescript
server.start();
```

### stop

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

```typescript
await server.stop();
```

### handleConnection

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

```typescript
const session = server.handleConnection(ws);
```

| パラメーター | 型           | 説明                |
| ------ | ----------- | ----------------- |
| `ws`   | `WebSocket` | 受け付けたWebSocket接続。 |

**戻り値：** `SpeechEngineSession`

## SpeechEngineSession

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

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

### プロパティ

| プロパティ            | 型         | 説明                                 |
| ---------------- | --------- | ---------------------------------- |
| `conversationId` | `string`  | APIによって割り当てられた会話ID。`init`後に使用できます。 |
| `isOpen`         | `boolean` | セッションがまだ開いているかどうか。                 |

### on

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

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

### off

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

```typescript
session.off("user_transcript", listener);
```

### once

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

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

### sendResponse

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

```typescript
// 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);
```

| パラメーター     | 型                                    | 説明                                        |
| ---------- | ------------------------------------ | ----------------------------------------- |
| `response` | `string` \| `AsyncIterable<unknown>` | 完全な文字列、またはテキストチャンク／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" }] } }] }`                 |

### close

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

```typescript
session.close();
```

## SpeechEngineAttachment

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

### close

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

```typescript
await attachment.close();
```

## コールバック

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

| コールバック         | シグネチャ                                                                              | 説明                                                                 |
| -------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `onInit`       | `(conversationId: string, session: Session) => void`                               | 会話IDを使用してセッションを初期化します。                                             |
| `onTranscript` | `(transcript: TranscriptMessage[], signal: AbortSignal, session: Session) => void` | ユーザーの音声が文字起こしされました。                                                |
| `onClose`      | `(session: Session) => void`                                                       | ElevenLabsから正常に切断されました。                                            |
| `onDisconnect` | `(session: Session) => void`                                                       | WebSocketが予期せず切断されました。                                             |
| `onError`      | `(error: Error, session: Session) => void`                                         | プロトコルまたはWebSocketのエラー。                                             |
| `debug`        | `boolean`                                                                          | デバッグログを有効にします。                                                     |
| `disableAuth`  | `boolean`                                                                          | 受信接続のJWT検証をスキップします。[認証を無効にする](#disabling-authentication)を参照してください。 |

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

### 認証を無効にする

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

```typescript
// 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`を出力します。

> **Warning**
>
> IP許可リスト、カスタムヘッダー値、または同等のネットワークレベルの制限をサーバーの前段に設定している場合にのみ、`disableAuth: true`を使用してください。
> 設定しない場合、インターネット上の誰でもセッションを開き、コンピューティングリソースとダウンストリームLLMの割り当てを消費できます。

## イベント

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

| イベント              | ハンドラーシグネチャ                                               |
| ----------------- | -------------------------------------------------------- |
| `user_transcript` | `(transcript: TranscriptMessage[], signal: AbortSignal)` |
| `init`            | `(conversationId: string)`                               |
| `close`           | `()`                                                     |
| `disconnected`    | `()`                                                     |
| `error`           | `(error: Error)`                                         |

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

```typescript
import { SpeechEngine } from "@elevenlabs/elevenlabs-js";

session.on(SpeechEngine.USER_TRANSCRIPT, (transcript, signal) => {
  /* ... */
});
```

## TranscriptMessage

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

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

## ワイヤープロトコル

参考として、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への応答。            |