Ephemeral tokens

I token effimeri sono token di autenticazione di breve durata per accedere all'API Gemini tramite WebSockets. Sono progettati per migliorare la sicurezza quando ti colleghi direttamente dal dispositivo di un utente all'API (un'implementazione client-to-server). Come le chiavi API standard, i token effimeri possono essere estratti da applicazioni lato client come browser web o app mobile. Tuttavia, poiché i token effimeri scadono rapidamente e possono essere limitati, riducono notevolmente i rischi per la sicurezza in un ambiente di produzione.

Come funzionano i token effimeri

Ecco come funzionano i token effimeri a livello generale:

  1. Il client (ad es. l'app web) si autentica con il tuo backend.
  2. Il backend richiede un token temporaneo dal servizio di provisioning dell'API Gemini.
  3. L'API Gemini emette un token di breve durata.
  4. Il backend invia il token al client per le connessioni WebSocket all'API Live. Per farlo, scambia la chiave API con un token temporaneo.
  5. Il client utilizza quindi il token come se fosse una chiave API.

Panoramica dei token temporanei

Ciò migliora la sicurezza perché, anche se estratto, il token ha una durata breve, diversamente da una chiave API a lungo termine di cui è stato eseguito il deployment lato client. Poiché il client invia i dati direttamente a Gemini, viene migliorata anche la latenza ed evita che i tuoi backend debbano eseguire il proxy dei dati in tempo reale.

Creare un token temporaneo

Ecco un esempio semplificato di come ottenere un token temporaneo da Gemini. Per impostazione predefinita, hai 1 minuto di tempo per avviare nuove sessioni dell'API Live utilizzando il token di questa richiesta (newSessionExpireTime) e 30 minuti per inviare messaggi tramite questa connessione (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'},
    },
  });

Per i vincoli dei valori expireTime, i valori predefiniti e altre specifiche dei campi, consulta il riferimento all'API. Entro il periodo di tempo expireTime, dovrai sessionResumption ricollegare la chiamata ogni 10 minuti (questa operazione può essere eseguita con lo stesso token anche se uses: 1).

È inoltre possibile bloccare un token temporaneo in un insieme di configurazioni. Questa funzionalità potrebbe essere utile per migliorare ulteriormente la sicurezza della tua applicazione e mantenere le istruzioni di sistema lato server.

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

Puoi anche bloccare un sottoinsieme di campi. Per ulteriori informazioni, consulta la documentazione dell'SDK.

Connettiti all'API Live con un token temporaneo

Ecco un esempio che si connette all'API Live tramite un token temporaneo. Tieni presente che l'utilizzo di token effimeri aggiunge valore solo quando viene eseguito il deployment di applicazioni che seguono l'approccio di implementazione client-to-server.

JavaScript

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

Per altri esempi, consulta Iniziare a utilizzare l'API Live.

Best practice

  • Imposta una durata di scadenza breve utilizzando il parametro expire_time.
  • I token scadono e richiedono il riavvio del processo di provisioning.
  • Verifica l'autenticazione sicura per il tuo backend. I token effimeri saranno protetti solo dal metodo di autenticazione di backend.
  • In genere, evita di utilizzare token effimeri per le connessioni dal backend a Gemini, poiché questo percorso è in genere considerato sicuro.

Limitazioni

Al momento, i token effimeri sono compatibili solo con l'API Live.

Passaggi successivi