> 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 Python SDK

Ta strona dokumentuje publiczne API Python SDK Speech Engine (`elevenlabs`).

## Pobieranie zasobu Speech Engine

Pobierz `SpeechEngineResource` za pomocą identyfikatora silnika. Zwrócony obiekt udostępnia metody uruchamiania serwera, weryfikowania żądań i tworzenia pojedynczych sesji.

```python
from elevenlabs import AsyncElevenLabs

elevenlabs = AsyncElevenLabs()
engine = await elevenlabs.speech_engine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6")
```

## SpeechEngineResource

### Właściwości

| Właściwość  | Typ   | Opis                        |
| ----------- | ----- | --------------------------- |
| `engine_id` | `str` | Identyfikator silnika mowy. |

### serve

Uruchamia samodzielny serwer WebSocket. Działa do zatrzymania.

```python
await engine.serve(
    port=3001,
    path="/ws",
    debug=True,
    on_transcript=handle_transcript,
)
```

| Parametr        | Typ        | Domyślnie | Opis                                                                                                                 |
| --------------- | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- |
| `port`          | `int`      | `3001`    | Port nasłuchiwania.                                                                                                  |
| `path`          | `str`      | `None`    | Ogranicza połączenia do tej ścieżki. `None` akceptuje wszystkie.                                                     |
| `debug`         | `bool`     | `False`   | Włącza logowanie debugowania do stdout.                                                                              |
| `disable_auth`  | `bool`     | `False`   | Pomija weryfikację JWT dla połączeń przychodzących. Zobacz [Wyłączanie uwierzytelniania](#disabling-authentication). |
| `on_init`       | `callable` |           | Wywoływane podczas inicjalizacji sesji.                                                                              |
| `on_transcript` | `callable` |           | Wywoływane po otrzymaniu transkrypcji użytkownika.                                                                   |
| `on_close`      | `callable` |           | Wywoływane przy poprawnym rozłączeniu.                                                                               |
| `on_disconnect` | `callable` |           | Wywoływane, gdy WebSocket niespodziewanie się rozłączy.                                                              |
| `on_error`      | `callable` |           | Wywoływane przy błędach protokołu lub WebSocket.                                                                     |

#### Wyłączanie uwierzytelniania

Domyślnie `serve()` weryfikuje nagłówek `X-Elevenlabs-Speech-Engine-Authorization` przy każdym połączeniu przychodzącym. Jeśli serwer działa za warstwą infrastruktury, która już ogranicza ruch przychodzący do ElevenLabs (zwykle listą dozwolonych adresów IP dla [zakresów wyjściowych ElevenLabs](/docs/pl/eleven-api/resources/ip-allowlisting)), możesz pominąć weryfikację JWT, przekazując `disable_auth=True`:

```python
# No api_key required when disable_auth is True
await engine.serve(port=3001, disable_auth=True, on_transcript=on_transcript)

# Or directly on SpeechEngineServer
from elevenlabs.speech_engine import SpeechEngineServer

server = SpeechEngineServer(port=3001, disable_auth=True, on_transcript=on_transcript)
await server.serve()
```

Gdy uwierzytelnianie jest wyłączone, serwer akceptuje każdego klienta, który może się z nim połączyć, i przy uruchomieniu emituje `UserWarning`.

> **Warning**
>
> Używaj `disable_auth=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 tego każda osoba w internecie może otworzyć
> sesję i zużyć twoje zasoby obliczeniowe oraz limit po stronie LLM.

### verify_request

Weryfikuje, czy żądanie przychodzące pochodzi z API ElevenLabs Speech Engine. Sprawdza nagłówek `X-Elevenlabs-Speech-Engine-Authorization` pod kątem poprawnego JWT podpisanego hashem SHA-256 twojego klucza API.

Potrzebne tylko wtedy, gdy samodzielnie obsługujesz przejście na WebSocket. Przy użyciu `serve()` weryfikacja odbywa się automatycznie (chyba że ustawiono `disable_auth=True`).

```python
is_valid = engine.verify_request(headers)
```

| Parametr  | Typ    | Opis                       |
| --------- | ------ | -------------------------- |
| `headers` | `dict` | Słownik nagłówków żądania. |

**Zwraca:** `bool` — `True`, jeśli żądanie jest poprawne.

### create_session

Opakowuje zaakceptowane połączenie WebSocket w `SpeechEngineSession`. Użyj tego do własnej integracji z serwerem (np. FastAPI, Starlette lub ręcznej obsługi WebSocket).

```python
session = engine.create_session(websocket, debug=True)
session.on("user_transcript", handle_transcript)
await session.run()
```

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

**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 pojawi się nowa transkrypcja, poprzedni handler transkrypcji jest automatycznie anulowany, co przerywa trwające wywołanie LLM.

### Właściwości

| Właściwość        | Typ             | Opis                                                        |
| ----------------- | --------------- | ----------------------------------------------------------- |
| `conversation_id` | `Optional[str]` | Identyfikator rozmowy nadany przez API. Dostępny po `init`. |
| `is_open`         | `bool`          | Czy sesja jest nadal otwarta.                               |

### on

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

```python
session.on("user_transcript", handler)
```

### off

Usuwa wcześniej zarejestrowany handler.

```python
session.off("user_transcript", handler)
```

### once

Rejestruje handler, który uruchamia się raz, a potem usuwa sam siebie.

```python
session.once("init", handler)
```

### send_response

Wysyła odpowiedź LLM do API Speech Engine w celu syntezy zamiany tekstu na mowę. Musi zostać wywołana wewnątrz handlera `on_transcript`. Wywołanie poza handlerem emituje ostrzeżenie i kończy się bez wysłania odpowiedzi.

```python
# String response
await session.send_response("Hello, how can I help?")

# Streamed response (OpenAI, Anthropic, or Gemini)
stream = await openai_client.responses.create(model="gpt-4o", input=messages, stream=True)
await session.send_response(stream)
```

| Parametr   | Typ                     | Opis                                                                                                   |
| ---------- | ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `response` | `str` \| async iterable | Pełny ciąg znaków lub asynchroniczny iterowalny obiekt z fragmentami tekstu / zdarzeniami streamu LLM. |

SDK automatycznie wykrywa i wyodrębnia tekst z poniższych formatów streamu 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" }] } }] }`                 |

### run

Uruchamia pętlę odbierania, aż WebSocket się zamknie. To główny punkt wejścia po ręcznym utworzeniu sesji przez `create_session()`.

```python
session = engine.create_session(websocket)
session.on("user_transcript", handle_transcript)
await session.run()
```

### close

Zamyka sesję i bazowe połączenie WebSocket.

```python
session.close()
```

## Callbacki

Argumenty nazwane przekazywane do `serve()`. Wszystkie callbacki są opcjonalne. Handlery mogą być synchronicznymi lub asynchronicznymi funkcjami (korutynami).

| Callback        | Sygnatura                                 | Opis                                              |
| --------------- | ----------------------------------------- | ------------------------------------------------- |
| `on_init`       | `(conversation_id: str, session) -> None` | Sesja zainicjalizowana z identyfikatorem rozmowy. |
| `on_transcript` | `(transcript: list, session) -> None`     | Mowa użytkownika została przetranskrybowana.      |
| `on_close`      | `(session) -> None`                       | Poprawne rozłączenie z ElevenLabs.                |
| `on_disconnect` | `(session) -> None`                       | WebSocket niespodziewanie się rozłączył.          |
| `on_error`      | `(error: Exception, session) -> None`     | Błąd protokołu lub WebSocket.                     |

## Zdarzenia

Przy bezpośrednim użyciu `session.on()` zamiast callbacków, poniżej znajdziesz nazwy zdarzeń i sygnatury ich handlerów.

| Zdarzenie         | Sygnatura handlera                        |
| ----------------- | ----------------------------------------- |
| `user_transcript` | `(transcript: list[ConversationMessage])` |
| `init`            | `(conversation_id: str)`                  |
| `close`           | `()`                                      |
| `disconnected`    | `()`                                      |
| `error`           | `(error: Exception)`                      |

Stałe nazw zdarzeń są dostępne do użycia z kontrolą typów:

```python
from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR

session.on(USER_TRANSCRIPT, handle_transcript)
```

## ConversationMessage

Pojedyncza wiadomość w historii rozmowy. Pełna transkrypcja jest przekazywana do `on_transcript` w każdej turze.

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

## Protokół komunikacji

Dla odniesienia: są to komunikaty JSON wymieniane przez połączenie WebSocket. SDK automatycznie obsługuje serializację i deserializację.

### Przychodzące (API ElevenLabs do serwera dewelopera)

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

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

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