Ephemeral tokens

Temporäre Tokens sind kurzlebige Authentifizierungstokens für den Zugriff auf die Gemini API über WebSockets. Sie sollen die Sicherheit verbessern, wenn Sie direkt vom Gerät eines Nutzers aus eine Verbindung zur API herstellen (eine Client-zu-Server-Implementierung). Wie Standard-API-Schlüssel können auch sitzungsspezifische Tokens aus clientseitigen Anwendungen wie Webbrowsern oder mobilen Apps extrahiert werden. Da temporäre Tokens jedoch schnell ablaufen und eingeschränkt werden können, werden die Sicherheitsrisiken in einer Produktionsumgebung dadurch erheblich reduziert.

Funktionsweise von temporären Tokens

So funktionieren temporäre Tokens:

  1. Ihr Client (z.B. eine Web-App) wird bei Ihrem Backend authentifiziert.
  2. Ihr Backend fordert ein temporäres Token vom Bereitstellungsdienst der Gemini API an.
  3. Die Gemini API gibt ein kurzlebiges Token aus.
  4. Ihr Backend sendet das Token an den Client für WebSocket-Verbindungen zur Live API. Dazu können Sie Ihren API-Schlüssel durch ein temporäres Token ersetzen.
  5. Der Client verwendet das Token dann so, als wäre es ein API-Schlüssel.

Sitzungsspezifische Tokens – Übersicht

Das erhöht die Sicherheit, da das Token auch im Fall eines Diebstahls nur kurzlebig ist. Das ist anders als bei einem clientseitig bereitgestellten, langlebigen API-Schlüssel. Da der Client Daten direkt an Gemini sendet, wird auch die Latenz verbessert und Ihre Back-Ends müssen die Echtzeitdaten nicht mehr weiterleiten.

Sitzungsspezifisches Token erstellen

Hier ist ein vereinfachtes Beispiel dafür, wie Sie ein temporäres Token von Gemini erhalten. Standardmäßig haben Sie 1 Minute Zeit, um neue Live API-Sitzungen mit dem Token aus dieser Anfrage (newSessionExpireTime) zu starten, und 30 Minuten Zeit, um Nachrichten über diese Verbindung (expireTime) zu senden.

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'},
    },
  });

Informationen zu Einschränkungen, Standardwerten und anderen Feldspezifikationen für expireTime finden Sie in der API-Referenz. Innerhalb des Zeitrahmens von expireTime müssen Sie sessionResumption alle 10 Minuten eine neue Verbindung herstellen (dies kann mit demselben Token erfolgen, auch wenn uses: 1).

Es ist auch möglich, ein temporäres Token für eine Reihe von Konfigurationen zu sperren. Das kann nützlich sein, um die Sicherheit Ihrer Anwendung weiter zu verbessern und Ihre Systemanweisungen auf der Serverseite zu behalten.

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

Sie können auch eine Teilmenge von Feldern sperren. Weitere Informationen finden Sie in der SDK-Dokumentation.

Mit einem temporären Token eine Verbindung zur Live API herstellen

Sobald Sie ein temporäres Token haben, verwenden Sie es so, als wäre es ein API-Schlüssel. Es funktioniert jedoch nur für die Live-API und nur mit der v1alpha-Version der API.

Die Verwendung von temporären Tokens ist nur bei der Bereitstellung von Anwendungen sinnvoll, die dem Client-zu-Server-Implementierungsansatz folgen.

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();

Weitere Beispiele finden Sie unter Erste Schritte mit der Live API.

Best Practices

  • Legen Sie mit dem Parameter expire_time eine kurze Ablaufdauer fest.
  • Tokens laufen ab und der Bereitstellungsprozess muss neu gestartet werden.
  • Sichere Authentifizierung für Ihr eigenes Backend überprüfen Die Sicherheit von Einmaltokens hängt von der Authentifizierungsmethode Ihres Back-Ends ab.
  • Im Allgemeinen sollten Sie keine temporären Tokens für Backend-zu-Gemini-Verbindungen verwenden, da dieser Pfad in der Regel als sicher gilt.

Beschränkungen

Kurzlebige Tokens sind derzeit nur mit der Live API kompatibel.

Nächste Schritte