WebSocket-päätepiste ja reaaliaikainen yhteys
Tällä sivulla
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.0nykyisenä 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ä.

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-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ä:
- Yhteys: avaa WebSocket todennuksella
- Määritys: lähetä
session.updateasetuksinesi - Vahvistus: vastaanota
session.updatedpalvelimelta - Keskustelu: vaihda ääni- ja tekstityökaluja
- 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/realtimeon 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 sittensession.update-tapahtumaasi keskustelun määrittämiseksi - Hinnoittelu on 0,08 dollaria minuutilta eli 4,80 dollaria tunnilta, plus 0,004 dollaria tekstisyötteeltä