Vai al contenuto principale
Italiano— Scegli una lingua
Menu

L'endpoint WebSocket e la connessione in tempo reale

Lezione 1 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. L’API Voice Agent in tempo reale
  2. Aprire la connessione WebSocket
  3. Ciclo di vita della sessione
  4. Punti chiave

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.0 come 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.

Documentazione dell'API Voice Agent

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.

WebSocket
Protocollo in tempo reale
grok-voice-3.0
Modello corrente
10
Sessioni concurrenti nel livello base
$0.08/min
Prezzi

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ì:

  1. Connessione: apri il WebSocket con l’autenticazione
  2. Configurazione: invia session.update con le tue impostazioni
  3. Conferma: ricevi session.updated dal server
  4. Conversazione: scambia eventi audio e testo
  5. 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.created alla connessione, poi attende il tuo session.update per configurare la conversazione
  • Il prezzo è di 0,08 $ al minuto, ovvero 4,80 $ all’ora, più 0,004 $ per input di testo