Guide du SDK JavaScript

Cette page documente l’API publique du SDK JavaScript Speech Engine (@elevenlabs/elevenlabs-js).

Obtenir une ressource Speech Engine

Récupérez une SpeechEngineResource à partir de son ID de moteur. L’objet renvoyé fournit des méthodes pour se connecter à un serveur HTTP existant, démarrer un serveur autonome ou créer des sessions individuelles.

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

SpeechEngineResource

Propriétés

attach

Connectez-vous à un serveur HTTP Node.js existant et commencez à accepter les connexions Speech Engine au chemin indiqué. Utilisez cette méthode si vous disposez déjà d’un serveur HTTP, par exemple Express, Fastify ou un simple http.createServer(), et souhaitez ajouter Speech Engine à vos routes existantes.

Gère automatiquement les mises à niveau WebSocket, le routage des chemins et la vérification des requêtes. Renvoie un SpeechEngineAttachment dont la méthode close() arrête l’acceptation des connexions sans affecter le serveur HTTP.

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

Un raccourci est disponible directement sur le client, combinant get() et attach() en un seul appel :

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

verifyRequest

Vérifiez qu’une requête entrante provient de l’API Speech Engine d’ElevenLabs. Vérifie que l’en-tête X-Elevenlabs-Speech-Engine-Authorization contient un JWT valide signé avec le hachage SHA-256 de votre clé API.

Nécessaire uniquement lorsque vous gérez vous-même la mise à niveau WebSocket. Avec attach() ou SpeechEngineServer, la vérification est effectuée automatiquement.

const isValid = await engine.verifyRequest(req);

Renvoie : Promise<boolean>, true si la requête est valide.

createSession

Encapsulez un WebSocket accepté dans une SpeechEngineSession. Utilisez cette méthode pour une intégration de serveur personnalisée ou une gestion manuelle des WebSocket.

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

Renvoie : SpeechEngineSession

SpeechEngineServer

Un serveur WebSocket autonome qui accepte les connexions Speech Engine sans nécessiter de serveur HTTP existant. Utilisez-le lorsque le seul rôle de votre serveur est de gérer les connexions Speech Engine.

Pour l’intégration à un serveur HTTP existant, par exemple Express ou Fastify, utilisez plutôt 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();

Options du constructeur

start

Démarrez le serveur WebSocket autonome sur le port configuré. Vérifie chaque connexion entrante auprès de l’API ElevenLabs à l’aide de la clé API configurée, sauf si disableAuth: true est défini.

server.start();

stop

Arrêtez le serveur WebSocket et fermez toutes les connexions actives.

await server.stop();

handleConnection

Encapsulez un WebSocket existant dans une SpeechEngineSession avec les rappels du serveur configurés. Utilisez cette méthode lorsque vous gérez votre propre serveur WebSocket et souhaitez encapsuler des connexions individuelles.

const session = server.handleConnection(ws);

Renvoie : SpeechEngineSession

SpeechEngineSession

Encapsule une connexion WebSocket unique. Chaque connexion représente une conversation. La session émet des événements pour les transcriptions et les changements de cycle de vie, et fournit des méthodes pour renvoyer des réponses de LLM.

Lorsqu’une nouvelle transcription arrive, le signal d’annulation du gestionnaire de transcription précédent est déclenché, interrompant tout appel LLM en cours.

Propriétés

on

Enregistrez un gestionnaire pour un événement. Renvoie la session pour permettre l’enchaînement.

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

off

Supprimez un gestionnaire précédemment enregistré.

session.off("user_transcript", listener);

once

Enregistrez un gestionnaire qui s’exécute une fois, puis se supprime.

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

sendResponse

Renvoyez une réponse de LLM à l’API Speech Engine pour la synthèse vocale. Doit être appelée dans un gestionnaire onTranscript. L’appeler hors d’un gestionnaire émet un avertissement et se termine sans envoi.

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

Le SDK détecte automatiquement et extrait le texte des formats de flux LLM suivants :

close

Fermez la session et la connexion WebSocket sous-jacente.

session.close();

SpeechEngineAttachment

Renvoyé par engine.attach(). Contrôle le cycle de vie du serveur WebSocket sans affecter le serveur HTTP auquel il est connecté.

close

Arrêtez d’accepter de nouvelles connexions, supprimez l’écouteur de mise à niveau du serveur HTTP et fermez le serveur WebSocket sous-jacent.

await attachment.close();

Rappels

L’objet de rappel transmis à attach() ou à SpeechEngineServer. Tous les rappels sont facultatifs.

Le gestionnaire onTranscript reçoit un AbortSignal qui se déclenche lorsque l’utilisateur interrompt la réponse en cours.

Désactiver l’authentification

Par défaut, attach() et SpeechEngineServer vérifient l’en-tête X-Elevenlabs-Speech-Engine-Authorization pour chaque connexion entrante. Si votre serveur se trouve derrière une couche d’infrastructure qui limite déjà le trafic entrant à ElevenLabs, généralement une liste d’autorisation d’IP limitée aux plages de sortie d’ElevenLabs, vous pouvez ignorer la vérification JWT en transmettant 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,
});

Lorsque l’authentification est désactivée, le serveur accepte tout client pouvant l’atteindre et émet un console.warn au démarrage.

Événements

Lorsque vous utilisez directement session.on() au lieu des rappels, voici les noms d’événements et les signatures de leurs gestionnaires.

Des constantes de noms d’événements sont disponibles pour une utilisation sécurisée par type :

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

TranscriptMessage

Un message unique dans l’historique de conversation. La transcription complète est transmise à onTranscript à chaque tour.

Protocole filaire

À titre de référence, voici les messages JSON échangés via la connexion WebSocket. Le SDK gère automatiquement la sérialisation et la désérialisation.

Entrants (API ElevenLabs vers serveur du développeur)

Sortants (serveur du développeur vers API ElevenLabs)