Ephemeral tokens

临时令牌是短期有效的身份验证令牌，用于通过 WebSockets 访问 Gemini API。它们旨在增强从用户设备直接连接到 API（ 客户端到服务器 实现）时的安全性。与标准 API 密钥一样，临时令牌可以从 Web 浏览器或移动应用等客户端应用中提取。但由于临时令牌会快速过期且可以受到限制，因此它们可以显著降低生产环境中的安全风险。当您直接从客户端应用访问 Live API 时，应使用它们来增强 API 密钥的安全性。

临时令牌的工作原理

下面简要介绍了临时令牌的工作原理：

  1. 您的客户端（例如 Web 应用）通过您的后端进行身份验证。
  2. 您的后端向 Gemini API 的预配服务请求临时令牌。
  3. Gemini API 会颁发一个短期有效的令牌。
  4. 您的后端会将该令牌发送给客户端，以便通过 WebSocket 连接到 Live API。您可以通过将 API 密钥替换为临时令牌来完成此操作。
  5. 然后，客户端会像使用 API 密钥一样使用该令牌。

临时令牌概览

这可以增强安全性，因为即使提取了令牌，该令牌也是短期有效的，这与部署在客户端的长期有效的 API 密钥不同。由于客户端直接向 Gemini 发送数据，因此这还可以缩短延迟时间，并避免后端需要代理实时数据。

创建临时令牌

下面是一个简化的示例，说明了如何从 Gemini 获取临时令牌。 默认情况下，您将有 1 分钟的时间来使用此请求中的令牌 (newSessionExpireTime) 启动新的 Live API 会话，以及 30 分钟的时间通过该连接发送消息 (expireTime)。

Python

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

JavaScript

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，也可以使用同一令牌完成此操作）。

您还可以将临时令牌锁定到一组配置。这有助于进一步提高应用的安全性，并将系统说明保留在服务器端。

Python

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

JavaScript

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 密钥一样使用它（但请注意，它仅适用于 Live API，并且仅适用于 API 的 v1alpha 版本）。

仅当部署遵循客户端到服务器实现方法应用 时，使用临时令牌才有价值。

JavaScript

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 参考文档 。