Ephemeral tokens

Tokeny tymczasowe to krótkotrwałe tokeny uwierzytelniające, które umożliwiają dostęp do interfejsu Gemini API za pomocą WebSockets. Zostały one zaprojektowane w celu zwiększenia bezpieczeństwa podczas łączenia się bezpośrednio z interfejsem API z urządzenia użytkownika (implementacja klient-serwer). Podobnie jak standardowe klucze interfejsu API, tymczasowe tokeny można wyodrębnić z aplikacji po stronie klienta, takich jak przeglądarki internetowe lub aplikacje mobilne. Jednak tokeny tymczasowe szybko wygasają i można je ograniczać, co znacznie zmniejsza ryzyko związane z bezpieczeństwem w środowisku produkcyjnym.

Jak działają tymczasowe tokeny

Oto jak działają tokeny tymczasowe:

1. Klient (np. aplikacja internetowa) uwierzytelnia się w backendzie.
2. Backend wysyła żądanie tokena tymczasowego do usługi udostępniania interfejsu Gemini API.
3. Interfejs Gemini API wydaje krótkotrwały token.
4. Backend wysyła token do klienta w przypadku połączeń WebSocket z Live API. Możesz to zrobić, zastępując klucz interfejsu API tokenem tymczasowym.
5. Klient używa tokena tak, jakby był kluczem interfejsu API.

Zwiększa to bezpieczeństwo, ponieważ nawet jeśli token zostanie wyodrębniony, będzie miał krótki okres ważności, w przeciwieństwie do klucza interfejsu API o długim okresie ważności wdrożonego po stronie klienta. Ponieważ klient wysyła dane bezpośrednio do Gemini, skraca to czas oczekiwania i eliminuje konieczność przekazywania danych w czasie rzeczywistym przez backendy.

Tworzenie tokena efemerycznego

Oto uproszczony przykład uzyskiwania tymczasowego tokena od Gemini. Domyślnie masz 1 minutę na rozpoczęcie nowych sesji Live API przy użyciu tokena z tego żądania (newSessionExpireTime) i 30 minut na wysyłanie wiadomości przez to połączenie (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'},
    },
  });

Ograniczenia wartości, wartości domyślne i inne specyfikacje pól expireTime znajdziesz w dokumentacji interfejsu API. W expireTime tym czasie musisz sessionResumption ponownie nawiązywać połączenie co 10 minut (możesz to zrobić za pomocą tego samego tokena, nawet jeśli uses: 1).

Możesz też powiązać token efemeryczny z zestawem konfiguracji. Może to być przydatne do dalszego zwiększania bezpieczeństwa aplikacji i przechowywania instrukcji systemowych po stronie serwera.

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

Możesz też zablokować podzbiór pól. Więcej informacji znajdziesz w dokumentacji pakietu SDK.

Łączenie z interfejsem Live API za pomocą tokena tymczasowego

Gdy uzyskasz token tymczasowy, używaj go tak, jakby był kluczem interfejsu API (pamiętaj jednak, że działa on tylko w przypadku interfejsu API w wersji produkcyjnej i tylko z wersją v1alpha interfejsu API).

Pamiętaj, że używanie tymczasowych tokenów ma sens tylko w przypadku wdrażania aplikacji, które korzystają z implementacji typu klient-serwer.

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

Więcej przykładów znajdziesz w artykule Pierwsze kroki z interfejsem Live API.

Sprawdzone metody

• Ustaw krótki czas wygaśnięcia za pomocą parametru expire_time.
• Tokeny wygasają, co wymaga ponownego zainicjowania procesu udostępniania.
• Sprawdź bezpieczne uwierzytelnianie na własnym backendzie. Tokeny tymczasowe będą tak bezpieczne, jak metoda uwierzytelniania backendu.
• Zasadniczo unikaj używania tymczasowych tokenów w przypadku połączeń między backendem a Gemini, ponieważ ta ścieżka jest zwykle uważana za bezpieczną.

Ograniczenia

Obecnie tokeny tymczasowe są zgodne tylko z interfejsem Live API.

Co dalej?

• Więcej informacji o tokenach tymczasowych znajdziesz w dokumentacji interfejsu Live API.