Ephemeral tokens

Ephemeral Tokens sind kurzlebige Authentifizierungstokens für den Zugriff auf die Gemini API über WebSockets. Sie sollen die Sicherheit erhöhen, wenn Sie eine direkte Verbindung vom Gerät eines Nutzers zur API herstellen (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 sitzungsspezifische Tokens jedoch schnell ablaufen und eingeschränkt werden können, reduzieren sie die Sicherheitsrisiken in einer Produktionsumgebung erheblich.

Funktionsweise von sitzungsspezifischen Tokens

So funktionieren sitzungsspezifische Tokens im Groben:

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

Das erhöht die Sicherheit, da das Token, auch wenn es extrahiert wird, nur kurz gültig ist, im Gegensatz zu einem langlebigen API-Schlüssel, der clientseitig bereitgestellt wird. Da der Client Daten direkt an Gemini sendet, wird auch die Latenz verbessert und Ihre Backends müssen die Echtzeitdaten nicht per Proxy senden.

Sitzungsspezifisches Token erstellen

Hier ein vereinfachtes Beispiel für das Abrufen eines sitzungsspezifischen Tokens von Gemini. Standardmäßig hast du eine Minute Zeit, um mit dem Token aus dieser Anfrage (newSessionExpireTime) neue Live API-Sitzungen zu starten, und 30 Minuten, um über diese Verbindung Nachrichten zu senden (expireTime).

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

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 Werteinschränkungen, Standardwerten und anderen Feldspezifikationen für expireTime finden Sie in der API-Referenz. Innerhalb des Zeitraums von expireTime Minuten müssen Sie den Anruf alle 10 Minuten mit sessionResumption wiederherstellen. Dies ist auch mit demselben Token möglich, wenn uses: 1.

Es ist auch möglich, ein sitzungsspezifisches Token für eine Reihe von Konfigurationen zu sperren. Dies kann nützlich sein, um die Sicherheit Ihrer Anwendung weiter zu verbessern und die Systemanweisungen auf der Serverseite zu belassen.

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

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 einen Teil der Felder sperren. Weitere Informationen finden Sie in der SDK-Dokumentation.

Mit einem sitzungsspezifischen Token eine Verbindung zur Live API herstellen

Im folgenden Beispiel wird über ein sitzungsspezifisches Token eine Verbindung zur Live API hergestellt. Die Verwendung sitzungsspezifischer Tokens ist nur dann sinnvoll, wenn Anwendungen bereitgestellt werden, die dem Ansatz der Client-zu-Server-Implementierung folgen.

import { GoogleGenAI, Modality } from '@google/genai';

// Use the token generated in the "Create an ephemeral token" section here
const ai = new GoogleGenAI({});
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 findest du 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.
• Prüfen Sie die sichere Authentifizierung für Ihr eigenes Backend. Einmalgültige Tokens sind nur so sicher wie Ihre Backend-Authentifizierungsmethode.
• Verwende in der Regel keine sitzungsspezifischen Tokens für Verbindungen zwischen dem Backend und Gemini, da dieser Pfad in der Regel als sicher gilt.

Beschränkungen

Zeitlich begrenzte Tokens sind derzeit nur mit der Live API kompatibel.

Nächste Schritte

• Weitere Informationen finden Sie in der Live API-Referenz zu sitzungsspezifischen Tokens.