Премини към основното съдържание
Български— Изберете език
Меню

Ефемерни токени и сигурност

Урок 13 от 14 Обновен 3 ноември 2026 г. Средно
На тази страница
  1. Проблемът с API ключа на клиента
  2. Как работи
  3. Архитектура от край до край
  4. Правила, които никога не трябва да нарушавате
  5. Ключови изводи

Обновено на 3 ноември 2026 г., въз основа на справочника за xAI Voice API. Източници: Ефемерни токени · Справочник за Voice API · Възобновяване на сесията.

Проблемът с API ключа на клиента

Гласово приложение, работещо в браузър или на телефон, не може да включва Вашия API ключ. Всеки посетител може да отвори инструментите за разработчици, да прочете ключа от JavaScript пакета или заглавката на заявката и след това да го използва във Вашия акаунт, докато квотата Ви не се изчерпи. Никаква степен на маскиране не защитава стойност, която клиентът трябва да притежава, за да извика API.

Отговорът на xAI са ефемерните токени, наричани още клиентски секрети: краткотраен токен, генериран от Вашия сървър, който упълномощава гласова сесия и нищо друго.

600s
живот по подразбиране
3600s
максимален живот
POST
/v1/realtime/client_secrets
стойност
токенът, с expires_at

Как работи

Процесът се свежда до пет стъпки:

  1. Вашият бекенд (сигурен сървър) извиква POST /v1/realtime/client_secrets с Вашия API ключ
  2. API връща временен токен с ограничен срок на валидност
  3. Вашият бекенд изпраща този токен до клиента (браузър или мобилно приложение)
  4. Клиентът използва токена, за да се свърже с WebSocket на гласовия агент
  5. Токенът изтича след избрания от Вас срок (expires_after.seconds)

Това, което може да изтече от страна на клиента, сега струва много по-малко: токен, който изтича за минути и може само да отвори гласова сесия, а не Вашия API ключ. На сървъра генерирането му отнема няколко реда код. Обърнете внимание, че обработчикът започва с проверка на потребителя: без тази проверка Вашият бекенд е просто публичен диспенсър за токени.

// Node.js бекенд (Express)
app.post("/api/voice-token", async (req, res) => {
  // Проверка дали потребителят е автентикиран
  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 минути, стойността по подразбиране
      })
    }
  );

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

Клиентът познава само Вашия собствен маршрут: той иска токен, след което отваря WebSocket с него.

// Фронтенд (браузър)
async function startVoiceSession() {
  // Заявка към бекенда за токен
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // WebSocket на браузъра не приема заглавки:
  // токенът отива в подпротокол, с префикс "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... конфигурация на сесията
}

Архитектура от край до край

Като цяло, процесът започва с влизането на потребителя във Вашето приложение. След това неговият клиент иска гласов токен от Вашия бекенд, а бекендът проверява автентикацията и разрешенията, преди да генерира ефемерния токен чрез xAI API. Токенът се връща обратно към клиента, който го използва, за да отвори сесията на гласовия агент, и той изтича автоматично в края на своя живот.

Тази проверка между заявката и генерирането превръща простото реле в контролна точка и точно там живеят Вашите бизнес правила. Можете да ограничите броя на гласовите сесии на потребител на ден, така че един акаунт да не може да изразходи месечния Ви бюджет за една нощ. Можете да запазите токени за активни абонаменти, налагайки Вашия бизнес модел някъде извън интерфейса. Можете да ограничите честотата на заявките, така че дефектен или злонамерен клиент да не може да иска хиляда токена в минута. И можете да записвате всеки генериран токен: това е единствената Ви надеждна основа за мониторинг, вътрешно фактуриране и анализ на инциденти.

Правила, които никога не трябва да нарушавате

API ключът никога не отива при клиента, под никаква форма. Пазете го далеч от фронтенд JavaScript и от всяка променлива на средата, изложена на браузър билда (променливи с префикс за инжектиране в пакета стават публични). Дръжте го далеч и от URL адреси, логове и съобщения за грешки, показвани на потребителите.

След това, поддържайте живота възможно най-кратък, доколкото е практично. Според справочника за API, expires_after.seconds по подразбиране е 600 секунди и достига максимум 3600; документацията използва 300 в своите примери. Над всичко, токенът трябва да е валиден, когато клиентът отваря връзката. Краткият живот свива прозореца, през който прихванат токен може да бъде използван.

Документацията не посочва дали изтичащият токен прекъсва вече отворена връзка. Ако Вашият клиент трябва да се свърже отново след прекъсване на мрежата или по време на много дълга сесия, поискайте нов токен и използвайте възобновяване на сесията: активирайте resumption.enabled в session.update, запазете ID, което получавате в conversation.created, след което отворете отново WebSocket с ?conversation_id=<id>. Предишните размени се възпроизвеждат и моделът продължава оттам, където е спрял.

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 } },  // изпращане отново при всяка връзка
  }));
  return ws;
}

За TTS в HTTP режим има още по-проста алтернатива на токените: прокси. Клиентът изпраща своя текст до Вашия бекенд, а Вашият бекенд извиква TTS и връща аудиото. Ключът никога не напуска Вашия сървър и получавате естествено място за филтриране на съдържанието и измерване на използването по пътя.

Ключови изводи

  • Ефемерните токени осигуряват достъп до гласовия агент от приложения от страна на клиента
  • POST /v1/realtime/client_secrets връща value и expires_at; expires_after.seconds по подразбиране е 600 и достига максимум 3600
  • В браузъра токенът отива в подпротокола xai-client-secret.<token>
  • Вашият бекенд трябва да проверява автентикацията и разрешенията преди генериране на токен
  • Никога не излагайте Вашия API ключ на клиента, в URL адреси или в логове
  • За HTTP TTS, проксирането през Вашия бекенд е валидна алтернатива на ефемерните токени