Cycle de vie WebSocket

Les API temps réel de Gradium utilisent le même cycle de vie WebSocket pour la TTS et le STT :

Connectez-vous avec authentification.
Envoyez un message setup.
Attendez ready, ou recevez-le en différé.
Envoyez les messages d’entrée (text pour le TTS, audio pour le STT).
Si besoin, faites un flush de l’entrée en tampon.
Envoyez end_of_stream.
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 :

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.

Setup

Le premier message logique de chaque requête est setup.

TTS setup

{
  "type": "setup",
  "model_name": "default",
  "voice_id": "YTpq7expH9539ERJ",
  "output_format": "pcm"
}

STT setup

{
  "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.
`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.

TTS ready

{
  "type": "ready",
  "request_id": "req_...",
  "model_name": "default",
  "model_ext": "resolved-model",
  "sample_rate": 48000,
  "frame_size": 3840,
  "audio_stream_names": [],
  "text_stream_names": []
}

STT ready

{
  "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 :

{"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 :

{"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 <flush> dans le texte :

{"type": "text", "text": "The answer is ready. <flush>"}

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 :

{"type": "flush", "flush_id": 1}

Le serveur traite l’audio en attente et répond avec :

{"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 :

{"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 :

Définissez close_ws_on_eos: false.
Associez un client_req_id unique à chaque message d’une requête.
Routez chaque réponse selon son client_req_id correspondant.

Consultez Multiplexage pour des exemples complets.

Erreurs

Les erreurs WebSocket sont envoyées en JSON, puis le socket se ferme :

{"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.

Étapes suivantes

WebSocket de synthèse vocale

Envoyez du texte en flux et recevez des fragments audio en retour.

WebSocket de transcription

Envoyez de l’audio en flux et recevez du texte, des événements VAD et flush.

Multiplexage

Exécutez plusieurs requêtes logiques sur un seul WebSocket.

WebSockets dans le navigateur

Utilisez des tokens de courte durée sans exposer vos clés API.

Premiers pas

Synthèse vocale (TTS)

Transcription (STT)

Speech-to-Speech

Commun

Recettes temps réel

Migrations

Voix

Auto-hébergé

Ressources

Cycle de vie WebSocket

Endpoints

Authentification

Setup

Ready

Entrée

Flush

Fin

Multiplexage

Erreurs

Étapes suivantes

WebSocket de synthèse vocale

WebSocket de transcription

Multiplexage

WebSockets dans le navigateur

​Endpoints

​Authentification

​Setup

​Ready

​Entrée

​Flush

​Fin

​Multiplexage

​Erreurs

​Étapes suivantes

WebSocket de synthèse vocale

WebSocket de transcription

Multiplexage

WebSockets dans le navigateur

Endpoints

Authentification

Setup

Ready

Entrée

Flush

Fin

Multiplexage

Erreurs

Étapes suivantes