Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

WebSocket-viestit: teksti ja ääni

Oppitunti 10 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. TTS-viestikäytäntö
  2. Asiakkaalta palvelimelle -viestit
  3. Palvelimelta asiakkaalle -viestit
  4. Koko viestintäkulku
  5. Täydellinen toteutus Pythonilla
  6. Toteutus JavaScriptillä (Node.js)
  7. Useiden deltojen käsittely
  8. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Text to Speech -sivun perusteella: deltat jopa 60 000 merkkiä, peruutus (text.clear, audio.clear) ja ääntämis­taulukko (session.update, session.updated). Lähde: Text to Speech.

TTS-viestikäytäntö

Kun WebSocket-yhteys on avattu, viestintä tapahtuu JSON-viestejä vaihtamalla. Lähetät tekstiä, ja palvelin vastaa base64-koodatulla äänellä. Tämän käytännön ymmärtäminen on välttämätöntä, jotta voit toteuttaa TTS-suoratoiston oikein.

Asiakkaalta palvelimelle -viestit

Sovelluksesi lähettää palvelimelle neljää viestityyppiä: text.delta ja text.done tekstille, text.clear peruutukseen ja session.update asetusten määrittämiseen.

text.delta: lähetä tekstinpätkä

text.delta-viesti lähettää muunnettavan tekstinpätkän. Voit lähettää tekstin useissa osissa:

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

Jokainen delta voi sisältää jopa 60 000 merkkiä, eikä koko tekstin pituudelle ole rajoitusta. Palvin aloittaa äänen tuottamisen heti, kun sillä on tarpeeksi kontekstia luonnollisen ääntämisen muodostamiseen.

text.done: ilmoita tekstin päättyminen

text.done-viesti kertoo palvelimelle, että olet lopettanut tekstin lähettämisen tälle jaksolle:

{"type": "text.done"}

Kun palvelin vastaanottaa tämän viestin, se viimeistelee äänen tuottamisen ja lähettää audio.done-viestin. Tämän jälkeen voit aloittaa uusien deltojen lähettämisen uutta jaksoa varten.

text.clear: peruuta nykyinen jakso

text.clear peruuttaa nykyisen jakson: palvelin lopettaa äänen tuottamisen, hylkää muistissaan olevat tiedot ja vastaa viestillä audio.clear. Yhteys on heti valmis seuraavaa jaksoa varten ilman uutta WebSocket-kättelyä; xAI arvioi säästön olevan noin 600 ms etäasiakkaalle. Tämä on keskeytysmekanismi (“barge-in”) tilanteisiin, joissa käyttäjä puuttuu puheeseen.

{"type": "text.clear"}

session.update: korjaa ääntäminen

session.update asentaa tai korvaa yhteyden replace-taulukon: jokainen tekstistä löytyvä lauseke korvataan puhutulla muodolla ennen synteesiä muuttamatta lähettämääsi tekstiä tai laskutettavien merkkien määrää. Lähetä tämä ennen ensimmäistä text.delta-viestiä, jotta se kattaa koko yhteyden; keskellä jaksoa vastaanotettu päivitys koskee vasta seuraavaa jaksoa.

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

Palvelimelta asiakkaalle -viestit

Palvelin vastaa viidellä viestityypillä: audio.delta, audio.done ja error (käsitelty alla), sekä audio.clear, joka vahvistaa peruutuksen, ja session.updated, joka palauttaa voimassa olevan replace-taulukon.

audio.delta: äänenpätkä

audio.delta-viesti sisältää base64-koodatun äänenpätkän:

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

Jokainen delta on kelvollinen äänenpätkä, jonka voit purkaa ja toistaa heti. Deltat saapuvat tuotannon edetessä.

audio.done: tuotanto valmis

audio.done-viesti ilmoittaa, että kaikki lähettämäsi tekstijakson ääni on tuotettu:

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

trace_id on jakson yksilöllinen tunniste, joka on hyödyllinen vianetsinnässä ja seurannassa.

error: tapahtui virhe

Jos jotain menee pieleen, palvelin lähettää virheilmoituksen:

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

Koko viestintäkulku

Näin tyypillinen istunto etenee:

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

Palvelin voi aloittaa audio.delta-viestien lähettämisen ennen kuin olet edes lähettänyt text.done-viestin. Siinä juuri piilee suoratoiston idea: tuotanto alkaa niin pian kuin mahdollista.

Täydellinen toteutus Pythonilla

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:
        # Lähetä teksti 2 000 merkin paloissa
        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
            }))

        # Ilmoita tekstin päättyminen
        await ws.send(json.dumps({"type": "text.done"}))

        # Vastaanota äänenpätkät
        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']}")

    # Kokoa koko ääni
    return b"".join(audio_chunks)

Toteutus JavaScriptillä (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", () => {
      // Lähetä teksti
      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);
  });
}

Useiden deltojen käsittely

Kun tekstiä tuotetaan vähitellen (esimerkiksi LLM:n tuloste), lähetä jokainen token suoraan TTS-WebSocketiin:

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"}))

Tämä “suoratoista LLM suoratoistaiseen TTS:ään” -arkkitehtuuri tarjoaa pienimmän mahdollisen viiveen: käyttäjä kuulee vastauksen samalla kun LLM vielä tuottaa sitä.

Keskeiset asiat

  • Neljä asiakasviestiä: text.delta (lähetä teksti), text.done (tekstin loppu), text.clear (peruuta) ja session.update (replace-taulukko)
  • Viisi palvelinviestiä: audio.delta (äänenpätkä), audio.done (loppu), audio.clear (peruutus vahvistettu), session.updated ja error
  • Ääni on base64-koodattu audio.delta-viesteissä
  • Palvelin aloittaa tuottamisen ennen kuin se vastaanottaa text.done-viestin
  • Jokainen tekstidelta on rajoitettu 60 000 merkkiin
  • Suoratoistavan LLM:n ketjuttaminen suoratoistavaan TTS:ään antaa pienimmän viiveen