Ephemeral tokens

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

临时令牌的运作方式

以下是暂时性令牌的大致运作方式：

您的客户端（例如 Web 应用）会与您的后端进行身份验证。
您的后端从 Gemini API 的配置服务请求临时令牌。
Gemini API 会发出短期有效的令牌。
您的后端将令牌发送给客户端，以便客户端与 Live API 建立 WebSocket 连接。为此，您可以将 API 密钥换成临时令牌。
然后，客户端会像使用 API 密钥一样使用令牌。

瞬时令牌概览

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

创建临时令牌

下面是一个简化示例，展示了如何从 Gemini 获取暂时性令牌。默认情况下，您有 1 分钟的时间来使用此请求中的令牌 (newSessionExpireTime) 启动新的实时 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 时间范围内，您需要每 10 分钟使用 sessionResumption 重新连接一次通话（即使 uses: 1，也可以使用相同的令牌执行此操作）。

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

Python

client = genai.Client(
    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

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-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。请注意，只有在部署遵循客户端到服务器实现方法的应用时，使用暂时性令牌才会带来价值。

JavaScript

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

// Use the token generated in the "Create an ephemeral token" section here
const ai = new GoogleGenAI({});
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 参考文档。