Ephemerni žetoni in varnost
Na tej strani
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.
Kako deluje
Postopek obsega pet korakov:
- Tvoje zaledje (varen strežnik) pokliče
POST /v1/realtime/client_secretss tvojim ključem API. - API vrne začasni žeton z omejeno življenjsko dobo.
- Tvoje zaledje pošlje ta žeton odjemalcu (brskalnik ali mobilna aplikacija).
- Odjemalec uporabi žeton za povezavo z WebSocketom glasovnega agenta.
- Ž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_secretsvrnevalueinexpires_at;expires_after.secondsje 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.