Streaming TTS via WebSocket
Op deze pagina
Bijgewerkt op 3 november 2026, gebaseerd op de xAI-pagina Text to Speech. Bron: Text to Speech.
Waarom streaming de ervaring verandert
In HTTP-modus geeft TTS de controle pas terug nadat alle audio is gegenereerd. Voor een melding van twee zinnen merkt niemand het wachten op. Voor een blogpost, een hoofdstuk uit een boek of een continu scrollende nieuwsfeed wordt dit wachten echter het grootste gebrek van uw product: gebruikers klikken en staren vervolgens enkele seconden naar een laadspinner.
De WebSocket-modus elimineert dit wachttijd door audio direct naar buiten te pushen terwijl deze wordt gesynthetiseerd. Het afspelen begint bij de eerste woorden, terwijl het einde van de tekst nog niet eens is verwerkt. Dat is het verschil tussen een pagina die bevroren lijkt en audio die direct wordt afgespeeld.
De verbinding openen
De verbinding wordt geopend op wss://api.x.ai/v1/tts. Alle configuratie gaat naar de query-string van de URL in plaats van naar een initialisatiebericht.
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
}
}
);
Dit zijn de geaccepteerde parameters:
- language (verplicht): een BCP-47-code of
auto - voice (optioneel, standaard:
eve): de voice-ID - codec (optioneel, standaard:
mp3): het uitvoeraudioformaat - sample_rate (optioneel, standaard:
24000): de samplefrequentie in Hz - bit_rate (optioneel, standaard:
128000): de bitsnelheid in bps (alleen MP3)
Deze instellingen gelden voor de hele sessie: u kunt de voice of codec niet halverwege wijzigen. Als uw app moet wisselen tussen twee vertellers, opent u twee verbindingen.
Het berichtprotocol
Aan de verzendkant heeft u slechts twee berichttypen nodig om de synthese aan te sturen. Het eerste verstuurt een tekstblok; het tweede kondigt aan dat de tekst voltooid is.
{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }
U kunt zoveel text.delta-berichten sturen als nodig is, elk tot maximaal 60.000 tekens. Het is echter beter om deze limiet niet te maximaliseren: door de tekst op te splitsen in brokken van enkele zinnen, ontvangt u het eerste audioblok veel sneller. Dat is immers het hele doel van streaming. Een enkele delta van enkele duizenden tekens brengt u terug bij het gedrag van de HTTP-modus.
Aan de ontvangstkant bevat elk audio.delta-bericht een fragment van base64-gecodeerde audio, in de codec die u bij het verbinden heeft ingesteld. Decodeer dit en voeg het toe aan uw afspeelbuffer.
{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }
De audio.done-gebeurtenis markeert het einde van de synthese. De bijbehorende trace_id is de identifier die u aan ondersteuning moet geven, of in uw logs moet vastleggen, als een generatie zich niet correct gedraagt. Als de tekst ongeldig is of als u uw quotum heeft overschreden, ontvangt u in plaats daarvan een foutbericht.
{ "type": "error", "message": "description of the error" }
Een volledige implementatie
Het onderstaande voorbeeld splitst een lange tekst in alinea’s, verzendt ze allemaal en assembleert de ontvangen audiofragmenten tot een MP3-bestand.
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();
}
});
Let op de para + " ": zonder die spatie loopt het einde van de ene alinea direct over in het begin van de volgende, waardoor de engine de twee woorden samen uitspreekt zonder ademhaling.
Bekende limieten
| Metriek | Waarde |
|---|---|
| Tekst per delta | Maximaal 60.000 tekens |
| Totale tekst | Onbeperkt |
| Gelijktijdige sessies | 50 per team |
| Sessietoestemming | 600 seconden |
| Time-out verbinding | Geen |
De xAI-pagina stelt dat de verbinding geen time-out heeft, en noemt apart een “sessietoestemming” van 600 seconden zonder uit te leggen wat er gebeurt wanneer deze verloopt. Verbind om veilig te zijn pas wanneer u tekst te verzenden heeft, in plaats van wanneer de pagina laadt, en houd rekening met opnieuw verbinden. Houd ook rekening met de limiet van 50 gelijktijdige sessies per team: een audiobibliotheek die zijn catalogus op de achtergrond converteert, moet zijn taken in de wachtrij zetten in plaats van tweehonderd verbindingen parallel te openen.
HTTP of WebSocket
De HTTP-modus blijft de juiste keuze voor korte teksten, eenmalige generaties en situaties waarin integratiegemak het belangrijkst is: één verzoek, één antwoord, geen status om te beheren. WebSocket is de aangewezen weg zodra de tekst lang wordt, wanneer de audio moet worden afgespeeld terwijl deze wordt geproduceerd, of wanneer de inhoud zelf als stream binnenkomt, typisch de output van een taalmodel dat u van stem voorziet terwijl het genereert.
Belangrijkste punten
- Met WebSocket TTS ontvangt u gestreamde audio zonder te wachten tot de generatie voltooid is
- Configuratieparameters gaan naar de query-string van de verbindings-URL
- Het protocol is eenvoudig:
text.deltaom tekst te verzenden,audio.deltaom audio te ontvangen - WebSocket-sessies zijn beperkt tot 50 gelijktijdig per team; houd rekening met opnieuw verbinden
- Geef de voorkeur aan WebSocket voor lange teksten en realtime luisterervaringen