WebSocket-viestit: teksti ja ääni
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI:n Text to Speech -sivun perusteella: deltat jopa 60 000 merkkiä, peruutus (
text.clear,audio.clear) ja ääntämistaulukko (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) jasession.update(replace-taulukko) - Viisi palvelinviestiä:
audio.delta(äänenpätkä),audio.done(loppu),audio.clear(peruutus vahvistettu),session.updatedjaerror - Ää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