Ephemeral tokens

توکن‌های زودگذر، توکن‌های احراز هویت کوتاه‌مدت برای دسترسی به API Gemini از طریق WebSockets هستند. آن‌ها برای افزایش امنیت هنگام اتصال مستقیم از دستگاه کاربر به API (پیاده‌سازی کلاینت به سرور ) طراحی شده‌اند. مانند کلیدهای استاندارد API، توکن‌های زودگذر را می‌توان از برنامه‌های سمت کلاینت مانند مرورگرهای وب یا برنامه‌های تلفن همراه استخراج کرد. اما از آنجا که توکن‌های زودگذر به سرعت منقضی می‌شوند و می‌توان آن‌ها را محدود کرد، خطرات امنیتی را در یک محیط عملیاتی به طور قابل توجهی کاهش می‌دهند. شما باید هنگام دسترسی مستقیم به API زنده از برنامه‌های سمت کلاینت، از آن‌ها استفاده کنید تا امنیت کلید API را افزایش دهید.

نحوه عملکرد توکن‌های زودگذر

در اینجا نحوه عملکرد توکن‌های زودگذر در سطح بالا آورده شده است:

1. کلاینت شما (مثلاً برنامه وب) با backend شما احراز هویت می‌شود.
2. بخش مدیریت شما یک توکن موقت از سرویس تأمین API مربوط به Gemini درخواست می‌کند.
3. رابط برنامه‌نویسی نرم‌افزار Gemini یک توکن کوتاه‌مدت صادر می‌کند.
4. بک‌اند شما توکن را برای اتصال WebSocket به Live API به کلاینت ارسال می‌کند. می‌توانید این کار را با تعویض کلید API خود با یک توکن موقت انجام دهید.
5. سپس کلاینت از توکن مانند یک کلید API استفاده می‌کند.

این امر امنیت را افزایش می‌دهد زیرا حتی اگر استخراج شود، توکن برخلاف یک کلید API با عمر طولانی که در سمت کلاینت مستقر می‌شود، کوتاه‌مدت است. از آنجایی که کلاینت داده‌ها را مستقیماً به Gemini ارسال می‌کند، این امر همچنین تأخیر را بهبود می‌بخشد و از نیاز backend های شما به پروکسی کردن داده‌های بلادرنگ جلوگیری می‌کند.

یک توکن موقت ایجاد کنید

در اینجا یک مثال ساده از نحوه دریافت یک توکن موقت از Gemini آورده شده است. به طور پیش‌فرض، شما ۱ دقیقه فرصت دارید تا جلسات جدید Live API را با استفاده از توکن این درخواست ( newSessionExpireTime ) شروع کنید و ۳۰ دقیقه فرصت دارید تا پیام‌ها را از طریق آن اتصال ( expireTime ) ارسال کنید.

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

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 ، برای اتصال مجدد تماس هر 10 دقیقه به sessionResumption نیاز خواهید داشت (این کار را می‌توان با همان توکن انجام داد، حتی اگر uses: 1 ).

همچنین می‌توان یک توکن موقت را به مجموعه‌ای از پیکربندی‌ها قفل کرد. این کار می‌تواند برای بهبود بیشتر امنیت برنامه شما و حفظ دستورالعمل‌های سیستم شما در سمت سرور مفید باشد.

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

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 متصل شوید

وقتی یک توکن موقت داشته باشید، می‌توانید از آن مانند یک کلید API استفاده کنید (اما به یاد داشته باشید، این توکن فقط برای API زنده و فقط با نسخه v1alpha آن API کار می‌کند).

استفاده از توکن‌های زودگذر تنها زمانی ارزش افزوده ایجاد می‌کند که برنامه‌هایی که از رویکرد پیاده‌سازی کلاینت به سرور پیروی می‌کنند، پیاده‌سازی شوند.

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-live-2.5-flash-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 شما ایمن خواهند بود.
• به طور کلی، از استفاده از توکن‌های زودگذر برای اتصالات backend به Gemini خودداری کنید، زیرا این مسیر معمولاً امن در نظر گرفته می‌شود.

محدودیت‌ها

توکن‌های موقت در حال حاضر فقط با Live API سازگار هستند.

قدم بعدی چیست؟

• برای اطلاعات بیشتر، مرجع Live API در مورد توکن‌های موقت را مطالعه کنید.