Live API 临时 token
临时 token 是短暂的身份验证 token,用于通过以下方式访问 Gemini API WebSocket。它们旨在增强从用户设备直接连接到 API(a 客户端到服务器 实施)。与标准 API 密钥一样,临时 token 可以从客户端应用程序(例如 Web 浏览器或移动应用程序)中提取。但由于临时 token 很快就会过期并且可以受到限制,因此它们可以显着降低生产环境中的安全风险。您应该在直接从客户端应用程序访问 Live API 时使用它们,以增强 API 密钥的安全性。
临时 token 的工作原理 #
以下是临时 token 在高级别上的工作方式:
- 您的客户端(例如网络应用程序)通过您的后端进行身份验证。
- 您的后端从 Gemini API 的配置服务请求临时 token。
- Gemini API 发行了一个短暂的 token。
- 您的后端将 token 发送到客户端,以实现与 Live API 的 WebSocket 连接。您可以通过将 API 密钥替换为临时 token 来完成此操作。
- 然后,客户端使用 token,就好像它是 API 密钥一样。

这增强了安全性,因为即使被提取,token 的寿命也是短暂的,这与长期部署在客户端的 API 密钥不同。由于客户端直接将数据发送到 Gemini,这也改善了延迟并避免后端需要代理实时数据。
创建一个临时的 token #
以下是如何从 Gemini 获取临时 token 的简化示例。默认情况下,您将有 1 分钟的时间使用此请求中的 token 启动新的 Live API 会话(newSessionExpireTime),以及通过该连接发送消息的 30 分钟(expireTime).
import datetime
from google import genai
now = datetime.datetime.now(tz=datetime.timezone.utc)
client = genai.Client(http_options={"api_version": "v1beta"})
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
}
)
# 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({ httpOptions: { apiVersion: "v1beta" } });
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();
const token = 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
},
});
curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"uses": 1,
"expireTime": "YYYY-MM-DDTHH:MM:SSZ",
"newSessionExpireTime": "YYYY-MM-DDTHH:MM:SSZ"
}'
对于 expireTime 值约束、默认值和其他字段规范,请参阅 API参考。内 expireTime 时间范围,你需要 sessionResumption 每 10 分钟重新连接呼叫(这可以使用相同的 token 完成,即使 uses: 1).
还可以将临时 token 锁定到一组配置。这可能有助于进一步提高应用程序的安全性并将系统指令保留在服务器端。
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
token = client.auth_tokens.create(
config = {
'uses': 1,
'live_connect_constraints': {
'model': 'gemini-3.8-live',
'config': {
'session_resumption':{},
'response_modalities':['AUDIO']
}
},
}
)
# 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({ httpOptions: { apiVersion: "v1beta" } });
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.8-live',
config: {
sessionResumption: {},
responseModalities: ['AUDIO']
}
},
}
});
// You'll need to pass the value under token.name back to your client to use it
curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"uses": 1,
"expireTime": "YYYY-MM-DDTHH:MM:SSZ",
"liveConnectConstraints": {
"model": "models/gemini-3.8-live",
"config": {
"sessionResumption": {},
"responseModalities": ["AUDIO"]
}
}
}'
您还可以锁定字段的子集,请参阅 SDK 文档 了解更多信息。
使用临时 token 连接到 Live API #
一旦您拥有了临时 token,您就可以像使用 API 密钥一样使用它(但请记住,它仅适用于实时 API,并且仅适用于 v1beta API 版本)。
使用临时 token 仅在部署遵循以下规则的应用程序时增加价值 客户端到服务器的实现 方法。
import { GoogleGenAI, Modality } from '@google/genai';
// Use the token generated in the "Create an ephemeral token" section here
const ai = new GoogleGenAI({
httpOptions: { apiVersion: "v1beta" },
apiKey: token.name
});
const model = 'gemini-3.8-live';
const config = { responseModalities: [Modality.AUDIO] };
async function main() {
const session = await ai.live.connect({
model: model,
config: config,
callbacks: { ... },
});
// Send content...
session.close();
}
await main();
参见 开始使用 Live API 了解更多示例。
最佳实践 #
- 使用以下命令设置较短的过期时间
expire_time参数。 - token过期,需要重新启动配置过程。
- 验证您自己的后端的安全身份验证。临时 token 的安全性取决于您的后端身份验证方法。
- 通常,避免使用临时 token 进行后端到 Gemini 的连接,因为此路径通常被认为是安全的。
限制 #
临时 token 仅兼容 Live API 此时。
后续步骤 #
- 阅读 Live API 参考 有关更多信息,请访问临时 token。