Ephemeral tokens

Os tokens efêmeros são tokens de autenticação de curta duração para acessar a API Gemini por WebSockets. Elas são projetadas para aumentar a segurança quando você se conecta diretamente de um dispositivo do usuário à API (uma implementação cliente-servidor). Assim como as chaves de API padrão, os tokens temporários podem ser extraídos de aplicativos do lado do cliente, como navegadores da Web ou apps para dispositivos móveis. No entanto, como os tokens efêmeros expiram rapidamente e podem ser restritos, eles reduzem significativamente os riscos de segurança em um ambiente de produção.

Como os tokens temporários funcionam

Veja como os tokens temporários funcionam de modo geral:

1. Seu cliente (por exemplo, um app da Web) faz a autenticação com seu back-end.
2. Seu back-end solicita um token efêmero do serviço de provisionamento da API Gemini.
3. A API Gemini emite um token de curta duração.
4. O back-end envia o token ao cliente para conexões WebSocket com a API Live API. Para isso, troque sua chave de API por um token efêmero.
5. Em seguida, o cliente usa o token como se fosse uma chave de API.

Isso aumenta a segurança porque, mesmo que seja extraído, o token tem curta duração, ao contrário de uma chave de API de longa duração implantada no lado do cliente. Como o cliente envia dados diretamente para o Gemini, isso também melhora a latência e evita que seus back-ends precisem fazer proxy dos dados em tempo real.

Criar um token temporário

Confira um exemplo simplificado de como receber um token efêmero do Gemini. Por padrão, você terá um minuto para iniciar novas sessões da API Live usando o token desta solicitação (newSessionExpireTime) e 30 minutos para enviar mensagens por essa conexão (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 restrições de valor expireTime, padrões e outras especificações de campo, consulte a referência da API. Dentro do período de expireTime, você precisará sessionResumption para reconectar a chamada a cada 10 minutos. Isso pode ser feito com o mesmo token, mesmo que uses: 1.

Também é possível bloquear um token efêmero em um conjunto de configurações. Isso pode ser útil para melhorar ainda mais a segurança do aplicativo e manter as instruções do sistema no lado do 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

Você também pode bloquear um subconjunto de campos. Consulte a documentação do SDK para mais informações.

Conectar-se à API Live com um token efêmero

Depois de ter um token efêmero, use-o como se fosse uma chave de API. No entanto, lembre-se de que ele só funciona com a API ativa e com a versão v1alpha dela.

O uso de tokens efêmeros só agrega valor ao implantar aplicativos que seguem a abordagem de implementação de cliente para 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();

Consulte Começar a usar a API Live para mais exemplos.

Práticas recomendadas

• Defina uma duração de expiração curta usando o parâmetro expire_time.
• Os tokens expiram, exigindo uma nova inicialização do processo de provisionamento.
• Verifique a autenticação segura para seu próprio back-end. Os tokens temporários só serão tão seguros quanto o método de autenticação do back-end.
• Em geral, evite usar tokens temporários para conexões do back-end com o Gemini, já que esse caminho normalmente é considerado seguro.

Limitações

No momento, os tokens efêmeros são compatíveis apenas com a API Live.

A seguir

• Leia a referência da API Live sobre tokens temporários para mais informações.