Ephemeral tokens

エフェメラル トークンは、WebSockets を介して Gemini API にアクセスするための有効期間の短い認証トークンです。これらは、ユーザーのデバイスから API に直接接続する場合のセキュリティを強化するように設計されています（クライアントからサーバーへの実装）。標準の API キーと同様に、エフェメラル トークンは、ウェブブラウザやモバイルアプリなどのクライアントサイド アプリケーションから抽出できます。ただし、エフェメラル トークンは有効期限が短く、制限できるため、本番環境でのセキュリティ リスクを大幅に軽減できます。

エフェメラル トークンの仕組み

エフェメラル トークンの大まかな仕組みは次のとおりです。

  1. クライアント（ウェブアプリなど）がバックエンドで認証を行う。
  2. バックエンドが Gemini API のプロビジョニング サービスからエフェメラル トークンをリクエストします。
  3. Gemini API は有効期間の短いトークンを発行します。
  4. バックエンドは、Live API への WebSocket 接続用のトークンをクライアントに送信します。これを行うには、API キーをエフェメラル トークンと入れ替えます。
  5. クライアントは、トークンを API キーのように使用します。

エフェメラル トークンの概要

クライアントサイドにデプロイされた長期間有効な API キーとは異なり、トークンは抽出されていても有効期間が短いため、セキュリティが強化されます。クライアントが Gemini にデータを直接送信するため、レイテンシも改善され、バックエンドでリアルタイム データをプロキシする必要がなくなります。

エフェメラル トークンを作成する

Gemini からエフェメラル トークンを取得する方法の簡単な例を次に示します。デフォルトでは、このリクエストのトークン（newSessionExpireTime）を使用して新しい Live API セッションを開始する時間は 1 分間、その接続を介してメッセージを送信する時間は 30 分間です（expireTime）。

Python

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

JavaScript

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 の場合でも、同じトークンで実行できます）。

エフェメラル トークンを一連の構成にロックすることもできます。これは、アプリケーションのセキュリティをさらに強化し、システム インストラクションをサーバー側に保持するのに役立ちます。

Python

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

JavaScript

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 に接続する例を次に示します。エフェメラル トークンの使用は、クライアントからサーバーへの実装アプローチに従うアプリケーションをデプロイする場合にのみ価値を追加します。

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 リファレンスをご覧ください。