L'endpoint WebSocket e la connessione in tempo reale
In questa pagina
Aggiornato il 3 novembre 2026, sulla base delle pagine xAI Speech to Speech, Pricing e Rate limits: 0,08 $ al minuto, sessioni concurrenti per livello e
grok-voice-3.0come modello corrente. Fonti: Speech to Speech · Pricing · Rate limits.
L’API Voice Agent in tempo reale
L’API Grok Voice Agent ti permette di creare agenti vocali conversazionali che interagiscono con i tuoi utenti in tempo reale. A differenza delle classiche API REST, che funzionano richiesta per richiesta, questa API utilizza il protocollo WebSocket per mantenere aperta una connessione bidirezionale persistente tra la tua applicazione e i server di xAI.

Esiste un unico endpoint:
wss://api.x.ai/v1/realtime
Selezioni il modello tramite il parametro URL model, ad esempio wss://api.x.ai/v1/realtime?model=grok-voice-latest. grok-voice-latest punta a grok-voice-3.0, il modello attuale, ed è anche l’impostazione predefinita. In produzione, xAI consiglia di fissare (pin) una versione nominata specifica.
Questo singolo endpoint gestisce l’intero ciclo di vita di una conversazione vocale: ricezione dell’audio, rilevamento della voce, generazione della risposta e invio dell’audio sintetizzato.
Aprire la connessione WebSocket
Per connetterti, inserisci la tua chiave API xAI nell’intestazione di autorizzazione. Ecco un esempio in JavaScript:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer " + process.env.XAI_API_KEY
}
});
ws.on("open", () => {
console.log("WebSocket connection established");
});
ws.on("message", (data) => {
const event = JSON.parse(data);
console.log("Event received:", event.type);
});
ws.on("close", (code, reason) => {
console.log("Connection closed:", code, reason);
});
ws.on("error", (err) => {
console.error("WebSocket error:", err);
});
In Python, puoi utilizzare la libreria 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"Event: {event['type']}")
asyncio.run(connect())
Ciclo di vita della sessione
Non appena la connessione WebSocket viene aperta, il server invia un evento session.created che conferma l’attivazione della sessione. Successivamente, invii un evento session.update per configurare la conversazione (voce, istruzioni, strumenti, rilevamento del turno).
Il ciclo tipico si presenta così:
- Connessione: apri il WebSocket con l’autenticazione
- Configurazione: invia
session.updatecon le tue impostazioni - Conferma: ricevi
session.updateddal server - Conversazione: scambia eventi audio e testo
- Chiusura: disconnetti il WebSocket correttamente
Gestire gli errori di connessione
Il server può chiudere o rifiutare la connessione per diversi motivi: un errore di autenticazione, il superamento del limite di sessioni concurrenti del tuo livello (10 nel livello base, fino a 200 nel livello più alto) o un incidente. La documentazione attuale non stabilisce una durata massima della sessione e la ripresa della sessione (lezione 4) ti consente di riprendere una conversazione dopo un’interruzione. La tua applicazione dovrebbe includere una logica di riconnessione con backoff esponenziale.
Prezzi verificati il 3 novembre 2026. I prezzi cambiano spesso: prima di pianificare qualsiasi budget, controlla le tariffe attuali sulla pagina ufficiale dei prezzi di xAI.
Punti chiave
- L’endpoint WebSocket
wss://api.x.ai/v1/realtimeè l’unico punto di ingresso per tutte le conversazioni vocali - Ti autentichi con l’intestazione
Authorization: Bearer {chiave API} - Il numero di sessioni concurrenti dipende dal tuo livello: 10 nel livello base, fino a 200
- Il server invia
session.createdalla connessione, poi attende il tuosession.updateper configurare la conversazione - Il prezzo è di 0,08 $ al minuto, ovvero 4,80 $ all’ora, più 0,004 $ per input di testo