Ephemeral tokens

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

איך פועלים אסימונים זמניים

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

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

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

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

יצירת אסימון חולף

הנה דוגמה פשוטה לאופן שבו מקבלים אסימון חולף מ-Gemini. כברירת מחדל, תהיה לכם דקה אחת כדי להתחיל סשנים חדשים של 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.