Riferimento SDK Python

Questa pagina documenta l’API pubblica dell’SDK Python di Speech Engine (elevenlabs).

Ottenere una risorsa Speech Engine

Recupera una SpeechEngineResource tramite l’ID del motore. L’oggetto restituito offre metodi per avviare un server, verificare le richieste o creare singole sessioni.

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

SpeechEngineResource

Proprietà

serve

Avvia un server WebSocket indipendente. Rimane in esecuzione finché non viene arrestato.

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

Disabilitare l’autenticazione

Per impostazione predefinita, serve() verifica l’header X-Elevenlabs-Speech-Engine-Authorization per ogni connessione in entrata. Se il tuo server si trova dietro un livello di infrastruttura che limita già il traffico in entrata a ElevenLabs (in genere una allowlist di IP limitata agli intervalli di uscita di ElevenLabs), puoi ignorare la verifica JWT passando 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()

Quando l’autenticazione è disabilitata, il server accetta qualsiasi client che riesca a raggiungerlo ed emette un UserWarning all’avvio.

verify_request

Verifica che una richiesta in entrata provenga dall’API Speech Engine di ElevenLabs. Controlla che l’header X-Elevenlabs-Speech-Engine-Authorization contenga un JWT valido firmato con l’hash SHA-256 della tua chiave API.

È necessario soltanto se gestisci personalmente l’upgrade WebSocket. Quando usi serve(), la verifica viene gestita automaticamente (a meno che non sia impostato disable_auth=True).

is_valid = engine.verify_request(headers)

Restituisce: bool — True se la richiesta è valida.

create_session

Racchiude un WebSocket accettato in una SpeechEngineSession. Usalo per un’integrazione personalizzata del server (ad esempio FastAPI, Starlette o gestione manuale del WebSocket).

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

Restituisce: SpeechEngineSession

SpeechEngineSession

Racchiude una singola connessione WebSocket. Ogni connessione rappresenta una conversazione. La sessione emette eventi per le trascrizioni e le modifiche del ciclo di vita e offre metodi per inviare risposte LLM.

Quando arriva una nuova trascrizione, il gestore della trascrizione precedente viene annullato automaticamente, interrompendo qualsiasi chiamata LLM in corso.

Proprietà

on

Registra un gestore per un evento. Restituisce la sessione per concatenare le chiamate.

session.on("user_transcript", handler)

off

Rimuove un gestore registrato in precedenza.

session.off("user_transcript", handler)

once

Registra un gestore che viene eseguito una volta, quindi si rimuove.

session.once("init", handler)

send_response

Invia una risposta LLM all’API Speech Engine per la sintesi Text to Speech. Deve essere chiamato all’interno di un gestore on_transcript. Se lo chiami al di fuori di un gestore, viene emesso un avviso e non viene inviato nulla.

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

L’SDK rileva ed estrae automaticamente il testo dai seguenti formati di streaming LLM:

run

Esegue il ciclo di ricezione finché il WebSocket non si chiude. Questo è il punto di ingresso principale dopo aver creato manualmente una sessione tramite create_session().

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

close

Chiude la sessione e la connessione WebSocket sottostante.

session.close()

Callback

Gli argomenti keyword passati a serve(). Tutti i callback sono facoltativi. I gestori possono essere funzioni sincrone o asincrone (coroutine).

Eventi

Quando usi direttamente session.on() invece dei callback, questi sono i nomi degli eventi e le firme dei relativi gestori.

Sono disponibili costanti per i nomi degli eventi, per un utilizzo type-safe:

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

ConversationMessage

Un singolo messaggio nella cronologia della conversazione. La trascrizione completa viene passata a on_transcript a ogni turno.

Protocollo wire

Come riferimento, questi sono i messaggi JSON scambiati tramite la connessione WebSocket. L’SDK gestisce automaticamente la serializzazione e la deserializzazione.

In entrata (API ElevenLabs al server dello sviluppatore)

In uscita (server dello sviluppatore all’API ElevenLabs)