Ephemeral tokens

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

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

Python

client = genai.Client(
    http_options={'api_version': 'v1alpha',}
)

token = client.auth_tokens.create(
    config = {
    'uses': 1,
    'live_connect_constraints': {
        'model': 'gemini-3.1-flash-live-preview',
        'config': {
            'session_resumption':{},
            'temperature':0.7,
            'response_modalities':['AUDIO']
        }
    },
    '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-3.1-flash-live-preview',
            config: {
                sessionResumption: {},
                temperature: 0.7,
                responseModalities: ['AUDIO']
            }
        },
        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 でのみ、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-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };

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