Ephemeral tokens

I token effimeri sono token di autenticazione di breve durata per accedere all'API Gemini tramite WebSockets. Sono progettate per migliorare la sicurezza quando ti connetti direttamente dal dispositivo di un utente all'API (un'implementazione da client a 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 significativamente 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) esegue l'autenticazione con il backend.
2. Il backend richiede un token effimero al servizio di provisioning dell'API Gemini.
3. L'API Gemini rilascia un token di breve durata.
4. Il backend invia il token al client per le connessioni WebSocket all'API Live. Puoi farlo sostituendo la chiave API con un token effimero.
5. Il client utilizza quindi il token come se fosse una chiave API.

In questo modo la sicurezza viene migliorata perché, anche se estratto, il token ha una durata breve, a differenza di una chiave API di lunga durata implementata lato client. Poiché il client invia i dati direttamente a Gemini, ciò migliora anche la latenza ed evita che i backend debbano fare da proxy per i dati in tempo reale.

Crea un token temporaneo

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

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

È anche possibile bloccare un token temporaneo per un insieme di configurazioni. Questo potrebbe essere utile per migliorare ulteriormente la sicurezza della tua applicazione e mantenere le istruzioni di sistema sul lato server.

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

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

Connettersi all'API Live con un token effimero

Una volta ottenuto un token effimero, lo utilizzi come se fosse una chiave API (ma ricorda che funziona solo con l'API live e solo con la versione v1alpha dell'API).

Tieni presente che l'utilizzo di token effimeri aggiunge valore solo quando vengono implementate applicazioni che seguono l'approccio di implementazione client-server.

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

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

Best practice

• Imposta una breve durata di scadenza utilizzando il parametro expire_time.
• I token scadono, pertanto è necessario riavviare il processo di provisioning.
• Verifica l'autenticazione sicura per il tuo backend. I token effimeri saranno sicuri solo quanto il tuo metodo di autenticazione backend.
• In genere, evita di utilizzare token temporanei per le connessioni backend-Gemini, in quanto questo percorso è in genere considerato sicuro.

Limitazioni

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

Passaggi successivi

• Per saperne di più, consulta il riferimento dell'API Live sui token effimeri.