Ephemeral tokens

暫時性權杖是短期驗證權杖，可透過 WebSockets 存取 Gemini API。這類金鑰的設計宗旨，是在您從使用者裝置直接連線至 API 時 (用戶端對伺服器的實作方式)，提升安全性。與標準 API 金鑰一樣，您可以從網路瀏覽器或行動應用程式等用戶端應用程式擷取臨時權杖。但由於臨時權杖很快就會過期，且可受到限制，因此能大幅降低生產環境中的安全風險。

臨時權杖的運作方式

暫時性權杖的大致運作方式如下：

您的用戶端 (例如網頁應用程式) 會向後端進行驗證。
後端向 Gemini API 的佈建服務要求臨時權杖。
Gemini API 會核發短期權杖。
後端會將權杖傳送至用戶端，以建立 WebSocket 連線至 Live API。方法是將 API 金鑰換成臨時權杖。
接著，用戶端會將權杖視為 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 時間範圍內，您需要每 10 分鐘重新連線通話 (即使 uses: 1，也可以使用相同權杖)。sessionResumption

您也可以將臨時權杖鎖定至一組設定。這項功能有助於進一步提升應用程式的安全性，並將系統指令保留在伺服器端。

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

取得臨時權杖後，您可以使用該權杖，就像使用 API 金鑰一樣 (但請注意，臨時權杖僅適用於 Live API，且僅適用於 v1alpha 版 API)。

請注意，只有在部署採用用戶端到伺服器實作方法的應用程式時，使用暫時性權杖才有價值。

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-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 參考資料。