Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Laikinieji žetonai ir saugumas

Paskaita 13 iš 14 Atnaujinta 2026 m. lapkričio 3 d. Vidutinis lygis
Šiame puslapyje
  1. API rakto naudojimas kliento pusėje kelia problemų
  2. Kaip tai veikia
  3. Galutinė architektūra
  4. Taisyklės, kurių niekada negalima pažeisti
  5. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 3 d., remiantis xAI Voice API dokumentacija. Šaltiniai: Laikinieji žetonai · Voice API nuoroda · Sesijos atnaujinimas.

API rakto naudojimas kliento pusėje kelia problemų

Naršyklėje arba telefone veikianti balso programėlė negali turėti tavo API rakto. Bet kuris lankytojas gali atidaryti kūrėjo įrankius, perskaityti raktą iš JavaScript ryšulio arba užklausos antraštės ir naudoti jį tavo sąskaitoje, kol baigsis tavo kvota. Joks užmaskavimas neapsaugos vertės, kurią klientas privalo turėti norėdamas kreiptis į API.

xAI sprendimas – laikinieji žetonai, dar vadinami kliento paslaptimis: tai trumpaamžis žetonas, sugeneruotas tavo serverio, kuris leidžia pradėti balso sesiją ir nieko daugiau.

600s
numatytasis galiojimo laikas
3600s
maksimalus galiojimo laikas
POST
/v1/realtime/client_secrets
value
žetonas su expires_at

Kaip tai veikia

Procesą sudaro penki žingsniai:

  1. Tavo galinė sistema (saugus serveris) iškviečia POST /v1/realtime/client_secrets naudodama tavo API raktą
  2. API grąžina laikiną žetoną su ribotu galiojimo laiku
  3. Tavo galinė sistema siunčia tą žetoną klientui (naršyklei arba mobiliąjai programėlei)
  4. Klientas naudoja žetoną prisijungimui prie Voice Agent WebSocket
  5. Žetonas nustoja galioti pasibaigus tavo pasirinktam laikui (expires_after.seconds)

Tai, kas gali nutekėti kliento pusėje, dabar turi daug mažesnę vertę: žetonas, kuris nustoja galioti per kelias minutes ir gali atidaryti tik balso sesiją, bet nėra tavo API raktas. Serveryje vienam sugeneruoti užtenka kelių kodo eilučių. Atkreipk dėmesį, kad apdorotojas pirmiausia patikrina vartotoją: be šio patikrinimo tavo galinė sistema taptų tiesiog viešu žetonų dalintuvu.

// Node.js galinė sistema (Express)
app.post("/api/voice-token", async (req, res) => {
  // Patikrinkite, ar vartotojas autentifikuotas
  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 minučių, numatytoji reikšmė
      })
    }
  );

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

Klientas žino tik tavo maršrutą: jis prašo žetono, o tada su juo atidaro WebSocket.

// Priekinė pusė (naršyklė)
async function startVoiceSession() {
  // Paprašykite galinės sistemos žetono
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // Naršyklės WebSocket nepriima antraščių:
  // žetonas siunčiamas subprotokole, priešdėliu „xai-client-secret.“
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... sesijos konfigūracija
}

Galutinė architektūra

Sujungus viską, procesas prasideda nuo vartotojo prisijungimo prie tavo programėlės. Tada jo klientas prašo tavo galinės sistemos balso žetono, o galinė sistema prieš sugeneruodama laikinąjį žetoną per xAI API patikrina autentifikavimą ir leidimus. Žetonas grįžta klientui, kuris jį naudoja Voice Agent sesijai atidaryti, ir jis automatiškai nustoja galioti pasibaigus savo gyvavimo laikui.

Tas patikrinimas tarp užklausos ir generavimo paprastą perdavimą paverčia kontrolės punktu, ir būtent čia veikia tavo verslo taisyklės. Gali apriboti balso sesijų skaičių vienam vartotojui per dieną, kad viena sąskaita per vieną naktį neišnaudotų tavo mėnesio biudžeto. Gali rezervuoti žetonus aktyvioms prenumeratoms, taip įgyvendindamas savo verslo modelį ne sąsajoje, o serverio lygmenyje. Gali taikyti užklausų dažnio ribojimą, kad sugedęs arba kenkėjiškas klientas negalėtų prašyti tūkstančio žetonų per minutę. Ir gali registruoti kiekvieną sugeneruotą žetoną: tai vienintelis patikimas pagrindas stebėsenai, vidiniam atsiskaitymui ir incidentų analizei.

Taisyklės, kurių niekada negalima pažeisti

API raktas niekada neturi patekti klientui jokiu pavidalu. Laikyk jį atokiau nuo priekinės pusės JavaScript ir nuo bet kurios kintamojo aplinkos, atviros naršyklės kūrimui (kintamieji, skirti įterpti į ryšulį, tampa vieši). Taip pat nelaikyk jo URL adresuose, žurnaluose ir vartotojams rodomuose klaidų pranešimuose.

Be to, laikyk galiojimo laiką kuo trumpesnį, kiek tai praktiška. Pagal API nuorodą, expires_after.seconds numatytoji reikšmė yra 600 sekundžių, o maksimali – 3 600; dokumentacijoje pavyzdžiuose naudojama 300. Svarbiausia, kad žetonas būtų galiojantis, kai klientas atidaro ryšį. Trumpas galiojimo laikas sumažina langą, per kurį perimtas žetonas gali būti panaudotas.

Dokumentacijoje nenurodyta, ar baigiantis žetono galiojimui nutraukiamas jau atidarytas ryšys. Jei tavo klientui reikia prisijungti iš naujo po tinklo sutrikimo arba labai ilgos sesijos metu, paprašyk naujo žetono ir naudok sesijos atnaujinimą: įjunk resumption.enabled parametru session.update, išsaugok ID, gautą conversation.created, tada iš naujo atidaryk WebSocket su ?conversation_id=<id>. Ankstesni veiksmai bus atkurti, o modelis tęs darbą nuo tos vietos, kur sustojo.

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 } },  // siųsti iš naujo kiekvieno prisijungimo metu
  }));
  return ws;
}

TTS HTTP režimu yra dar paprastesnė alternatyva žetonams: tarpinis serveris (proxy). Klientas siunčia tekstą tavo galinei sistemai, o tavo galinė sistema iškviečia TTS ir grąžina garso įrašą. Raktas niekada neišeina iš tavo serverio, ir gauni natūralią vietą filtruoti turinį bei matuoti naudojimą.

Svarbiausi punktai

  • Laikinieji žetonai apsaugo prieigą prie Voice Agent iš kliento pusės programėlių
  • POST /v1/realtime/client_secrets grąžina value ir expires_at; expires_after.seconds numatytoji reikšmė yra 600, o maksimali – 3 600
  • Naršyklėje žetonas siunčiamas xai-client-secret.<token> subprotokole
  • Tavo galinė sistema prieš generuodama žetoną privalo patikrinti autentifikavimą ir leidimus
  • Niekada neatskleisk savo API rakto klientui, URL adresuose ar žurnaluose
  • HTTP TTS atveju tarpinis serveris per tavo galinę sistemą yra tinkama alternatyva laikiniesiems žetonams