Ephemeral tokens

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

Cara kerja token sementara

Berikut cara kerja token sementara di tingkat umum:

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 berumur pendek.
4. Backend Anda mengirimkan token ke klien untuk koneksi WebSocket ke Live API. Anda dapat melakukannya dengan menukar kunci API dengan token sementara.
5. Klien kemudian menggunakan token seolah-olah itu adalah kunci API.

Hal ini meningkatkan keamanan karena meskipun diekstrak, token tersebut berumur pendek, tidak seperti kunci API berumur panjang yang di-deploy di sisi klien. Karena klien mengirimkan data langsung ke Gemini, hal ini juga meningkatkan latensi dan menghindari backend Anda perlu memproxy data real time.

Membuat token sementara

Berikut adalah contoh sederhana 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 (hal ini dapat dilakukan dengan token yang sama bahkan jika uses: 1).

Anda juga dapat mengunci token sementara ke sekumpulan konfigurasi. Hal ini mungkin berguna untuk lebih meningkatkan keamanan aplikasi Anda 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-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

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

Menghubungkan ke Live API dengan token sementara

Setelah memiliki token sementara, Anda menggunakannya seolah-olah itu adalah kunci API (tetapi ingat, token ini hanya berfungsi untuk live API, dan hanya dengan API versi v1alpha).

Penggunaan token sementara hanya memberikan 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({
  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();

Lihat Memulai Live API untuk contoh lainnya.

Praktik terbaik

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

Batasan

Token sementara hanya kompatibel dengan Live API saat ini.

Langkah berikutnya

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