> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # 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. ```python from elevenlabs import AsyncElevenLabs elevenlabs = AsyncElevenLabs() engine = await elevenlabs.speech_engine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6") ``` ## SpeechEngineResource ### Propriétés | Propriété | Type | Description | | ----------- | ----- | --------------------- | | `engine_id` | `str` | L’ID du moteur vocal. | ### serve Démarre un serveur WebSocket autonome. Bloque jusqu’à son arrêt. ```python await engine.serve( port=3001, path="/ws", debug=True, on_transcript=handle_transcript, ) ``` | Paramètre | Type | Valeur par défaut | Description | | --------------- | ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `port` | `int` | `3001` | Port sur lequel écouter. | | `path` | `str` | `None` | Restreint les connexions à ce chemin. `None` accepte toutes les connexions. | | `debug` | `bool` | `False` | Active la journalisation de débogage vers stdout. | | `disable_auth` | `bool` | `False` | Ignore la vérification JWT pour les connexions entrantes. Consultez [Désactiver l’authentification](#disabling-authentication). | | `on_init` | `callable` | | Appelé lors de l’initialisation d’une session. | | `on_transcript` | `callable` | | Appelé lorsqu’une transcription utilisateur arrive. | | `on_close` | `callable` | | Appelé lors d’une déconnexion propre. | | `on_disconnect` | `callable` | | Appelé lorsque le WebSocket se ferme de manière inattendue. | | `on_error` | `callable` | | Appelé en cas d’erreurs de protocole ou WebSocket. | #### 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](/docs/fr/eleven-api/resources/ip-allowlisting), vous pouvez ignorer la vérification JWT en transmettant `disable_auth=True` : ```python # 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. > **Warning** > > Utilisez `disable_auth=True` uniquement si une liste d’autorisation d’adresses IP, des valeurs d’en-tête personnalisées ou une restriction réseau équivalente > se trouve devant le serveur. Sans cela, toute personne sur Internet peut ouvrir une > session et consommer vos ressources de calcul ainsi que votre quota LLM en aval. ### 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. ```python is_valid = engine.verify_request(headers) ``` | Paramètre | Type | Description | | --------- | ------ | ------------------------------------- | | `headers` | `dict` | Dictionnaire des en-têtes de requête. | **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. ```python session = engine.create_session(websocket, debug=True) session.on("user_transcript", handle_transcript) await session.run() ``` | Paramètre | Type | Valeur par défaut | Description | | --------- | --------- | ----------------- | ------------------------------------- | | `ws` | WebSocket | | Une connexion WebSocket acceptée. | | `debug` | `bool` | `False` | Active la journalisation de débogage. | **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 | Propriété | Type | Description | | ----------------- | --------------- | ----------------------------------------------------------------- | | `conversation_id` | `Optional[str]` | L’ID de conversation attribué par l’API. Disponible après `init`. | | `is_open` | `bool` | Indique si la session est toujours ouverte. | ### on Enregistre un gestionnaire pour un événement. Renvoie la session pour permettre l’enchaînement. ```python session.on("user_transcript", handler) ``` ### off Supprime un gestionnaire précédemment enregistré. ```python session.off("user_transcript", handler) ``` ### once Enregistre un gestionnaire qui s’exécute une fois puis se supprime. ```python 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. ```python # 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) ``` | Paramètre | Type | Description | | ---------- | ---------------------------- | ----------------------------------------------------------------------------------------------- | | `response` | `str` \| itérable asynchrone | Une chaîne complète ou un itérable asynchrone de segments de texte ou d’événements de flux LLM. | Le SDK détecte automatiquement et extrait le texte des formats de flux LLM suivants : | Fournisseur | Format d’événement | | ------------------------- | ------------------------------------------------------------------------------ | | API Responses d’OpenAI | `{ type: "response.output_text.delta", delta: "text" }` | | Chat Completions d’OpenAI | `{ choices: [{ delta: { content: "text" } }] }` | | API Messages d’Anthropic | `{ type: "content_block_delta", delta: { type: "text_delta", text: "text" } }` | | API Gemini de Google | `{ candidates: [{ content: { parts: [{ text: "text" }] } }] }` | ### 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()`. ```python session = engine.create_session(websocket) session.on("user_transcript", handle_transcript) await session.run() ``` ### close Ferme la session et la connexion WebSocket sous-jacente. ```python 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. | Rappel | Signature | Description | | --------------- | ----------------------------------------- | ----------------------------------------------- | | `on_init` | `(conversation_id: str, session) -> None` | Session initialisée avec un ID de conversation. | | `on_transcript` | `(transcript: list, session) -> None` | Parole de l’utilisateur transcrite. | | `on_close` | `(session) -> None` | Déconnexion propre d’ElevenLabs. | | `on_disconnect` | `(session) -> None` | WebSocket fermé de manière inattendue. | | `on_error` | `(error: Exception, session) -> None` | Erreur de protocole ou WebSocket. | ## É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. | Événement | Signature du gestionnaire | | ----------------- | ----------------------------------------- | | `user_transcript` | `(transcript: list[ConversationMessage])` | | `init` | `(conversation_id: str)` | | `close` | `()` | | `disconnected` | `()` | | `error` | `(error: Exception)` | Des constantes de noms d’événements sont disponibles pour une utilisation avec sûreté de type : ```python 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. | Propriété | Type | Description | | --------- | --------------------- | ------------------------------ | | `role` | `"user"` \| `"agent"` | L’expéditeur du message. | | `content` | `str` | Le contenu textuel du message. | ## 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 | Type de message | Champs | Description | | ----------------- | ---------------------------------------------------------- | ---------------------------------------------- | | `init` | `conversation_id: string` | Session initialisée. | | `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | Parole de l’utilisateur transcrite. | | `ping` | | Maintien de connexion. Le SDK répond par pong. | | `close` | | Déconnexion propre. | | `error` | `message: string` | Erreur provenant de l’API. | ### Sortants, du serveur du développeur vers l’API ElevenLabs | Type de message | Champs | Description | | ---------------- | ---------------------------------------------------------- | -------------------------------------------- | | `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | Segment de réponse LLM pour la synthèse TTS. | | `pong` | | Réponse à ping. |