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

โทเค็นชั่วคราวคือโทเค็นการตรวจสอบสิทธิ์ที่มีอายุสั้นสำหรับเข้าถึง 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
from google import genai

now = datetime.datetime.now(tz=datetime.timezone.utc)

client = genai.Client()

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

# 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, // Default is 30 mins
      newSessionExpireTime: new Date(Date.now() + (1 * 60 * 1000)), // Default 1 minute in the future
    },
  });

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uses": 1,
    "expireTime": "YYYY-MM-DDTHH:MM:SSZ",
    "newSessionExpireTime": "YYYY-MM-DDTHH:MM:SSZ"
  }'

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

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

Python

from google import genai

client = genai.Client()

token = client.auth_tokens.create(
    config = {
    'uses': 1,
    'live_connect_constraints': {
        'model': 'gemini-3.1-flash-live-preview',
        'config': {
            'session_resumption':{},
            'response_modalities':['AUDIO']
        }
    },
    }
)

# 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: {},
                responseModalities: ['AUDIO']
            }
        },
    }
});

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

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uses": 1,
    "expireTime": "YYYY-MM-DDTHH:MM:SSZ",
    "liveConnectConstraints": {
      "model": "models/gemini-3.1-flash-live-preview",
      "config": {
        "sessionResumption": {},
        "responseModalities": ["AUDIO"]
      }
    }
  }'

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

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

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

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

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