Python SDK-referentie | ElevenLabs Documentation

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.

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.

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.
`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), kun je JWT-verificatie overslaan door disable_auth=True door te geven:

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

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

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

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.

session.on("user_transcript", handler)

off

Verwijder een eerder geregistreerde handler.

session.off("user_transcript", handler)

once

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

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.

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

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

close

Sluit de sessie en de onderliggende WebSocket-verbinding.

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:

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.