> ## Documentation Index > Fetch the complete documentation index at: https://docs.gradium.ai/llms.txt > Use this file to discover all available pages before exploring further. # Cycle de vie WebSocket > Connexion, messages ready, entrée, flush, fin de flux, multiplexage et erreurs Les API temps réel de Gradium utilisent le même cycle de vie WebSocket pour la TTS et le STT : 1. Connectez-vous avec authentification. 2. Envoyez un message `setup`. 3. Attendez `ready`, ou recevez-le en différé. 4. Envoyez les messages d'entrée (`text` pour le TTS, `audio` pour le STT). 5. Si besoin, faites un flush de l'entrée en tampon. 6. Envoyez `end_of_stream`. 7. Lisez la sortie jusqu'à ce que le serveur envoie `end_of_stream` ou `error`. Le SDK Python gère la connexion pour vous, mais le cycle de vie est le même si vous utilisez directement le protocole. ## Endpoints | Produit | Endpoint WebSocket | Entrée | Sortie | | - | - | - | - | | TTS | `wss://api.gradium.ai/api/speech/tts` | Messages `text` | `audio`, `text`, `ready`, `end_of_stream`, `error` | | STT | `wss://api.gradium.ai/api/speech/asr` | Messages `audio`, `flush` | `text`, `end_text`, `step`, `flushed`, `ready`, `end_of_stream`, `error` | ## Authentification Les clients côté serveur doivent envoyer la clé API dans l'en-tête `x-api-key` : ```bash theme={null} wscat -c "wss://api.gradium.ai/api/speech/tts" \ -H "x-api-key: your_api_key" ``` Les clients navigateur ne doivent pas exposer de clés API. Générez sur votre serveur un token à usage unique et de courte durée, puis connectez-vous avec `?token=...` ; voir [WebSockets dans le navigateur](/fr/guides/browser-websockets). ## Setup Le premier message logique de chaque requête est `setup`. ```json TTS setup theme={null} { "type": "setup", "model_name": "default", "voice_id": "YTpq7expH9539ERJ", "output_format": "pcm" } ``` ```json STT setup theme={null} { "type": "setup", "model_name": "default", "input_format": "pcm", "json_config": {"language": "en", "delay_in_frames": 16} } ``` Champs de setup communs : | Champ | S'applique à | Rôle | | - | - | - | | `model_name` | TTS, STT | Pour le TTS, vaut `"default"` (stable) par défaut. Utilisez `"gradium-tts-beta"` pour suivre les versions bêta. Voir [Choix du modèle](/fr/guides/text-to-speech#choix-du-modèle). | | `json_config` | TTS, STT | Paramètres avancés du modèle. Les appels SDK acceptent un dict ; les clients WebSocket bruts peuvent envoyer un objet ou une chaîne JSON. | | `client_req_id` | TTS, STT | Met en correspondance les messages lorsque plusieurs requêtes partagent un même socket. | | `close_ws_on_eos` | TTS, STT | Vaut `true` par défaut. Définissez `false` pour garder le socket ouvert après une requête. | | `retry_for_s` | TTS, STT | Fenêtre facultative de nouvelles tentatives du setup en cas d'échec transitoire d'allocation d'un worker. | Champs de setup propres au TTS : | Champ | Rôle | | - | - | | `voice_id` | ID d'une voix de la bibliothèque ou d'une voix personnalisée. À privilégier en production. | | `voice` | Nom de voix de repli, `"default"` par défaut si aucun `voice_id` n'est fourni. | | `output_format` | `wav`, `pcm`, `opus`, `ulaw_8000`, `alaw_8000`, ou des fréquences PCM explicites comme `pcm_16000`. | | `pronunciation_id` | Dictionnaire de prononciation à appliquer à cette requête. | Champs de setup propres au STT : | Champ | Rôle | | - | - | | `input_format` | `pcm`, `wav`, `opus`, `ulaw_8000`, `alaw_8000`, ou des fréquences PCM explicites comme `pcm_16000`. | ## Ready Après le setup, le serveur envoie `ready`. Vous pouvez l'attendre avant d'envoyer l'entrée, ou commencer à envoyer immédiatement et laisser le SDK le récupérer pendant la réception. ```json TTS ready theme={null} { "type": "ready", "request_id": "req_...", "model_name": "default", "model_ext": "resolved-model", "sample_rate": 48000, "frame_size": 3840, "audio_stream_names": [], "text_stream_names": [] } ``` ```json STT ready theme={null} { "type": "ready", "request_id": "req_...", "model_name": "default", "sample_rate": 24000, "frame_size": 1920, "delay_in_frames": 16, "text_stream_names": [] } ``` Utilisez `request_id` dans vos logs et vos tickets de support. Pour le STT, utilisez `delay_in_frames` pour régler la gestion des tours de parole ou le comportement du flush forcé. ## Entrée Le TTS accepte des messages texte : ```json theme={null} {"type": "text", "text": "Hello, world."} ``` Lorsque vous diffusez en streaming le texte d'un LLM, découpez-le sur les espaces ou aux limites de phrases. Ne coupez pas à l'intérieur d'un mot et n'isolez pas la ponctuation dans un message à part : le serveur traite les messages texte successifs comme des fragments distincts et insère un espace entre eux. Le STT accepte des messages audio encodés en base64 : ```json theme={null} {"type": "audio", "audio": "base64_encoded_audio"} ``` Pour du PCM brut, utilisez si possible des fragments de 80 ms : | Format | Fréquence d'échantillonnage | Échantillons par 80 ms | Octets par fragment | | - | -: | -: | -: | | `pcm` | 24 kHz | 1920 | 3840 | | `pcm_8000` | 8 kHz | 640 | 1280 | | `pcm_16000` | 16 kHz | 1280 | 2560 | | `pcm_48000` | 48 kHz | 3840 | 7680 | ## Flush Le TTS prend en charge le flush au niveau du modèle avec la balise `` dans le texte : ```json theme={null} {"type": "text", "text": "The answer is ready. "} ``` Utilisez-la lorsqu'un LLM en amont a terminé une idée et que vous voulez que le modèle émette l'audio restant en tampon sans attendre davantage de texte. Évitez de faire un flush après chaque token : de petits fragments de texte dégradent la prosodie. Le STT prend en charge un message `flush` : ```json theme={null} {"type": "flush", "flush_id": 1} ``` Le serveur traite l'audio en attente et répond avec : ```json theme={null} {"type": "flushed", "flush_id": 1} ``` Utilisez le flush STT lorsque votre application a détecté une fin de tour de parole et a besoin de la transcription en attente avant de passer la main à un agent. ## Fin Envoyez `end_of_stream` lorsque vous avez fini d'envoyer l'entrée d'une requête : ```json theme={null} {"type": "end_of_stream"} ``` Pour une connexion à usage unique, le serveur envoie la sortie finale puis ferme le WebSocket. Pour une connexion réutilisable ou multiplexée, définissez `close_ws_on_eos: false` dans le setup et continuez à envoyer de nouveaux groupes setup/entrée. ## Multiplexage Pour exécuter plusieurs requêtes logiques sur un seul socket : 1. Définissez `close_ws_on_eos: false`. 2. Associez un `client_req_id` unique à chaque message d'une requête. 3. Routez chaque réponse selon son `client_req_id` correspondant. Consultez [Multiplexage](/fr/guides/multiplexing) pour des exemples complets. ## Erreurs Les erreurs WebSocket sont envoyées en JSON, puis le socket se ferme : ```json theme={null} {"type": "error", "message": "Session not found. Send setup first.", "code": 1002} ``` Considérez `error` comme définitif pour ce socket. Ouvrez une nouvelle connexion pour réessayer. Codes courants : | Code | Signification | | -: | - | | `1002` | Erreur de protocole, par exemple envoi d'une entrée avant le setup ou réutilisation d'un `client_req_id` actif. | | `1008` | Violation de politique, par exemple authentification invalide, abonnement manquant ou requête non conforme. | | `1011` | Erreur interne du serveur ou échec inattendu de la session. | Pour les contrats d'erreur REST et WebSocket, voir [Erreurs](/fr/guides/errors). ## Étapes suivantes Envoyez du texte en flux et recevez des fragments audio en retour. Envoyez de l'audio en flux et recevez du texte, des événements VAD et flush. Exécutez plusieurs requêtes logiques sur un seul WebSocket. Utilisez des tokens de courte durée sans exposer vos clés API. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.