Salt la conținutul principal
Română— Alege o limbă
Meniu

Jetoane efemere și securitate

Lecția 13 din 14 Actualizată 3 noiembrie 2026 Intermediar
Pe această pagină
  1. Problema cheii API pe partea clientului
  2. Cum funcționează
  3. Arhitectura end-to-end
  4. Reguli pe care nu trebuie să le încălcați niciodată
  5. Puncte cheie

Actualizat la 3 noiembrie 2026, pe baza referinței API Voice de la xAI. Surse: Jetoane Efemere · Referință API Voice · Reluarea Sesiunii.

Problema cheii API pe partea clientului

O aplicație vocală care rulează într-un browser sau pe un telefon nu poate include cheia dumneavoastră API. Orice vizitator poate deschide instrumentele pentru dezvoltatori, poate citi cheia din pachetul JavaScript sau dintr-un antet de cerere și o poate utiliza în contul dumneavoastră până când cota se epuizează. Nicio cantitate de obscurizare nu protejează o valoare pe care clientul trebuie să o dețină pentru a apela API-ul.

Răspunsul xAI îl constituie jetoanele efemere, numite și secrete de client: un jeton cu durată scurtă de viață, generat de serverul dumneavoastră, care autorizează o sesiune vocală și nimic altceva.

600s
durată de viață implicită
3600s
durată de viață maximă
POST
/v1/realtime/client_secrets
valoare
jetonul, cu expires_at

Cum funcționează

Fluxul se rezumă la cinci pași:

  1. Backend-ul dumneavoastră (un server securizat) apelează POST /v1/realtime/client_secrets cu cheia dumneavoastră API
  2. API-ul returnează un jeton temporar cu o durată de viață limitată
  3. Backend-ul dumneavoastră trimite acel jeton către client (browser sau aplicație mobilă)
  4. Clientul utilizează jetonul pentru a se conecta la WebSocket-ul Agentului Voice
  5. Jetonul expiră după durata de viață aleasă de dumneavoastră (expires_after.seconds)

Ceea ce poate fi compromis pe partea clientului valorează acum mult mai puțin: un jeton care expiră în câteva minute și poate deschide doar o sesiune vocală, nu cheia dumneavoastră API. Pe server, generarea unui astfel de jeton necesită câteva linii de cod. Observați că handler-ul începe prin verificarea utilizatorului: fără acea verificare, backend-ul dumneavoastră devine doar un distribuitor public de jetoane.

// Backend Node.js (Express)
app.post("/api/voice-token", async (req, res) => {
  // Verificați dacă utilizatorul este autentificat
  if (!req.user) return res.status(401).json({ error: "Unauthorized" });

  const response = await fetch(
    "https://api.x.ai/v1/realtime/client_secrets",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer " + process.env.XAI_API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        expires_after: { seconds: 600 }  // 10 minute, valoarea implicită
      })
    }
  );

  const data = await response.json();  // { value, expires_at }
  res.json({ token: data.value, expiresAt: data.expires_at });
});

Clientul cunoaște doar ruta dumneavoastră proprie: solicită un jeton, apoi deschide WebSocket-ul cu acesta.

// Frontend (browser)
async function startVoiceSession() {
  // Solicitați un jeton de la backend
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // WebSocket-ul din browser nu acceptă antete:
  // jetonul merge într-un subprotocol, prefixat cu "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... configurarea sesiunii
}

Arhitectura end-to-end

Privind ansamblul, fluxul începe cu autentificarea utilizatorului în aplicația dumneavoastră. Clientul său solicită apoi backend-ului dumneavoastră un jeton vocal, iar backend-ul verifică autentificarea și permisiunile înainte de a genera jetonul efemer prin API-ul xAI. Jetonul călătorește înapoi către client, care îl utilizează pentru a deschide sesiunea Agentului Voice, expirând automat la sfârșitul duratei sale de viață.

Această verificare între cerere și generare transformă un simplu releu într-un punct de control, iar aici rezidă regulile dumneavoastră de afaceri. Puteți limita numărul de sesiuni vocale per utilizator pe zi, astfel încât un singur cont să nu poată epuiza bugetul lunar peste noapte. Puteți rezerva jetoane pentru abonamente active, impunând modelul de afaceri în altă parte decât la interfață. Puteți limita rata cererilor, astfel încât un client defect sau rău intenționat să nu poată solicita o mie de jetoane pe minut. Și puteți înregistra fiecare jeton generat: aceasta este singura bază fiabilă pentru monitorizare, facturare internă și analiza incidentelor.

Reguli pe care nu trebuie să le încălcați niciodată

Cheia API nu ajunge niciodată la client, sub nicio formă. Țineți-o departe de JavaScript-ul din front-end și departe de orice variabilă de mediu expusă compilării pentru browser (variabilele prefixate pentru a fi injectate în pachet devin publice). Țineți-o departe și de URL-uri, jurnale (logs) și mesaje de eroare afișate utilizatorilor.

În continuare, mențineți durata de viață cât mai scurtă posibil, în limitele practicii. Conform referinței API, expires_after.seconds are implicit 600 de secunde și o valoare maximă de 3.600; documentația utilizează 300 în exemplele sale. Mai presus de toate, jetonul trebuie să fie valid atunci când clientul deschide conexiunea. O durată de viață scurtă reduce fereastra de timp în care un jeton interceptat poate fi utilizat.

Documentația nu specifică dacă un jeton care expiră întrerupe o conexiune deja deschisă. Dacă clientul dumneavoastră trebuie să se reconecteze, după o întrerupere de rețea sau în timpul unei sesiuni foarte lungi, solicitați un nou jeton și utilizați reluarea sesiunii: activați resumption.enabled în session.update, păstrați ID-ul primit în conversation.created, apoi redeschideți WebSocket-ul cu ?conversation_id=<id>. Schimburile anterioare sunt redate, iar modelul continuă de unde a rămas.

async function reconnect(conversationId) {
  const { token } = await (await fetch("/api/voice-token", { method: "POST" })).json();
  const url = `wss://api.x.ai/v1/realtime?model=grok-voice-latest&conversation_id=${conversationId}`;
  const ws = new WebSocket(url, [`xai-client-secret.${token}`]);
  ws.onopen = () => ws.send(JSON.stringify({
    type: "session.update",
    session: { resumption: { enabled: true } },  // trimite din nou la fiecare conexiune
  }));
  return ws;
}

Pentru TTS în mod HTTP, există o alternativă și mai simplă la jetoane: un proxy. Clientul trimite textul către backend-ul dumneavoastră, iar backend-ul apelează TTS și returnează audio-ul. Cheia nu părăsește niciodată serverul dumneavoastră, iar dumneavoastră obțineți un loc natural pentru a filtra conținutul și a măsura utilizarea în acest proces.

Puncte cheie

  • Jetoanele efemere securizează accesul la Agentul Voice din aplicațiile lato-client
  • POST /v1/realtime/client_secrets returnează value și expires_at; expires_after.seconds are implicit 600 și o valoare maximă de 3.600
  • În browser, jetonul merge în subprotocolul xai-client-secret.<token>
  • Backend-ul dumneavoastră trebuie să verifice autentificarea și permisiunile înainte de a genera un jeton
  • Nu expuneți niciodată cheia API pe client, în URL-uri sau în jurnale
  • Pentru TTS HTTP, utilizarea unui proxy prin backend-ul dumneavoastră este o alternativă validă la jetoanele efemere