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.

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

SpeechEngineResource

Eigenschaften

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.

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

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

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.

const isValid = await engine.verifyRequest(req);

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.

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

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

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

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.

server.start();

stop

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

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.

const session = server.handleConnection(ws);

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

on

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

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

off

Entfernen Sie einen zuvor registrierten Handler.

session.off("user_transcript", listener);

once

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

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.

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

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

close

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

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.

await attachment.close();

Callbacks

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

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), können Sie die JWT-Verifizierung überspringen, indem Sie disableAuth: true übergeben:

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

Ereignisse

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

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

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.

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)

Ausgehend (Entwickler-Server an ElevenLabs API)