Μηνύματα WebSocket: κείμενο και ήχος
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 3 Νοεμβρίου 2026, με βάση τη σελίδα Text to Speech της xAI: διαφορές (deltas) έως 60.000 χαρακτήρες, ακύρωση (
text.clear,audio.clear) και πίνακας προφοράς (session.update,session.updated). Πηγή: Text to Speech.
Το πρωτόκολλο μηνυμάτων TTS
Μόλις ανοίξει η σύνδεση WebSocket, η επικοινωνία λειτουργεί μέσω ανταλλαγής μηνυμάτων JSON. Εσείς στέλνετε κείμενο και ο διακομιστής απαντά με ήχο κωδικοποιημένο σε base64. Η κατανόηση αυτού του πρωτοκόλλου είναι απαραίτητη για τη σωστή υλοποίηση της ροής TTS.
Μηνύματα από τον πελάτη προς τον διακομιστή
Η εφαρμογή σας στέλνει τέσσερις τύπους μηνυμάτων στον διακομιστή: text.delta και text.done για το κείμενο, text.clear για ακύρωση και session.update για διαμόρφωση.
text.delta: αποστολή τμήματος κειμένου
Το μήνυμα text.delta στέλνει ένα τμήμα κειμένου προς μετατροπή. Μπορείτε να στείλετε το κείμενο σε διαδοχικά κομμάτια:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Κάθε delta μπορεί να περιέχει έως 60.000 χαρακτήρες, ενώ το συνολικό κείμενο δεν έχει όριο. Ο διακομιστής ξεκινά τη δημιουργία ήχου μόλις διαθέτει αρκετό πλαίσιο για να παράγει φυσική προφορά.
text.done: σήμα τέλους κειμένου
Το μήνυμα text.done ενημερώνει τον διακομιστή ότι ολοκληρώσατε την αποστολή κειμένου για αυτή την ακολουθία:
{"type": "text.done"}
Μόλις λάβει αυτό το μήνυμα, ο διακομιστής ολοκληρώνει τη δημιουργία του ήχου και στέλνει ένα μήνυμα audio.done. Στη συνέχεια, μπορείτε να ξεκινήσετε την αποστολή νέων deltas για μια νέα ακολουθία.
text.clear: ακύρωση της τρέχουσας ακολουθίας
Το text.clear ακυρώνει την τρέχουσα ακολουθία: ο διακομιστής σταματά τη δημιουργία ήχου, απορρίπτει ό,τι είχε στη μνήμη και απαντά με audio.clear. Η σύνδεση είναι άμεσα έτοιμη για την επόμενη ακολουθία, χωρίς νέο handshake WebSocket· η xAI εκτιμά την εξοικονόμηση σε περίπου 600 ms για έναν απομακρυσμένο πελάτη. Πρόκειται για τον μηχανισμό διακοπής («barge-in») όταν ο χρήστης παρεμβαίνει.
{"type": "text.clear"}
session.update: διόρθωση προφοράς
Το session.update εγκαθιστά ή αντικαθιστά τον πίνακα replace της σύνδεσης: κάθε φράση που βρίσκεται στο κείμενο αντικαθίσταται από την προφορική της μορφή πριν από τη σύνθεση, χωρίς να αλλάζει το κείμενο που στέλνετε ή ο αριθμός των χαρακτήρων για τους οποίους χρεώνεστε. Στείλτε το πριν από το πρώτο text.delta ώστε να καλύπτει ολόκληρη τη σύνδεση· μια ενημέρωση που λαμβάνεται κατά τη διάρκεια μιας ακολουθίας ισχύει μόνο από την επόμενη ακολουθία.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Μηνύματα από τον διακομιστή προς τον πελάτη
Ο διακομιστής απαντά με πέντε τύπους μηνυμάτων: audio.delta, audio.done και error, τα οποία αναλύονται παρακάτω, καθώς και audio.clear, που επιβεβαιώνει μια ακύρωση, και session.updated, που επιστρέφει τον ενεργό πίνακα replace.
audio.delta: ένα τμήμα ήχου
Το μήνυμα audio.delta περιέχει ένα τμήμα ήχου κωδικοποιημένο σε base64:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Κάθε delta αποτελεί ένα έγκυρο τμήμα ήχου που μπορείτε να αποκωδικοποιήσετε και να αναπαράγετε αμέσως. Τα deltas φτάνουν καθώς προχωρά η δημιουργία.
audio.done: ολοκλήρωση δημιουργίας
Το μήνυμα audio.done σηματοδοτεί ότι έχει δημιουργηθεί ολόκληρος ο ήχος για την ακολουθία κειμένου που στείλατε:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
Το trace_id είναι ένα μοναδικό αναγνωριστικό για την ακολουθία, χρήσιμο για αποσφαλμάτωση και παρακολούθηση.
error: συνέβη ένα σφάλμα
Εάν κάτι πάει στραβά, ο διακομιστής στέλνει ένα μήνυμα σφάλματος:
{
"type": "error",
"message": "Invalid text encoding"
}
Η πλήρης ροή επικοινωνίας
Ακολουθεί η τυπική εξέλιξη μιας συνεδρίας:
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 ----------------|
Ο διακομιστής μπορεί να ξεκινήσει την αποστολή μηνυμάτων audio.delta πριν καν στείλετε το text.done. Αυτή είναι ακριβώς η ιδέα της ροής: η δημιουργία ξεκινά το συντομότερο δυνατό.
Πλήρης υλοποίηση σε 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:
# Send the text in pieces of 2,000 characters
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
}))
# Signal the end of the text
await ws.send(json.dumps({"type": "text.done"}))
# Receive the audio pieces
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']}")
# Assemble the complete audio
return b"".join(audio_chunks)
Υλοποίηση σε 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", () => {
// Send the text
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);
});
}
Διαχείριση πολλών deltas
Για κείμενο που παράγεται προοδευτικά (για παράδειγμα, η έξοδος ενός LLM), στείλτε κάθε token απευθείας στο WebSocket TTS:
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"}))
Αυτή η αρχιτεκτονική «ροή LLM σε ροή TTS» προσφέρει τη χαμηλότερη δυνατή καθυστέρηση: ο χρήστης ακούει την απάντηση ενώ το LLM εξακολουθεί να παράγει περιεχόμενο.
Βασικά σημεία
- Τέσσερα μηνύματα πελάτη:
text.delta(αποστολή κειμένου),text.done(τέλος κειμένου),text.clear(ακύρωση) καιsession.update(πίνακαςreplace) - Πέντε μηνύματα διακομιστή:
audio.delta(τμήμα ήχου),audio.done(τέλος),audio.clear(επιβεβαίωση ακύρωσης),session.updatedκαιerror - Ο ήχος είναι κωδικοποιημένος σε base64 στα μηνύματα
audio.delta - Ο διακομιστής ξεκινά τη δημιουργία πριν λάβει το
text.done - Κάθε delta κειμένου περιορίζεται σε 60.000 χαρακτήρες
- Η σύνδεση μιας ροής LLM με μια ροή TTS προσφέρει τη χαμηλότερη καθυστέρηση