Ephemeral tokens

Los tokens efímeros son tokens de autenticación de corta duración para acceder a la API de Gemini a través de WebSockets. Están diseñadas para mejorar la seguridad cuando te conectas directamente desde el dispositivo de un usuario a la API (una implementación de cliente a servidor). Al igual que las claves de API estándar, los tokens efímeros se pueden extraer de aplicaciones del cliente, como navegadores web o aplicaciones para dispositivos móviles. Sin embargo, debido a que los tokens efímeros vencen rápidamente y se pueden restringir, reducen significativamente los riesgos de seguridad en un entorno de producción.

Cómo funcionan los tokens efímeros

A continuación, se explica cómo funcionan los tokens efímeros a un nivel general:

1. Tu cliente (p.ej., una app web) se autentica con tu backend.
2. Tu backend solicita un token efímero al servicio de aprovisionamiento de la API de Gemini.
3. La API de Gemini emite un token de corta duración.
4. Tu backend envía el token al cliente para las conexiones de WebSocket a la API de Live. Para ello, reemplaza tu clave de API por un token efímero.
5. Luego, el cliente usa el token como si fuera una clave de API.

Esto mejora la seguridad porque, incluso si se extrae, el token es de corta duración, a diferencia de una clave de API de larga duración implementada del lado del cliente. Dado que el cliente envía datos directamente a Gemini, esto también mejora la latencia y evita que tus backends necesiten proxy para los datos en tiempo real.

Crea un token efímero

A continuación, se muestra un ejemplo simplificado de cómo obtener un token efímero de Gemini. De forma predeterminada, tendrás 1 minuto para iniciar nuevas sesiones de la API de Live con el token de esta solicitud (newSessionExpireTime) y 30 minutos para enviar mensajes a través de esa conexión (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'},
    },
  });

Para conocer las restricciones, los valores predeterminados y otras especificaciones del campo expireTime, consulta la referencia de la API. Dentro del período de expireTime, deberás sessionResumption para volver a conectar la llamada cada 10 minutos (esto se puede hacer con el mismo token incluso si uses: 1).

También es posible bloquear un token efímero para un conjunto de configuraciones. Esto puede ser útil para mejorar aún más la seguridad de tu aplicación y mantener las instrucciones del sistema en el servidor.

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

También puedes bloquear un subconjunto de campos. Consulta la documentación del SDK para obtener más información.

Conéctate a la API de Live con un token efímero

Una vez que tengas un token efímero, úsalo como si fuera una clave de API (pero recuerda que solo funciona para la API en vivo y solo con la versión v1alpha de la API).

Ten en cuenta que el uso de tokens efímeros solo agrega valor cuando se implementan aplicaciones que siguen el enfoque de implementación de cliente a servidor.

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

Consulta Comienza a usar la API de Live para obtener más ejemplos.

Prácticas recomendadas

• Establece una duración de vencimiento corta con el parámetro expire_time.
• Los tokens vencen, por lo que se debe reiniciar el proceso de aprovisionamiento.
• Verifica la autenticación segura para tu propio backend. Los tokens efímeros solo serán tan seguros como tu método de autenticación de backend.
• En general, evita usar tokens efímeros para las conexiones del backend a Gemini, ya que esta ruta suele considerarse segura.

Limitaciones

Por el momento, los tokens efímeros solo son compatibles con la API de Live.

¿Qué sigue?

• Lee la referencia de la API de Live sobre los tokens efímeros para obtener más información.