Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Koncový bod WebSocket a připojení v reálném čase

Lekce 1 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Voice Agent API v reálném čase
  2. Otevření připojení WebSocket
  3. Životní cyklus relace
  4. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě stránek xAI Speech to Speech, Pricing a Rate limits: 0,08 USD za minutu, souběžné relace podle úrovně a grok-voice-3.0 jako aktuální model. Zdroje: Speech to Speech · Pricing · Rate limits.

Voice Agent API v reálném čase

API Grok Voice Agent ti umožňuje vytvářet konverzační hlasové agenty, které komunikují s tvými uživateli v reálném čase. Na rozdíl od klasických REST API, která fungují na principu požadavek-odpověď, toto API využívá protokol WebSocket k udržení trvalého obousměrného spojení mezi tvou aplikací a servery xAI.

Dokumentace Voice Agent API

Existuje pouze jeden koncový bod:

wss://api.x.ai/v1/realtime

Model vybereš pomocí URL parametru model, například wss://api.x.ai/v1/realtime?model=grok-voice-latest. Hodnota grok-voice-latest odkazuje na grok-voice-3.0, což je aktuální model, a zároveň představuje výchozí nastavení. Pro produkční prostředí xAI doporučuje explicitně specifikovat konkrétní verzi modelu.

Tento jediný koncový bod zpracovává celý životní cyklus hlasové konverzace: příjem zvuku, detekci řeči, generování odpovědi a odesílání zpět syntetizovaného zvuku.

WebSocket
Protokol pro reálný čas
grok-voice-3.0
Aktuální model
10
Souběžných relací v základní úrovni
$0.08/min
Ceník

Otevření připojení WebSocket

Pro připojení musíš do hlavičky authorization uvést svůj API klíč xAI. Zde je příklad v JavaScriptu:

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 Pythonu můžeš využít knihovnu 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 relace

Jakmile se připojení WebSocket otevře, server odešle událost session.created, která potvrzuje, že je relace aktivní. Následně odešleš událost session.update pro nastavení konverzace (hlas, instrukce, nástroje, detekce střídání řečníků).

Typický cyklus vypadá takto:

  1. Připojení: otevři WebSocket s autentizací
  2. Konfigurace: odešli session.update s tvým nastavením
  3. Potvrzení: přijmi od serveru session.updated
  4. Konverzace: vyměňuj si události obsahující zvuk a text
  5. Ukončení: korektně uzavři připojení WebSocket

Zpracování chyb připojení

Server může připojení uzavřít nebo odmítnout z několika důvodů: chyba autentizace, překročení limitu souběžných relací pro tvou úroveň (10 v základní úrovni, až 200 v nejvyšší) nebo technický výpadek. Aktuální dokumentace nestanovuje maximální délku relace a funkce obnovení relace (lekce 4) ti umožní pokračovat v konverzaci i po přerušení spojení. Tvá aplikace by měla obsahovat logiku pro opětovné připojení s exponenciálním zpětným čekáním (exponential backoff).

Ceny ověřeny k 3. listopadu 2026. Ceny se často mění: před jakýmkoli plánováním rozpočtu si ověř aktuální sazby na oficiální stránce s cenami xAI.

Klíčové poznatky

  • Koncový bod WebSocket wss://api.x.ai/v1/realtime je jediným vstupním bodem pro všechny hlasové konverzace
  • Autentizace probíhá pomocí hlavičky Authorization: Bearer {API klíč}
  • Počet souběžných relací závisí na tvé úrovni: 10 v základní úrovni, až 200
  • Server po připojení odešle session.created a poté čeká na tvou událost session.update pro nastavení konverzace
  • Cena činí 0,08 USD za minutu, což je 4,80 USD za hodinu, plus 0,004 USD za textový vstup