Geçici jetonlar

Geçici jetonlar, WebSockets üzerinden Gemini API'ye erişmek için kullanılan kısa ömürlü kimlik doğrulama jetonlarıdır. Bu jetonlar, doğrudan kullanıcının cihazından API'ye bağlandığınızda (istemciden sunucuya uygulama) güvenliği artırmak için tasarlanmıştır. Geçici jetonlar, standart API anahtarları gibi web tarayıcıları veya mobil uygulamalar gibi istemci tarafı uygulamalardan çıkarılabilir. Ancak geçici jetonlar hızlı bir şekilde sona erdiğinden ve kısıtlanabildiğinden üretim ortamındaki güvenlik risklerini önemli ölçüde azaltır. API anahtarı güvenliğini artırmak için Live API'ye doğrudan istemci tarafı uygulamalarından erişirken bu jetonları kullanmanız gerekir.

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

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

1. İstemciniz (ör. web uygulaması) arka ucunuzda kimlik doğrular.
2. Arka ucunuz, Gemini API'nin sağlama hizmetinden kısa ömürlü bir jeton ister.
3. Gemini API, kısa ömürlü bir jeton yayınlar.
4. Arka uçunuz, Live API'ye WebSocket bağlantıları için jetonu istemciye gönderir. Bunu, API anahtarınızı kısa ömürlü bir jetonla değiştirerek yapabilirsiniz.
5. İstemci daha sonra jetonu API anahtarı gibi kullanır.

Bu, jetonun kısa ömürlü olması nedeniyle güvenliği artırır. İstemci tarafında dağıtılan uzun ömürlü bir API anahtarının aksine, jeton çıkarılsa bile kısa ömürlüdür. İstemci verileri doğrudan Gemini'a gönderdiğinden bu durum gecikmeyi de azaltır ve arka uçlarınızın gerçek zamanlı verileri proxy'lemesi gerekmez.

Kısa ömürlü jeton oluşturma

Gemini'dan kısa ömürlü jeton alma işleminin 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 (expireTime) mesaj göndermek için ise 30 dakikanız olur.

import datetime
from google import genai

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 = 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ılanlar ve diğer alan özellikleri için API referansına bakın. expireTime zaman aralığında, sessionResumption için her 10 dakikada bir aramayı yeniden bağlamanız gerekir (bu işlem, uses: 1 olsa bile aynı jetonla yapılabilir).

Geçici bir jetonu bir dizi yapılandırmaya 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 faydalı olabilir.

from google import genai

client = genai.Client(
    http_options={'api_version': 'v1alpha',}
)

token = client.auth_tokens.create(
    config = {
    'uses': 1,
    'live_connect_constraints': {
        'model': 'gemini-3.1-flash-live-preview',
        'config': {
            'session_resumption':{},
            'temperature':0.7,
            'response_modalities':['AUDIO']
        }
    },
    '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-3.1-flash-live-preview',
            config: {
                sessionResumption: {},
                temperature: 0.7,
                responseModalities: ['AUDIO']
            }
        },
        httpOptions: {
            apiVersion: 'v1alpha'
        }
    }
});

// You'll need to pass the value under token.name back to your client to use it

Ayrıca, 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

Geçici bir jetonunuz olduğunda, bunu API anahtarı gibi kullanırsınız (ancak yalnızca canlı API'de ve yalnızca API'nin v1alpha sürümünde çalıştığını unutmayın).

Geçici jetonların kullanılması yalnızca istemciden sunucuya uygulama yaklaşımını izleyen uygulamalar dağıtılırken değer katar.

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-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };

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 dolduğunda temel hazırlık işleminin yeniden başlatılması gerekir.
• Kendi arka uç sisteminiz için güvenli kimlik doğrulamayı doğrulayın. Kısa ömürlü jetonlar yalnızca arka uç kimlik doğrulama yönteminiz kadar güvenlidir.
• Genellikle, arka uçtan Gemini'a bağlantılar için kısa ömürlü jeton kullanmaktan kaçının. Bu yol genellikle güvenli kabul edilir.

Sınırlamalar

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

Sırada ne var?

• Daha fazla bilgi için Live API referansındaki geçici jetonlar bölümünü inceleyin.