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

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

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

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

## SpeechEngineResource

### Właściwości

| Właściwość | Typ      | Opis                        |
| ---------- | -------- | --------------------------- |
| `engineId` | `string` | Identyfikator silnika mowy. |

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

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

| Parametr     | Typ                     | Opis                                                |
| ------------ | ----------------------- | --------------------------------------------------- |
| `httpServer` | `http.Server`           | Serwer HTTP Node.js do podłączenia.                 |
| `path`       | `string`                | Ścieżka URL do obsługi aktualizacji WebSocket.      |
| `handler`    | `SpeechEngineCallbacks` | Obiekt callbacków (zobacz [Callbacki](#callbacks)). |

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

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

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

| Parametr | Typ                                                            | Opis                                |
| -------- | -------------------------------------------------------------- | ----------------------------------- |
| `req`    | `{ headers: Record<string, string \| string[] \| undefined> }` | Obiekt przychodzącego żądania HTTP. |

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

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

| Parametr        | Typ       | Domyślnie | Opis                                |
| --------------- | --------- | --------- | ----------------------------------- |
| `ws`            | WebSocket |           | Zaakceptowane połączenie WebSocket. |
| `options.debug` | `boolean` | `false`   | Włącza logowanie debugowania.       |

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

### Opcje konstruktora

| Parametr   | Typ                     | Domyślnie | Opis                                                                                                                                                                                 |
| ---------- | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `port`     | `number`                | `3001`    | Port do nasłuchiwania.                                                                                                                                                               |
| `apiKey`   | `string`                |           | Klucz API ElevenLabs do weryfikacji połączeń. Jeśli go nie podasz, użyta zostanie zmienna środowiskowa `ELEVENLABS_API_KEY`. Nie jest wymagany, gdy `disableAuth` ma wartość `true`. |
| `engineId` | `string`                |           | Identyfikator silnika mowy. Ustawiany automatycznie po utworzeniu przez zasób.                                                                                                       |
| ...        | `SpeechEngineCallbacks` |           | Wszystkie opcje callbacków (`onInit`, `onTranscript`, `onClose`, `onDisconnect`, `onError`, `debug`, `disableAuth`). Zobacz [Callbacki](#callbacks).                                 |

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

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

### stop

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

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

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

| Parametr | Typ         | Opis                                |
| -------- | ----------- | ----------------------------------- |
| `ws`     | `WebSocket` | Zaakceptowane połączenie WebSocket. |

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

| Właściwość       | Typ       | Opis                                                            |
| ---------------- | --------- | --------------------------------------------------------------- |
| `conversationId` | `string`  | Identyfikator rozmowy przypisany przez API. Dostępny po `init`. |
| `isOpen`         | `boolean` | Czy sesja jest nadal otwarta.                                   |

### on

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

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

### off

Usuń wcześniej zarejestrowany handler.

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

### once

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

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

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

| Parametr   | Typ                                  | Opis                                                                                               |
| ---------- | ------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `response` | `string` \| `AsyncIterable<unknown>` | Pełny ciąg znaków lub asynchroniczny iterowalny obiekt fragmentów tekstu / zdarzeń strumienia LLM. |

SDK automatycznie wykrywa i wyodrębnia tekst z poniższych formatów strumieni LLM:

| Dostawca                | Format zdarzenia                                                               |
| ----------------------- | ------------------------------------------------------------------------------ |
| 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

Zamknij sesję i bazowe połączenie WebSocket.

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

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

## Callbacki

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

| Callback       | Sygnatura                                                                          | Opis                                                                                                                 |
| -------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `onInit`       | `(conversationId: string, session: Session) => void`                               | Sesja została zainicjowana identyfikatorem rozmowy.                                                                  |
| `onTranscript` | `(transcript: TranscriptMessage[], signal: AbortSignal, session: Session) => void` | Mowa użytkownika została transkrybowana.                                                                             |
| `onClose`      | `(session: Session) => void`                                                       | Poprawne rozłączenie z ElevenLabs.                                                                                   |
| `onDisconnect` | `(session: Session) => void`                                                       | Połączenie WebSocket nieoczekiwanie przerwane.                                                                       |
| `onError`      | `(error: Error, session: Session) => void`                                         | Błąd protokołu lub WebSocket.                                                                                        |
| `debug`        | `boolean`                                                                          | Włącza logowanie debugowania.                                                                                        |
| `disableAuth`  | `boolean`                                                                          | Pomija weryfikację JWT dla przychodzących połączeń. Zobacz [Wyłączanie uwierzytelniania](#disabling-authentication). |

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](/docs/pl/eleven-api/resources/ip-allowlisting)), możesz pominąć weryfikację JWT, przekazując `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,
});
```

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

> **Warning**
>
> Używaj `disableAuth: true` tylko, jeśli przed serwerem masz listę dozwolonych adresów IP, własne wartości nagłówków
> lub równoważne ograniczenie na poziomie sieci. Bez niego każda osoba w internecie może otworzyć
> sesję i zużyć twoje zasoby obliczeniowe oraz limit użycia LLM.

## Zdarzenia

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

| Zdarzenie         | Sygnatura handlera                                       |
| ----------------- | -------------------------------------------------------- |
| `user_transcript` | `(transcript: TranscriptMessage[], signal: AbortSignal)` |
| `init`            | `(conversationId: string)`                               |
| `close`           | `()`                                                     |
| `disconnected`    | `()`                                                     |
| `error`           | `(error: Error)`                                         |

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

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

| Właściwość | Typ                   | Opis                  |
| ---------- | --------------------- | --------------------- |
| `role`     | `"user"` \| `"agent"` | Kto wysłał wiadomość. |
| `content`  | `string`              | Treść wiadomości.     |

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

| Typ wiadomości    | Pola                                                       | Opis                                          |
| ----------------- | ---------------------------------------------------------- | --------------------------------------------- |
| `init`            | `conversation_id: string`                                  | Sesja zainicjowana.                           |
| `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | Mowa użytkownika została transkrybowana.      |
| `ping`            |                                                            | Utrzymanie połączenia. SDK odpowiada pongiem. |
| `close`           |                                                            | Poprawne rozłączenie.                         |
| `error`           | `message: string`                                          | Błąd z API.                                   |

### Wychodzące (serwer dewelopera do API ElevenLabs)

| Typ wiadomości   | Pola                                                       | Opis                                    |
| ---------------- | ---------------------------------------------------------- | --------------------------------------- |
| `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | Fragment odpowiedzi LLM do syntezy TTS. |
| `pong`           |                                                            | Odpowiedź na ping.                      |