Ephemeral tokens

Geçici jetonlar, WebSockets üzerinden Gemini API'ye erişmek için kullanılan kısa süreli kimlik doğrulama jetonlarıdır. Bu anahtarlar, doğrudan kullanıcının cihazından API'ye bağlanırken güvenliği artırmak için tasarlanmıştır (istemci-sunucu uygulaması). Standart API anahtarları gibi geçici jetonlar da web tarayıcıları veya mobil uygulamalar gibi istemci tarafı uygulamalardan alınabilir. Ancak geçici jetonların süresi hızlı bir şekilde sona erdiği ve kısıtlanabileceği için üretim ortamındaki güvenlik risklerini önemli ölçüde azaltırlar.

Geçici jetonların işleyiş şekli

Geçici jetonların genel işleyiş şekli:

1. İstemciniz (ör. web uygulaması) arka ucunuzla kimlik doğrulaması yapar.
2. Arka uçunuz, Gemini API'nin temel hazırlama hizmetinden geçici bir jeton ister.
3. Gemini API kısa süreli bir jeton verir.
4. Arka uç, Live API'ye WebSocket bağlantıları için jetonu istemciye gönderir. Bunu, API anahtarınızı geçici bir jetonla değiştirerek yapabilirsiniz.
5. İstemci daha sonra jetonu API anahtarı gibi kullanır.

Bu, jetonun istemci tarafında dağıtılan uzun ömürlü bir API anahtarının aksine kısa ömürlü olması nedeniyle güvenliği artırır. Müşteri verileri doğrudan Gemini'ye gönderdiğinden bu durum gecikmeyi de iyileştirir ve arka uçlarınızın gerçek zamanlı verileri proxy'lemesi gerekmez.

Geçici jeton oluşturma

Gemini'den geçici jeton almanın basitleştirilmiş bir örneğini aşağıda bulabilirsiniz. Varsayılan olarak, bu istekteki jetonu (newSessionExpireTime) kullanarak yeni Live API oturumları başlatmak için 1 dakikanız, bu bağlantı üzerinden mesaj göndermek için 30 dakikanız (expireTime) vardır.

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'},
    },
  });

expireTime değer kısıtlamaları, varsayılan değerler ve diğer alan özellikleri için API referansına bakın. expireTime zaman aralığında, sessionResumption aramayı 10 dakikada bir yeniden bağlamanız gerekir (bu işlem, uses: 1 olsa bile aynı jetonla yapılabilir).

Geçici jetonları bir yapılandırma grubuna kilitlemek de mümkündür. Bu, uygulamanızın güvenliğini daha da artırmak ve sistem talimatlarınızı sunucu tarafında tutmak için yararlı olabilir.

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

Alanların bir alt kümesini de kilitleyebilirsiniz. Daha fazla bilgi için SDK dokümanlarına bakın.

Geçici jetonla Live API'ye bağlanma

Aşağıda, geçici jeton aracılığıyla Live API'ye bağlanan bir örnek verilmiştir. Geçici jetonların yalnızca istemci-sunucu uygulama yaklaşımını izleyen uygulamaları dağıtırken değer kattığını unutmayın.

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

Daha fazla örnek için Live API'yi kullanmaya başlama bölümüne bakın.

En iyi uygulamalar

• expire_time parametresini kullanarak kısa bir geçerlilik süresi ayarlayın.
• Jetonların süresi dolar ve temel hazırlama işleminin yeniden başlatılması gerekir.
• Kendi arka uçunuz için güvenli kimlik doğrulamayı doğrulayın. Geçici jetonlar, arka uç kimlik doğrulama yönteminiz kadar güvenlidir.
• Bu yol genellikle güvenli kabul edildiğinden, arka uçtan Gemini'ye bağlantılar için geçici jetonlar kullanmaktan genellikle kaçının.

Sınırlamalar

Geçici jetonlar şu anda yalnızca Live API ile uyumludur.

Sırada ne var?

• Daha fazla bilgi için geçici jetonlarla ilgili Live API referansını okuyun.