Ephemeral tokens

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

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

Вот как работают эфемерные токены на высоком уровне:

1. Ваш клиент (например, веб-приложение) аутентифицируется на вашем бэкэнде.
2. Ваш бэкэнд запрашивает эфемерный токен у службы предоставления API Gemini.
3. Gemini API выпускает краткосрочный токен.
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(
    api_key="GEMINI_API_KEY",
    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({ apiKey: "GEMINI_API_KEY" });
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(
    api_key="GEMINI_API_KEY",
    http_options={'api_version': 'v1alpha',}
)

token = client.auth_tokens.create(
    config = {
    'uses': 1,
    'live_connect_constraints': {
        'model': 'gemini-2.0-flash-live-001',
        'config': {
            'session_resumption':{},
            'temperature':0.7,
            'response_modalities':['TEXT']
        }
    },
    '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({ apiKey: "GEMINI_API_KEY" });
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-2.0-flash-live-001',
            config: {
                sessionResumption: {},
                temperature: 0.7,
                responseModalities: ['TEXT']
            }
        },
        httpOptions: {
            apiVersion: 'v1alpha'
        }
    }
});

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

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

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

Вот пример, который подключается к Live API через эфемерный токен. Обратите внимание, что использование эфемерных токенов добавляет ценность только при развертывании приложений, которые следуют подходу реализации клиент-сервер .

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-2.0-flash-live-001';
const config = { responseModalities: [Modality.TEXT] };

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 по эфемерным токенам.