Strumieniowanie TTS przez WebSocket
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie strony xAI Text to Speech. Źródło: Text to Speech.
Dlaczego strumieniowanie zmienia doświadczenie użytkownika
W trybie HTTP usługa TTS zwraca kontrolę dopiero po wygenerowaniu całego dźwięku. Przy dwuzdaniowym powiadomieniu nikt nie zauważy oczekiwania. Jednak w przypadku wpisu na bloga, rozdziału książki czy ciągle przewijanego serwisu informacyjnego czas oczekiwania staje się największą wadą Twojego produktu: użytkownicy klikają, a potem przez kilka sekund wpatrują się w wirujący wskaźnik ładowania.
Tryb WebSocket eliminuje to opóźnienie, wypychając dźwięk w miarę jego syntezy. Odtwarzanie zaczyna się od pierwszych słów, zanim koniec tekstu zostanie jeszcze przetworzony. To właśnie różnica między stroną, która wydaje się zawieszona, a dźwiękiem, który odtwarza się natychmiast.
Nawiązywanie połączenia
Połączenie otwierasz na adresie wss://api.x.ai/v1/tts, a całą konfigurację umieszczasz w ciągu zapytania URL, a nie w wiadomości inicjalizacyjnej.
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
}
}
);
Oto akceptowane parametry:
- language (wymagane): kod BCP-47 lub
auto - voice (opcjonalne, domyślnie:
eve): identyfikator głosu - codec (opcjonalne, domyślnie:
mp3): format wyjściowy dźwięku - sample_rate (opcjonalne, domyślnie:
24000): częstotliwość próbkowania w Hz - bit_rate (opcjonalne, domyślnie:
128000): szybkość transmisji bitów w bps (tylko MP3)
Ustawienia te obowiązują przez całą sesję: nie możesz zmienić głosu ani kodeku w jej trakcie. Jeśli Twoja aplikacja musi przeplatać dwóch narratorów, otwórz dwa osobne połączenia.
Protokół wiadomości
Po stronie nadawczej potrzebujesz tylko dwóch typów wiadomości, aby sterować syntezą. Pierwsza wysyła fragment tekstu, druga ogłasza jego zakończenie.
{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }
Możesz wysłać tyle wiadomości text.delta, ile potrzebujesz, każda o długości do 60 000 znaków. Warto jednak nie wykorzystywać tego limitu do maksimum: podział tekstu na fragmenty liczące kilka zdań sprawia, że pierwszy fragment dźwięku dotrze do Ciebie znacznie szybciej, a o to właśnie chodzi w strumieniowaniu. Pojedynczy delta liczący kilka tysięcy znaków cofnie Cię do zachowania charakterystycznego dla trybu HTTP.
Po stronie odbiorczej każde audio.delta niesie fragment dźwięku zakodowanego w base64, w formacie kodeku wybranego podczas łączenia. Zdekoduj go i dołącz do bufora odtwarzania.
{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }
Zdarzenie audio.done oznacza koniec syntezy. Jego trace_id to identyfikator, który podajesz wsparciu technicznemu lub zapisujesz w logach, gdy generowanie przebiega nieprawidłowo. Jeśli tekst jest nieprawidłowy lub przekroczyłeś przydzielony limit, otrzymasz zamiast tego komunikat o błędzie.
{ "type": "error", "message": "description of the error" }
Kompletna implementacja
Poniższy przykład dzieli długi tekst na akapity, wysyła je wszystkie, a następnie składa otrzymane fragmenty dźwięku w plik 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();
}
});
Zwróć uwagę na para + " ": bez tej spacji koniec jednego akapitu zleje się z początkiem następnego, a silnik przeczyta dwa słowa razem, bez przerwy na oddech.
Limity, które warto znać
| Metryka | Wartość |
|---|---|
| Tekst na delta | maks. 60 000 znaków |
| Całkowity tekst | bez limitu |
| Sesje równoczesne | 50 na zespół |
| Czas trwania sesji | 600 sekund |
| Limit czasu połączenia | brak |
Strona xAI podaje, że połączenie nie ma limitu czasu, a osobno wspomina o „czasie trwania sesji“ wynoszącym 600 sekund, nie wyjaśniając jednak, co dzieje się po jego upływie. Dla bezpieczeństwa nawiązuj połączenie dopiero, gdy masz tekst do wysłania, a nie w momencie ładowania strony, i zaplanuj mechanizm ponownego łączenia. Podobnie postępuj z limitem 50 sesji równoczesnych na zespół: biblioteka audio konwertująca swój katalog w tle powinna kolejkować zadania, zamiast otwierać dwieście połączeń równolegle.
HTTP czy WebSocket?
Tryb HTTP nadal jest właściwym wyborem dla krótkich tekstów, jednorazowych generowań i wszędzie tam, gdzie najważniejsza jest prostota integracji: jedno żądanie, jedna odpowiedź, brak stanu do zarządzania. WebSocket to rozwiązanie, gdy tekst jest długi, gdy dźwięk musi być odtwarzany w trakcie jego tworzenia lub gdy sama zawartość dociera strumieniowo – typowo jako wyjście modelu językowego, który głosisz w miarę generowania.
Kluczowe wnioski
- TTS przez WebSocket pozwala otrzymywać strumieniowy dźwięk bez oczekiwania na zakończenie generowania
- Parametry konfiguracji umieszczasz w ciągu zapytania adresu URL połączenia
- Protokół jest prosty:
text.deltado wysyłania tekstu,audio.deltado odbierania dźwięku - Sesje WebSocket są ograniczone do 50 równoczesnych na zespół; zaplanuj ponowne łączenie
- Wybieraj WebSocket dla długich tekstów i doświadczeń odsłuchu w czasie rzeczywistym