A WebSocket végpont és a valós idejű kapcsolat
Ezen az oldalon
Frissítve: 2026. november 3., az xAI Speech to Speech, Pricing és Rate limits oldalai alapján: percenként 0,08 USD, csomagonkénti egyidejű munkamenetek, valamint a
grok-voice-3.0mint aktuális modell. Források: Speech to Speech · Pricing · Rate limits.
A valós idejű Voice Agent API
A Grok Voice Agent API lehetővé teszi, hogy olyan beszélgető hangalapú ügynököket építs, amelyek valós időben kommunikálnak a felhasználóiddal. A klasszikus REST API-kkal ellentétben, amelyek kérésenként működnek, ez az API a WebSocket protokollt használja, hogy állandó kétirányú kapcsolatot tartson fenn az alkalmazásod és az xAI szerverei között.

Csak egyetlen végpont létezik:
wss://api.x.ai/v1/realtime
A modellt a model URL-paraméterrel választod ki, például így: wss://api.x.ai/v1/realtime?model=grok-voice-latest. A grok-voice-latest a jelenlegi grok-voice-3.0 modellre mutat, és ez az alapértelmezett beállítás is. Éles környezetben az xAI egy konkrét, névvel ellátott verzió rögzítését javasolja.
Ez az egyetlen végpont kezeli a hangalapú beszélgetés teljes életciklusát: fogadja a hangot, érzékeli a beszédet, generálja a választ, és visszaküldi a szintetizált hangot.
A WebSocket-kapcsolat megnyitása
A csatlakozáshoz az xAI API-kulcsodat az authorization fejlécben kell elhelyezned. Íme egy példa JavaScriptben:
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);
});
Pythonban a websockets könyvtárat használhatod:
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())
A munkamenet életciklusa
Amint a WebSocket-kapcsolat megnyílik, a szerver küld egy session.created eseményt, amely megerősíti, hogy a munkamenet aktív. Ezt követően egy session.update eseményt küldesz a beszélgetés konfigurálásához (hang, utasítások, eszközök, fordulódetectálás).
A tipikus ciklus a következőképpen néz ki:
- Kapcsolódás: a WebSocket megnyitása hitelesítéssel
- Konfigurálás: a
session.updateelküldése a beállításaiddal - Megerősítés: a
session.updatedfogadása a szervertől - Beszélgetés: hang- és szövegesemények cseréje
- Lezárás: a WebSocket-kapcsolat szabályos bontása
Kapcsolati hibák kezelése
A szerver több okból is megszakíthatja vagy elutasíthatja a kapcsolatot: hitelesítési hiba, a csomagodhoz tartozó egyidejű munkamenetek korlátjának túllépése (belépő szinten 10, a legmagasabb szinten akár 200), vagy egy incidens. A jelenlegi dokumentáció nem határoz meg maximális munkamenet-hosszt, a munkamenet-folytatás (4. lecke) pedig lehetővé teszi, hogy egy megszakadás után folytathasd a beszélgetést. Az alkalmazásodnak tartalmaznia kell újrapcsolódási logikát exponenciális visszalépéssel (exponential backoff).
Árak ellenőrizve: 2026. november 3. Az árak gyakran változnak: mielőtt bármit terveznél, ellenőrizd az aktuális díjszabást a hivatalos xAI árazási oldalon.
Főbb megállapítások
- A
wss://api.x.ai/v1/realtimeWebSocket-végpont az egyetlen belépési pont minden hangalapú beszélgetéshez - A hitelesítés az
Authorization: Bearer {API kulcs}fejléccel történik - Az egyidejű munkamenetek száma a csomagodtól függ: belépő szinten 10, egészen 200-ig
- A szerver kapcsolódáskor elküldi a
session.createdeseményt, majd várja asession.updateüzenetedet a beszélgetés konfigurálásához - Az ár percenként 0,08 USD, azaz óránként 4,80 USD, plusz szöveges bemenetenként 0,004 USD