Référence du SDK Python

Cette page documente l’API publique du SDK Python Speech Engine (elevenlabs).

Obtenir une ressource Speech Engine

Récupérez une SpeechEngineResource à partir de son ID de moteur. L’objet renvoyé fournit des méthodes pour démarrer un serveur, vérifier des requêtes ou créer des sessions individuelles.

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

SpeechEngineResource

Propriétés

serve

Démarre un serveur WebSocket autonome. Bloque jusqu’à son arrêt.

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

Désactiver l’authentification

Par défaut, serve() vérifie l’en-tête X-Elevenlabs-Speech-Engine-Authorization sur chaque connexion entrante. Si votre serveur se trouve derrière une couche d’infrastructure qui restreint déjà le trafic entrant à ElevenLabs, généralement une liste d’autorisation d’adresses IP limitée aux plages de sortie d’ElevenLabs, vous pouvez ignorer la vérification JWT en transmettant 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()

Lorsque l’authentification est désactivée, le serveur accepte tout client pouvant l’atteindre et émet un UserWarning au démarrage.

verify_request

Vérifie qu’une requête entrante provient de l’API Speech Engine d’ElevenLabs. Vérifie que l’en-tête X-Elevenlabs-Speech-Engine-Authorization contient un JWT valide signé avec le hachage SHA-256 de votre clé API.

Nécessaire uniquement si vous gérez vous-même la mise à niveau WebSocket. Avec serve(), la vérification est effectuée automatiquement, sauf si disable_auth=True a été défini.

is_valid = engine.verify_request(headers)

Renvoie : bool, True si la requête est valide.

create_session

Encapsule un WebSocket accepté dans une SpeechEngineSession. Utilisez cette méthode pour une intégration serveur personnalisée, par exemple FastAPI, Starlette ou une gestion manuelle de WebSocket.

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

Renvoie : SpeechEngineSession

SpeechEngineSession

Encapsule une seule connexion WebSocket. Chaque connexion représente une conversation. La session émet des événements pour les transcriptions et les changements de cycle de vie, et fournit des méthodes pour renvoyer des réponses LLM.

Lorsqu’une nouvelle transcription arrive, le gestionnaire de la transcription précédente est automatiquement annulé, interrompant tout appel LLM en cours.

Propriétés

on

Enregistre un gestionnaire pour un événement. Renvoie la session pour permettre l’enchaînement.

session.on("user_transcript", handler)

off

Supprime un gestionnaire précédemment enregistré.

session.off("user_transcript", handler)

once

Enregistre un gestionnaire qui s’exécute une fois puis se supprime.

session.once("init", handler)

send_response

Renvoie une réponse LLM à l’API Speech Engine pour la synthèse vocale. Cette méthode doit être appelée dans un gestionnaire on_transcript. L’appeler en dehors d’un gestionnaire émet un avertissement et s’arrête sans envoyer de réponse.

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

Le SDK détecte automatiquement et extrait le texte des formats de flux LLM suivants :

run

Exécute la boucle de réception jusqu’à la fermeture du WebSocket. Il s’agit du point d’entrée principal après la création manuelle d’une session via create_session().

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

close

Ferme la session et la connexion WebSocket sous-jacente.

session.close()

Rappels

Les arguments nommés transmis à serve(). Tous les rappels sont facultatifs. Les gestionnaires peuvent être des fonctions synchrones ou asynchrones, sous forme de coroutines.

Événements

Lorsque vous utilisez directement session.on() plutôt que des rappels, voici les noms des événements et les signatures de leurs gestionnaires.

Des constantes de noms d’événements sont disponibles pour une utilisation avec sûreté de type :

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

ConversationMessage

Un message unique dans l’historique de conversation. La transcription complète est transmise à on_transcript à chaque tour.

Protocole filaire

À titre de référence, voici les messages JSON échangés via la connexion WebSocket. Le SDK gère automatiquement la sérialisation et la désérialisation.

Entrants, de l’API ElevenLabs vers le serveur du développeur

Sortants, du serveur du développeur vers l’API ElevenLabs