Ephemeral tokens

โทเค็นชั่วคราวคือโทเค็นการตรวจสอบสิทธิ์ที่มีอายุการใช้งานสั้นสำหรับการเข้าถึง Gemini API ผ่าน WebSockets ซึ่งออกแบบมาเพื่อเพิ่มความปลอดภัยเมื่อ คุณเชื่อมต่อจากอุปกรณ์ของผู้ใช้กับ API โดยตรง (การใช้งานแบบ ไคลเอ็นต์กับเซิร์ฟเวอร์ ) โทเค็นชั่วคราวสามารถดึงข้อมูลจากแอปพลิเคชันฝั่งไคลเอ็นต์ เช่น เว็บเบราว์เซอร์หรือแอปบนอุปกรณ์เคลื่อนที่ ได้เช่นเดียวกับคีย์ API มาตรฐาน แต่เนื่องจากโทเค็นชั่วคราวหมดอายุอย่างรวดเร็วและสามารถจำกัดได้ จึงช่วยลดความเสี่ยงด้านความปลอดภัยในสภาพแวดล้อมการใช้งานจริงได้อย่างมาก คุณควรใช้โทเค็นชั่วคราวเมื่อเข้าถึง Live API จากแอปพลิเคชันฝั่งไคลเอ็นต์โดยตรงเพื่อเพิ่มความปลอดภัยของคีย์ API

วิธีทำงานของโทเค็นชั่วคราว

โทเค็นชั่วคราวทำงานในระดับสูงดังนี้

  1. ไคลเอ็นต์ (เช่น เว็บแอป) จะตรวจสอบสิทธิ์กับแบ็กเอนด์
  2. แบ็กเอนด์จะขอโทเค็นชั่วคราวจากบริการจัดสรรของ Gemini API
  3. Gemini API จะออกโทเค็นที่มีอายุการใช้งานสั้น
  4. แบ็กเอนด์จะส่งโทเค็นไปยังไคลเอ็นต์สำหรับการเชื่อมต่อ WebSocket กับ Live API คุณสามารถทำได้โดยการแทนที่คีย์ API ด้วยโทเค็นชั่วคราว
  5. จากนั้นไคลเอ็นต์จะใช้โทเค็นราวกับว่าเป็นคีย์ API

ภาพรวมโทเค็นชั่วคราว

การดำเนินการนี้จะช่วยเพิ่มความปลอดภัย เนื่องจากโทเค็นมีอายุการใช้งานสั้น แม้ว่าจะมีการดึงข้อมูลออกมาก็ตาม ซึ่งแตกต่างจากคีย์ API ที่มีอายุการใช้งานยาวนานซึ่งใช้งานในฝั่งไคลเอ็นต์ เนื่องจากไคลเอ็นต์ส่งข้อมูลไปยัง Gemini โดยตรง การดำเนินการนี้จึงช่วยลดเวลาในการตอบสนองและหลีกเลี่ยงไม่ให้แบ็กเอนด์ต้องทำหน้าที่เป็นพร็อกซีข้อมูลแบบเรียลไทม์

สร้างโทเค็นชั่วคราว

ต่อไปนี้เป็นตัวอย่างแบบง่ายๆ เกี่ยวกับวิธีรับโทเค็นชั่วคราวจาก Gemini โดยค่าเริ่มต้น คุณจะมีเวลา 1 นาทีในการเริ่มเซสชัน Live API ใหม่โดยใช้โทเค็นจากการขอครั้งนี้ (newSessionExpireTime) และ 30 นาทีในการส่งข้อความผ่านการเชื่อมต่อดังกล่าว (expireTime)

Python

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

JavaScript

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 ค่าเริ่มต้น และข้อกำหนดอื่นๆ ของช่องได้ที่ เอกสารอ้างอิง API ภายในกรอบเวลา expireTime คุณจะต้องใช้ sessionResumption เพื่อ เชื่อมต่อการโทรใหม่ทุกๆ 10 นาที (สามารถทำได้ด้วยโทเค็นเดียวกันแม้ ว่า uses: 1)

นอกจากนี้ คุณยังล็อกโทเค็นชั่วคราวไว้กับการกำหนดค่าชุดหนึ่งได้ด้วย ซึ่งอาจมีประโยชน์ในการปรับปรุงความปลอดภัยของแอปพลิเคชันเพิ่มเติมและเก็บคำแนะนำของระบบไว้ในฝั่งเซิร์ฟเวอร์

Python

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

JavaScript

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

นอกจากนี้ คุณยังล็อกช่องบางช่องได้ด้วย ดูข้อมูลเพิ่มเติมได้ในเอกสารประกอบ SDK

เชื่อมต่อกับ Live API ด้วยโทเค็นชั่วคราว

เมื่อมีโทเค็นชั่วคราวแล้ว ให้ใช้โทเค็นดังกล่าวราวกับว่าเป็นคีย์ API (แต่โปรดทราบว่าโทเค็นนี้ใช้ได้กับ Live API เท่านั้น และใช้ได้กับ API เวอร์ชัน v1alpha เท่านั้น)

การใช้โทเค็นชั่วคราวจะมีประโยชน์ก็ต่อเมื่อมีการใช้งานแอปพลิเคชัน ตามแนวทางการใช้งานแบบไคลเอ็นต์กับเซิร์ฟเวอร์

JavaScript

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

ดูตัวอย่างเพิ่มเติมได้ที่ เริ่มต้นใช้งาน Live API

แนวทางปฏิบัติแนะนำ

  • กำหนดระยะเวลาหมดอายุสั้นๆ โดยใช้พารามิเตอร์ expire_time
  • โทเค็นจะหมดอายุและต้องเริ่มกระบวนการจัดสรรใหม่
  • ตรวจสอบการตรวจสอบสิทธิ์ที่ปลอดภัยสำหรับแบ็กเอนด์ของคุณเอง โทเค็นชั่วคราวจะปลอดภัยเท่ากับวิธีการตรวจสอบสิทธิ์แบ็กเอนด์ของคุณ
  • โดยทั่วไป ให้หลีกเลี่ยงการใช้โทเค็นชั่วคราวสำหรับการเชื่อมต่อแบ็กเอนด์กับ Gemini เนื่องจากโดยปกติแล้วเส้นทางนี้ถือว่าปลอดภัย

ข้อจำกัด

ปัจจุบันโทเค็นชั่วคราวใช้ได้กับ Live API เท่านั้น

ขั้นตอนถัดไป

  • อ่านเอกสารอ้างอิง Live API reference เกี่ยวกับโทเค็นชั่วคราวเพื่อดูข้อมูลเพิ่มเติม