Endpoint WebSocket et connexion temps réel

Leçon corrigée le 3 novembre 2026 d’après les pages Speech to Speech, Pricing et Rate limits de xAI : 0,08 $ par minute et non 0,05 $, sessions simultanées par palier (10 au palier d’entrée et non 100), modèle grok-voice-3.0 ; la limite de 30 minutes par session ne figure plus dans la documentation. Sources : Speech to Speech · Pricing · Rate limits.

L’API Voice Agent en temps réel

L’API Voice Agent de Grok permet de construire des agents conversationnels vocaux qui interagissent en temps réel avec vos utilisateurs. Contrairement aux API REST classiques qui fonctionnent en requête-réponse, cette API utilise le protocole WebSocket pour maintenir une connexion bidirectionnelle persistante entre votre application et les serveurs xAI.

L’endpoint unique est :

wss://api.x.ai/v1/realtime

Le modèle se choisit par le paramètre model de l’URL, par exemple wss://api.x.ai/v1/realtime?model=grok-voice-latest : grok-voice-latest pointe vers grok-voice-3.0, le modèle actuel, et c’est aussi la valeur par défaut. En production, xAI conseille d’épingler une version nommée.

Ce point d’entrée gère l’intégralité du cycle de vie d’une conversation vocale : réception de l’audio, détection de la parole, génération de la réponse et envoi de l’audio synthétisé.

Établir la connexion WebSocket

Pour vous connecter, vous devez fournir votre clé API xAI dans le header d’autorisation. Voici un exemple en JavaScript :

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer " + process.env.XAI_API_KEY
  }
});

ws.on("open", () => {
  console.log("Connexion WebSocket établie");
});

ws.on("message", (data) => {
  const event = JSON.parse(data);
  console.log("Événement reçu :", event.type);
});

ws.on("close", (code, reason) => {
  console.log("Connexion fermée :", code, reason);
});

ws.on("error", (err) => {
  console.error("Erreur WebSocket :", err);
});

En Python, vous pouvez utiliser la bibliothèque websockets :

import asyncio
import websockets
import json
import os

async def connect():
    uri = "wss://api.x.ai/v1/realtime"
    headers = {
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}"
    }

    async with websockets.connect(uri, additional_headers=headers) as ws:
        async for message in ws:
            event = json.loads(message)
            print(f"Événement : {event['type']}")

asyncio.run(connect())

Cycle de vie d’une session

Une fois la connexion WebSocket ouverte, le serveur envoie immédiatement un événement session.created confirmant que la session est active. Vous devez ensuite envoyer un événement session.update pour configurer les paramètres de la conversation (voix, instructions, outils, détection de tour de parole).

Le cycle typique est le suivant :

1. Connexion : ouverture du WebSocket avec authentification
2. Configuration : envoi de session.update avec vos paramètres
3. Confirmation : réception de session.updated par le serveur
4. Conversation : échange d’événements audio et texte
5. Fermeture : déconnexion propre du WebSocket

Gestion des erreurs de connexion

Le serveur peut fermer ou refuser la connexion pour plusieurs raisons : erreur d’authentification, dépassement du nombre de sessions simultanées de votre palier (10 au palier d’entrée, jusqu’à 200 au palier le plus haut), incident. La documentation actuelle ne fixe pas de durée maximale de session ; la reprise de session (leçon 4) permet de reprendre une conversation après une coupure. Votre application doit prévoir une logique de reconnexion avec un backoff exponentiel.

Tarifs vérifiés le 3 novembre 2026 — les prix évoluent régulièrement : avant tout calcul de budget, vérifiez la grille en vigueur sur la page officielle des tarifs xAI.

Points clés à retenir

• L’endpoint WebSocket wss://api.x.ai/v1/realtime est le point d’entrée unique pour toutes les conversations vocales
• L’authentification se fait via le header Authorization: Bearer {clé API}
• Le nombre de sessions simultanées dépend du palier : 10 au palier d’entrée, jusqu’à 200
• Le serveur envoie session.created dès la connexion, puis attend votre session.update pour configurer la conversation
• La tarification est de $0.08 par minute, soit $4.80 par heure, plus $0.004 par entrée texte