Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Comhthaobhán sealadacha agus slándáil

Ceacht 13 as 14 Nuashonraithe 3 Samhain 2026 Meánleibhéal
Ar an leathanach seo
  1. An fhadhb le heochair API ar an gcliant
  2. Conas a oibríonn sé
  3. An ailtireacht ó cheann go ceann
  4. Rialacha nach mór duit a bhriseadh riamh
  5. Príomhphointí

Nuashonraithe an 3 Samhain 2026, bunaithe ar thagairt API Gutha xAI. Foinse: Comhthaobhán Sealadacha · Tagairt API Gutha · Athshumú Seisiúin.

An fhadhb le heochair API ar an gcliant

Ní féidir le feidhmchlár gutha atá ag rith i mbrabhsálaí nó ar ghuthán do eochair API a sheachadadh. Is féidir le haon chuairteoir uirlisí an fhorbróra a oscailt, an t-eochair a léamh ó bhunachar JavaScript nó ó cheanntásc iarratais, agus ansin é a úsáid ar do chuntas go dtí go mbeidh do chuóta ídithe. Ní chosnaíonn aon méid doiléirithe luach a chaithfidh an cliant a bheith aige chun glaoch ar an API.

Is é freagra xAI ná comhthaobhán sealadacha, ar a dtugtar rúin chliaint freisin: comhthaobhán gearrshaolach, a ghineann do fhreastalaí, a údaróidh seisiún gutha agus aon rud eile seachas sin.

600s
ré shaol réamhshocraithe
3600s
uasmhéid ré shaol
POST
/v1/realtime/client_secrets
luach
an comhthaobhán, le expires_at

Conas a oibríonn sé

Tagann an sruth anuas ar chúig chéim:

  1. Glaoíonn do chúldeireadh (freastalaí slán) ar POST /v1/realtime/client_secrets le do eochair API
  2. Tugann an API comhthaobhán sealadach ar ais le ré shaol teoranta
  3. Seolann do chúldeireadh an comhthaobhán sin chuig an cliant (brabhsálaí nó feidhmchlár soghluaiste)
  4. Úsáideann an cliant an comhthaobhán chun ceangal le WebSocket an Ghníomhaire Gutha
  5. Téann an comhthaobhán in éag tar éis na ré saoil a roghnaigh tú (expires_after.seconds)

Tá luach i bhfad níos lú anois ar rud ar bith a d’fhéadfadh sceitheadh ar thaobh an chliaint: comhthaobhán a théann in éag laistigh de nóiméid agus nach féidir leis ach seisiún gutha a oscailt, seachas do eochair API. Ar an bhfreastalaí, ní ghlacann sé ach cúpla líne cód ceann a ghiniúint. Tabhair faoi deara go dtosaíonn an láimhseálaí trí sheiceáil a dhéanamh ar an úsáideoir: gan an seiceáil sin, ní bheadh i do chúldeireadh ach dáileoir poiblí comhthaobhán.

// Cúldeireadh Node.js (Express)
app.post("/api/voice-token", async (req, res) => {
  // Seiceáil go bhfuil an t-úsáideoir fíordheimhnithe
  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 nóiméad, an réamhshocrú
      })
    }
  );

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

Níl a fhios ag an gcliant ach do bhealach do féin: iarrann sé comhthaobhán, agus ansin osclaíonn sé an WebSocket leis.

// Tosaigh (brabhsálaí)
async function startVoiceSession() {
  // Iarr comhthaobhán ar an gcúldeireadh
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // Ní ghlacann WebSocket an bhrabhsálaí le ceanntáscanna:
  // téann an comhthaobhán i bhfo-phrótacal, réamhlitrithe le "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... cumraíocht an tseisiúin
}

An ailtireacht ó cheann go ceann

Le chéile, tosaíonn an sruth leis an úsáideoir ag síniú isteach i d’fheidhmchlár. Iarrann a chliant comhthaobhán gutha ansin ar do chúldeireadh, agus déanann an cúldeireadh seiceáil ar fhíordheimhniú agus ar cheadanna sula ngineann sé an comhthaobhán sealadach trí API xAI. Taistealaíonn an comhthaobhán ar ais chuig an gcliant, a úsáideann é chun seisiún an Ghníomhaire Gutha a oscailt, agus téann sé in éag go huathoibríoch ag deireadh a ré saoil.

