Przejdź do głównej treści
Polski— Wybierz język
Menu

Punkt końcowy WebSocket i połączenie w czasie rzeczywistym

Lekcja 1 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Voice Agent API w czasie rzeczywistym
  2. Nawiązywanie połączenia WebSocket
  3. Cykl życia sesji
  4. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie stron xAI dotyczących Speech to Speech, Cennika oraz Limitów szybkości: 0,08 USD za minutę, sesje równoległe zależne od poziomu oraz grok-voice-3.0 jako bieżący model. Źródła: Speech to Speech · Cennik · Limity szybkości.

Voice Agent API w czasie rzeczywistym

Grok Voice Agent API pozwala tworzyć konwersacyjne asystenty głosowe, które rozmawiają z użytkownikami w czasie rzeczywistym. W przeciwieństwie do klasycznych interfejsów REST, działających na zasadzie pojedynczych żądań, to API wykorzystuje protokół WebSocket do utrzymania stałego, dwukierunkowego połączenia między Twoją aplikacją a serwerami xAI.

Dokumentacja Voice Agent API

Dostępny jest tylko jeden punkt końcowy:

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

Model wybierasz za pomocą parametru URL model, na przykład wss://api.x.ai/v1/realtime?model=grok-voice-latest. grok-voice-latest wskazuje na grok-voice-3.0, czyli bieżący model, i jest również wartością domyślną. W środowisku produkcyjnym xAI zaleca przypięcie konkretnej, nazwanej wersji.

Ten pojedynczy punkt końcowy obsługuje cały cykl życia rozmowy głosowej: odbieranie dźwięku, wykrywanie mowy, generowanie odpowiedzi i odsyłanie zsyntetyzowanego audio.

WebSocket
Protokół czasu rzeczywistego
grok-voice-3.0
Bieżący model
10
Sesje równoległe w poziomie podstawowym
0,08 USD/min
Cennik

Nawiązywanie połączenia WebSocket

Aby się połączyć, przekaż swój klucz API xAI w nagłówku autoryzacji. Oto przykład w JavaScript:

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);
});

W Pythonie możesz użyć biblioteki 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())

Cykl życia sesji

Gdy tylko połączenie WebSocket zostanie otwarte, serwer wysyła zdarzenie session.created, potwierdzając aktywację sesji. Następnie wysyłasz zdarzenie session.update, aby skonfigurować rozmowę (głos, instrukcje, narzędzia, wykrywanie zmiany mówcy).

Typowy cykl wygląda następująco:

  1. Połączenie: otwarcie WebSocket z autoryzacją
  2. Konfiguracja: wysłanie session.update z Twoimi ustawieniami
  3. Potwierdzenie: otrzymanie session.updated od serwera
  4. Rozmowa: wymiana zdarzeń audio i tekstowych
  5. Zamykanie: czyste rozłączenie WebSocket

Obsługa błędów połączenia

Serwer może zamknąć lub odrzucić połączenie z kilku powodów: błędu autoryzacji, przekroczenia limitu sesji równoległych dla Twojego poziomu (10 w poziomie podstawowym, do 200 w najwyższym) lub awarii. Obecna dokumentacja nie określa maksymalnego czasu trwania sesji, a wznowienie sesji (lekcja 4) pozwala kontynuować rozmowę po jej przerwaniu. Twoja aplikacja powinna zawierać logikę ponownego łączenia z wykładniczym opóźnieniem (exponential backoff).

Ceny sprawdzone 3 listopada 2026 r. Ceny często ulegają zmianom: przed zaplanowaniem budżetu sprawdź aktualne stawki na oficjalnej stronie cennika xAI.

Kluczowe wnioski

  • Punkt końcowy WebSocket wss://api.x.ai/v1/realtime to jedyne wejście dla wszystkich rozmów głosowych
  • Autoryzacja odbywa się przez nagłówek Authorization: Bearer {klucz API}
  • Liczba sesji równoległych zależy od Twojego poziomu: 10 w poziomie podstawowym, do 200
  • Serwer wysyła session.created upon połączeniu, a następnie oczekuje na Twoje session.update w celu skonfigurowania rozmowy
  • Cennik wynosi 0,08 USD za minutę, czyli 4,80 USD za godzinę, plus 0,004 USD za każde wprowadzone słowo tekstowe