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:
- Il tuo client (ad es. l'app web) esegue l'autenticazione con il backend.
- Il backend richiede un token effimero al servizio di provisioning dell'API Gemini.
- L'API Gemini rilascia un token di breve durata.
- Il backend invia il token al client per le connessioni WebSocket all'API Live. Puoi farlo sostituendo la chiave API con un token effimero.
- 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
).
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, i valori predefiniti e altre specifiche del campo expireTime
, consulta il
Riferimento API.
Entro il periodo di tempo expireTime
, dovrai
sessionResumption
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.
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 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.
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();
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 temporanei 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.