Fíordheimhniú agus comharthaí sealadacha
Ar an leathanach seo
Dhá bhealach le fíordheimhniú a dhéanamh
Tá dhá bhealach ar fáil sa Voice Agent API chun do nasc WebSocket a fhíordheimhniú. Braitheann an ceann a roghnaíonn tú ar an áit a ritheann do chód: ar an bhfreastalaí nó ar an gcliant.
Eochair API dhíreach (taobh an fhreastalaí)
Is é an modh is simplí ná d’eochair API a chur sa cheanntásc údaraithe nuair a osclaíonn tú an WebSocket. Oibríonn sé seo d’fheidhmchláir fhreastalaí, áit a bhfanann an eochair faoi chosaint:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Ná húsáid an modh seo riamh i gcód a ritheann sa bhrabhsálaí: nochtfaí an eochair API sa chód foinseach nó sna huirlisí forbróra.
Comharthaí sealadacha (taobh an chliaint)
Do fheidhmchláir front-end (brabhsálaí, soghluaiste), soláthraíonn xAI comharthaí sealadacha. Gineann do chúlchóras comhartha gearrshaolach, a chuireann tú ar fáil don chliant ansin chun an nasc WebSocket a oscailt.
Cruthaíonn tú comhartha le hiarratas POST:
curl -X POST "https://api.x.ai/v1/realtime/client_secrets" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expires_after": {"seconds": 300}}'
Socraíonn an réimse expires_after.seconds cá fhad a bheidh an comhartha bailí, i soicind. Úsáideann sampla na doiciméadachta oifigiúla 300 soicind (5 nóiméad): tá comhartha sealadach ceaptha chun seisiún gutha a chlúdach, ní chun maireachtáil go ceann i bhfad. Dírich ar an saolré is giorra a oireann do do sheisiúin.
Ailtireacht mholta le comharthaí sealadacha
Seo an sruth iomlán d’fheidhmchlár gréasáin:
// 1. Taobh an fhreastalaí (Node.js/Express): gin an comhartha
app.post("/api/realtime-token", async (req, res) => {
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 } })
}
);
// Fill corp freagartha xAI mar atá sé;
// tá an comhartha sealadach ann
res.json(await response.json());
});
// 2. Taobh an chliaint (brabhsálaí): úsáid an comhartha
// Ní ghlacann tógálaí WebSocket an bhrabhsálaí le ceanntásca:
// cuirtear an comhartha i bhFO-PRÓTACAL, réamhaithe le "xai-client-secret."
async function startVoiceSession(ephemeralToken) {
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime",
[`xai-client-secret.${ephemeralToken}`]
);
ws.onopen = () => {
console.log("Voice session started");
};
}
Comharthaí a athnuachan
Ní luaitear sa doiciméadacht an ndúnann comhartha atá ag dul in éag nasc atá oscailte cheana féin. Cibé scéal é, ní mór plean a bheith ag d’fheidhmchlár don uair a thiteann an nasc: bí ar an airdeall don imeacht dúnta, iarr comhartha nua ó do chúlchóras, agus athnasc ansin:
ws.onclose = async () => {
// Cailltear an nasc nó dúnadh é: iarr comhartha nua
const newToken = await fetchNewToken();
reconnect(newToken);
};
Dea-chleachtais slándála
Coinníonn roinnt rialacha riachtanacha do naisc slán:
- Ná nocht riamh do phríomheochair API ar an gcliant
- Coinnigh an saolré (
expires_after.seconds) chomh gearr agus is féidir: má mhaireann do sheisiún meánach cúig nóiméad, tá 300 go 600 soicind go leor - Fíordheimhnigh iarratais comhartha ar an bhfreastalaí (fíordheimhniú úsáideora, teorannú ráta)
- Déan logáil ar chruthú comhartha ionas gur féidir leat úsáid mhínormálta a bhrath
- Rothlaigh do phríomheochair API má amhras tú go bhfuil sí curtha i mbaol
Príomhphointí
- Níl eochair API dhíreach oiriúnach ach d’fheidhmchláir fhreastalaí
- Tá comharthaí sealadacha riachtanach d’fheidhmchláir taobh an chliaint (brabhsálaí, soghluaiste)
- Socraigh saolré an chomhartha le
expires_after.secondsagus coinnigh gearr é (300 soicind sa sampla oifigiúil) - Is é an sruth molta: gineann do chúlchóras an comhartha, agus cuireann do thosaigh ar fáil é mar an fho-phrótacal
xai-client-secret.chun an WebSocket a oscailt - Pleanáil i gcónaí d’athnuachan uathoibríoch comharthaí