Dokumentacja JavaScript SDK

Ta strona dokumentuje publiczne API pakietu Speech Engine JavaScript SDK (@elevenlabs/elevenlabs-js).

Pobieranie zasobu Speech Engine

Pobierz SpeechEngineResource według identyfikatora silnika. Zwrócony obiekt udostępnia metody do podłączenia do istniejącego serwera HTTP, uruchomienia niezależnego serwera lub tworzenia pojedynczych sesji.

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

SpeechEngineResource

Właściwości

attach

Podłącz do istniejącego serwera HTTP Node.js i zacznij przyjmować połączenia Speech Engine pod wskazaną ścieżką. Użyj tej metody, jeśli masz już serwer HTTP (np. Express, Fastify lub zwykły http.createServer()) i chcesz dodać Speech Engine obok istniejących tras.

Automatycznie obsługuje aktualizacje WebSocket, routing ścieżek i weryfikację żądań. Zwraca SpeechEngineAttachment, którego metoda close() przestaje przyjmować połączenia bez wpływu na serwer HTTP.

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

Skrót jest dostępny bezpośrednio na kliencie i łączy get() oraz attach() w jednym wywołaniu:

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

verifyRequest

Sprawdź, czy przychodzące żądanie pochodzi z API ElevenLabs Speech Engine. Metoda sprawdza nagłówek X-Elevenlabs-Speech-Engine-Authorization, aby znaleźć prawidłowy JWT podpisany hashem SHA-256 twojego klucza API.

Jest potrzebna tylko wtedy, gdy samodzielnie zarządzasz aktualizacją WebSocket. Przy użyciu attach() lub SpeechEngineServer weryfikacja odbywa się automatycznie.

const isValid = await engine.verifyRequest(req);

Zwraca: Promise<boolean> — true, jeśli żądanie jest prawidłowe.

createSession

Opakuj zaakceptowany WebSocket w SpeechEngineSession. Użyj tej metody do własnej integracji serwera lub ręcznej obsługi WebSocket.

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

Zwraca: SpeechEngineSession

SpeechEngineServer

Niezależny serwer WebSocket, który przyjmuje połączenia Speech Engine bez istniejącego serwera HTTP. Użyj go, gdy serwer służy wyłącznie do obsługi połączeń Speech Engine.

Do integracji z istniejącym serwerem HTTP (np. Express, Fastify) użyj zamiast tego 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();

Opcje konstruktora

start

Uruchom niezależny serwer WebSocket na skonfigurowanym porcie. Każde przychodzące połączenie jest weryfikowane przez API ElevenLabs przy użyciu skonfigurowanego klucza API, chyba że ustawiono disableAuth: true.

server.start();

stop

Zatrzymaj serwer WebSocket i zamknij wszystkie aktywne połączenia.

await server.stop();

handleConnection

Opakuj istniejący WebSocket w SpeechEngineSession z podłączonymi callbackami serwera. Użyj tej metody, gdy zarządzasz własnym serwerem WebSocket i chcesz opakować pojedyncze połączenia.

const session = server.handleConnection(ws);

Zwraca: SpeechEngineSession

SpeechEngineSession

Opakowuje pojedyncze połączenie WebSocket. Każde połączenie reprezentuje jedną rozmowę. Sesja emituje zdarzenia dla transkrypcji i zmian cyklu życia oraz udostępnia metody wysyłania odpowiedzi LLM.

Gdy nadejdzie nowa transkrypcja, wyzwalany jest sygnał przerwania poprzedniego handlera transkrypcji, przerywając trwające wywołanie LLM.

Właściwości

on

Zarejestruj handler zdarzenia. Zwraca sesję, aby umożliwić łączenie wywołań.

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

off

Usuń wcześniej zarejestrowany handler.

session.off("user_transcript", listener);

once

Zarejestruj handler, który uruchomi się raz, a potem usunie sam siebie.

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

sendResponse

Wyślij odpowiedź LLM do API Speech Engine w celu syntezy zamiany tekstu na mowę. Metodę trzeba wywołać wewnątrz handlera onTranscript. Wywołanie jej poza handlerem wyświetla ostrzeżenie i kończy się bez wysyłania danych.

// 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 automatycznie wykrywa i wyodrębnia tekst z poniższych formatów strumieni LLM:

close

Zamknij sesję i bazowe połączenie WebSocket.

session.close();

SpeechEngineAttachment

Zwracany przez engine.attach(). Zarządza cyklem życia serwera WebSocket bez wpływu na serwer HTTP, do którego został podłączony.

close

Przestań przyjmować nowe połączenia, usuń listener aktualizacji z serwera HTTP i zamknij bazowy serwer WebSocket.

await attachment.close();

Callbacki

Obiekt callbacków przekazywany do attach() lub SpeechEngineServer. Wszystkie callbacki są opcjonalne.

Handler onTranscript otrzymuje AbortSignal, który jest wyzwalany, gdy użytkownik przerwie odpowiedź w trakcie.

Wyłączanie uwierzytelniania

Domyślnie zarówno attach(), jak i SpeechEngineServer weryfikują nagłówek X-Elevenlabs-Speech-Engine-Authorization przy każdym przychodzącym połączeniu. Jeśli twój serwer znajduje się za warstwą infrastruktury, która już ogranicza ruch przychodzący do ElevenLabs (zwykle lista dozwolonych adresów IP dla zakresów wyjściowych ElevenLabs), możesz pominąć weryfikację JWT, przekazując 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,
});

Gdy uwierzytelnianie jest wyłączone, serwer akceptuje każdego klienta, który może się z nim połączyć, i przy uruchomieniu emituje console.warn.

Zdarzenia

Jeśli używasz bezpośrednio session.on() zamiast callbacków, poniżej znajdziesz nazwy zdarzeń i sygnatury ich handlerów.

Stałe nazw zdarzeń są dostępne, aby zapewnić bezpieczeństwo typów:

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

TranscriptMessage

Pojedyncza wiadomość w historii rozmowy. Pełna transkrypcja jest przekazywana do onTranscript przy każdej turze.

Protokół komunikacji

Dla odniesienia: poniżej znajdują się wiadomości JSON wymieniane przez połączenie WebSocket. SDK automatycznie obsługuje serializację i deserializację.

Przychodzące (API ElevenLabs do serwera dewelopera)

Wychodzące (serwer dewelopera do API ElevenLabs)