> 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-Referenz Diese Seite dokumentiert die öffentliche API für das Speech Engine Python SDK (`elevenlabs`). ## Speech Engine-Ressource abrufen Rufen Sie eine `SpeechEngineResource` über ihre Engine-ID ab. Das zurückgegebene Objekt bietet Methoden zum Starten eines Servers, zum Verifizieren von Anfragen oder zum Erstellen einzelner Sitzungen. ```python from elevenlabs import AsyncElevenLabs elevenlabs = AsyncElevenLabs() engine = await elevenlabs.speech_engine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6") ``` ## SpeechEngineResource ### Eigenschaften | Eigenschaft | Typ | Beschreibung | | ----------- | ----- | ------------------------- | | `engine_id` | `str` | Die ID der Speech Engine. | ### serve Startet einen eigenständigen WebSocket-Server. Blockiert bis zum Beenden. ```python await engine.serve( port=3001, path="/ws", debug=True, on_transcript=handle_transcript, ) ``` | Parameter | Typ | Standard | Beschreibung | | --------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `port` | `int` | `3001` | Port, auf dem gelauscht wird. | | `path` | `str` | `None` | Beschränkt Verbindungen auf diesen Pfad. `None` akzeptiert alle. | | `debug` | `bool` | `False` | Aktiviert Debug-Protokollierung in stdout. | | `disable_auth` | `bool` | `False` | Überspringt die JWT-Verifizierung bei eingehenden Verbindungen. Siehe [Authentifizierung deaktivieren](#disabling-authentication). | | `on_init` | `callable` | | Wird aufgerufen, wenn eine Sitzung initialisiert wird. | | `on_transcript` | `callable` | | Wird aufgerufen, wenn ein Nutzertranskript eintrifft. | | `on_close` | `callable` | | Wird bei einer ordnungsgemäßen Trennung aufgerufen. | | `on_disconnect` | `callable` | | Wird aufgerufen, wenn die WebSocket-Verbindung unerwartet abbricht. | | `on_error` | `callable` | | Wird bei Protokoll- oder WebSocket-Fehlern aufgerufen. | #### Authentifizierung deaktivieren Standardmäßig verifiziert `serve()` bei jeder eingehenden Verbindung den Header `X-Elevenlabs-Speech-Engine-Authorization`. Wenn Ihr Server hinter einer Infrastrukturschicht liegt, die eingehenden Datenverkehr bereits auf ElevenLabs beschränkt (in der Regel eine IP-Zulassungsliste für [die Egress-Bereiche von ElevenLabs](/docs/de/eleven-api/resources/ip-allowlisting)), können Sie die JWT-Verifizierung überspringen, indem Sie `disable_auth=True` übergeben: ```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() ``` Wenn die Authentifizierung deaktiviert ist, akzeptiert der Server jeden Client, der ihn erreichen kann, und gibt beim Start eine `UserWarning` aus. > **Warning** > > Verwenden Sie `disable_auth=True` nur, wenn sich vor dem Server eine IP-Zulassungsliste, benutzerdefinierte Header-Werte oder eine gleichwertige > Einschränkung auf Netzwerkebene befindet. Ohne diese kann jeder im Internet eine > Sitzung öffnen und Ihre Rechenkapazität sowie Ihr nachgelagertes LLM-Kontingent verbrauchen. ### verify_request Verifiziert, dass eine eingehende Anfrage von der ElevenLabs Speech Engine API stammt. Prüft den Header `X-Elevenlabs-Speech-Engine-Authorization` auf ein gültiges JWT, das mit dem SHA-256-Hash Ihres API-Schlüssels signiert ist. Nur erforderlich, wenn Sie das WebSocket-Upgrade selbst verwalten. Bei Verwendung von `serve()` wird die Verifizierung automatisch durchgeführt (außer wenn `disable_auth=True` gesetzt ist). ```python is_valid = engine.verify_request(headers) ``` | Parameter | Typ | Beschreibung | | --------- | ------ | ------------------------------- | | `headers` | `dict` | Wörterbuch mit Anfrage-Headern. | **Rückgabe:** `bool` — `True`, wenn die Anfrage gültig ist. ### create_session Kapselt eine akzeptierte WebSocket-Verbindung in einer `SpeechEngineSession`. Verwenden Sie dies für die Integration in benutzerdefinierte Server (z. B. FastAPI, Starlette oder manuelle WebSocket-Verarbeitung). ```python session = engine.create_session(websocket, debug=True) session.on("user_transcript", handle_transcript) await session.run() ``` | Parameter | Typ | Standard | Beschreibung | | --------- | --------- | -------- | -------------------------------------- | | `ws` | WebSocket | | Eine akzeptierte WebSocket-Verbindung. | | `debug` | `bool` | `False` | Aktiviert Debug-Protokollierung. | **Rückgabe:** `SpeechEngineSession` ## SpeechEngineSession Kapselt eine einzelne WebSocket-Verbindung. Jede Verbindung repräsentiert eine Unterhaltung. Die Sitzung sendet Ereignisse für Transkripte und Lebenszyklusänderungen und bietet Methoden, um LLM-Antworten zurückzusenden. Wenn ein neues Transkript eintrifft, wird der vorherige Transkript-Handler automatisch abgebrochen. Dadurch wird ein laufender LLM-Aufruf unterbrochen. ### Eigenschaften | Eigenschaft | Typ | Beschreibung | | ----------------- | --------------- | -------------------------------------------------------------------- | | `conversation_id` | `Optional[str]` | Die von der API zugewiesene Unterhaltungs-ID. Nach `init` verfügbar. | | `is_open` | `bool` | Ob die Sitzung noch geöffnet ist. | ### on Registriert einen Handler für ein Ereignis. Gibt die Sitzung für Verkettungen zurück. ```python session.on("user_transcript", handler) ``` ### off Entfernt einen zuvor registrierten Handler. ```python session.off("user_transcript", handler) ``` ### once Registriert einen Handler, der einmal ausgeführt wird und sich dann selbst entfernt. ```python session.once("init", handler) ``` ### send_response Sendet eine LLM-Antwort zur Text-to-Speech-Synthese an die Speech Engine API zurück. Muss innerhalb eines `on_transcript`-Handlers aufgerufen werden. Ein Aufruf außerhalb eines Handlers gibt eine Warnung aus und kehrt zurück, ohne etwas zu senden. ```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 | Typ | Beschreibung | | ---------- | ----------------------- | --------------------------------------------------------------------------------------------------------- | | `response` | `str` \| async iterable | Ein vollständiger String oder ein asynchron iterierbares Objekt aus Text-Chunks / LLM-Stream-Ereignissen. | Das SDK erkennt automatisch Text aus den folgenden LLM-Stream-Formaten und extrahiert ihn: | Anbieter | Ereignisformat | | ----------------------- | ------------------------------------------------------------------------------ | | 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 Führt die Empfangsschleife aus, bis die WebSocket-Verbindung geschlossen wird. Dies ist der Haupteinstiegspunkt, nachdem Sie eine Sitzung manuell über `create_session()` erstellt haben. ```python session = engine.create_session(websocket) session.on("user_transcript", handle_transcript) await session.run() ``` ### close Schließt die Sitzung und die zugrunde liegende WebSocket-Verbindung. ```python session.close() ``` ## Callbacks Die an `serve()` übergebenen Keyword-Argumente. Alle Callbacks sind optional. Handler können synchrone oder asynchrone (Coroutine-)Funktionen sein. | Callback | Signatur | Beschreibung | | --------------- | ----------------------------------------- | ------------------------------------------------- | | `on_init` | `(conversation_id: str, session) -> None` | Sitzung mit einer Unterhaltungs-ID initialisiert. | | `on_transcript` | `(transcript: list, session) -> None` | Nutzersprache transkribiert. | | `on_close` | `(session) -> None` | Ordnungsgemäße Trennung von ElevenLabs. | | `on_disconnect` | `(session) -> None` | WebSocket-Verbindung unerwartet abgebrochen. | | `on_error` | `(error: Exception, session) -> None` | Protokoll- oder WebSocket-Fehler. | ## Ereignisse Wenn Sie `session.on()` direkt statt Callbacks verwenden, finden Sie hier die Ereignisnamen und die Signaturen ihrer Handler. | Ereignis | Handler-Signatur | | ----------------- | ----------------------------------------- | | `user_transcript` | `(transcript: list[ConversationMessage])` | | `init` | `(conversation_id: str)` | | `close` | `()` | | `disconnected` | `()` | | `error` | `(error: Exception)` | Konstanten für Ereignisnamen sind zur typsicheren Verwendung verfügbar: ```python from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR session.on(USER_TRANSCRIPT, handle_transcript) ``` ## ConversationMessage Eine einzelne Nachricht im Unterhaltungsverlauf. Das vollständige Transkript wird bei jeder Runde an `on_transcript` übergeben. | Eigenschaft | Typ | Beschreibung | | ----------- | --------------------- | ------------------------------- | | `role` | `"user"` \| `"agent"` | Wer die Nachricht gesendet hat. | | `content` | `str` | Der Textinhalt der Nachricht. | ## Wire-Protokoll Zur Referenz: Dies sind die JSON-Nachrichten, die über die WebSocket-Verbindung ausgetauscht werden. Das SDK übernimmt Serialisierung und Deserialisierung automatisch. ### Eingehend (ElevenLabs API an Entwickler-Server) | Nachrichtentyp | Felder | Beschreibung | | ----------------- | ---------------------------------------------------------- | --------------------------------------- | | `init` | `conversation_id: string` | Sitzung initialisiert. | | `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | Nutzersprache transkribiert. | | `ping` | | Keep-alive. Das SDK antwortet mit pong. | | `close` | | Ordnungsgemäße Trennung. | | `error` | `message: string` | Fehler von der API. | ### Ausgehend (Entwickler-Server an ElevenLabs API) | Nachrichtentyp | Felder | Beschreibung | | ---------------- | ---------------------------------------------------------- | --------------------------------------- | | `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | LLM-Antwort-Chunk für die TTS-Synthese. | | `pong` | | Antwort auf ping. |