JavaScript SDK-referentie

Op deze pagina wordt de openbare API voor de Speech Engine JavaScript SDK (@elevenlabs/elevenlabs-js) beschreven.

Een Speech Engine-resource ophalen

Haal een SpeechEngineResource op via de engine-ID. Het geretourneerde object biedt methoden om te koppelen aan een bestaande HTTP-server, een zelfstandige server te starten of afzonderlijke sessies te maken.

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

SpeechEngineResource

Eigenschappen

attach

Koppel aan een bestaande Node.js HTTP-server en begin Speech Engine-verbindingen te accepteren op het opgegeven pad. Gebruik dit als je al een HTTP-server hebt (bijvoorbeeld Express, Fastify of een gewone http.createServer()) en Speech Engine wilt toevoegen naast je bestaande routes.

Handelt WebSocket-upgrades, padrouting en requestverificatie automatisch af. Retourneert een SpeechEngineAttachment waarvan de methode close() geen nieuwe verbindingen meer accepteert zonder de HTTP-server te beïnvloeden.

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

Er is rechtstreeks op de client een snelkoppeling beschikbaar die get() en attach() in één aanroep combineert:

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

verifyRequest

Controleer of een binnenkomend request afkomstig is van de ElevenLabs Speech Engine API. Controleert de header X-Elevenlabs-Speech-Engine-Authorization op een geldige JWT die is ondertekend met de SHA-256-hash van je API-sleutel.

Alleen nodig wanneer je de WebSocket-upgrade zelf beheert. Bij gebruik van attach() of SpeechEngineServer wordt de verificatie automatisch afgehandeld.

const isValid = await engine.verifyRequest(req);

Retourneert: Promise<boolean> — true als het request geldig is.

createSession

Verpak een geaccepteerde WebSocket in een SpeechEngineSession. Gebruik dit voor aangepaste serverintegratie of handmatige WebSocket-afhandeling.

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

Retourneert: SpeechEngineSession

SpeechEngineServer

Een zelfstandige WebSocket-server die Speech Engine-verbindingen accepteert zonder een bestaande HTTP-server nodig te hebben. Gebruik deze wanneer je server uitsluitend bedoeld is voor het afhandelen van Speech Engine-verbindingen.

Gebruik engine.attach() voor integratie met een bestaande HTTP-server (bijvoorbeeld Express of Fastify).

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

Constructoropties

start

Start de zelfstandige WebSocket-server op de geconfigureerde poort. Verifieert elke binnenkomende verbinding met de ElevenLabs API via de geconfigureerde API-sleutel, tenzij disableAuth: true is ingesteld.

server.start();

stop

Stop de WebSocket-server en sluit alle actieve verbindingen.

await server.stop();

handleConnection

Verpak een bestaande WebSocket in een SpeechEngineSession met de callbacks van de server gekoppeld. Gebruik dit als je je eigen WebSocket-server beheert en afzonderlijke verbindingen wilt verpakken.

const session = server.handleConnection(ws);

Retourneert: SpeechEngineSession

SpeechEngineSession

Verpakt één WebSocket-verbinding. Elke verbinding vertegenwoordigt één gesprek. De sessie geeft events af voor transcripts en wijzigingen in de levenscyclus, en biedt methoden om LLM-antwoorden terug te sturen.

Wanneer er een nieuw transcript binnenkomt, wordt het abort-signaal van de vorige transcripthandler geactiveerd, waardoor lopende LLM-aanroepen worden onderbroken.

Eigenschappen

on

Registreer een handler voor een event. Retourneert de sessie voor chaining.

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

off

Verwijder een eerder geregistreerde handler.

session.off("user_transcript", listener);

once

Registreer een handler die één keer wordt uitgevoerd en zichzelf vervolgens verwijdert.

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

sendResponse

Stuur een LLM-antwoord terug naar de Speech Engine API voor text-to-speechsynthese. Moet binnen een onTranscript-handler worden aangeroepen. Als je deze buiten een handler aanroept, wordt een waarschuwing gegeven en keert de methode terug zonder iets te verzenden.

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

De SDK detecteert automatisch tekst in de volgende LLM-streamformaten en extraheert deze:

close

Sluit de sessie en de onderliggende WebSocket-verbinding.

session.close();

SpeechEngineAttachment

Geretourneerd door engine.attach(). Beheert de levenscyclus van de WebSocket-server zonder de HTTP-server waaraan deze is gekoppeld te beïnvloeden.

close

Stop met het accepteren van nieuwe verbindingen, verwijder de upgradelistener van de HTTP-server en sluit de onderliggende WebSocket-server.

await attachment.close();

Callbacks

Het callbackobject dat wordt doorgegeven aan attach() of SpeechEngineServer. Alle callbacks zijn optioneel.

De onTranscript-handler ontvangt een AbortSignal dat wordt geactiveerd wanneer de gebruiker midden in een antwoord onderbreekt.

Authenticatie uitschakelen

Standaard verifiëren zowel attach() als SpeechEngineServer de header X-Elevenlabs-Speech-Engine-Authorization bij elke binnenkomende verbinding. Als je server achter een infrastructuurlaag staat die binnenkomend verkeer al beperkt tot ElevenLabs (doorgaans een IP-allowlist voor de egress-ranges van ElevenLabs), kun je JWT-verificatie overslaan door disableAuth: true door te geven:

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

Wanneer authenticatie is uitgeschakeld, accepteert de server elke client die hem kan bereiken en geeft hij bij het opstarten een console.warn af.

Events

Wanneer je session.on() rechtstreeks gebruikt in plaats van callbacks, zijn dit de eventnamen en de bijbehorende handlersignaturen.

Eventnaamconstanten zijn beschikbaar voor typeveilig gebruik:

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

TranscriptMessage

Eén bericht in de gespreksgeschiedenis. Bij elke beurt wordt het volledige transcript doorgegeven aan onTranscript.

Wire protocol

Ter referentie: dit zijn de JSON-berichten die via de WebSocket-verbinding worden uitgewisseld. De SDK handelt serialisatie en deserialisatie automatisch af.

Binnenkomend (ElevenLabs API naar ontwikkelaarsserver)

Uitgaand (ontwikkelaarsserver naar ElevenLabs API)