Ephemeral tokens

Эфемерные токены — это кратковременные токены аутентификации для доступа к API Gemini через WebSockets . Они предназначены для повышения безопасности при прямом подключении к API с устройства пользователя (реализация «клиент-сервер» ). Как и стандартные ключи API, эфемерные токены могут быть получены из клиентских приложений, таких как веб-браузеры или мобильные приложения. Но поскольку эфемерные токены быстро истекают и могут быть ограничены, они значительно снижают риски безопасности в производственной среде. Их следует использовать при прямом доступе к Live API из клиентских приложений для повышения безопасности ключей API.

Как работают эфемерные токены

Вот как в общих чертах работают эфемерные токены:

1. Ваш клиент (например, веб-приложение) проходит аутентификацию на вашем бэкэнде.
2. Ваш бэкэнд запрашивает временный токен у службы предоставления ресурсов API Gemini.
3. API Gemini выпускает краткосрочный токен.
4. Ваш бэкэнд отправляет токен клиенту для установления WebSocket-соединений с Live API. Это можно сделать, заменив ваш API-ключ на временный токен.
5. Затем клиент использует токен так же, как если бы это был ключ API.

Это повышает безопасность, поскольку даже если токен будет извлечен, он будет иметь короткий срок действия, в отличие от долгоживущего ключа API, развернутого на стороне клиента. Поскольку клиент отправляет данные напрямую в Gemini, это также улучшает задержку и избавляет ваши бэкэнды от необходимости использовать прокси для передачи данных в реальном времени.

Создать временный токен

Вот упрощенный пример того, как получить временный токен от Gemini. По умолчанию у вас будет 1 минута для запуска новых сессий Live API с использованием токена из этого запроса ( newSessionExpireTime ) и 30 минут для отправки сообщений по этому соединению ( expireTime ).

import datetime

now = datetime.datetime.now(tz=datetime.timezone.utc)

client = genai.Client(
    http_options={'api_version': 'v1alpha',}
)

token = client.auth_tokens.create(
    config = {
    'uses': 1, # The ephemeral token can only be used to start a single session
    'expire_time': now + datetime.timedelta(minutes=30), # Default is 30 minutes in the future
    # 'expire_time': '2025-05-17T00:00:00Z',   # Accepts isoformat.
    'new_session_expire_time': now + datetime.timedelta(minutes=1), # Default 1 minute in the future
    'http_options': {'api_version': 'v1alpha'},
  }
)

# You'll need to pass the value under token.name back to your client to use it

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();

  const token: AuthToken = await client.authTokens.create({
    config: {
      uses: 1, // The default
      expireTime: expireTime, // Default is 30 mins
      newSessionExpireTime: new Date(Date.now() + (1 * 60 * 1000)), // Default 1 minute in the future
      httpOptions: {apiVersion: 'v1alpha'},
    },
  });

Ограничения значения expireTime , значения по умолчанию и другие характеристики поля см. в справочнике API . В течение заданного временного интервала expireTime необходимо, чтобы sessionResumption переподключал вызов каждые 10 минут (это можно сделать с тем же токеном, даже если uses: 1 ).

Также можно привязать временный токен к определенному набору конфигураций. Это может быть полезно для дальнейшего повышения безопасности вашего приложения и хранения системных инструкций на стороне сервера.

client = genai.Client(
    http_options={'api_version': 'v1alpha',}
)

token = client.auth_tokens.create(
    config = {
    'uses': 1,
    'live_connect_constraints': {
        'model': 'gemini-3.1-flash-live-preview',
        'config': {
            'session_resumption':{},
            'temperature':0.7,
            'response_modalities':['AUDIO']
        }
    },
    'http_options': {'api_version': 'v1alpha'},
    }
)

# You'll need to pass the value under token.name back to your client to use it

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();

const token = await client.authTokens.create({
    config: {
        uses: 1, // The default
        expireTime: expireTime,
        liveConnectConstraints: {
            model: 'gemini-3.1-flash-live-preview',
            config: {
                sessionResumption: {},
                temperature: 0.7,
                responseModalities: ['AUDIO']
            }
        },
        httpOptions: {
            apiVersion: 'v1alpha'
        }
    }
});

// You'll need to pass the value under token.name back to your client to use it

Вы также можете заблокировать подмножество полей; подробную информацию см. в документации SDK .

Подключитесь к Live API с помощью временного токена.

Получив временный токен, вы можете использовать его так же, как и ключ API (но помните, что он работает только с действующим API и только с версией v1alpha ).

Использование временных токенов имеет смысл только при развертывании приложений, использующих подход "клиент-сервер" .

import { GoogleGenAI, Modality } from '@google/genai';

// Use the token generated in the "Create an ephemeral token" section here
const ai = new GoogleGenAI({
  apiKey: token.name
});
const model = 'gemini-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: { ... },
  });

  // Send content...

  session.close();
}

main();

Дополнительные примеры см. в разделе «Начало работы с Live API» .

Передовые методы

• Установите короткий срок действия, используя параметр expire_time .
• Срок действия токенов истекает, что требует повторного запуска процесса предоставления токенов.
• Убедитесь в надежности аутентификации для вашей собственной серверной части. Безопасность временных токенов зависит от метода аутентификации вашей серверной части.
• Как правило, следует избегать использования временных токенов для соединений между бэкэндом и Gemini, поскольку этот путь обычно считается безопасным.

Ограничения

В настоящее время временные токены совместимы только с Live API .

Что дальше?

• Для получения более подробной информации ознакомьтесь со справочником по Live API для временных токенов.