Ephemeral tokens

Os tokens temporários são tokens de autenticação de curta duração para acessar a API Gemini por meio de WebSockets. Elas foram criadas para melhorar a segurança quando você se conecta diretamente do dispositivo de um 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 temporários 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

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

1. O cliente (por exemplo, o app da Web) é autenticado com o back-end.
2. O back-end solicita um token temporário 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 para o cliente para conexões WebSocket com a API Live. Para fazer isso, troque a chave de API por um token temporário.
5. O cliente usa o token como se fosse uma chave de API.

Isso aumenta a segurança porque, mesmo que extraído, o token tem vida curta, diferente 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 os back-ends precisem fazer proxy dos dados em tempo real.

Criar um token temporário

Confira um exemplo simplificado de como receber um token temporário do Gemini. Por padrão, você terá 1 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. No período de expireTime, você vai precisar de sessionResumption para reconectar a chamada a cada 10 minutos. Isso pode ser feito com o mesmo token, mesmo se uses: 1.

Também é possível bloquear um token temporário em um conjunto de configurações. Isso pode ser útil para melhorar ainda mais a segurança do seu 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 temporário

Confira um exemplo que se conecta à API Live por um token temporário. O uso de tokens temporários só agrega valor ao implantar aplicativos que seguem a abordagem de implementação cliente-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();

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

Práticas recomendadas

• Defina um período de expiração curto usando o parâmetro expire_time.
• Os tokens expiram, exigindo a reativação do processo de provisionamento.
• Verifique a autenticação segura do seu próprio back-end. Os tokens temporários só serão tão seguros quanto seu método de autenticação de back-end.
• Em geral, evite usar tokens temporários para conexões de back-end para Gemini, porque esse caminho geralmente é considerado seguro.

Limitações

Os tokens temporários são compatíveis apenas com a API Live no momento.

A seguir

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