> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 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.

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();
const engine = await elevenlabs.speechEngine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6");
```

## SpeechEngineResource

### Propriétés

| Propriété  | Type     | Description           |
| ---------- | -------- | --------------------- |
| `engineId` | `string` | L'ID du moteur vocal. |

### 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.

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

| Paramètre    | Type                    | Description                                               |
| ------------ | ----------------------- | --------------------------------------------------------- |
| `httpServer` | `http.Server`           | Le serveur HTTP Node.js auquel se connecter.              |
| `path`       | `string`                | Chemin URL sur lequel gérer les mises à niveau WebSocket. |
| `handler`    | `SpeechEngineCallbacks` | Objet de rappel (voir [Rappels](#callbacks)).             |

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

```typescript
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.

```typescript
const isValid = await engine.verifyRequest(req);
```

| Paramètre | Type                                                           | Description                     |
| --------- | -------------------------------------------------------------- | ------------------------------- |
| `req`     | `{ headers: Record<string, string \| string[] \| undefined> }` | Objet de requête HTTP entrante. |

**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.

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

| Paramètre       | Type      | Par défaut | Description                           |
| --------------- | --------- | ---------- | ------------------------------------- |
| `ws`            | WebSocket |            | Une connexion WebSocket acceptée.     |
| `options.debug` | `boolean` | `false`    | Active la journalisation de débogage. |

**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()`](#attach).

```typescript
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

| Paramètre  | Type                    | Par défaut | Description                                                                                                                                                                   |
| ---------- | ----------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`     | `number`                | `3001`     | Port d'écoute.                                                                                                                                                                |
| `apiKey`   | `string`                |            | Clé API ElevenLabs permettant de vérifier les connexions. Utilise la variable d'environnement `ELEVENLABS_API_KEY` par défaut. Non requise lorsque `disableAuth` vaut `true`. |
| `engineId` | `string`                |            | L'ID du moteur vocal. Renseigné automatiquement lors de la création via la ressource.                                                                                         |
| ...        | `SpeechEngineCallbacks` |            | Toutes les options de rappel (`onInit`, `onTranscript`, `onClose`, `onDisconnect`, `onError`, `debug`, `disableAuth`). Voir [Rappels](#callbacks).                            |

### 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.

```typescript
server.start();
```

### stop

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

```typescript
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.

```typescript
const session = server.handleConnection(ws);
```

| Paramètre | Type        | Description                       |
| --------- | ----------- | --------------------------------- |
| `ws`      | `WebSocket` | Une connexion WebSocket acceptée. |

**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

| Propriété        | Type      | Description                                                       |
| ---------------- | --------- | ----------------------------------------------------------------- |
| `conversationId` | `string`  | L'ID de conversation attribué par l'API. Disponible après `init`. |
| `isOpen`         | `boolean` | Indique si la session est toujours ouverte.                       |

### on

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

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

### off

Supprimez un gestionnaire précédemment enregistré.

```typescript
session.off("user_transcript", listener);
```

### once

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

```typescript
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.

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

| Paramètre  | Type                                 | Description                                                                                      |
| ---------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `response` | `string` \| `AsyncIterable<unknown>` | Une chaîne complète ou un itérable asynchrone de fragments de texte ou d'événements de flux LLM. |

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

| Fournisseur               | Format d'événement                                                             |
| ------------------------- | ------------------------------------------------------------------------------ |
| API Responses d'OpenAI    | `{ type: "response.output_text.delta", delta: "text" }`                        |
| Chat Completions d'OpenAI | `{ choices: [{ delta: { content: "text" } }] }`                                |
| API Messages d'Anthropic  | `{ type: "content_block_delta", delta: { type: "text_delta", text: "text" } }` |
| API Gemini de Google      | `{ candidates: [{ content: { parts: [{ text: "text" }] } }] }`                 |

### close

Fermez la session et la connexion WebSocket sous-jacente.

```typescript
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.

```typescript
await attachment.close();
```

## Rappels

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

| Rappel         | Signature                                                                          | Description                                                                                                           |
| -------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `onInit`       | `(conversationId: string, session: Session) => void`                               | Session initialisée avec un ID de conversation.                                                                       |
| `onTranscript` | `(transcript: TranscriptMessage[], signal: AbortSignal, session: Session) => void` | Parole de l'utilisateur transcrite.                                                                                   |
| `onClose`      | `(session: Session) => void`                                                       | Déconnexion propre d'ElevenLabs.                                                                                      |
| `onDisconnect` | `(session: Session) => void`                                                       | WebSocket interrompu de manière inattendue.                                                                           |
| `onError`      | `(error: Error, session: Session) => void`                                         | Erreur de protocole ou WebSocket.                                                                                     |
| `debug`        | `boolean`                                                                          | Active la journalisation de débogage.                                                                                 |
| `disableAuth`  | `boolean`                                                                          | Ignore la vérification JWT des connexions entrantes. Voir [Désactiver l'authentification](#disabling-authentication). |

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](/docs/fr/eleven-api/resources/ip-allowlisting), vous pouvez ignorer la vérification JWT en transmettant `disableAuth: true` :

```typescript
// 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.

> **Warning**
>
> Utilisez `disableAuth: true` uniquement si une liste d'autorisation d'IP, des valeurs d'en-tête personnalisées ou une restriction équivalente
> au niveau du réseau se trouve devant le serveur. Sans cela, toute personne sur Internet peut ouvrir une
> session et consommer vos ressources de calcul ainsi que votre quota LLM en aval.

## Événements

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

| Événement         | Signature du gestionnaire                                |
| ----------------- | -------------------------------------------------------- |
| `user_transcript` | `(transcript: TranscriptMessage[], signal: AbortSignal)` |
| `init`            | `(conversationId: string)`                               |
| `close`           | `()`                                                     |
| `disconnected`    | `()`                                                     |
| `error`           | `(error: Error)`                                         |

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

```typescript
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.

| Propriété | Type                  | Description                    |
| --------- | --------------------- | ------------------------------ |
| `role`    | `"user"` \| `"agent"` | L'expéditeur du message.       |
| `content` | `string`              | Le contenu textuel du message. |

## 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)

| Type de message   | Champs                                                     | Description                                    |
| ----------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| `init`            | `conversation_id: string`                                  | Session initialisée.                           |
| `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | Parole de l'utilisateur transcrite.            |
| `ping`            |                                                            | Maintien de connexion. Le SDK répond par pong. |
| `close`           |                                                            | Déconnexion propre.                            |
| `error`           | `message: string`                                          | Erreur de l'API.                               |

### Sortants (serveur du développeur vers API ElevenLabs)

| Type de message  | Champs                                                     | Description                                   |
| ---------------- | ---------------------------------------------------------- | --------------------------------------------- |
| `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | Fragment de réponse LLM pour la synthèse TTS. |
| `pong`           |                                                            | Réponse au ping.                              |