JavaScript SDK-referens

Den här sidan dokumenterar det offentliga API:et för Speech Engine JavaScript SDK (@elevenlabs/elevenlabs-js).

Hämta en Speech Engine-resurs

Hämta en SpeechEngineResource med dess motor-ID. Det returnerade objektet innehåller metoder för att ansluta till en befintlig HTTP-server, starta en fristående server eller skapa enskilda sessioner.

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

SpeechEngineResource

Egenskaper

attach

Anslut till en befintlig Node.js HTTP-server och börja acceptera Speech Engine-anslutningar på den angivna sökvägen. Använd detta när du redan har en HTTP-server (t.ex. Express, Fastify eller en vanlig http.createServer()) och vill lägga till Speech Engine vid sidan av dina befintliga routes.

Hanterar automatiskt WebSocket-uppgraderingar, sökvägsrouting och begärandeverifiering. Returnerar en SpeechEngineAttachment vars metod close() slutar acceptera anslutningar utan att påverka HTTP-servern.

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

En genväg finns direkt på klienten och kombinerar get() och attach() i ett enda anrop:

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

verifyRequest

Verifiera att en inkommande begäran kommer från ElevenLabs Speech Engine API. Kontrollerar headern X-Elevenlabs-Speech-Engine-Authorization efter en giltig JWT som signerats med SHA-256-hashen av din API-nyckel.

Behövs bara när du själv hanterar WebSocket-uppgraderingen. När du använder attach() eller SpeechEngineServer hanteras verifieringen automatiskt.

const isValid = await engine.verifyRequest(req);

Returnerar: Promise<boolean> — true om begäran är giltig.

createSession

Omslut en accepterad WebSocket med en SpeechEngineSession. Använd detta för anpassad serverintegrering eller manuell WebSocket-hantering.

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

Returnerar: SpeechEngineSession

SpeechEngineServer

En fristående WebSocket-server som accepterar Speech Engine-anslutningar utan att kräva en befintlig HTTP-server. Använd detta när serverns enda syfte är att hantera Speech Engine-anslutningar.

För integrering med en befintlig HTTP-server (t.ex. Express, Fastify) använder du engine.attach() i stället.

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

Konstruktoralternativ

start

Starta den fristående WebSocket-servern på den konfigurerade porten. Verifierar varje inkommande anslutning mot ElevenLabs API med den konfigurerade API-nyckeln, om inte disableAuth: true har angetts.

server.start();

stop

Stoppa WebSocket-servern och stäng alla aktiva anslutningar.

await server.stop();

handleConnection

Omslut en befintlig WebSocket med en SpeechEngineSession där serverns callbacks är kopplade. Använd detta när du hanterar din egen WebSocket-server och vill omsluta enskilda anslutningar.

const session = server.handleConnection(ws);

Returnerar: SpeechEngineSession

SpeechEngineSession

Omsluter en enskild WebSocket-anslutning. Varje anslutning representerar en konversation. Sessionen skickar händelser för transkriptioner och livscykelförändringar och innehåller metoder för att skicka tillbaka LLM-svar.

När en ny transkription kommer aktiveras den föregående transkriptionshanterarens avbrottssignal, vilket avbryter pågående LLM-anrop.

Egenskaper

on

Registrera en hanterare för en händelse. Returnerar sessionen för kedjning.

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

off

Ta bort en tidigare registrerad hanterare.

session.off("user_transcript", listener);

once

Registrera en hanterare som körs en gång och sedan tar bort sig själv.

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

sendResponse

Skicka tillbaka ett LLM-svar till Speech Engine API för text-till-tal-syntes. Måste anropas inuti en onTranscript-hanterare. Om den anropas utanför en hanterare visas en varning och metoden returnerar utan att skicka något.

// 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:t identifierar automatiskt och extraherar text från följande LLM-strömformat:

close

Stäng sessionen och den underliggande WebSocket-anslutningen.

session.close();

SpeechEngineAttachment

Returneras av engine.attach(). Styr livscykeln för WebSocket-servern utan att påverka HTTP-servern som den anslöts till.

close

Sluta acceptera nya anslutningar, ta bort uppgraderingslyssnaren från HTTP-servern och stäng den underliggande WebSocket-servern.

await attachment.close();

Callbacks

Callback-objektet som skickas till attach() eller SpeechEngineServer. Alla callbacks är valfria.

Hanteraren onTranscript får en AbortSignal som aktiveras när användaren avbryter mitt i ett svar.

Inaktivera autentisering

Som standard verifierar både attach() och SpeechEngineServer headern X-Elevenlabs-Speech-Engine-Authorization för varje inkommande anslutning. Om din server ligger bakom ett infrastrukturlager som redan begränsar inkommande trafik till ElevenLabs (vanligtvis en IP-tillåtelselista begränsad till ElevenLabs utgående IP-intervall) kan du hoppa över JWT-verifiering genom att ange disableAuth: true:

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

När autentisering är inaktiverad accepterar servern alla klienter som kan nå den och skickar en console.warn vid start.

Händelser

När du använder session.on() direkt i stället för callbacks är detta händelsenamnen och deras hanterarsignaturer.

Händelsenamnskonstanter finns tillgängliga för typsäker användning:

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

TranscriptMessage

Ett enskilt meddelande i konversationshistoriken. Hela transkriptionen skickas till onTranscript vid varje tur.

Wire protocol

Som referens visas här JSON-meddelandena som utbyts via WebSocket-anslutningen. SDK:t hanterar serialisering och deserialisering automatiskt.

Inkommande (ElevenLabs API till utvecklarserver)

Utgående (utvecklarserver till ElevenLabs API)