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

Diese Seite dokumentiert die öffentliche API für das Speech Engine JavaScript SDK (`@elevenlabs/elevenlabs-js`).

## Speech Engine-Ressource abrufen

Rufen Sie eine `SpeechEngineResource` über ihre Engine-ID ab. Das zurückgegebene Objekt bietet Methoden, um eine Verbindung zu einem bestehenden HTTP-Server herzustellen, einen eigenständigen Server zu starten oder einzelne Sitzungen zu erstellen.

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

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

## SpeechEngineResource

### Eigenschaften

| Eigenschaft | Typ      | Beschreibung              |
| ----------- | -------- | ------------------------- |
| `engineId`  | `string` | Die ID der Speech Engine. |

### attach

Stellen Sie eine Verbindung zu einem bestehenden Node.js-HTTP-Server her und akzeptieren Sie Speech Engine-Verbindungen unter dem angegebenen Pfad. Verwenden Sie diese Methode, wenn Sie bereits einen HTTP-Server haben (z. B. Express, Fastify oder einen einfachen `http.createServer()`) und Speech Engine neben Ihren bestehenden Routen hinzufügen möchten.

WebSocket-Upgrades, Pfadrouting und Anfragenverifizierung werden automatisch verarbeitet. Gibt ein `SpeechEngineAttachment` zurück, dessen Methode `close()` keine neuen Verbindungen mehr akzeptiert, ohne den HTTP-Server zu beeinflussen.

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

