Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

WebSocket-berichten: tekst en audio

Les 10 van 14 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Het TTS-berichtprotocol
  2. Berichten van client naar server
  3. Berichten van server naar client
  4. De volledige communicatiestroom
  5. Volledige implementatie in Python
  6. Implementatie in JavaScript (Node.js)
  7. Omgaan met meerdere delta’s
  8. Belangrijkste punten

Bijgewerkt op 3 november 2026, gebaseerd op de xAI-pagina Text to Speech: delta’s tot 60.000 tekens, annulering (text.clear, audio.clear) en de uitspraaktabel (session.update, session.updated). Bron: Text to Speech.

Het TTS-berichtprotocol

Zodra de WebSocket-verbinding tot stand is gebracht, verloopt de communicatie via de uitwisseling van JSON-berichten. U verzendt tekst en de server antwoordt met base64-gecodeerde audio. Inzicht in dit protocol is essentieel voor een correcte implementatie van TTS-streaming.

Berichten van client naar server

Uw applicatie verzendt vier soorten berichten naar de server: text.delta en text.done voor tekst, text.clear om te annuleren, en session.update om te configureren.

text.delta: een tekstfragment verzenden

Het bericht text.delta verzendt een fragment van de te converteren tekst. U kunt de tekst in opeenvolgende stukken verzenden:

{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}

Elke delta kan maximaal 60.000 tekens bevatten, terwijl er geen limiet is op de totale tekstlengte. De server begint met het genereren van audio zodra er voldoende context is voor een natuurlijke uitspraak.

text.done: het einde van de tekst signaleren

Het bericht text.done informeert de server dat u klaar bent met het verzenden van tekst voor deze reeks:

{"type": "text.done"}

Zodra de server dit bericht ontvangt, voltooit deze de audiogeneratie en verzendt een audio.done-bericht. Vervolgens kunt u nieuwe delta’s starten voor een volgende reeks.

text.clear: de huidige reeks annuleren

text.clear annuleert de huidige reeks: de server stopt met het genereren van audio, verwijdert de gegevens uit het geheugen en antwoordt met audio.clear. De verbinding is direct weer gereed voor de volgende reeks, zonder nieuwe WebSocket-handshake; xAI schat de besparing voor een externe client op ongeveer 600 ms. Dit is het interruptiemechanisme (“barge-in”) voor wanneer de gebruiker onderbreekt.

{"type": "text.clear"}

session.update: uitspraak corrigeren

session.update installeert of vervangt de replace-tabel van de verbinding: elke zin die in de tekst wordt gevonden, wordt vervangen door de gesproken vorm vóór de synthese, zonder dat de verzonden tekst of het aantal gefactureerde tekens verandert. Verzend dit bericht vóór de eerste text.delta zodat het de hele verbinding bestrijkt; een update die midden in een reeks wordt ontvangen, geldt pas vanaf de volgende reeks.

{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}

Berichten van server naar client

De server antwoordt met vijf soorten berichten: audio.delta, audio.done en error (hieronder toegelicht), plus audio.clear ter bevestiging van een annulering, en session.updated dat de actieve replace-tabel retourneert.

audio.delta: een audiofragment

Het bericht audio.delta bevat een base64-gecodeerd audiofragment:

