אסימונים זמניים

טוקנים זמניים הם טוקנים קצרי-חיים לאימות גישה ל-Gemini API דרך WebSockets. הם נועדו לשפר את האבטחה כשמתחברים ישירות ממכשיר של משתמש ל-API (הטמעה של client-to-server). כמו מפתחות API רגילים, אפשר לחלץ טוקנים זמניים מאפליקציות בצד הלקוח, כמו דפדפני אינטרנט או אפליקציות לנייד. אבל מכיוון שהטוקנים הזמניים פוקעים במהירות ואפשר להגביל אותם, הם מפחיתים באופן משמעותי את סיכוני האבטחה בסביבת ייצור. מומלץ להשתמש בהם כשניגשים ל-Live API ישירות מאפליקציות בצד הלקוח כדי לשפר את האבטחה של מפתחות ה-API.

איך פועלים טוקנים זמניים

כך פועלים טוקנים זמניים ברמה גבוהה:

  1. הלקוח (לדוגמה, אפליקציית אינטרנט) עובר אימות עם ה-Backend.
  2. הבקשות מהקצה העורפי שולחות טוקן זמני משירות ההקצאה של Gemini API.
  3. ‫Gemini API מנפיק אסימון לטווח קצר.
  4. הקצה העורפי שולח את הטוקן ללקוח לחיבורי WebSocket ל-Live API. אפשר לעשות זאת על ידי החלפת מפתח ה-API בטוקן זמני.
  5. לאחר מכן הלקוח משתמש באסימון כאילו היה מפתח API.

סקירה כללית על טוקנים זמניים

השימוש בשיטה הזו משפר את האבטחה, כי גם אם האסימון יחולץ, הוא יהיה תקף לזמן קצר, בניגוד למפתח API לטווח ארוך שמוטמע בצד הלקוח. בנוסף, מכיוון שהלקוח שולח נתונים ישירות ל-Gemini, השיטה הזו משפרת את זמן האחזור ומונעת מהקצה העורפי שלכם להעביר את הנתונים בזמן אמת.

יצירת טוקן זמני

הנה דוגמה פשוטה שמראה איך לקבל מ-Gemini טוקן זמני. כברירת מחדל, יש לכם דקה אחת להתחיל סשנים חדשים של Live API באמצעות האסימון מהבקשה הזו (newSessionExpireTime), ו-30 דקות לשלוח הודעות דרך החיבור הזה (expireTime).

Python

import datetime
from google import genai

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 = 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'},
    },
  });

בהפניית ה-API מפורטים אילוצים, ערכי ברירת מחדל ומפרטים אחרים של השדה expireTime. במהלך expireTime הזמן הזה, תצטרכו sessionResumption להתחבר מחדש לשיחה כל 10 דקות (אפשר לעשות את זה עם אותו אסימון גם אם uses: 1).

אפשר גם לנעול טוקן זמני לקבוצה של הגדרות. האפשרות הזו יכולה להיות שימושית לשיפור נוסף של האבטחה באפליקציה ולשמירה על הוראות המערכת בצד השרת.

Python

from google import genai

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 (אבל חשוב לזכור שהוא פועל רק עם ה-API הפעיל, ורק עם גרסה v1alpha של ה-API).

השימוש בטוקנים זמניים מוסיף ערך רק כשפורסים אפליקציות שפועלות לפי גישת הטמעה מלקוח לשרת.

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.

המאמרים הבאים