Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Yhteys TTS WebSocketiin

Oppitunti 9 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Puheen synteesi reaaliajassa WebSocketin yli
  2. WebSocket-päätepiste
  3. Yhteyden avaaminen
  4. Istunnon hallinta
  5. Yksittäinen HTTP versus WebSocket
  6. Milloin käyttää WebSocketia
  7. Keskeiset asiat

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.

wss://
Suojattu protokolla
50
Istuntoa tiimiä kohden
600 s
Istuntolupa
∞
Rajoittamaton teksti

WebSocket-päätepiste

Yhdistät osoitteeseen wss://api.x.ai/v1/tts. Määritysparametrit sijoitetaan alkuperäisen yhteyden kyselymerkkijonoon.

Yhteysparametrit

ParametriVaadittuOletusKuvaus
languageKyllä—BCP-47-koodi tai auto
voiceEi—Sisäisen tai mukautetun äänen tunnus
codecEimp3mp3, wav, pcm, mulaw (tai ulaw), alaw
sample_rateEi24000Näytteenottotaajuus
bit_rateEi128000Bittinopeus (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:

  1. Havaita, milloin yhteys sulkeutuu
  2. Muodostaa yhteys uudelleen automaattisesti tarvittaessa
  3. 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ökulmaYksittäinen HTTPWebSocket
ViiveKoko ääni käsittelyn jälkeenEnsimmäiset tavut heti
Tekstin enimmäismäärä60 000 merkkiä pyyntöä kohdenRajoittamaton (erot maksimissaan 60 000)
Aikakatkaisu15 minuuttiaEi ole; istuntolupa 600 sekuntia
IstunnotEi sovelleta50 tiimiä kohden
KäyttötapauksetEräajo, äänitiedostotReaaliaika, 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