Ephemeral tokens

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

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

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

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

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

یک توکن زودگذر ایجاد کنید

در اینجا یک مثال ساده از نحوه دریافت یک توکن زودگذر از Gemini آورده شده است. به‌طور پیش‌فرض، 1 دقیقه برای شروع جلسات Live API جدید با استفاده از رمز این درخواست ( newSessionExpireTime ) و 30 دقیقه برای ارسال پیام از طریق آن اتصال ( 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 متصل شوید

در اینجا یک مثال است که از طریق یک توکن زودگذر به Live API متصل می شود. توجه داشته باشید که استفاده از توکن‌های زودگذر فقط هنگام استقرار برنامه‌هایی که از رویکرد پیاده‌سازی کلاینت به سرور پیروی می‌کنند، ارزش می‌افزاید.

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 یک مدت انقضا کوتاه تنظیم کنید.
• توکن‌ها منقضی می‌شوند و نیاز به شروع مجدد فرآیند تأمین است.
• احراز هویت ایمن را برای باطن خود تأیید کنید. توکن های زودگذر فقط به اندازه روش احراز هویت باطن شما ایمن خواهند بود.
• به طور کلی، از استفاده از توکن های زودگذر برای اتصالات Backend-to-Gemini خودداری کنید، زیرا این مسیر معمولاً ایمن در نظر گرفته می شود.

محدودیت ها

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

بعدش چی

• برای اطلاعات بیشتر مرجع Live API در توکن های زودگذر را بخوانید.