Referens för Python SDK | ElevenLabs Documentation

Den här sidan dokumenterar det offentliga API:et för Python SDK:t för Speech Engine (elevenlabs).

Hämta en Speech Engine-resurs

Hämta en SpeechEngineResource via dess motor-ID. Det returnerade objektet innehåller metoder för att starta en server, verifiera förfrågningar eller skapa enskilda sessioner.

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

SpeechEngineResource

Egenskaper

Egenskap	Typ	Beskrivning
`engine_id`	`str`	Talmodorns ID.

serve

Starta en fristående WebSocket-server. Blockerar tills den stoppas.

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

Parameter	Typ	Standard	Beskrivning
`port`	`int`	`3001`	Port att lyssna på.
`path`	`str`	`None`	Begränsa anslutningar till den här sökvägen. `None` accepterar alla.
`debug`	`bool`	`False`	Aktivera felsökningsloggning till stdout.
`disable_auth`	`bool`	`False`	Hoppa över JWT-verifiering för inkommande anslutningar. Se Inaktivera autentisering.
`on_init`	`callable`		Anropas när en session initieras.
`on_transcript`	`callable`		Anropas när en användartranskription kommer in.
`on_close`	`callable`		Anropas vid en korrekt frånkoppling.
`on_disconnect`	`callable`		Anropas när WebSocket-anslutningen oväntat bryts.
`on_error`	`callable`		Anropas vid protokoll- eller WebSocket-fel.

Inaktivera autentisering

Som standard verifierar serve() rubriken X-Elevenlabs-Speech-Engine-Authorization för varje inkommande anslutning. Om servern ligger bakom ett infrastrukturlager som redan begränsar inkommande trafik till ElevenLabs (vanligtvis en IP-tillåtelselista begränsad till ElevenLabs utgående IP-intervall) kan du hoppa över JWT-verifiering genom att ange disable_auth=True:

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

När autentisering är inaktiverad accepterar servern alla klienter som kan nå den och visar en UserWarning vid start.

Använd bara disable_auth=True om du har en IP-tillåtelselista, egna rubrikvärden eller en motsvarande begränsning på nätverksnivå framför servern. Utan en sådan kan vem som helst på internet öppna en session och förbruka din beräkningskapacitet och LLM-kvot för efterföljande tjänster.

verify_request

Verifiera att en inkommande förfrågan kommer från ElevenLabs Speech Engine API. Kontrollerar rubriken X-Elevenlabs-Speech-Engine-Authorization efter en giltig JWT som signerats med SHA-256-hashen av din API-nyckel.

Behövs bara när du själv hanterar WebSocket-uppgraderingen. När du använder serve() hanteras verifieringen automatiskt (såvida inte disable_auth=True har angetts).

is_valid = engine.verify_request(headers)

Parameter	Typ	Beskrivning
`headers`	`dict`	Ordbok med förfrågningsrubriker.

Returnerar: bool — True om förfrågan är giltig.

create_session

Omslut en accepterad WebSocket i en SpeechEngineSession. Använd detta för egen serverintegration (t.ex. FastAPI, Starlette eller manuell WebSocket-hantering).

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

Parameter	Typ	Standard	Beskrivning
`ws`	WebSocket		En accepterad WebSocket-anslutning.
`debug`	`bool`	`False`	Aktivera felsökningsloggning.

Returnerar: SpeechEngineSession

SpeechEngineSession

Omsluter en enskild WebSocket-anslutning. Varje anslutning representerar en konversation. Sessionen skickar händelser för transkriptioner och livscykelförändringar samt innehåller metoder för att skicka tillbaka LLM-svar.

När en ny transkription kommer in avbryts den föregående transkriptionshanteraren automatiskt, vilket avbryter pågående LLM-anrop.

Egenskaper

Egenskap	Typ	Beskrivning
`conversation_id`	`Optional[str]`	Konversations-ID:t som tilldelas av API:et. Tillgängligt efter `init`.
`is_open`	`bool`	Om sessionen fortfarande är öppen.

on

Registrera en hanterare för en händelse. Returnerar sessionen för kedjning.

session.on("user_transcript", handler)

off

Ta bort en tidigare registrerad hanterare.

session.off("user_transcript", handler)

once

Registrera en hanterare som körs en gång och sedan tar bort sig själv.

session.once("init", handler)

send_response

Skicka tillbaka ett LLM-svar till Speech Engine API för talsyntes. Måste anropas inuti en on_transcript-hanterare. Om den anropas utanför en hanterare visas en varning och funktionen returnerar utan att skicka något.

# 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	Beskrivning
`response`	`str` \| async iterable	En komplett sträng eller en asynkron iterable med textsegment/LLM-strömhändelser.

SDK:t identifierar automatiskt och extraherar text från följande LLM-strömformat:

Leverantör	Händelseformat
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

Kör mottagningsloopen tills WebSocket-anslutningen stängs. Detta är huvudingångspunkten efter att du har skapat en session manuellt via create_session().

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

close

Stäng sessionen och den underliggande WebSocket-anslutningen.

session.close()

Återanrop

Nyckelordsargumenten som skickas till serve(). Alla återanrop är valfria. Hanterare kan vara synkrona eller asynkrona funktioner (koroutiner).

Återanrop	Signatur	Beskrivning
`on_init`	`(conversation_id: str, session) -> None`	Sessionen initierades med ett konversations-ID.
`on_transcript`	`(transcript: list, session) -> None`	Användarens tal har transkriberats.
`on_close`	`(session) -> None`	Korrekt frånkoppling från ElevenLabs.
`on_disconnect`	`(session) -> None`	WebSocket-anslutningen bröts oväntat.
`on_error`	`(error: Exception, session) -> None`	Protokoll- eller WebSocket-fel.

Händelser

När du använder session.on() direkt i stället för återanrop är detta händelsenamnen och deras hanterarsignaturer.

Händelse	Hanterarsignatur
`user_transcript`	`(transcript: list[ConversationMessage])`
`init`	`(conversation_id: str)`
`close`	`()`
`disconnected`	`()`
`error`	`(error: Exception)`

Konstanter för händelsenamn finns tillgängliga för typsäker användning:

from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR
session.on(USER_TRANSCRIPT, handle_transcript)

ConversationMessage

Ett enskilt meddelande i konversationshistoriken. Hela transkriptionen skickas till on_transcript vid varje tur.

Egenskap	Typ	Beskrivning
`role`	`"user"` \| `"agent"`	Vem som skickade meddelandet.
`content`	`str`	Meddelandets textinnehåll.

Wire-protokoll

Som referens visas här JSON-meddelandena som utbyts över WebSocket-anslutningen. SDK:t hanterar serialisering och deserialisering automatiskt.

Inkommande (ElevenLabs API till utvecklarserver)

Meddelandetyp	Fält	Beskrivning
`init`	`conversation_id: string`	Sessionen initierades.
`user_transcript`	`user_transcript: TranscriptMessage[]`, `event_id: number`	Användarens tal har transkriberats.
`ping`		Keep-alive. SDK:t svarar med pong.
`close`		Korrekt frånkoppling.
`error`	`message: string`	Fel från API:et.

Utgående (utvecklarserver till ElevenLabs API)

Meddelandetyp	Fält	Beskrivning
`agent_response`	`content: string`, `event_id: number`, `is_final: boolean`	LLM-svarssegment för TTS-syntes.
`pong`		Svar på ping.