Ephemeral tokens

Token sementara adalah token autentikasi berumur pendek untuk mengakses Gemini API melalui WebSockets. API ini dirancang untuk meningkatkan keamanan saat Anda terhubung langsung dari perangkat pengguna ke API (penerapan klien ke server). Seperti kunci API standar, token sementara dapat diekstrak dari aplikasi sisi klien seperti browser web atau aplikasi seluler. Namun, karena token sementara berakhir masa berlakunya dengan cepat dan dapat dibatasi, token tersebut secara signifikan mengurangi risiko keamanan di lingkungan produksi.

Cara kerja token sementara

Berikut cara kerja token singkat di tingkat tinggi:

1. Klien Anda (misalnya aplikasi web) melakukan autentikasi dengan backend Anda.
2. Backend Anda meminta token sementara dari layanan penyediaan Gemini API.
3. Gemini API menerbitkan token dengan masa aktif singkat.
4. Backend Anda mengirimkan token ke klien untuk koneksi WebSocket ke Live API. Anda dapat melakukannya dengan menukar kunci API dengan token sementara.
5. Kemudian, klien menggunakan token seolah-olah itu adalah kunci API.

Hal ini meningkatkan keamanan karena meskipun diekstrak, token memiliki masa berlaku singkat, tidak seperti kunci API dengan masa berlaku lama yang di-deploy sisi klien. Karena klien mengirim data langsung ke Gemini, hal ini juga meningkatkan latensi dan menghindari backend Anda yang perlu melakukan proxy data real time.

Membuat token sementara

Berikut adalah contoh sederhana tentang cara mendapatkan token sementara dari Gemini. Secara default, Anda akan memiliki waktu 1 menit untuk memulai sesi Live API baru menggunakan token dari permintaan ini (newSessionExpireTime), dan 30 menit untuk mengirim pesan melalui koneksi tersebut (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'},
    },
  });

Untuk batasan nilai expireTime, default, dan spesifikasi kolom lainnya, lihat referensi API. Dalam jangka waktu expireTime, Anda memerlukan sessionResumption untuk menghubungkan kembali panggilan setiap 10 menit (ini dapat dilakukan dengan token yang sama meskipun uses: 1).

Anda juga dapat mengunci token sementara ke serangkaian konfigurasi. Hal ini mungkin berguna untuk lebih meningkatkan keamanan aplikasi dan menyimpan petunjuk sistem di sisi server.

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

Anda juga dapat mengunci sebagian kolom. Lihat dokumentasi SDK untuk mengetahui info selengkapnya.

Menghubungkan ke Live API dengan token sementara

Berikut adalah contoh yang terhubung ke Live API melalui token sementara. Perhatikan bahwa penggunaan token sementara hanya akan menambah nilai saat men-deploy aplikasi yang mengikuti pendekatan implementasi klien ke server.

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

Lihat Memulai Live API untuk mengetahui contoh lainnya.

Praktik terbaik

• Tetapkan durasi masa berlaku yang singkat menggunakan parameter expire_time.
• Masa berlaku token berakhir, sehingga memerlukan inisiasi ulang proses penyediaan.
• Verifikasi autentikasi aman untuk backend Anda sendiri. Token sementara hanya akan seaman metode autentikasi backend Anda.
• Secara umum, hindari penggunaan token sementara untuk koneksi backend ke Gemini, karena jalur ini biasanya dianggap aman.

Batasan

Token sementara hanya kompatibel dengan Live API untuk saat ini.

Langkah berikutnya

• Baca referensi Live API tentang token sementara untuk mengetahui informasi selengkapnya.