Ephemeral tokens

Temporäre Tokens sind kurzlebige Authentifizierungstokens für den Zugriff auf die Gemini API über WebSockets. Sie wurden entwickelt, um die Sicherheit zu erhöhen, wenn Sie eine direkte Verbindung vom Gerät eines Nutzers zur API herstellen (eine Client-Server Implementierung). Wie Standard-API-Schlüssel können temporäre Tokens aus clientseitigen Anwendungen wie Webbrowsern oder mobilen Apps extrahiert werden. Da temporäre Tokens jedoch schnell ablaufen und eingeschränkt werden können, verringern sie die Sicherheitsrisiken in einer Produktionsumgebung erheblich. Sie sollten verwendet werden, wenn Sie direkt von clientseitigen Anwendungen auf die Live API zugreifen, um die Sicherheit von API-Schlüsseln zu erhöhen.

Funktionsweise von temporären Tokens

So funktionieren temporäre Tokens:

1. Ihr Client (z.B. eine Web-App) authentifiziert sich bei Ihrem Backend.
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.

Dadurch wird die Sicherheit erhöht, da das Token auch bei Extraktion nur kurzlebig 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 weiterleiten.

Temporäres Token erstellen

Hier ist ein vereinfachtes Beispiel dafür, wie Sie ein temporäres Token von Gemini erhalten. Standardmäßig haben Sie eine Minute Zeit, um neue Live API-Sitzungen mit dem Token aus dieser Anfrage zu starten (newSessionExpireTime), und 30 Minuten, um Nachrichten über diese Verbindung 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 Einschränkungen für den Wert von expireTime, Standardwerten und anderen Feldspezifikationen finden Sie in der API-Referenz. Innerhalb des expireTime Zeitrahmens müssen Sie sessionResumption verwenden, um die Verbindung alle 10 Minuten wiederherzustellen. Dies kann mit demselben Token erfolgen, auch wenn uses: 1.

Es ist auch möglich, ein temporäres Token an eine Reihe von Konfigurationen zu binden. Dies kann nützlich sein, um die Sicherheit Ihrer Anwendung weiter zu verbessern und Ihre Systemanweisungen serverseitig zu speichern.

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

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

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 Version v1alpha der API.

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

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

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 erfordern eine erneute Initiierung des Bereitstellungsprozesses.
• Prüfen Sie die sichere Authentifizierung für Ihr eigenes Backend. Temporäre Tokens sind nur so sicher wie Ihre Backend-Authentifizierungsmethode.
• Vermeiden Sie im Allgemeinen die Verwendung von temporären Tokens für Backend-zu-Gemini-Verbindungen, da dieser Pfad in der Regel als sicher gilt.

Beschränkungen

Temporäre Tokens sind derzeit nur mit der Live API kompatibel.

Nächste Schritte

• Weitere Informationen finden Sie in der Live API-Referenz zu temporären Tokens.