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

# Python SDK-referentie

Deze pagina documenteert de openbare API voor de Speech Engine Python SDK (`elevenlabs`).

## Een Speech Engine-resource ophalen

Haal een `SpeechEngineResource` op via de engine-ID. Het geretourneerde object biedt methoden om een server te starten, requests te verifiëren of afzonderlijke sessies te maken.

```python
from elevenlabs import AsyncElevenLabs

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

## SpeechEngineResource

### Eigenschappen

| Eigenschap  | Type  | Beschrijving                |
| ----------- | ----- | --------------------------- |
| `engine_id` | `str` | De ID van de speech engine. |

### serve

Start een zelfstandige WebSocket-server. Blokkeert totdat deze wordt gestopt.

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

| Parameter       | Type       | Standaard | Beschrijving                                                                                                       |
| --------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
| `port`          | `int`      | `3001`    | Poort waarop wordt geluisterd.                                                                                     |
| `path`          | `str`      | `None`    | Beperk verbindingen tot dit pad. `None` accepteert alle verbindingen.                                              |
| `debug`         | `bool`     | `False`   | Schakel debuglogging naar stdout in.                                                                               |
| `disable_auth`  | `bool`     | `False`   | Sla JWT-verificatie voor inkomende verbindingen over. Zie [Authenticatie uitschakelen](#disabling-authentication). |
| `on_init`       | `callable` |           | Wordt aangeroepen wanneer een sessie wordt geïnitialiseerd.                                                        |
| `on_transcript` | `callable` |           | Wordt aangeroepen wanneer een gebruikerstranscript binnenkomt.                                                     |
| `on_close`      | `callable` |           | Wordt aangeroepen bij een nette verbreking van de verbinding.                                                      |
| `on_disconnect` | `callable` |           | Wordt aangeroepen wanneer de WebSocket onverwacht wegvalt.                                                         |
| `on_error`      | `callable` |           | Wordt aangeroepen bij protocol- of WebSocket-fouten.                                                               |

#### Authenticatie uitschakelen

Standaard verifieert `serve()` de header `X-Elevenlabs-Speech-Engine-Authorization` bij elke inkomende verbinding. Als je server achter een infrastructuurlaag staat die inkomend verkeer al beperkt tot ElevenLabs (meestal een IP-allowlist voor de [egress-ranges van ElevenLabs](/docs/nl/eleven-api/resources/ip-allowlisting)), kun je JWT-verificatie overslaan door `disable_auth=True` door te geven:

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

Wanneer authenticatie is uitgeschakeld, accepteert de server elke client die deze kan bereiken en geeft hij bij het opstarten een `UserWarning`.

> **Warning**
>
> Gebruik `disable_auth=True` alleen als je vóór de server een IP-allowlist, aangepaste headerwaarden of een gelijkwaardige
> beperking op netwerkniveau hebt. Zonder zo'n beperking kan iedereen op internet een
> sessie openen en je compute- en downstream-LLM-quotum verbruiken.

### verify\_request

Verifieer dat een inkomende request afkomstig is van de ElevenLabs Speech Engine API. Controleert de header `X-Elevenlabs-Speech-Engine-Authorization` op een geldige JWT die is ondertekend met de SHA-256-hash van je API-sleutel.

Alleen nodig wanneer je de WebSocket-upgrade zelf beheert. Bij gebruik van `serve()` wordt verificatie automatisch afgehandeld (tenzij `disable_auth=True` is ingesteld).

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

| Parameter | Type   | Beschrijving                   |
| --------- | ------ | ------------------------------ |
| `headers` | `dict` | Dictionary met requestheaders. |

**Retourneert:** `bool` — `True` als de request geldig is.

### create\_session

Verpak een geaccepteerde WebSocket in een `SpeechEngineSession`. Gebruik dit voor aangepaste serverintegratie (bijv. FastAPI, Starlette of handmatige WebSocket-afhandeling).

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

| Parameter | Type      | Standaard | Beschrijving                            |
| --------- | --------- | --------- | --------------------------------------- |
| `ws`      | WebSocket |           | Een geaccepteerde WebSocket-verbinding. |
| `debug`   | `bool`    | `False`   | Schakel debuglogging in.                |

**Retourneert:** `SpeechEngineSession`

## SpeechEngineSession

Verpakt één WebSocket-verbinding. Elke verbinding vertegenwoordigt één gesprek. De sessie geeft events voor transcripts en wijzigingen in de levenscyclus en biedt methoden om LLM-responses terug te sturen.

Wanneer een nieuw transcript binnenkomt, wordt de vorige transcripthandler automatisch geannuleerd, waardoor een actieve LLM-call wordt onderbroken.

### Eigenschappen

| Eigenschap        | Type            | Beschrijving                                                         |
| ----------------- | --------------- | -------------------------------------------------------------------- |
| `conversation_id` | `Optional[str]` | De gespreks-ID die door de API is toegewezen. Beschikbaar na `init`. |
| `is_open`         | `bool`          | Of de sessie nog open is.                                            |

### on

Registreer een handler voor een event. Retourneert de sessie voor chaining.

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

### off

Verwijder een eerder geregistreerde handler.

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

### once

Registreer een handler die één keer wordt uitgevoerd en zichzelf daarna verwijdert.

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

### send\_response

Stuur een LLM-response terug naar de Speech Engine API voor text-to-speech-synthese. Moet worden aangeroepen binnen een `on_transcript`-handler. Als je deze buiten een handler aanroept, wordt een waarschuwing gegeven en niets verzonden.

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

| Parameter  | Type                    | Beschrijving                                                                   |
| ---------- | ----------------------- | ------------------------------------------------------------------------------ |
| `response` | `str` \| async iterable | Een volledige string of een async iterable met tekstchunks / LLM-streamevents. |

De SDK detecteert automatisch tekst en extraheert deze uit de volgende LLM-streamformaten:

| Provider                | Eventformaat                                                                   |
| ----------------------- | ------------------------------------------------------------------------------ |
| 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

Voer de receive-loop uit totdat de WebSocket wordt gesloten. Dit is het belangrijkste toegangspunt nadat je handmatig een sessie hebt gemaakt via `create_session()`.

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

### close

Sluit de sessie en de onderliggende WebSocket-verbinding.

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

## Callbacks

De keywordarguments die aan `serve()` worden doorgegeven. Alle callbacks zijn optioneel. Handlers kunnen synchrone of asynchrone (coroutine) functies zijn.

| Callback        | Handlersignatuur                          | Beschrijving                                       |
| --------------- | ----------------------------------------- | -------------------------------------------------- |
| `on_init`       | `(conversation_id: str, session) -> None` | Sessie geïnitialiseerd met een gespreks-ID.        |
| `on_transcript` | `(transcript: list, session) -> None`     | Spraak van gebruiker getranscribeerd.              |
| `on_close`      | `(session) -> None`                       | Nette verbreking van de verbinding met ElevenLabs. |
| `on_disconnect` | `(session) -> None`                       | WebSocket is onverwacht weggevallen.               |
| `on_error`      | `(error: Exception, session) -> None`     | Protocol- of WebSocket-fout.                       |

## Events

Wanneer je `session.on()` rechtstreeks gebruikt in plaats van callbacks, zijn dit de eventnamen en hun handlersignaturen.

| Event             | Handlersignatuur                          |
| ----------------- | ----------------------------------------- |
| `user_transcript` | `(transcript: list[ConversationMessage])` |
| `init`            | `(conversation_id: str)`                  |
| `close`           | `()`                                      |
| `disconnected`    | `()`                                      |
| `error`           | `(error: Exception)`                      |

Eventnaamconstanten zijn beschikbaar voor typeveilig gebruik:

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

session.on(USER_TRANSCRIPT, handle_transcript)
```

