Yhteys TTS WebSocketiin
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI:n Text to Speech -sivun perusteella: erot (deltas) jopa 60 000 merkkiä, ei yhteysaikakatkaisua ja istuntolupa (session permit) 600 sekunniksi. Lähde: Text to Speech.
Puheen synteesi reaaliajassa WebSocketin yli
Grok TTS API tarjoaa WebSocket-tilan äänen suoratoistoon. Toisin kuin yksittäinen HTTP-tila, joka odottaa käsittelyn valmistumista palauttaakseen koko äänen, WebSocket lähettää äänipaloja sitä mukaa kun niitä tuotetaan. Se on ihanteellinen interaktiivisille sovelluksille, joissa havaitun viiveen on oltava mahdollisimman pieni.
WebSocket-päätepiste
Yhdistät osoitteeseen wss://api.x.ai/v1/tts. Määritysparametrit sijoitetaan alkuperäisen yhteyden kyselymerkkijonoon.
Yhteysparametrit
| Parametri | Vaadittu | Oletus | Kuvaus |
|---|---|---|---|
language | Kyllä | — | BCP-47-koodi tai auto |
voice | Ei | — | Sisäisen tai mukautetun äänen tunnus |
codec | Ei | mp3 | mp3, wav, pcm, mulaw (tai ulaw), alaw |
sample_rate | Ei | 24000 | Näytteenottotaajuus |
bit_rate | Ei | 128000 | Bittinopeus (vain MP3) |
Täydellinen yhteysosoite
wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3&sample_rate=24000
Yhteyden avaaminen
JavaScriptillä (selain tai Node.js)
const ws = new WebSocket(
"wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3",
{
headers: {
"Authorization": `Bearer ${API_KEY}`
}
}
);
ws.onopen = () => {
console.log("TTS-yhteys muodostettu");
};
ws.onerror = (error) => {
console.error("WebSocket-virhe:", error);
};
Tärkeää: selaimessa natiivi WebSocket-API ei tue mukautettuja otsikoita. Sinun on kuljetettava yhteys backendisi kautta (katso tuotantotunnista).
Pythonilla ja websockets-kirjastolla
import asyncio
import websockets
import json
async def connect_tts():
uri = "wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3"
headers = {"Authorization": f"Bearer {api_key}"}
async with websockets.connect(uri, additional_headers=headers) as ws:
print("TTS-yhteys muodostettu")
# Lähetä teksti ja vastaanota ääntä...
Istunnon hallinta
Elinikä
xAI:n Text to Speech -sivu kertoo kaksi asiaa, jotka on luettava yhdessä: WebSocket-yhteydellä ei ole pyyntöaikakatkaisua (se pysyy auki), ja “istuntoluvalla” on elinikä 600 sekuntia, ilman että sivulla selitetään, mitä tapahtuu sen umpeutuessa. Varmuuden vuoksi sovelluksesi pitäisi:
- Havaita, milloin yhteys sulkeutuu
- Muodostaa yhteys uudelleen automaattisesti tarvittaessa
- Jatkaa tekstin lähettämistä siitä kohdasta, mihin se jäi
Samanaikaiset istunnot
Text to Speech -sivun mukaan tiimisi on rajoitettu 50:een samanaikaiseen WebSocket-istuntoon (sivu Rate limits laskee TTS-istunnot tason mukaan alkaen 100:sta). Tämän ylittyessä uudet yhteydet evätään. Hallitse yhteyspoolia suurliikenteisissä sovelluksissa.
Useita tekstejä samassa yhteydessä
Toisin kuin yksittäisessä HTTP-tilassa, jossa pyynnöt aikakatkaistaan 15 minuutin jälkeen, yhteys pysyy auki jokaisen audio.done-viestin jälkeen: voit lähettää tekstiä toisen perään ilman uudelleenyhteyden muodostamista ja peruuttaa nykyisen komennolla text.clear (tunti 10).
Yksittäinen HTTP versus WebSocket
| Näkökulma | Yksittäinen HTTP | WebSocket |
|---|---|---|
| Viive | Koko ääni käsittelyn jälkeen | Ensimmäiset tavut heti |
| Tekstin enimmäismäärä | 60 000 merkkiä pyyntöä kohden | Rajoittamaton (erot maksimissaan 60 000) |
| Aikakatkaisu | 15 minuuttia | Ei ole; istuntolupa 600 sekuntia |
| Istunnot | Ei sovelleta | 50 tiimiä kohden |
| Käyttötapaukset | Eräajo, äänitiedostot | Reaaliaika, suoratoisto |
Milloin käyttää WebSocketia
WebSocket on oikea valinta aina, kun kyseessä on reaaliaika. Kun käyttäjä odottaa välitöntä puhuttua vastausta chatbotilta tai ääniavustajalta, jokainen hiljaisuuden sekunti ennen ensimmäistä ääntä heikentää kokemusta, ja WebSocket mahdollistaa toiston alkamisen ensimmäisistä äänipaloista, ennen kuin generointi on edes valmistunut. Se on myös luonteva arkkitehtuuri, kun itse teksti saapuu vähitellen: LLM:n streamattu ulostulo kytkeytyy suoraan TTS:ään delta kerrallaan odottamatta koko tekstiä. Se poistaa myös pituusrajoituksen: kokonaistekstille ei ole yleistä rajaa, vain yksittäiset erot on rajoitettu 60 000 merkkiin, mikä riittää koko asiakirjan äänittämiseen jatkuvana virtana.
Yksittäisellä HTTP-tilalla on edelleen paikkansa siellä, missä reaaliaika ei tuo lisäarvoa: äänitiedostojen luominen eräajona, prosessit, jotka tarvitsevat koko tiedoston ennen toimintaa (jälkikäsittely, tallennus, lähetys), ja yksinkertaisesti mikä tahansa arkkitehtuuri, joka suosii tilatonta pyyntö-vastaus-kierrosta pysyvän yhteyden hallinnan sijaan.
Keskeiset asiat
- TTS WebSocket on saatavilla osoitteessa
wss://api.x.ai/v1/tts - Parametrit sijoitetaan kyselymerkkijonoon yhteyden muodostamisen yhteydessä
- Yhteys ei vanhene itsestään, mutta dokumentaatio mainitsee 600 sekunnin istuntoluvan: varaudu uudelleenyhteyden muodostamiseen
- Raja on 50 samanaikaista istuntoa tiimiä kohden
- Teksti on rajoittamaton (lähetetään eroina, joissa on enintään 60 000 merkkiä)
- Käytä WebSocketia reaaliaikaan ja HTTP:tä eräajoon