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

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

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

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

## SpeechEngineResource

### Egenskaper

| Egenskap   | Typ      | Beskrivning         |
| ---------- | -------- | ------------------- |
| `engineId` | `string` | ID:t för talmotorn. |

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

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

| Parameter    | Typ                     | Beskrivning                                           |
| ------------ | ----------------------- | ----------------------------------------------------- |
| `httpServer` | `http.Server`           | Node.js HTTP-servern att ansluta till.                |
| `path`       | `string`                | URL-sökväg för hantering av WebSocket-uppgraderingar. |
| `handler`    | `SpeechEngineCallbacks` | Callback-objekt (se [Callbacks](#callbacks)).         |

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

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

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

| Parameter | Typ                                                            | Beskrivning                      |
| --------- | -------------------------------------------------------------- | -------------------------------- |
| `req`     | `{ headers: Record<string, string \| string[] \| undefined> }` | Inkommande HTTP-begärandeobjekt. |

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

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

| Parameter       | Typ       | Standard | Beskrivning                         |
| --------------- | --------- | -------- | ----------------------------------- |
| `ws`            | WebSocket |          | En accepterad WebSocket-anslutning. |
| `options.debug` | `boolean` | `false`  | Aktivera felsökningsloggning.       |

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

```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();
```

### Konstruktoralternativ

| Parameter  | Typ                     | Standard | Beskrivning                                                                                                                                           |
| ---------- | ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`     | `number`                | `3001`   | Port att lyssna på.                                                                                                                                   |
| `apiKey`   | `string`                |          | ElevenLabs API-nyckel för att verifiera anslutningar. Faller tillbaka på miljövariabeln `ELEVENLABS_API_KEY`. Krävs inte när `disableAuth` är `true`. |
| `engineId` | `string`                |          | Talmotorns ID. Fylls i automatiskt när den skapas via resursen.                                                                                       |
| ...        | `SpeechEngineCallbacks` |          | Alla callback-alternativ (`onInit`, `onTranscript`, `onClose`, `onDisconnect`, `onError`, `debug`, `disableAuth`). Se [Callbacks](#callbacks).        |

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

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

### stop

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

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

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

| Parameter | Typ         | Beskrivning                         |
| --------- | ----------- | ----------------------------------- |
| `ws`      | `WebSocket` | En accepterad WebSocket-anslutning. |

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

| Egenskap         | Typ       | Beskrivning                                                           |
| ---------------- | --------- | --------------------------------------------------------------------- |
| `conversationId` | `string`  | Konversations-ID som tilldelats av API:et. Tillgängligt efter `init`. |
| `isOpen`         | `boolean` | Om sessionen fortfarande är öppen.                                    |

### on

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

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

### off

Ta bort en tidigare registrerad hanterare.

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

### once

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

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

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

| Parameter  | Typ                                  | Beskrivning                                                                            |
| ---------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| `response` | `string` \| `AsyncIterable<unknown>` | En komplett sträng eller en asynkron itererbar samling textdelar / LLM-strömhändelser. |

SDK:t identifierar automatiskt och extraherar text från följande LLM-strömformat:

| Leverantör              | Händelseformat                                                                 |
| ----------------------- | ------------------------------------------------------------------------------ |
| OpenAI Responses API    | `{ type: "response.output_text.delta", delta: "text" }`                        |
| OpenAI Chat Completions | `{ choices: [{ delta: { content: "text" } }] }`                                |
| Anthropic Messages API  | `{ type: "content_block_delta", delta: { type: "text_delta", text: "text" } }` |
| Google Gemini API       | `{ candidates: [{ content: { parts: [{ text: "text" }] } }] }`                 |

### close

Stäng sessionen och den underliggande WebSocket-anslutningen.

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

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

## Callbacks

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

| Callback       | Signatur                                                                           | Beskrivning                                                                                                       |
| -------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `onInit`       | `(conversationId: string, session: Session) => void`                               | Sessionen har initierats med ett konversations-ID.                                                                |
| `onTranscript` | `(transcript: TranscriptMessage[], signal: AbortSignal, session: Session) => void` | Användarens tal har transkriberats.                                                                               |
| `onClose`      | `(session: Session) => void`                                                       | Ren frånkoppling från ElevenLabs.                                                                                 |
| `onDisconnect` | `(session: Session) => void`                                                       | WebSocket-anslutningen avbröts oväntat.                                                                           |
| `onError`      | `(error: Error, session: Session) => void`                                         | Protokoll- eller WebSocket-fel.                                                                                   |
| `debug`        | `boolean`                                                                          | Aktivera felsökningsloggning.                                                                                     |
| `disableAuth`  | `boolean`                                                                          | Hoppa över JWT-verifiering för inkommande anslutningar. Se [Inaktivera autentisering](#disabling-authentication). |

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](/docs/sv/eleven-api/resources/ip-allowlisting)) kan du hoppa över JWT-verifiering genom att ange `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,
});
```

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

> **Warning**
>
> Använd bara `disableAuth: true` om du har en IP-tillåtelselista, anpassade headervärden eller en motsvarande
> begränsning på nätverksnivå framför servern. Utan en sådan kan vem som helst på internet öppna en
> session och förbruka din beräkningskapacitet och kvot för efterföljande LLM-anrop.

## Händelser

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

| Händelse          | Hanterarsignatur                                         |
| ----------------- | -------------------------------------------------------- |
| `user_transcript` | `(transcript: TranscriptMessage[], signal: AbortSignal)` |
| `init`            | `(conversationId: string)`                               |
| `close`           | `()`                                                     |
| `disconnected`    | `()`                                                     |
| `error`           | `(error: Error)`                                         |

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

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

| Egenskap  | Typ                   | Beskrivning                   |
| --------- | --------------------- | ----------------------------- |
| `role`    | `"user"` \| `"agent"` | Vem som skickade meddelandet. |
| `content` | `string`              | Meddelandets textinnehåll.    |

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

| Meddelandetyp     | Fält                                                       | Beskrivning                         |
| ----------------- | ---------------------------------------------------------- | ----------------------------------- |
| `init`            | `conversation_id: string`                                  | Sessionen har initierats.           |
| `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | Användarens tal har transkriberats. |
| `ping`            |                                                            | Keep-alive. SDK:t svarar med pong.  |
| `close`           |                                                            | Ren frånkoppling.                   |
| `error`           | `message: string`                                          | Fel från API:et.                    |

### Utgående (utvecklarserver till ElevenLabs API)

| Meddelandetyp    | Fält                                                       | Beskrivning                  |
| ---------------- | ---------------------------------------------------------- | ---------------------------- |
| `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | LLM-svarsdel för TTS-syntes. |
| `pong`           |                                                            | Svar på ping.                |