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

השימוש באסימון משפר את האבטחה, כי גם אם הוא נשלף, הוא תקף לזמן קצר, בניגוד למפתח API תקף לזמן ארוך שמוטמע בצד הלקוח. מכיוון שהלקוח שולח נתונים ישירות ל-Gemini, זה גם משפר את זמן האחזור ומונע את הצורך בשרתי קצה עורפיים (back-end) שיפעלו כשרתי proxy לנתונים בזמן אמת.
יצירת טוקן זמני
הנה דוגמה פשוטה שמראה איך לקבל מ-Gemini טוקן זמני.
כברירת מחדל, יש לכם דקה אחת להתחיל סשנים חדשים של 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"
}'
בהפניית ה-API מפורטים אילוצים, ערכי ברירת מחדל ומפרטים אחרים של השדה expireTime.
במהלך 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 הפעיל, ורק עם גרסה v1beta של ה-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. - התוקף של האסימונים פג, ולכן צריך להפעיל מחדש את תהליך ההקצאה.
- אימות מאובטח של ה-Backend שלכם. האבטחה של טוקנים זמניים תהיה זהה לזו של שיטת האימות של ה-Backend.
- בדרך כלל, מומלץ להימנע משימוש בטוקנים זמניים לחיבורים בין קצה העורפי ל-Gemini, כי הנתיב הזה נחשב בדרך כלל למאובטח.
מגבלות
בשלב הזה, טוקנים זמניים תואמים רק ל-Live API.
המאמרים הבאים
- מידע נוסף על טוקנים זמניים זמין במאמר בנושא Live API.