## ConversationMessage

Eén bericht in de gespreksgeschiedenis. Het volledige transcript wordt bij elke beurt doorgegeven aan `on_transcript`.

| Eigenschap | Type                  | Beschrijving                     |
| ---------- | --------------------- | -------------------------------- |
| `role`     | `"user"` \| `"agent"` | Wie het bericht heeft verzonden. |
| `content`  | `str`                 | De tekstinhoud van het bericht.  |

## Wire protocol

Ter referentie: dit zijn de JSON-berichten die via de WebSocket-verbinding worden uitgewisseld. De SDK handelt serialisatie en deserialisatie automatisch af.

### Inkomend (ElevenLabs API naar ontwikkelaarsserver)

| Berichttype       | Velden                                                     | Beschrijving                          |
| ----------------- | ---------------------------------------------------------- | ------------------------------------- |
| `init`            | `conversation_id: string`                                  | Sessie geïnitialiseerd.               |
| `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | Spraak van gebruiker getranscribeerd. |
| `ping`            |                                                            | Keep-alive. SDK antwoordt met pong.   |
| `close`           |                                                            | Nette verbreking van de verbinding.   |
| `error`           | `message: string`                                          | Fout van de API.                      |

### Uitgaand (ontwikkelaarsserver naar ElevenLabs API)

| Berichttype      | Velden                                                     | Beschrijving                         |
| ---------------- | ---------------------------------------------------------- | ------------------------------------ |
| `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | LLM-responsechunk voor TTS-synthese. |
| `pong`           |                                                            | Antwoord op ping.                    |