Lähe põhisisu juurde
Eesti— Vali keel
Menüü

WebSocketi lõpp-punkt ja reaalajas ühendus

Õppetund 1 / 16 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Reaalajas Voice Agent API
  2. WebSocketi ühenduse loomine
  3. Seansi elutsükkel
  4. Peamised punktid

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.0 kui 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.

Voice Agent API dokumentatsioon

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.

WebSocket
Reaalajas protokoll
grok-voice-3.0
Praegune mudel
10
Samaaegset seanssi algustasemel
0,08 USD/min
Hinnakiri

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:

  1. Ühendus: ava WebSocket autentimisega
  2. Konfigureerimine: saada session.update koos oma seadetega
  3. Kinnitus: võta serverilt vastu session.updated
  4. Vestlus: vaheta heli- ja tekstisündmusi
  5. 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/realtime on 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.created ja ootab seejärel sinu saadetavat session.update, et vestlust konfigureerida
  • Hind on 0,08 USD minutis ehk 4,80 USD tunnis, pluss 0,004 USD tekstisisendi kohta