Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Žetoni ar īsu dzīves laiku un drošība

Nodarbība 13 no 14 Atjaunota 2026. gada 3. novembris Vidējs
Šajā lapā
  1. Problēma ar API atslēgu klienta pusē
  2. Kā tas darbojas
  3. End-to-end arhitektūra
  4. Noteikumi, kurus nedrīkst pārkāpt
  5. Galvenās atziņas

Atjaunināts 2026. gada 3. novembrī, pamatojoties uz xAI Voice API atsauces dokumentāciju. Avoti: Žetoni ar īsu dzīves laiku · Voice API atsauce · Sesijas atsākšana.

Problēma ar API atslēgu klienta pusē

Lietotne, kas darbojas pārlūkprogrammā vai mobilajā tālrunī, nevar saturēt tavu API atslēgu. Jebkurš apmeklētājs var atvērt izstrādātāja rīkus, nolasīt atslēgu no JavaScript pakotnes vai pieprasījuma galvenes un pēc tam izmantot to tavā kontā, līdz tava kvota beigsies. Nekāda apslēpšana nepasargās vērtību, kas klientam ir jāzina, lai izsauktu API.

xAI risinājums ir žetoni ar īsu dzīves laiku (angļu valodā ephemeral tokens), ko dēvē arī par klienta noslēpumiem: tas ir īslaicīgs žetons, ko ģenerē tavs serveris un kas autorizē tikai balss sesiju, neko citu.

600s
noklusējuma darbības laiks
3600s
maksimālais darbības laiks
POST
/v1/realtime/client_secrets
value
žetons ar expires_at

Kā tas darbojas

Process sastāv no pieciem soļiem:

  1. Tavs backend (drošs serveris) izsauc POST /v1/realtime/client_secrets, norādot savu API atslēgu.
  2. API atgriež pagaidu žetonu ar ierobežotu darbības laiku.
  3. Tavs backend nosūta šo žetonu klientam (pārlūkprogrammai vai mobilajai lietotnei).
  4. Klients izmanto žetonu, lai izveidotu savienojumu ar Voice Agent WebSocket.
  5. Žetons beidz darboties pēc tavā izvēlētā laika (expires_after.seconds).

Tagad informācijas noplūde klienta pusē rada daudz mazāku risku: žetons, kas beidz darboties dažu minūšu laikā un var atvērt tikai balss sesiju, nevis piekļūt tavai API atslēgai. Serverī tā ģenerēšana aizņem tikai dažas koda rindiņas. Ņem vērā, ka apstrādātājam vispirms ir jāpārbauda lietotājs: bez šīs pārbaudes tavs backend kļūst par publisku žetonu izsniedzēju.

// Node.js backend (Express)
app.post("/api/voice-token", async (req, res) => {
  // Pārbauda, vai lietotājs ir autentificēts
  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 minūtes, noklusējuma vērtība
      })
    }
  );

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

Klients zina tikai tavu maršrutu: tas pieprasa žetonu un pēc tam ar to atver WebSocket savienojumu.

// Frontend (pārlūkprogramma)
async function startVoiceSession() {
  // Pieprasa žetonu no backend
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // Pārlūkprogrammas WebSocket nepieņem galvenes:
  // žetons tiek ievietots apakšprotokolā ar prefiksu "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... sesijas konfigurācija
}

End-to-end arhitektūra

Kopumā process sākas ar lietotāja pierakstīšanos tavā lietotnē. Tad klients pieprasa tavam backend balss žetonu, un backend pārbauda autentifikāciju un atļaujas, pirms ģenerē žetonu ar īsu dzīves laiku, izmantojot xAI API. Žetons tiek nosūtīts atpakaļ klientam, kurš to izmanto, lai atvērtu Voice Agent sesiju, un tas automātiski beidz darboties pēc sava darbības laika beigām.

Šī pārbaude starp pieprasījumu un ģenerēšanu pārvērš vienkāršu releju kontrolpunktā, un tieši šeit darbojas tavi biznesa noteikumi. Tu vari ierobežot balss sesiju skaitu vienam lietotājam dienā, lai viens konts neiztērētu tavu mēneša budžētu vienas nakts laikā. Tu vari rezervēt žetonus aktīvām abonēšanām, īstenojot savu biznesa modeli citur, nevis saskarnē. Tu vari ierobežot pieprasījumu biežumu, lai kļūdains vai ļaunprātīgs klients nevarētu pieprasīt tūkstošiem žetonu minūtē. Un tu vari reģistrēt katru ģenerēto žetonu: tas ir tavs vienīgais uzticamais pamats uzraudzībai, iekšējai rēķinu veidošanai un incidentu analīzei.

Noteikumi, kurus nedrīkst pārkāpt

API atslēga nekad netiek nosūtīta klientam nekādā veidā. Glabā to ārpus front-end JavaScript koda un ārpus jebkura mainīgā vidē, kas tiek eksponēts pārlūkprogrammas būvei (mainīgie ar prefiksu, lai tie tiktu ievietoti pakotnē, kļūst publiski). Neiekļauj to URL adresēs, žurnālos vai kļūdu ziņojumos, ko rāda lietotājiem.

Tālāk, uzturi darbības laiku pēc iespējas īsāku, cik tas ir praktiski. Saskaņā ar API atsauces dokumentāciju, expires_after.seconds noklusējuma vērtība ir 600 sekundes, bet maksimālā – 3600; dokumentācijā piemēros tiek izmantota vērtība 300. Pats galvenais, žetonam ir jābūt derīgam brīdī, kad klients atver savienojumu. Īss darbības laiks saīsina logu, kurā pārtverts žetons var tikt izmantots.

Dokumentācijā nav norādīts, vai beidzies žetons pārtrauc jau atvērtu savienojumu. Ja klientam ir jāizveido savienojums no jauna pēc tīkla pārtraukuma vai ļoti garas sesijas laikā, pieprasi jaunu žetonu un izmanto sesijas atsākšanu: ieslēdz resumption.enabled objektā session.update, saglabā ID, ko saņemsi conversation.created, un pēc tam atkārtoti atver WebSocket ar ?conversation_id=<id>. Iepriekšējie gājieni tiek atkārtoti, un modelis turpina darbu no vietas, kur tas apstājās.

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 } },  // nosūta atkārtoti katrā savienojumā
  }));
  return ws;
}

TTS (teksta pārvēršanai runā) HTTP režīmā pastāv vēl vienkāršāka alternatīva žetoniem: starpniekserveris (proxy). Klients nosūta savu tekstu tavam backend, tavs backend izsauc TTS un atgriež audio. Atslēga nekad neatstāj tavu serveri, un tu iegūsti dabisku vietu satura filtrēšanai un lietojuma mērīšanai procesa laikā.

Galvenās atziņas

  • Žetoni ar īsu dzīves laiku nodrošina drošu piekļuvi Voice Agent no klienta puses lietotnēm.
  • POST /v1/realtime/client_secrets atgriež value un expires_at; expires_after.seconds noklusējuma vērtība ir 600, bet maksimālā – 3600.
  • Pārlūkprogrammā žetons tiek ievietots apakšprotokolā xai-client-secret.<token>.
  • Tavam backend ir jāpārbauda autentifikācija un atļaujas pirms žetona ģenerēšanas.
  • Nekad neeksponē savu API atslēgu klienta pusē, URL adresēs vai žurnālos.
  • HTTP TTS gadījumā maršrutēšana caur tavu backend ir derīga alternatīva žetoniem ar īsu dzīves laiku.