Ροή TTS μέσω WebSocket
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 3 Νοεμβρίου 2026, με βάση τη σελίδα Text to Speech της xAI. Πηγή: Text to Speech.
Γιατί η ροή αλλάζει την εμπειρία
Στη λειτουργία HTTP, το TTS επιστρέφει τον έλεγχο μόνο αφού παραχθεί όλο το αρχείο ήχου. Για μια ειδοποίηση δύο προτάσεων, κανείς δεν αντιλαμβάνεται την αναμονή. Για μια ανάρτηση σε blog, ένα κεφάλαιο βιβλίου ή μια συνεχώς κυλιόμενη ροή ειδήσεων, η αναμονή γίνεται το μεγαλύτερο ελάττωμα του προϊόντος σας: οι χρήστες κάνουν κλικ και στη συνέχεια κοιτούν έναν δείκτη φόρτωσης για αρκετά δευτερόλεπτα.
Η λειτουργία WebSocket καταργεί αυτή την αναμονή, προωθώντας τον ήχο μόλις συντίθεται. Η αναπαραγωγή ξεκινά με τις πρώτες λέξεις, ενώ το τέλος του κειμένου δεν έχει ακόμη υποστεί επεξεργασία. Αυτή είναι η διαφορά μεταξύ μιας σελίδας που φαίνεται παγωμένη και ήχου που παίζει αμέσως.
Άνοιγμα της σύνδεσης
Η σύνδεση ανοίγει στο wss://api.x.ai/v1/tts και όλες οι ρυθμίσεις τοποθετούνται στη συμβολοσειρά ερωτήματος (query string) του URL, αντί σε ένα μήνυμα αρχικοποίησης.
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
}
}
);
Αυτές είναι οι αποδεκτές παράμετροι:
- language (απαιτείται): ένας κώδικας BCP-47 ή
auto - voice (προαιρετικό, προεπιλογή:
eve): το αναγνωριστικό της φωνής - codec (προαιρετικό, προεπιλογή:
mp3): η μορφή εξόδου ήχου - sample_rate (προαιρετικό, προεπιλογή:
24000): ο ρυθμός δειγματοληψίας σε Hz - bit_rate (προαιρετικό, προεπιλογή:
128000): ο ρυθμός bit σε bps (μόνο για MP3)
Αυτές οι ρυθμίσεις ισχύουν για ολόκληρη τη συνεδρία: δεν μπορείτε να αλλάξετε τη φωνή ή τον κωδικοποιητή στη διάρκεια της διαδικασίας. Εάν η εφαρμογή σας χρειάζεται να εναλλάσσεται μεταξύ δύο αφηγητών, ανοίξτε δύο συνδέσεις.
Το πρωτόκολλο μηνυμάτων
Στην πλευρά αποστολής, χρειάζεστε μόνο δύο μηνύματα για να οδηγήσετε τη σύνθεση. Το πρώτο στέλνει ένα τμήμα κειμένου· το δεύτερο ανακοινώνει ότι το κείμενο έχει ολοκληρωθεί.
{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }
Μπορείτε να στείλετε όσα μηνύματα text.delta χρειάζεστε, καθένα έως 60.000 χαρακτήρες. Ωστόσο, είναι προτιμότερο να μην φτάνετε σε αυτό το όριο: η διαίρεση του κειμένου σε τμήματα μερικών προτάσεων σας παραδίδει το πρώτο τμήμα ήχου πολύ νωρίτερα, κάτι που αποτελεί τον κύριο σκοπό της ροής. Ένα ενιαίο delta several χιλιάδων χαρακτήρων σας επαναφέρει στη συμπεριφορά της λειτουργίας HTTP.
Στην πλευρά λήψης, κάθε audio.delta μεταφέρει ένα θραύσμα ήχου κωδικοποιημένο σε base64, στον κωδικοποιητή που ορίσατε κατά τη σύνδεση. Αποκωδικοποιήστε το και προσαρτήστε το στο buffer αναπαραγωγής σας.
{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }
Το συμβάν audio.done σηματοδοτεί το τέλος της σύνθεσης. Το trace_id του είναι το αναγνωριστικό που πρέπει να δώσετε στην υποστήριξη ή να καταγράψετε στα αρχεία καταγραφής (logs) σας, όταν μια δημιουργία παρουσιάζει δυσλειτουργία. Εάν το κείμενο είναι άκυρο ή έχετε υπερβεί την ποσόσωσή σας, θα λάβετε αντίθετα ένα μήνυμα σφάλματος.
{ "type": "error", "message": "description of the error" }
Μια πλήρης υλοποίηση
Το παρακάτω παράδειγμα διαιρεί ένα μεγάλο κείμενο σε παραγράφους, τις στέλνει όλες και στη συνέχεια συναρμολογεί τα θραύσματα ήχου που λαμβάνει σε ένα αρχείο MP3.
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();
}
});
Σημειώστε το para + " ": χωρίς αυτόν τον χώρο, το τέλος μιας παραγράφου ενώνεται με την αρχή της επόμενης και η μηχανή διαβάζει τις δύο λέξεις μαζί χωρίς ανάσα.
Όρια που πρέπει να γνωρίζετε
| Μετρική | Τιμή |
|---|---|
| Κείμενο ανά delta | Μέγιστο 60.000 χαρακτήρες |
| Συνολικό κείμενο | Απεριόριστο |
| Ταυτόχρονες συνεδρίες | 50 ανά ομάδα |
| Άδεια συνεδρίας | 600 δευτερόλεπτα |
| Χρονικό όριο σύνδεσης | Κανένα |
Η σελίδα της xAI αναφέρει ότι η σύνδεση δεν έχει χρονικό όριο λήξης, ενώ ξεχωριστά αναφέρει μια «άδεια συνεδρίας» 600 δευτερολέπτων χωρίς να εξηγεί τι συμβαίνει όταν αυτή εξαντλείται. Για ασφάλεια, συνδέεστε όταν έχετε κείμενο προς αποστολή και όχι όταν φορτώνει η σελίδα, και σχεδιάστε την επανασύνδεση. Αντιμετωπίστε το όριο των 50 ταυτόχρονων συνεδριών ανά ομάδα με τον ίδιο τρόπο: μια βιβλιοθήκη ήχου που μετατρέπει τον κατάλογό της στο παρασκήνιο θα πρέπει να θέτει τις εργασίες της σε ουρά, αντί να ανοίγει διακόσιες συνδέσεις παράλληλα.
HTTP ή WebSocket
Η λειτουργία HTTP παραμένει η σωστή επιλογή για σύντομα κείμενα, μεμονωμένες δημιουργίες και οπουδήποτε η απλότητα της ενσωμάτωσης έχει τη μεγαλύτερη σημασία: ένα αίτημα, μία απόκριση, χωρίς κατάσταση προς διαχείριση. Το WebSocket είναι η ενδεδειγμένη λύση όταν το κείμενο γίνεται μεγάλο, όταν ο ήχος πρέπει να παίζει ενώ παράγεται, ή όταν το ίδιο το περιεχόμενο φτάνει ως ροή, τυπικά η έξοδος ενός γλωσσικού μοντέλου που εκφωνείτε καθώς παράγεται.
Βασικά σημεία
- Το TTS μέσω WebSocket σας επιτρέπει να λαμβάνετε ροή ήχου χωρίς να περιμένετε την ολοκλήρωση της δημιουργίας
- Οι παράμετροι διαμόρφωσης τοποθετούνται στη συμβολοσειρά ερωτήματος του URL σύνδεσης
- Το πρωτόκολλο είναι απλό:
text.deltaγια αποστολή κειμένου,audio.deltaγια λήψη ήχου - Οι συνεδρίες WebSocket περιορίζονται σε 50 ταυτόχρονες ανά ομάδα· σχεδιάστε την επανασύνδεση
- Προτιμήστε το WebSocket για μεγάλα κείμενα και εμπειρίες ακρόασης σε πραγματικό χρόνο