Streaming TTS su WebSocket
In questa pagina
Aggiornato il 3 novembre 2026, sulla base della pagina Text to Speech di xAI. Fonte: Text to Speech.
Perché lo streaming cambia l’esperienza
In modalità HTTP, il TTS restituisce il controllo solo dopo aver prodotto tutto l’audio. Per una notifica di due frasi, nessuno nota l’attesa. Per un post di un blog, un capitolo di un libro o un feed di notizie a scorrimento continuo, quell’attesa diventa il difetto più grande del tuo prodotto: gli utenti cliccano, poi fissano un indicatore di caricamento per diversi secondi.
La modalità WebSocket elimina quell’attesa inviando l’audio man mano che viene sintetizzato. La riproduzione inizia dalle prime parole mentre la fine del testo non è ancora stata elaborata. Questa è la differenza tra una pagina che sembra bloccata e un audio che parte immediatamente.
Aprire la connessione
La connessione si apre su wss://api.x.ai/v1/tts e tutta la configurazione va nella stringa di query dell’URL, non in un messaggio di inizializzazione.
const ws = new WebSocket(
"wss://api.x.ai/v1/tts?language=en&voice=ara&codec=mp3&sample_rate=24000",
{
headers: {
"Authorization": "Bearer " + XAI_API_KEY
}
}
);
Ecco i parametri accettati:
- language (obbligatorio): un codice BCP-47 o
auto - voice (opzionale, predefinito:
eve): l’ID della voce - codec (opzionale, predefinito:
mp3): il formato audio di output - sample_rate (opzionale, predefinito:
24000): la frequenza di campionamento in Hz - bit_rate (opzionale, predefinito:
128000): il bitrate in bps (solo MP3)
Queste impostazioni valgono per l’intera sessione: non puoi cambiare voce o codec durante il percorso. Se la tua app deve alternare due narratori, apri due connessioni.
Il protocollo dei messaggi
Lato invio, ti servono solo due messaggi per guidare la sintesi. Il primo invia un blocco di testo; il secondo annuncia che il testo è completo.
{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }
Puoi inviare quanti messaggi text.delta desideri, ognuno fino a 60.000 caratteri. Tuttavia, è meglio non saturare quel limite: dividere il testo in blocchi di poche frasi ti fa arrivare il primo chunk audio molto prima, che è proprio lo scopo dello streaming. Un singolo delta di diverse migliaia di caratteri ti riporta al comportamento della modalità HTTP.
Lato ricezione, ogni audio.delta trasporta un frammento di audio codificato in base64, nel codec impostato alla connessione. Decodificalo e aggiungilo al tuo buffer di riproduzione.
{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }
L’evento audio.done segna la fine della sintesi. Il suo trace_id è l’identificativo da fornire al supporto o da registrare nei tuoi log quando una generazione non funziona correttamente. Se il testo non è valido o hai superato la tua quota, ricevi invece un messaggio di errore.
{ "type": "error", "message": "description of the error" }
Un’implementazione completa
L’esempio seguente divide un testo lungo in paragrafi, li invia tutti, quindi assembla i frammenti audio ricevuti in un file MP3.
const WebSocket = require("ws");
const fs = require("fs");
const ws = new WebSocket(
"wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3",
{ headers: { "Authorization": "Bearer " + process.env.XAI_API_KEY } }
);
const audioChunks = [];
ws.on("open", () => {
const paragraphs = longText.split("\n\n");
for (const para of paragraphs) {
ws.send(JSON.stringify({
type: "text.delta",
delta: para + " "
}));
}
ws.send(JSON.stringify({ type: "text.done" }));
});
ws.on("message", (data) => {
const msg = JSON.parse(data);
if (msg.type === "audio.delta") {
audioChunks.push(Buffer.from(msg.delta, "base64"));
} else if (msg.type === "audio.done") {
fs.writeFileSync("output.mp3", Buffer.concat(audioChunks));
ws.close();
}
});
Nota il para + " ": senza quello spazio, la fine di un paragrafo si fonde con l’inizio del successivo e il motore legge le due parole insieme senza pausa.
Limiti da conoscere
| Metrica | Valore |
|---|---|
| Testo per delta | Max 60.000 caratteri |
| Testo totale | Illimitato |
| Sessioni concurrenti | 50 per team |
| Permesso sessione | 600 secondi |
| Timeout connessione | Nessuno |
La pagina di xAI afferma che la connessione non ha timeout e menziona separatamente un “permesso sessione” di 600 secondi senza spiegare cosa accade quando scade. Per sicurezza, connettiti quando hai testo da inviare, non al caricamento della pagina, e prevedi una riconnessione. Gestisci allo stesso modo il limite di 50 sessioni concurrenti per team: una libreria audio che converte il suo catalogo in background dovrebbe mettere in coda i suoi job invece di aprire duecento connessioni in parallelo.
HTTP o WebSocket
La modalità HTTP rimane la scelta giusta per testi brevi, generazioni una tantum e ovunque la semplicità di integrazione sia prioritaria: una richiesta, una risposta, nessuno stato da gestire. WebSocket è la strada da percorrere quando il testo diventa lungo, quando l’audio deve essere riprodotto mentre viene prodotto, o quando il contenuto stesso arriva come stream, tipicamente l’output di un modello linguistico che dai voce mentre genera.
Punti chiave
- Il TTS su WebSocket ti permette di ricevere audio in streaming senza attendere la fine della generazione
- I parametri di configurazione vanno nella stringa di query dell’URL di connessione
- Il protocollo è semplice:
text.deltaper inviare testo,audio.deltaper ricevere audio - Le sessioni WebSocket sono limitate a 50 concurrenti per team; prevedi la riconnessione
- Preferisci WebSocket per testi lunghi ed esperienze di ascolto in tempo reale