WebSocketi lõpp-punkt ja reaalajas ühendus
Uuendatud 3. novembril 2026, tuginedes xAi lehtedele Speech to Speech, Pricing ja Rate limits: 0,08 USD minutis, samaaegsed seansid vastavalt tasemele ja
grok-voice-3.0kui praegune mudel. Allikad: Speech to Speech · Pricing · Rate limits.
Reaalajas Voice Agent API
Grok Voice Agent API võimaldab sul luua vestlevaid hääleagente, mis suhtlevad kasutajatega reaalajas. Erinevalt klassikalistest REST API-dest, mis töötavad päring-päringu haaval, kasutab see API WebSocketi protokolli, et hoida avatud püsivat kahepoolset ühendust sinu rakenduse ja xAi serverite vahel.

Lõpp-punkte on ainult üks:
wss://api.x.ai/v1/realtime
Valid mudeli URL-i parameetri model abil, näiteks wss://api.x.ai/v1/realtime?model=grok-voice-latest. grok-voice-latest viitab praegusele mudelile grok-voice-3.0 ja on ühtlasi vaikimisi valik. Tootekeskkonnas soovitab xAi fikseerida konkreetne versiooninimi.
See ainus lõpp-punkt haldab kogu häälevestluse elutsüklit: heli vastuvõtmist, kõne tuvastamist, vastuse genereerimist ja sünteesitud heli tagasisaatmist.
WebSocketi ühenduse loomine
Ühenduse loomiseks lisa oma xAi API võti päise Authorization väärtusena. Siin on näide JavaScriptis:
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);
});
Pythonis saad kasutada teeki websockets:
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())
Seansi elutsükkel
Niipea kui WebSocketi ühendus avaneb, saadab server sündmuse session.created, kinnitades seansi aktiivsust. Seejärel saadad sündmuse session.update, et konfigureerida vestlust (hääl, juhised, tööriistad, pöörde tuvastamine).
Tüüpiline tsükkel näeb välja selline:
- Ühendus: ava WebSocket autentimisega
- Konfigureerimine: saada
session.updatekoos oma seadetega - Kinnitus: võta serverilt vastu
session.updated - Vestlus: vaheta heli- ja tekstisündmusi
- Sulgemine: katkesta WebSocketi ühendus korrektselt
Ühendusvigade käsitlemine
Server võib ühenduse sulgeda või sellest keelduda mitmel põhjusel: autentimisviga, sinu taseme samaaegsete seansside piirangu ületamine (algustasemel 10, kõrgeimal tasemel kuni 200) või tehniline intsident. Praegune dokumentatsioon ei sätesta seansi maksimaalset kestust ning seansi taastamine (4. õppetund) võimaldab vestlust pärast katkemist jätkata. Sinu rakendus peaks sisaldama uuesti ühendumise loogikat eksponentsiaalse tagasiminekuga (exponential backoff).
Hinnad kontrollitud 3. novembril 2026. Hinnad muutuvad sageli: enne eelarve planeerimist kontrolli kehtivaid hindu xAi ametlikul hinnalehel.
Peamised punktid
- WebSocketi lõpp-punkt
wss://api.x.ai/v1/realtimeon ainuke sisenemispunkt kõigile häälevestlustele - Autendid päise
Authorization: Bearer {API võti}abil - Samaaegsete seansside arv sõltub sinu tasemest: algustasemel 10, kuni 200 kõrgeimal tasemel
- Server saadab ühenduse loomisel sündmuse
session.createdja ootab seejärel sinu saadetavatsession.update, et vestlust konfigureerida - Hind on 0,08 USD minutis ehk 4,80 USD tunnis, pluss 0,004 USD tekstisisendi kohta