Koncový bod WebSocket a pripojenie v reálnom čase
Na tejto strane
Aktualizované 3. novembra 2026 na základe stránok xAI Speech to Speech, Pricing a Rate limits: 0,08 USD za minútu, súbežné relácie podľa úrovne a
grok-voice-3.0ako aktuálny model. Zdroje: Speech to Speech · Pricing · Rate limits.
Voice Agent API v reálnom čase
API Grok Voice Agent ti umožňuje budovať konverzačných hlasových agentov, ktorí komunikujú s tvojimi používateľmi v reálnom čase. Na rozdiel od klasických REST API, ktoré pracujú požiadavku po požiadavke, toto API využíva protokol WebSocket na udržanie trvalého obojsmerného pripojenia medzi tvojou aplikáciou a servermi xAI.

Existuje iba jeden koncový bod:
wss://api.x.ai/v1/realtime
Model vyberieš pomocou URL parametra model, napríklad wss://api.x.ai/v1/realtime?model=grok-voice-latest. Hodnota grok-voice-latest odkazuje na grok-voice-3.0, čo je aktuálny model, a zároveň predstavuje predvolenú hodnotu. V produkčnom prostredí xAI odporúča pripnúť konkrétnu pomenovanú verziu.
Tento jediný koncový bod obsluhuje celý životný cyklus hlasovej konverzácie: prijímanie zvuku, detekciu reči, generovanie odpovede a odosielanie späť syntetizovaného zvuku.
Otvorenie pripojenia WebSocket
Ak sa chceš pripojiť, vlož svoj kľúč API xAI do hlavičky autorizácie. Tu je príklad v JavaScripte:
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);
});
V Pythone môžeš použiť knižnicu 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())
Životný cyklus relácie
Hneď ako sa pripojenie WebSocket otvorí, server odošle udalosť session.created, ktorá potvrdzuje, že relácia je aktívna. Následne odošleš udalosť session.update, aby si nakonfiguroval konverzáciu (hlas, inštrukcie, nástroje, detekciu zmeny hovoriaceho).
Typický cyklus vyzerá takto:
- Pripojenie: otvor WebSocket s autentifikáciou
- Konfigurácia: pošli
session.updates tvojimi nastaveniami - Potvrdenie: prijmi
session.updatedzo servera - Konverzácia: výmena udalostí so zvukom a textom
- Ukončenie: čisté odpojenie WebSocketu
Spracovanie chýb pripojenia
Server môže pripojenie uzavrieť alebo odmietnuť z niekoľkých dôvodov: chyba autentifikácie, prekročenie limitu súbežných relácií pre tvoju úroveň (10 v základnej úrovni, až 200 vo najvyššej) alebo incident. Aktuálna dokumentácia nestanovuje maximálnu dĺžku relácie a obnovenie relácie (lekcia 4) ti umožňuje pokračovať v konverzácii po výpadku. Tvoja aplikácia by mala obsahovať logiku opätovného pripojenia s exponenciálnym oneskorením (exponential backoff).
Ceny skontrolované 3. novembra 2026. Ceny sa často menia: pred akýmkoľvek plánovaním rozpočtu si over aktuálne sadzby na oficiálnej stránke s cenníkom xAI.
Kľúčové poznatky
- Koncový bod WebSocket
wss://api.x.ai/v1/realtimeje jediným vstupným bodom pre všetky hlasové konverzácie - Autentifikuješ sa pomocou hlavičky
Authorization: Bearer {API kľúč} - Počet súbežných relácií závisí od tvojej úrovne: 10 v základnej úrovni, až 200
- Server po pripojení odošle
session.createda následne čaká na tvojesession.updatena konfiguráciu konverzácie - Cena je 0,08 USD za minútu, čo predstavuje 4,80 USD za hodinu, plus 0,004 USD za textový vstup