Endpointul WebSocket și conexiunea în timp real
Pe această pagină
Actualizat la 3 noiembrie 2026, pe baza paginilor xAI Speech to Speech, Pricing și Rate limits: 0,08 USD pe minut, sesiuni concurente în funcție de nivel și
grok-voice-3.0ca model curent. Surse: Speech to Speech · Pricing · Rate limits.
API-ul Voice Agent în timp real
API-ul Grok Voice Agent vă permite să construiți agenți vocali conversaționali care comunică cu utilizatorii dumneavoastră în timp real. Spre deosebire de API-urile REST clasice, care funcționează cerere cu cerere, acest API utilizează protocolul WebSocket pentru a menține o conexiune bidirecțională persistentă între aplicația dumneavoastră și serverele xAI.

Există un singur endpoint:
wss://api.x.ai/v1/realtime
Selectați modelul folosind parametrul URL model, de exemplu wss://api.x.ai/v1/realtime?model=grok-voice-latest. grok-voice-latest indică spre grok-voice-3.0, modelul curent, fiind și opțiunea implicită. În producție, xAI recomandă fixarea unei versiuni denumite specifice.
Acest unic endpoint gestionează întregul ciclu de viață al unei conversații vocale: recepționarea audio, detectarea vorbirii, generarea răspunsului și trimiterea înapoi a audio-ului sintetizat.
Deschiderea conexiunii WebSocket
Pentru a vă conecta, includeți cheia API xAI în antetul de autorizare. Iată un exemplu în 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);
});
În Python, puteți utiliza biblioteca 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())
Ciclul de viață al sesiunii
Imediat ce conexiunea WebSocket se deschide, serverul trimite un eveniment session.created care confirmă că sesiunea este activă. Apoi, dumneavoastră trimiteți un eveniment session.update pentru a configura conversația (voce, instrucțiuni, instrumente, detectarea schimbului de replici).
Ciclul tipic arată astfel:
- Conexiune: deschideți WebSocket-ul cu autentificare
- Configurare: trimiteți
session.updatecu setările dumneavoastră - Confirmare: primiți
session.updatedde la server - Conversație: schimbați evenimente audio și text
- Închidere: deconectați WebSocket-ul corect
Gestionarea erorilor de conexiune
Serverul poate închide sau refuza conexiunea din mai multe motive: o eroare de autentificare, depășirea limitei de sesiuni concurente a nivelului dumneavoastră (10 la nivelul de intrare, până la 200 la cel mai înalt) sau un incident. Documentația curentă nu stabilește o durată maximă a sesiunii, iar reluarea sesiunii (lecția 4) vă permite să reluați o conversație după o întrerupere. Aplicația dumneavoastră ar trebui să includă o logică de reconectare cu backoff exponențial.
Prețuri verificate la 3 noiembrie 2026. Prețurile se modifică frecvent: înainte de a face orice bugetare, verificați tarifele actuale pe pagina oficială de prețuri xAI.
Puncte cheie
- Endpointul WebSocket
wss://api.x.ai/v1/realtimeeste singurul punct de intrare pentru toate conversațiile vocale - Vă autentificați folosind antetul
Authorization: Bearer {cheie API} - Numărul de sesiuni concurente depinde de nivelul dumneavoastră: 10 la nivelul de intrare, până la 200
- Serverul trimite
session.createdla conectare, apoi așteaptăsession.updatedin partea dumneavoastră pentru a configura conversația - Prețul este de 0,08 USD pe minut, adică 4,80 USD pe oră, plus 0,004 USD per input de text