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ñados para mejorar la seguridad cuando te conectas directamente desde el dispositivo de un usuario a la API (una implementación cliente-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, como 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 muestra cómo funcionan los tokens efímeros en un nivel general:

1. Tu cliente (p.ej., una app web) se autentica con tu backend.
2. Tu backend solicita un token efímero del 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, cambia 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 deban usar un proxy para los datos en tiempo real.

Crea un token efímero

Este es 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 API en vivo 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 de valor, los valores predeterminados y otras especificaciones de campos de expireTime, consulta la referencia de la API. Dentro del período expireTime, deberás llamar a sessionResumption para volver a conectar la llamada cada 10 minutos (esto se puede hacer con el mismo token, incluso si es uses: 1).

También es posible bloquear un token efímero en un conjunto de parámetros de configuración. Esto podría 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.

Cómo conectarse a la API de Live con un token efímero

A continuación, se muestra un ejemplo que se conecta a la API en vivo a través de un token efímero. 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({});
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 Cómo comenzar 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, lo que requiere que se reinicie 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 de backend a Gemini, ya que esta ruta se considera 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.