Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Ephemerni žetoni in varnost

Lekcija 13 od 14 Posodobljeno 3. november 2026 Srednje napredni
Na tej strani
  1. Težava s ključem API na strani odjemalca
  2. Kako deluje
  3. Arhitektura od konca do konca
  4. Pravila, ki jih nikoli ne smeš kršiti
  5. Ključne ugotovitve

Posodobljeno 3. novembra 2026 na podlagi referenčne dokumentacije za xAI Voice API. Viri: Ephemerni žetoni · Referenca za Voice API · Nadaljevanje seje.

Težava s ključem API na strani odjemalca

Glasovna aplikacija, ki teče v brskalniku ali na telefonu, ne sme vsebovati tvojega ključa API. Vsak obiskovalec lahko odpre orodja za razvijalce, prebere ključ iz paketa JavaScript ali glave zahteve in ga nato uporabi na tvojem računu, dokler se tvoja kvota ne izčrpa. Nobena količina prikrivanja ne more zaščititi vrednosti, ki jo mora odjemalec imeti za klicanje API-ja.

xAI-jev odgovor so ephemerni žetoni, imenovani tudi skrivnosti odjemalca: kratkotrajni žeton, ki ga generira tvoj strežnik in pooblašča izključno glasovno sejo, ničesar drugega.

600s
privzeta življenjska doba
3600s
najdaljša življenjska doba
POST
/v1/realtime/client_secrets
value
žeton z expires_at

Kako deluje

Postopek obsega pet korakov:

  1. Tvoje zaledje (varen strežnik) pokliče POST /v1/realtime/client_secrets s tvojim ključem API.
  2. API vrne začasni žeton z omejeno življenjsko dobo.
  3. Tvoje zaledje pošlje ta žeton odjemalcu (brskalnik ali mobilna aplikacija).
  4. Odjemalec uporabi žeton za povezavo z WebSocketom glasovnega agenta.
  5. Žeton poteče po življenjski dobi, ki si jo izbral (expires_after.seconds).

Kar lahko uhaja na strani odjemalca, ima zdaj veliko manjšo vrednost: žeton, ki poteče v nekaj minutah in lahko odpre le glasovno sejo, ne pa tvojega ključa API. Na strežniku generiranje traja le nekaj vrstic kode. Opazi, da rokavec najprej preveri uporabnika: brez tega preverjanja je tvoje zaledje le javni razdeljevalec žetonov.

// Zaledje v Node.js (Express)
app.post("/api/voice-token", async (req, res) => {
  // Preveri, ali je uporabnik avtenticiran
  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 minut, privzeto
      })
    }
  );

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

Odjemalec pozna le tvojo pot: zahteva žeton, nato pa z njim odpre WebSocket.

// Odjemalec (brskalnik)
async function startVoiceSession() {
  // Zahtevaj žeton od zaledja
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // Brskalniški WebSocket ne sprejema glav:
  // žeton gre v podprotokol s predpono "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... konfiguracija seje
}

Arhitektura od konca do konca

Če vse skupaj združimo, se postopek začne s prijavo uporabnika v tvojo aplikacijo. Njegov odjemalec nato od tvojega zaledja zahteva glasovni žeton, zaledje pa pred generiranjem ephemerne žetona prek API-ja xAI preveri avtenticacijo in dovoljenja. Žeton potuje nazaj do odjemalca, ki ga uporabi za odprtje seje glasovnega agenta, ob koncu življenjske dobe pa samodejno poteče.

To preverjanje med zahtevo in generiranjem spremeni preprost rele v kontrolno točko, kjer živijo tvoja poslovna pravila. Lahko omejiš število glasovnih sej na uporabnika na dan, tako da en račun čez noč ne more porabiti tvojega mesečnega proračuna. Žetone lahko rezerviraš za aktivne naročnine in s tem uveljaviš svoj poslovni model drugje kot le v vmesniku. Zahteve lahko omejiš po pogostosti, da pokvarjen ali zlonameren odjemalec ne more zahtevati tisoč žetonov na minuto. In vsak generirani žeton lahko beležiš: to je tvoja edina zanesljiva osnova za nadzor, interno obračunavanje in analizo incidentov.

Pravila, ki jih nikoli ne smeš kršiti

Ključ API nikoli ne sme priti do odjemalca, v nobeni obliki. Hrani ga stran od JavaScripta na sprednji strani in stran od katere koli spremenljivke okolja, ki je izpostavljena gradnji za brskalnik (spremenljivke s predpono za vbrizganje v paket na koncu postanejo javne). Hrani ga tudi stran od URL-jev, dnevnikov in sporočil o napakah, ki so prikazana uporabnikom.

Naslednje: življenjsko dobo ohrani čim krajšo, kolikor je praktično. Glede na referenčno dokumentacijo API-ja je expires_after.seconds privzeto nastavljen na 600 sekund, največ pa znaša 3.600; dokumentacija v svojih primerih uporablja 300. Predvsem mora biti žeton veljaven, ko odjemalec odpre povezavo. Kratka življenjska doba skrči časovno okno, v katerem lahko prestreženi žeton uporabijo.

Dokumentacija ne navaja, ali žeton, ki poteče, prekine že odprto povezavo. Če se mora tvoj odjemalec ponovno povezati po izpadu omrežja ali med zelo dolgo sejo, zahtevaj nov žeton in uporabi nadaljevanje seje: omogoči resumption.enabled v session.update, ohrani ID, ki ga prejmeš v conversation.created, nato pa ponovno odpri WebSocket z ?conversation_id=<id>. Prejšnji obrati se predvajajo znova in model nadaljuje tam, kjer je končal.

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 } },  // pošlji znova ob vsaki povezavi
  }));
  return ws;
}

Za TTS v načinu HTTP obstaja še enostavnejša alternativa žetonom: posredniški strežnik. Odjemalec pošlje besedilo tvojemu zaledju, tvoje zaledje pokliče TTS in vrne zvok. Ključ nikoli ne zapusti tvojega strežnika, ti pa dobiš naravno mesto za filtriranje vsebine in merjenje uporabe med potjo.

Ključne ugotovitve

  • Ephemerni žetoni varujejo dostop do glasovnega agenta iz aplikacij na strani odjemalca.
  • POST /v1/realtime/client_secrets vrne value in expires_at; expires_after.seconds je privzeto 600, največ 3.600.
  • V brskalniku žeton gre v podprotokol xai-client-secret.<žeton>.
  • Tvoje zaledje mora pred generiranjem žetona preveriti avtenticacijo in dovoljenja.
  • Nikoli ne izpostavljaj svojega ključa API na strani odjemalca, v URL-jih ali dnevnikih.
  • Za HTTP TTS je posredovanje prek tvojega zaledja veljavna alternativa ephemernim žetonom.