La connessione WebSocket TTS
In questa pagina
Aggiornato il 3 novembre 2026, sulla base della pagina Text to Speech di xAI: delta fino a 60.000 caratteri, nessun timeout di connessione e un “permesso di sessione” di 600 secondi. Fonte: Text to Speech.
Sintesi vocale in tempo reale tramite WebSocket
L’API TTS di Grok offre una modalità WebSocket per lo streaming della sintesi vocale. A differenza della modalità HTTP unaria, che attende il completamento dell’elaborazione per restituire l’audio completo, WebSocket invia i chunk audio man mano che vengono generati. È ideale per le applicazioni interattive in cui la latenza percepita deve essere la più bassa possibile.
Endpoint WebSocket
Ti connetti a wss://api.x.ai/v1/tts. I parametri di configurazione vanno inseriti nella query string della connessione iniziale.
Parametri di connessione
| Parametro | Obbligatorio | Predefinito | Descrizione |
|---|---|---|---|
language | Sì | — | Codice BCP-47 o auto |
voice | No | — | ID di una voce integrata o personalizzata |
codec | No | mp3 | mp3, wav, pcm, mulaw (o ulaw), alaw |
sample_rate | No | 24000 | Frequenza di campionamento |
bit_rate | No | 128000 | Bitrate (solo MP3) |
URL di connessione completo
wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3&sample_rate=24000
Apertura della connessione
In JavaScript (browser o Node.js)
const ws = new WebSocket(
"wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3",
{
headers: {
"Authorization": `Bearer ${API_KEY}`
}
}
);
ws.onopen = () => {
console.log("Connessione TTS stabilita");
};
ws.onerror = (error) => {
console.error("Errore WebSocket:", error);
};
Importante: nel browser, l’API WebSocket nativa non supporta gli header personalizzati. Dovrai passare attraverso il tuo backend per la connessione (vedi la lezione sulla produzione).
In Python con websockets
import asyncio
import websockets
import json
async def connect_tts():
uri = "wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3"
headers = {"Authorization": f"Bearer {api_key}"}
async with websockets.connect(uri, additional_headers=headers) as ws:
print("Connessione TTS stabilita")
# Invia testo e ricevi audio...
Gestione della sessione
Durata
La pagina Text to Speech di xAI indica due cose che devi leggere insieme: la connessione WebSocket non ha un timeout di richiesta (rimane aperta) e il “permesso di sessione” ha una durata di 600 secondi, senza che la pagina spieghi cosa succede alla scadenza. Per sicurezza, la tua applicazione dovrebbe:
- Rilevare quando la connessione si chiude
- Riconnettersi automaticamente se necessario
- Riprendere l’invio del testo da dove si era interrotto
Sessioni concorrenti
Secondo la pagina Text to Speech, il tuo team è limitato a 50 sessioni WebSocket concorrenti (la pagina Rate limits conteggia le sessioni TTS per livello, a partire da 100). Oltre questo limite, le nuove connessioni vengono rifiutate. Gestisci un pool di connessioni per le applicazioni ad alto traffico.
Più testi su una singola connessione
A differenza della modalità HTTP unaria, dove le richieste scadono dopo 15 minuti, la connessione rimane aperta dopo ogni audio.done: puoi inviare un testo dopo l’altro senza riconnetterti e annullare quello corrente con text.clear (lezione 10).
HTTP unario versus WebSocket
| Aspetto | HTTP unario | WebSocket |
|---|---|---|
| Latenza | Audio completo dopo l’elaborazione | Primi byte immediati |
| Testo max | 60.000 caratteri per richiesta | Illimitato (delta max di 60.000) |
| Timeout | 15 minuti | Nessuno; permesso di sessione di 600 secondi |
| Sessioni | N/D | 50 per team |
| Casi d’uso | Batch, file audio | Tempo reale, streaming |
Quando usare WebSocket
WebSocket è la scelta obbligata non appena entra in gioco il tempo reale. Quando un utente attende una risposta vocale immediata da un chatbot o un assistente vocale, ogni secondo di silenzio prima del primo suono costa in termini di esperienza percepita; WebSocket permette di avviare la riproduzione sui primi frammenti audio, prima ancora che la generazione sia terminata. È anche l’architettura naturale quando il testo stesso arriva gradualmente: l’output in streaming di un LLM si collega direttamente al TTS, delta per delta, senza attendere il testo completo. Inoltre, rimuove il vincolo di lunghezza: non c’è alcun limite globale sul testo totale, solo i singoli delta sono limitati a 60.000 caratteri, sufficienti per vocalizzare un intero documento come flusso continuo.
La modalità HTTP unaria ha ancora il suo posto ovunque il tempo reale non aggiunga valore: generazione di file audio in batch, processi che necessitano del file completo prima di agire (post-elaborazione, archiviazione, invio) e, più semplicemente, qualsiasi architettura che preferisca un round trip stateless alla gestione di una connessione persistente.
Punti chiave
- TTS WebSocket è disponibile all’indirizzo
wss://api.x.ai/v1/tts - I parametri vanno nella query string al momento della connessione
- La connessione non scade da sola, ma la documentazione menziona un permesso di sessione di 600 secondi: pianifica la riconnessione
- Il limite è di 50 sessioni concorrenti per team
- Il testo è illimitato (inviato in delta fino a 60.000 caratteri)
- Usa WebSocket per il tempo reale, HTTP per i batch