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.

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

SpeechEngineResource

Eigenschaften

serve

Startet einen eigenständigen WebSocket-Server. Blockiert bis zum Beenden.

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

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), können Sie die JWT-Verifizierung überspringen, indem Sie disable_auth=True übergeben:

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

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

is_valid = engine.verify_request(headers)

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

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

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

on

Registriert einen Handler für ein Ereignis. Gibt die Sitzung für Verkettungen zurück.

session.on("user_transcript", handler)

off

Entfernt einen zuvor registrierten Handler.

session.off("user_transcript", handler)

once

Registriert einen Handler, der einmal ausgeführt wird und sich dann selbst entfernt.

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.

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

Das SDK erkennt automatisch Text aus den folgenden LLM-Stream-Formaten und extrahiert ihn:

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.

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.

session.close()

Callbacks

Die an serve() übergebenen Keyword-Argumente. Alle Callbacks sind optional. Handler können synchrone oder asynchrone (Coroutine-)Funktionen sein.

Ereignisse

Wenn Sie session.on() direkt statt Callbacks verwenden, finden Sie hier die Ereignisnamen und die Signaturen ihrer Handler.

Konstanten für Ereignisnamen sind zur typsicheren Verwendung verfügbar:

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.

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)

Ausgehend (Entwickler-Server an ElevenLabs API)