Ephemeral tokens

โทเค็นชั่วคราวคือโทเค็นการตรวจสอบสิทธิ์ที่มีอายุสั้นสําหรับการเข้าถึง Gemini API ผ่าน WebSockets ซึ่งออกแบบมาเพื่อเพิ่มความปลอดภัยเมื่อคุณเชื่อมต่อจากอุปกรณ์ของผู้ใช้ไปยัง 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-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

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-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

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

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

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

JavaScript

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

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

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

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

ข้อจำกัด

ขณะนี้โทเค็นชั่วคราวใช้ได้กับ Live API เท่านั้น

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

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