الرموز المميزة المؤقتة هي رموز مصادقة قصيرة الأجل للوصول إلى Gemini API من خلال WebSockets. تم تصميمها لتعزيز الأمان عند الاتصال مباشرةً من جهاز المستخدم بواجهة برمجة التطبيقات (تنفيذ من العميل إلى الخادم ). على غرار مفاتيح واجهة برمجة التطبيقات العادية، يمكن استخراج الرموز المميزة المؤقتة من التطبيقات من جهة العميل، مثل متصفّحات الويب أو تطبيقات الأجهزة الجوّالة. ولكن نظرًا إلى أنّ الرموز المميزة المؤقتة تنتهي صلاحيتها بسرعة ويمكن تقييدها، فإنّها تقلّل بشكلٍ كبير من المخاطر الأمنية في بيئة التشغيل الفعلي. عليك استخدامها عند الوصول إلى Live API مباشرةً من التطبيقات من جهة العميل لتعزيز أمان مفتاح واجهة برمجة التطبيقات.
آلية عمل الرموز المميزة المؤقتة
في ما يلي آلية عمل الرموز المميزة المؤقتة على مستوى عالٍ:
- يتم التحقّق من هوية العميل (مثل تطبيق الويب) باستخدام الخلفية.
- تطلب الخلفية رمزًا مميزًا مؤقتًا من خدمة توفير Gemini API.
- يصدر Gemini API رمزًا مميزًا قصير الأجل.
- ترسل الخلفية الرمز المميز إلى العميل من أجل اتصالات WebSocket بـ Live 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()
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 والإعدادات التلقائية ومواصفات الحقول الأخرى، يُرجى مراجعة مرجع واجهة برمجة التطبيقات
.
ضمن الإطار الزمني 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 باستخدام رمز مميز مؤقت
بعد الحصول على رمز مميز مؤقت، يمكنك استخدامه كما لو كان مفتاح واجهة برمجة تطبيقات (ولكن تذكَّر أنّه لا يعمل إلا مع Live 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 حول الرموز المميزة المؤقتة لمزيد من المعلومات.