Riferimento SDK JavaScript

Questa pagina documenta l’API pubblica dell’SDK JavaScript Speech Engine (@elevenlabs/elevenlabs-js).

Ottenere una risorsa Speech Engine

Recupera una SpeechEngineResource tramite l’ID del motore. L’oggetto restituito fornisce metodi per collegarsi a un server HTTP esistente, avviare un server autonomo o creare singole sessioni.

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

SpeechEngineResource

Proprietà

attach

Collegati a un server HTTP Node.js esistente e inizia ad accettare connessioni Speech Engine nel path specificato. Usalo se disponi già di un server HTTP (ad esempio Express, Fastify o un semplice http.createServer()) e vuoi aggiungere Speech Engine alle route esistenti.

Gestisce automaticamente gli upgrade WebSocket, il routing dei path e la verifica delle richieste. Restituisce un SpeechEngineAttachment il cui metodo close() interrompe l’accettazione delle connessioni senza influire sul server HTTP.

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

È disponibile una scorciatoia direttamente sul client, che combina get() e attach() in un’unica chiamata:

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

verifyRequest

Verifica che una richiesta in arrivo provenga dall’API Speech Engine di ElevenLabs. Controlla l’header X-Elevenlabs-Speech-Engine-Authorization alla ricerca di un JWT valido firmato con l’hash SHA-256 della tua chiave API.

È necessario solo quando gestisci personalmente l’upgrade WebSocket. Se utilizzi attach() o SpeechEngineServer, la verifica viene gestita automaticamente.

const isValid = await engine.verifyRequest(req);

Restituisce: Promise<boolean> — true se la richiesta è valida.

createSession

Racchiude un WebSocket accettato in una SpeechEngineSession. Usalo per l’integrazione con server personalizzati o per la gestione manuale dei WebSocket.

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

Restituisce: SpeechEngineSession

SpeechEngineServer

Un server WebSocket autonomo che accetta connessioni Speech Engine senza richiedere un server HTTP esistente. Usalo se l’unico scopo del tuo server è gestire le connessioni Speech Engine.

Per l’integrazione con un server HTTP esistente (ad esempio Express, Fastify), utilizza invece 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();

Opzioni del costruttore

start

Avvia il server WebSocket autonomo sulla porta configurata. Verifica ogni connessione in arrivo tramite l’API ElevenLabs usando la chiave API configurata, a meno che non sia stato impostato disableAuth: true.

server.start();

stop

Arresta il server WebSocket e chiude tutte le connessioni attive.

await server.stop();

handleConnection

Racchiude un WebSocket esistente in una SpeechEngineSession con le callback del server già collegate. Usalo quando gestisci il tuo server WebSocket e vuoi racchiudere singole connessioni.

const session = server.handleConnection(ws);

Restituisce: SpeechEngineSession

SpeechEngineSession

Racchiude una singola connessione WebSocket. Ogni connessione rappresenta una conversazione. La sessione emette eventi per le trascrizioni e le modifiche del ciclo di vita e fornisce metodi per inviare risposte LLM.

Quando arriva una nuova trascrizione, viene attivato il segnale di interruzione del gestore della trascrizione precedente, interrompendo qualsiasi chiamata LLM in corso.

Proprietà

on

Registra un gestore per un evento. Restituisce la sessione per il concatenamento.

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

off

Rimuove un gestore registrato in precedenza.

session.off("user_transcript", listener);

once

Registra un gestore che viene eseguito una volta e poi si rimuove.

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

sendResponse

Invia una risposta LLM all’API Speech Engine per la sintesi Text to Speech. Deve essere chiamato all’interno di un gestore onTranscript. Se lo chiami al di fuori di un gestore, emette un avviso e termina senza inviare nulla.

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

L’SDK rileva ed estrae automaticamente il testo dai seguenti formati di stream LLM:

close

Chiude la sessione e la connessione WebSocket sottostante.

session.close();

SpeechEngineAttachment

Restituito da engine.attach(). Controlla il ciclo di vita del server WebSocket senza influire sul server HTTP a cui è stato collegato.

close

Interrompe l’accettazione di nuove connessioni, rimuove il listener di upgrade dal server HTTP e chiude il server WebSocket sottostante.

await attachment.close();

Callback

L’oggetto callback passato a attach() o SpeechEngineServer. Tutte le callback sono facoltative.

Il gestore onTranscript riceve un AbortSignal che viene attivato quando l’utente interrompe la risposta a metà.

Disabilitare l’autenticazione

Per impostazione predefinita, sia attach() sia SpeechEngineServer verificano l’header X-Elevenlabs-Speech-Engine-Authorization su ogni connessione in arrivo. Se il tuo server si trova dietro un livello dell’infrastruttura che limita già il traffico in arrivo a ElevenLabs (in genere una lista di indirizzi IP consentiti limitata agli intervalli di uscita di ElevenLabs), puoi saltare la verifica JWT passando 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,
});

Quando l’autenticazione è disabilitata, il server accetta qualsiasi client che riesca a raggiungerlo ed emette un console.warn all’avvio.

Eventi

Quando utilizzi direttamente session.on() invece delle callback, questi sono i nomi degli eventi e le firme dei rispettivi gestori.

Le costanti dei nomi degli eventi sono disponibili per un utilizzo type-safe:

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

TranscriptMessage

Un singolo messaggio nella cronologia della conversazione. La trascrizione completa viene passata a onTranscript a ogni turno.

Protocollo wire

A titolo di riferimento, questi sono i messaggi JSON scambiati tramite la connessione WebSocket. L’SDK gestisce automaticamente la serializzazione e la deserializzazione.

In entrata (API ElevenLabs al server dello sviluppatore)

In uscita (server dello sviluppatore all’API ElevenLabs)