| Parameter    | Typ                     | Beschreibung                                     |
| ------------ | ----------------------- | ------------------------------------------------ |
| `httpServer` | `http.Server`           | Der Node.js-HTTP-Server, mit dem verbunden wird. |
| `path`       | `string`                | URL-Pfad für WebSocket-Upgrades.                 |
| `handler`    | `SpeechEngineCallbacks` | Callback-Objekt (siehe [Callbacks](#callbacks)). |

Direkt auf dem Client ist eine Kurzform verfügbar, die `get()` und `attach()` in einem Aufruf kombiniert:

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

### verifyRequest

Prüfen Sie, ob eine eingehende Anfrage von der ElevenLabs Speech Engine API stammt. Prüft den Header `X-Elevenlabs-Speech-Engine-Authorization` auf ein gültiges JWT, das mit dem SHA-256-Hash Ihres API-Schlüssels signiert ist.

Nur erforderlich, wenn Sie das WebSocket-Upgrade selbst verwalten. Bei Verwendung von `attach()` oder `SpeechEngineServer` wird die Verifizierung automatisch durchgeführt.

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

| Parameter | Typ                                                            | Beschreibung                    |
| --------- | -------------------------------------------------------------- | ------------------------------- |
| `req`     | `{ headers: Record<string, string \| string[] \| undefined> }` | Eingehendes HTTP-Anfrageobjekt. |

**Gibt zurück:** `Promise<boolean>` — `true`, wenn die Anfrage gültig ist.

### createSession

Verpacken Sie einen akzeptierten WebSocket in eine `SpeechEngineSession`. Verwenden Sie dies für benutzerdefinierte Serverintegrationen oder die manuelle WebSocket-Verarbeitung.

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

| Parameter       | Typ       | Standardwert | Beschreibung                           |
| --------------- | --------- | ------------ | -------------------------------------- |
| `ws`            | WebSocket |              | Eine akzeptierte WebSocket-Verbindung. |
| `options.debug` | `boolean` | `false`      | Debug-Protokollierung aktivieren.      |

**Gibt zurück:** `SpeechEngineSession`

## SpeechEngineServer

Ein eigenständiger WebSocket-Server, der Speech Engine-Verbindungen ohne bestehenden HTTP-Server akzeptiert. Verwenden Sie ihn, wenn Ihr Server ausschließlich Speech Engine-Verbindungen verarbeitet.

Für die Integration mit einem bestehenden HTTP-Server (z. B. Express, Fastify) verwenden Sie stattdessen [`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();
```

### Konstruktoroptionen

| Parameter  | Typ                     | Standardwert | Beschreibung                                                                                                                                                                                 |
| ---------- | ----------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`     | `number`                | `3001`       | Port, auf dem der Server lauscht.                                                                                                                                                            |
| `apiKey`   | `string`                |              | ElevenLabs-API-Schlüssel zur Verifizierung von Verbindungen. Verwendet alternativ die Umgebungsvariable `ELEVENLABS_API_KEY`. Nicht erforderlich, wenn `disableAuth` auf `true` gesetzt ist. |
| `engineId` | `string`                |              | Die Speech Engine-ID. Wird bei Erstellung über die Ressource automatisch ausgefüllt.                                                                                                         |
| ...        | `SpeechEngineCallbacks` |              | Alle Callback-Optionen (`onInit`, `onTranscript`, `onClose`, `onDisconnect`, `onError`, `debug`, `disableAuth`). Siehe [Callbacks](#callbacks).                                              |

### start

Starten Sie den eigenständigen WebSocket-Server auf dem konfigurierten Port. Jede eingehende Verbindung wird mit dem konfigurierten API-Schlüssel gegen die ElevenLabs API verifiziert, sofern nicht `disableAuth: true` gesetzt wurde.

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

### stop

Stoppen Sie den WebSocket-Server und schließen Sie alle aktiven Verbindungen.

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

### handleConnection

Verpacken Sie einen bestehenden WebSocket in eine `SpeechEngineSession` mit den Callbacks des Servers. Verwenden Sie dies, wenn Sie einen eigenen WebSocket-Server verwalten und einzelne Verbindungen verpacken möchten.

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

| Parameter | Typ         | Beschreibung                           |
| --------- | ----------- | -------------------------------------- |
| `ws`      | `WebSocket` | Eine akzeptierte WebSocket-Verbindung. |

**Gibt zurück:** `SpeechEngineSession`

## SpeechEngineSession

Verpackt eine einzelne WebSocket-Verbindung. Jede Verbindung steht für eine Unterhaltung. Die Sitzung löst Ereignisse für Transkripte und Änderungen im Lebenszyklus aus und bietet Methoden zum Zurücksenden von LLM-Antworten.

Wenn ein neues Transkript eintrifft, wird das Abbruchsignal des vorherigen Transkript-Handlers ausgelöst und unterbricht laufende LLM-Aufrufe.

### Eigenschaften

| Eigenschaft      | Typ       | Beschreibung                                                         |
| ---------------- | --------- | -------------------------------------------------------------------- |
| `conversationId` | `string`  | Die von der API zugewiesene Unterhaltungs-ID. Nach `init` verfügbar. |
| `isOpen`         | `boolean` | Ob die Sitzung noch geöffnet ist.                                    |

### on

Registrieren Sie einen Handler für ein Ereignis. Gibt die Sitzung für Verkettungen zurück.

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

### off

Entfernen Sie einen zuvor registrierten Handler.

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

### once

Registrieren Sie einen Handler, der einmal ausgelöst wird und sich dann selbst entfernt.

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

### sendResponse

Senden Sie eine LLM-Antwort zur Text-zu-Sprache-Synthese an die Speech Engine API zurück. Muss innerhalb eines `onTranscript`-Handlers aufgerufen werden. Ein Aufruf außerhalb eines Handlers gibt eine Warnung aus und sendet nichts.

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

| Parameter  | Typ                                  | Beschreibung                                                                                                        |
| ---------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `response` | `string` \| `AsyncIterable<unknown>` | Eine vollständige Zeichenfolge oder ein asynchron iterierbares Objekt mit Textabschnitten / LLM-Stream-Ereignissen. |

Das SDK erkennt automatisch Text aus den folgenden LLM-Stream-Formaten und extrahiert ihn:

| Anbieter                | Ereignisformat                                                                 |
| ----------------------- | ------------------------------------------------------------------------------ |
| 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

Schließen Sie die Sitzung und die zugrunde liegende WebSocket-Verbindung.

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

## SpeechEngineAttachment

Wird von `engine.attach()` zurückgegeben. Steuert den Lebenszyklus des WebSocket-Servers, ohne den HTTP-Server zu beeinflussen, mit dem er verbunden wurde.

### close

Akzeptieren Sie keine neuen Verbindungen mehr, entfernen Sie den Upgrade-Listener vom HTTP-Server und schließen Sie den zugrunde liegenden WebSocket-Server.

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

## Callbacks

Das Callback-Objekt, das an `attach()` oder `SpeechEngineServer` übergeben wird. Alle Callbacks sind optional.

| Callback       | Signatur                                                                           | Beschreibung                                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `onInit`       | `(conversationId: string, session: Session) => void`                               | Sitzung mit einer Unterhaltungs-ID initialisiert.                                                                               |
| `onTranscript` | `(transcript: TranscriptMessage[], signal: AbortSignal, session: Session) => void` | Nutzersprache transkribiert.                                                                                                    |
| `onClose`      | `(session: Session) => void`                                                       | Ordnungsgemäße Trennung von ElevenLabs.                                                                                         |
| `onDisconnect` | `(session: Session) => void`                                                       | WebSocket unerwartet getrennt.                                                                                                  |
| `onError`      | `(error: Error, session: Session) => void`                                         | Protokoll- oder WebSocket-Fehler.                                                                                               |
| `debug`        | `boolean`                                                                          | Debug-Protokollierung aktivieren.                                                                                               |
| `disableAuth`  | `boolean`                                                                          | JWT-Verifizierung bei eingehenden Verbindungen überspringen. Siehe [Authentifizierung deaktivieren](#disabling-authentication). |

Der `onTranscript`-Handler erhält ein `AbortSignal`, das ausgelöst wird, wenn der Nutzer während einer Antwort unterbricht.

### Authentifizierung deaktivieren

Standardmäßig überprüfen sowohl `attach()` als auch `SpeechEngineServer` bei jeder eingehenden Verbindung den Header `X-Elevenlabs-Speech-Engine-Authorization`. Wenn Ihr Server hinter einer Infrastrukturebene liegt, die eingehenden Datenverkehr bereits auf ElevenLabs beschränkt (normalerweise über eine IP-Allowlist für [ausgehende IP-Bereiche von ElevenLabs](/docs/de/eleven-api/resources/ip-allowlisting)), können Sie die JWT-Verifizierung überspringen, indem Sie `disableAuth: true` übergeben:

```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,
});
```

Wenn die Authentifizierung deaktiviert ist, akzeptiert der Server jeden Client, der ihn erreichen kann, und gibt beim Start eine `console.warn` aus.

> **Warning**
>
> Verwenden Sie `disableAuth: true` nur, wenn vor dem Server eine IP-Allowlist, benutzerdefinierte Header-Werte oder eine gleichwertige
> Einschränkung auf Netzwerkebene eingerichtet ist. Andernfalls kann jeder im Internet eine
> Sitzung öffnen und Ihre Rechenressourcen sowie Ihr nachgelagertes LLM-Kontingent verbrauchen.

## Ereignisse

Wenn Sie `session.on()` direkt statt Callbacks verwenden, sind dies die Ereignisnamen und ihre Handler-Signaturen.

| Ereignis          | Handler-Signatur                                         |
| ----------------- | -------------------------------------------------------- |
| `user_transcript` | `(transcript: TranscriptMessage[], signal: AbortSignal)` |
| `init`            | `(conversationId: string)`                               |
| `close`           | `()`                                                     |
| `disconnected`    | `()`                                                     |
| `error`           | `(error: Error)`                                         |

Konstanten für Ereignisnamen sind für typsichere Nutzung verfügbar:

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

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

## TranscriptMessage

Eine einzelne Nachricht im Unterhaltungsverlauf. Das vollständige Transkript wird bei jeder Runde an `onTranscript` übergeben.

| Eigenschaft | Typ                   | Beschreibung                    |
| ----------- | --------------------- | ------------------------------- |
| `role`      | `"user"` \| `"agent"` | Wer die Nachricht gesendet hat. |
| `content`   | `string`              | Der Textinhalt der Nachricht.   |

## Wire-Protokoll

Zur Referenz: Dies sind die JSON-Nachrichten, die über die WebSocket-Verbindung ausgetauscht werden. Das SDK verarbeitet Serialisierung und Deserialisierung automatisch.

### Eingehend (ElevenLabs API an Entwickler-Server)

| Nachrichtentyp    | Felder                                                     | Beschreibung                            |
| ----------------- | ---------------------------------------------------------- | --------------------------------------- |
| `init`            | `conversation_id: string`                                  | Sitzung initialisiert.                  |
| `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | Nutzersprache transkribiert.            |
| `ping`            |                                                            | Keep-alive. Das SDK antwortet mit Pong. |
| `close`           |                                                            | Ordnungsgemäße Trennung.                |
| `error`           | `message: string`                                          | Fehler von der API.                     |

### Ausgehend (Entwickler-Server an ElevenLabs API)

| Nachrichtentyp   | Felder                                                     | Beschreibung                           |
| ---------------- | ---------------------------------------------------------- | -------------------------------------- |
| `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | LLM-Antwortabschnitt für TTS-Synthese. |
| `pong`           |                                                            | Antwort auf Ping.                      |