Punkt końcowy WebSocket i połączenie w czasie rzeczywistym
Na tej stronie
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.0jako 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.

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.
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:
- Połączenie: otwarcie WebSocket z autoryzacją
- Konfiguracja: wysłanie
session.updatez Twoimi ustawieniami - Potwierdzenie: otrzymanie
session.updatedod serwera - Rozmowa: wymiana zdarzeń audio i tekstowych
- 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/realtimeto 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.createdupon połączeniu, a następnie oczekuje na Twojesession.updatew 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