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

WebSocket-päätepiste ja reaaliaikainen yhteys

Oppitunti 1 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Reaaliaikainen Voice Agent API
  2. WebSocket-yhteyden avaaminen
  3. Istunnon elinkaari
  4. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Speech to Speech -, Pricing - ja Rate limits -sivujen perusteella: 0,08 dollaria minuutilta, samanaikaiset istunnot tason mukaan ja grok-voice-3.0 nykyisenä mallina. Lähteet: Speech to Speech · Pricing · Rate limits.

Reaaliaikainen Voice Agent API

Grok Voice Agent API:n avulla voit rakentaa keskustelevia ääniagentteja, jotka ovat vuorovaikutuksessa käyttäjiesi kanssa reaaliajassa. Toisin kuin perinteiset REST-APIt, jotka toimivat pyyntö kerrallaan, tämä API käyttää WebSocket-protokollaa pitääkseen pysyvän kaksisuuntaisen yhteyden auki sovelluksesi ja xAI:n palvelimien välillä.

Voice Agent API -dokumentaatio

Päätepisteitä on vain yksi:

wss://api.x.ai/v1/realtime

Valitset mallin model-URL-parametrilla, esimerkiksi wss://api.x.ai/v1/realtime?model=grok-voice-latest. grok-voice-latest viittaa nykyiseen malliin grok-voice-3.0, ja se on myös oletusarvo. Tuotantoympäristössä xAI suosittelee nimetyn version kiinnittämistä.

Tämä yksi päätepiste hoitaa koko äänikeskustelun elinkaaren: äänen vastaanoton, puheen tunnistuksen, vastauksen generoinnin ja synteettisen äänen lähettämisen takaisin.

WebSocket
Reaaliaikainen protokolla
grok-voice-3.0
Nykyinen malli
10
Samanaikaisia istuntoja aloitustasolla
$0.08/min
Hinnoittelu

WebSocket-yhteyden avaaminen

Muodostaaksesi yhteyden, sijoita xAI API -avaimesi authorization-otsikkoon. Tässä esimerkki JavaScriptillä:

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer " + process.env.XAI_API_KEY
  }
});

ws.on("open", () => {
  console.log("WebSocket connection established");
});

ws.on("message", (data) => {
  const event = JSON.parse(data);
  console.log("Event received:", event.type);
});

ws.on("close", (code, reason) => {
  console.log("Connection closed:", code, reason);
});

ws.on("error", (err) => {
  console.error("WebSocket error:", err);
});

Pythonissa voit käyttää websockets-kirjastoa:

import asyncio
import websockets
import json
import os

async def connect():
    uri = "wss://api.x.ai/v1/realtime"
    headers = {
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}"
    }

    async with websockets.connect(uri, additional_headers=headers) as ws:
        async for message in ws:
            event = json.loads(message)
            print(f"Event: {event['type']}")

asyncio.run(connect())

Istunnon elinkaari

Heti kun WebSocket-yhteys avautuu, palvelin lähettää session.created-tapahtuman, joka vahvistaa istunnon olevan aktiivinen. Tämän jälkeen lähetät session.update-tapahtuman määrittääksesi keskustelun (ääni, ohjeet, työkalut, vuoron tunnistus).

Tyypillinen sykli näyttää tältä:

  1. Yhteys: avaa WebSocket todennuksella
  2. Määritys: lähetä session.update asetuksinesi
  3. Vahvistus: vastaanota session.updated palvelimelta
  4. Keskustelu: vaihda ääni- ja tekstityökaluja
  5. Sulkeminen: katkaise WebSocket-yhteys siististi

Yhteysvirheiden käsittely

Palvelin voi sulkea tai kieltäytyä yhteydestä useista syistä: todennusvirhe, tason samanaikaisten istuntojen rajan ylitys (10 aloitustasolla, jopa 200 korkeimmalla tasolla) tai häiriötilanne. Nykyinen dokumentaatio ei aseta enimmäiskestoa istunnolle, ja istunnon jatkaminen (oppitunti 4) antaa sinun jatkaa keskustelua katkoksen jälkeen. Sovelluksesi tulisi sisältää uudelleenyhdistyslogiikka eksponentiaalisella viiveellä.

Hinnat tarkistettu 3. marraskuuta 2026. Hinnat muuttuvat usein: ennen kuin budjetoit mitään, tarkista nykyiset hinnat xAI:n viralliselta hinnoittelusivulta.

Keskeiset asiat

  • WebSocket-päätepiste wss://api.x.ai/v1/realtime on ainoa sisäänmenopiste kaikille äänikeskusteluille
  • Todennat itsesi Authorization: Bearer {API-avain} -otsikolla
  • Samanaikaisten istuntojen määrä riippuu tasostasi: 10 aloitustasolla, jopa 200
  • Palvelin lähettää session.created-tapahtuman yhteyden muodostuessa ja odottaa sitten session.update-tapahtumaasi keskustelun määrittämiseksi
  • Hinnoittelu on 0,08 dollaria minuutilta eli 4,80 dollaria tunnilta, plus 0,004 dollaria tekstisyötteeltä