{
  "type": "audio.delta",
  "delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}

Elke delta is een geldig audiofragment dat u direct kunt decoderen en afspelen. Delta’s arriveren naarmate de generatie vordert.

audio.done: generatie voltooid

Het bericht audio.done geeft aan dat alle audio voor de verzonden tekstreeks is gegenereerd:

{
  "type": "audio.done",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

De trace_id is een unieke ID voor de reeks, nuttig voor debugging en tracking.

error: er is een fout opgetreden

Als er iets misgaat, verzendt de server een foutbericht:

{
  "type": "error",
  "message": "Invalid text encoding"
}

De volledige communicatiestroom

Zo ziet een typische sessie eruit:

Client                          Server
  |                                |
  |-- text.delta ("Hello, ") ----->|
  |-- text.delta ("how are ") ---->|
  |-- text.delta ("you?") -------->|
  |<-- audio.delta (chunk 1) -----|
  |<-- audio.delta (chunk 2) -----|
  |-- text.done ----------------->|
  |<-- audio.delta (chunk 3) -----|
  |<-- audio.done ----------------|

De server kan audio.delta-berichten verzenden nog voordat u text.done hebt gestuurd. Dat is precies het idee van streaming: de generatie start zo snel mogelijk.

Volledige implementatie in Python

import asyncio
import websockets
import json
import base64

async def stream_tts(api_key, text, voice="eve", language="en"):
    uri = f"wss://api.x.ai/v1/tts?language={language}&voice={voice}&codec=mp3"
    headers = {"Authorization": f"Bearer {api_key}"}

    audio_chunks = []

    async with websockets.connect(uri, additional_headers=headers) as ws:
        # Verzend de tekst in stukken van 2.000 tekens
        chunk_size = 2000
        for i in range(0, len(text), chunk_size):
            chunk = text[i:i + chunk_size]
            await ws.send(json.dumps({
                "type": "text.delta",
                "delta": chunk
            }))

        # Signaleer het einde van de tekst
        await ws.send(json.dumps({"type": "text.done"}))

        # Ontvang de audiofragmenten
        async for message in ws:
            data = json.loads(message)

            if data["type"] == "audio.delta":
                audio_bytes = base64.b64decode(data["delta"])
                audio_chunks.append(audio_bytes)

            elif data["type"] == "audio.done":
                print(f"Generation finished (trace: {data['trace_id']})")
                break

            elif data["type"] == "error":
                raise Exception(f"TTS error: {data['message']}")

    # Stel de volledige audio samen
    return b"".join(audio_chunks)

Implementatie in JavaScript (Node.js)

const WebSocket = require("ws");

function streamTTS(apiKey, text, voice = "eve", language = "en") {
  return new Promise((resolve, reject) => {
    const ws = new WebSocket(
      `wss://api.x.ai/v1/tts?language=${language}&voice={voice}&codec=mp3`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );

    const audioChunks = [];

    ws.on("open", () => {
      // Verzend de tekst
      ws.send(JSON.stringify({ type: "text.delta", delta: text }));
      ws.send(JSON.stringify({ type: "text.done" }));
    });

    ws.on("message", (raw) => {
      const data = JSON.parse(raw);

      if (data.type === "audio.delta") {
        audioChunks.push(Buffer.from(data.delta, "base64"));
      } else if (data.type === "audio.done") {
        ws.close();
        resolve(Buffer.concat(audioChunks));
      } else if (data.type === "error") {
        ws.close();
        reject(new Error(data.message));
      }
    });

    ws.on("error", reject);
  });
}

Omgaan met meerdere delta’s

Voor tekst die progressief wordt gegenereerd (bijvoorbeeld de output van een LLM), verzendt u elke token direct naar de TTS-WebSocket:

async def llm_to_speech(ws_tts, llm_stream):
    async for token in llm_stream:
        await ws_tts.send(json.dumps({
            "type": "text.delta",
            "delta": token
        }))

    await ws_tts.send(json.dumps({"type": "text.done"}))

Deze architectuur, waarbij een streaming LLM wordt gekoppeld aan streaming TTS, biedt de laagst mogelijke latentie: de gebruiker hoort het antwoord terwijl de LLM nog bezig is met genereren.

Belangrijkste punten

  • Vier clientberichten: text.delta (tekst verzenden), text.done (einde tekst), text.clear (annuleren) en session.update (replace-tabel)
  • Vijf serverberichten: audio.delta (audiofragment), audio.done (einde), audio.clear (annulering bevestigd), session.updated en error
  • Audio is base64-gecodeerd in audio.delta-berichten
  • De server start met genereren voordat text.done is ontvangen
  • Elke tekstdelta is beperkt tot 60.000 tekens
  • Het koppelen van een streaming LLM aan streaming TTS resulteert in de laagste latentie