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 分、その接続（expireTime）を介してメッセージを送信するのに 30 分が与えられます。

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-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 キーと同じように使用します（ただし、ライブ 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-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 のリファレンスをご覧ください。