Déanann an seiceáil sin idir an t-iarratas agus an ghiniúint as seachadán simplí seicphointe, agus is ann a chónaíonn do rialacha gnó. Is féidir leat uasteorainn a chur le líon na seisiún gutha in aghaidh an úsáideora in aghaidh an lae, ionas nach féidir le cuntas amháin do bhuiséad míosúil a dhó thar oíche. Is féidir leat comhthaobháin a chur in áirithe do shíntiúis ghníomhacha, ag cur do mhúnla gnó i bhfeidhm in áit éigin seachas an comhéadan. Is féidir leat teorainn ráta a chur ar iarratais, ionas nach féidir le cliant atá fabhtach nó mailíseach míle comhthaobhán a iarradh in aghaidh an nóiméid. Agus is féidir leat logáil a dhéanamh ar gach comhthaobhán a ghineann tú: is é sin do bhonn iontaofa amháin le haghaidh monatóireachta, billeála inmheánaí, agus anailíse ar tharluithe.

Rialacha nach mór duit a bhriseadh riamh

Ní théann an t-eochair API chuig an gcliant riamh, in aon fhoirm. Coinnigh amach as JavaScript tosaigh agus as aon athróg timpeallachta atá nochttha don tógáil brabhsálaí (críochnaíonn athróga atá réamhlitrithe le bheith insteallta sa bhunachar go poiblí). Coinnigh amach as URLanna, logaí, agus teachtaireachtaí earráide a thaispeántar d’úsáideoirí freisin.

Ina theannta sin, coinigh an ré shaol chomh gearr agus is praiticiúil. De réir na tagairte API, is é 600 soicind réamhshocrú expires_after.seconds agus is é 3,600 an t-uasmhéid; úsáideann an doiciméadú 300 ina shamplaí. Os cionn gach rud eile, ní mór an comhthaobhán a bheith bailí nuair a osclaíonn an cliant an ceangal. Laghdaíonn ré shaol gairid an fhuinneog ama ina bhféadfar comhthaobhán idirghafa a úsáid.

Ní luaitear sa doiciméadú an gcuireann comhthaobhán atá ag dul in éag deireadh le ceangal atá ar oscailt cheana féin. Má theastaíonn ó do chliant athcheangal, tar éis titim líonra nó le linn seisiúin an-fhada, iarr comhthaobhán nua agus úsáid athshumú seisiúin: cumasaigh resumption.enabled i session.update, coinnigh an ID a fhaigheann tú i conversation.created, ansin athoscail an WebSocket le ?conversation_id=<id>. Déantar na casanna roimhe seo a athsheinm, agus leanann an tsamhail ar aghaidh ón áit ar fhág 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 } },  // seol arís ar gach ceangal
  }));
  return ws;
}

Le haghaidh TTS i mód HTTP, tá rogha níos simplí fós ann seachas comhthaobháin: seachfhreastalaí. Seolann an cliant a chuid téacs chuig do chúldeireadh, agus glaonn do chúldeireadh ar TTS agus filleann sé an fuaime. Ní fhágann an t-eochair do fhreastalaí riamh, agus faigheann tú áit nádúrtha chun ábhar a scagadh agus úsáid a thomhas ar an mbealach.

Príomhphointí

  • Dearbhaíonn comhthaobháin sealadacha rochtain ar an nGníomhaire Gutha ó fheidhmchláir taobh chliaint
  • Filleann POST /v1/realtime/client_secrets value agus expires_at; is é 600 réamhshocrú expires_after.seconds agus is é 3,600 an t-uasmhéid
  • Sa bhrabhsálaí, téann an comhthaobhán san fho-phrótacal xai-client-secret.<token>
  • Ní mór do do chúldeireadh fíordheimhniú agus ceadanna a sheiceáil sula ngineann sé comhthaobhán
  • Ná nocht do eochair API riamh ar an gcliant, in URLanna, ná i logaí
  • Le haghaidh TTS HTTP, is rogha bhailí é seachfhreastalaíocht trí do chúldeireadh in ionad comhthaobhán sealadach