Endpoint WebSocket et connexion temps réel

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

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, extra_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 la connexion pour plusieurs raisons : expiration de session (30 minutes maximum), erreur d’authentification ou dépassement de la limite de sessions concurrentes (100). Votre application doit prévoir une logique de reconnexion avec un backoff exponentiel.

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}
• Une session dure au maximum 30 minutes et vous pouvez maintenir jusqu’à 100 sessions simultanées
• Le serveur envoie session.created dès la connexion, puis attend votre session.update pour configurer la conversation
• La tarification est de $0.05 par minute, soit $3.00 par heure