Gemini 3.8 Flash اکنون در دسترس است. آن را امتحان کنید .

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

Live API - WebSockets API reference

‫Live API یک API حالت‌دار است که از WebSockets استفاده می‌کند. در این بخش، جزئیات بیشتری درباره «میانای برنامه‌سازی کاربردی WebSockets» خواهید دید.

جلسات

اتصال WebSocket جلسه‌ای بین کارخواه و سرور Gemini برقرار می‌کند. پس‌از اینکه کارخواه اتصال جدیدی را آغاز کرد، جلسه می‌تواند با سرور پیام ردوبدل کند تا:

نوشتار، صدا، یا ویدیو را به سرور Gemini ارسال کنید.
درخواست‌های تماس عملکرد، نوشتار، یا صدا را از سرور Gemini دریافت کنید.

اتصال WebSocket

برای شروع جلسه، به این نقطه پایانی وب‌سوکت متصل شوید:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

پیکربندی جلسه

پیام اولیه که پس‌از ایجاد اتصال WebSocket ارسال می‌شود، پیکربندی جلسه را تنظیم می‌کند که شامل مدل، پارامترهای تولید، دستورالعمل‌های سیستم، و ابزارها است.

وقتی اتصال باز است نمی‌توانید پیکربندی را به‌روز کنید. بااین‌حال، هنگام توقف موقت و ازسرگیری ازطریق سازوکار ازسرگیری جلسه، می‌توانید پارامترهای پیکربندی را به‌جز مدل تغییر دهید.

پیکربندی نمونه زیر را ببینید. توجه داشته باشید که حروف نام در کیت‌های توسعه نرم‌افزار ممکن است متفاوت باشد. می‌توانید گزینه‌های پیکربندی «کیت توسعه نرم‌افزار Python» را در اینجا جستجو کنید.


{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object,
    "mediaResolution": object,
    "translationConfig": object
  },
  "systemInstruction": string,
  "tools": [object]
}

برای کسب اطلاعات بیشتر درباره فیلد API، به generationConfig مراجعه کنید.

ارسال کردن پیام‌ها

برای تبادل پیام ازطریق اتصال WebSocket، مشتری باید یک شیء JSON را ازطریق اتصال WebSocket باز ارسال کند. شیء JSON باید دقیقاً یکی از فیلدهای مجموعه شیء زیر را داشته باشد:


{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

پیام‌های کارخواه پشتیبانی‌شده

پیام‌های مشتری پشتیبانی‌شده را در جدول زیر ببینید:

پیام	شرح
`BidiGenerateContentSetup`	پیکربندی جلسه که در اولین پیام ارسال می‌شود
`BidiGenerateContentClientContent`	به‌روزرسانی افزایشی محتوای مکالمه کنونی که از کارخواه ارسال شده است
`BidiGenerateContentRealtimeInput`	ورودی هم‌زمان صوتی، ویدیویی، یا نوشتاری
`BidiGenerateContentToolResponse`	پاسخ به `ToolCallMessage` دریافتی از سرور

دریافت پیام

برای دریافت پیام از Gemini، به رویداد WebSocket «پیام» گوش دهید، و سپس نتیجه را براساس تعریف پیام‌های سرور پشتیبانی‌شده تجزیه کنید.

به موارد زیر مراجعه کنید:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

پیام‌های سرور ممکن است فیلد usageMetadata داشته باشند اما درغیراین‌صورت دقیقاً یکی از فیلدهای دیگر را از BidiGenerateContentServerMessage پیام شامل می‌شوند. (اتحاد messageType در JSON بیان نشده است، بنابراین این فیلد در سطح بالای پیام ظاهر خواهد شد.)

پیام‌ها و رویدادها

ActivityEnd

این نوع فیلدی ندارد.

پایان فعالیت کاربر را علامت‌گذاری می‌کند.

ActivityHandling

روش‌های مختلف مدیریت فعالیت کاربر.

شمارشی‌ها
`ACTIVITY_HANDLING_UNSPECIFIED`	اگر مشخص نشده باشد، عملکرد پیش‌فرض `START_OF_ACTIVITY_INTERRUPTS` است.
`START_OF_ACTIVITY_INTERRUPTS`	اگر درست باشد، شروع فعالیت پاسخ مدل را قطع می‌کند (که به آن «مداخله» نیز گفته می‌شود). پاسخ کنونی مدل در لحظه وقفه قطع خواهد شد. این رفتار پیش‌فرض است.
`NO_INTERRUPTION`	پاسخ مدل قطع نخواهد شد.

ActivityStart

این نوع فیلدی ندارد.

شروع فعالیت کاربر را علامت‌گذاری می‌کند.

AudioTranscriptionConfig

پیکربندی آوانویسی صوتی.

فیلدها
`languageCodes[]`	`string` اختیاری. کدهای زبان BCP-47 که سرنخ‌هایی درباره زبان‌های موجود در صدا ارائه می‌دهند. اگر حذف شود یا خالی باشد، به‌طور پیش‌فرض روی تشخیص خودکار زبان تنظیم می‌شود.
`customVocabulary[]`	`string` اختیاری. فهرستی از عبارت‌های واژگان سفارشی برای گرایش مدل تشخیص گفتار به‌سمت تشخیص اصطلاحات خاص (نام محصولات، اسم خاص، زبان تخصصی).
`wordTimestamp`	`bool` اختیاری. تولید مُهر زمان سطح کلمه را پیکربندی می‌کند.
`diarization`	`bool` اختیاری. بخش‌بندی صدای گوینده را پیکربندی می‌کند.
`mode`	`Mode` اختیاری. حالت ترانویسی را پیکربندی می‌کند. مقادیر پشتیبانی‌شده: `VERBATIM`، `SMART`. اگر مشخص نشده باشد، به‌طور پیش‌فرض روی ترانویسی `VERBATIM` تنظیم می‌شود. در حالت `SMART`، مدل حذف ناروانی (حذف کلمات پرکننده، تکرارها، و شروع‌های نادرست)، پاک‌سازی دستور زبان سبک، قالب‌بندی خودکار (پاراگراف‌ها، نقطه‌گذاری‌ها، فهرست‌های شماره‌دار)، و ویرایش‌های جزئی کاربر (خوداصلاحی‌های درون‌خطی) را انجام می‌دهد. مُهرهای زمان و تفکیک گویندگان با حالت `SMART` سازگار نیست.

حالت

حالت ترانویسی.

شمارشی‌ها
`MODE_UNSPECIFIED`	حالت ترانویسی نامشخص.
`VERBATIM`	حالت ترانویسی دقیق.
`SMART`	حالت ترانویسی هوشمند.

AutomaticActivityDetection

تشخیص خودکار فعالیت را پیکربندی می‌کند.

فیلدها
`disabled`	`bool` اختیاری. اگر فعال باشد (پیش‌فرض)، صدای تشخیص‌داده‌شده و ورودی نوشتاری به‌عنوان فعالیت محسوب می‌شود. اگر غیرفعال باشد، مشتری باید سیگنال‌های فعالیت ارسال کند.
`startOfSpeechSensitivity`	`StartSensitivity` اختیاری. تعیین می‌کند که گفتار چقدر احتمال دارد شناسایی شود.
`prefixPaddingMs`	`int32` اختیاری. مدت زمان لازم برای گفتار تشخیص‌داده‌شده قبل‌از شروع گفتار که باید تعهد شود. هرچه این مقدار کمتر باشد، تشخیص شروع گفتار حساس‌تر است و گفتارهای کوتاه‌تر را می‌توان تشخیص داد. بااین‌حال، این کار احتمال مثبت‌های کاذب را نیز افزایش می‌دهد.
`endOfSpeechSensitivity`	`EndSensitivity` اختیاری. تعیین می‌کند که گفتار شناسایی‌شده چقدر احتمال دارد پایان یابد.
`silenceDurationMs`	`int32` اختیاری. مدت زمان لازم برای شناسایی غیرگفتار (مثلاً سکوت) قبل‌از اینکه پایان گفتار ثبت شود. هرچه این مقدار بزرگ‌تر باشد، فاصله‌های بین گفتار می‌تواند طولانی‌تر باشد بدون اینکه فعالیت کاربر را قطع کند، اما این کار باعث افزایش تأخیر مدل می‌شود.

BidiGenerateContentClientContent

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

پیام در اینجا باعث قطع شدن تولید مدل فعلی می‌شود.

فیلدها

فیلدها
`turns[]`	`Content` اختیاری. محتوا به مکالمه فعلی با مدل پیوست شد. برای پُرسمان‌های تک‌نوبتی، این یک نمونه واحد است. برای پُرسمان‌های چندنوبتی، این فیلد تکرارشونده‌ای است که حاوی سابقه مکالمه و جدیدترین درخواست است.
`turnComplete`	`bool` اختیاری. اگر درست باشد، نشان می‌دهد که تولید محتوای سرور باید با پیام‌واره انباشته‌شده فعلی شروع شود. درغیراین‌صورت، سرور قبل‌از شروع تولید منتظر پیام‌های بیشتری می‌ماند.

turns[]

Content

اختیاری. محتوا به مکالمه فعلی با مدل پیوست شد.

برای پُرسمان‌های تک‌نوبتی، این یک نمونه واحد است. برای پُرسمان‌های چندنوبتی، این فیلد تکرارشونده‌ای است که حاوی سابقه مکالمه و جدیدترین درخواست است.

turnComplete

bool

اختیاری. اگر درست باشد، نشان می‌دهد که تولید محتوای سرور باید با پیام‌واره انباشته‌شده فعلی شروع شود. درغیراین‌صورت، سرور قبل‌از شروع تولید منتظر پیام‌های بیشتری می‌ماند.

BidiGenerateContentRealtimeInput

درونداد کاربر که به‌صورت هم‌زمان ارسال می‌شود.

روش‌های مختلف (صوتی، ویدیویی، و نوشتاری) به‌عنوان جاری‌سازی‌های هم‌زمان مدیریت می‌شوند. ترتیب در این جاری‌سازی‌ها تضمین نمی‌شود.

این ویژگی از چند جهت با BidiGenerateContentClientContent متفاوت است:

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

فیلدها
`mediaChunks[]`	`Blob` اختیاری. داده‌های بایت‌های درون‌خطی برای ورودی رسانه. از چند `mediaChunks` پشتیبانی نمی‌شود، همه به‌جز اولین مورد نادیده گرفته خواهند شد. منسوخ‌شده: درعوض از `audio`،‏ `video`، یا `text` استفاده کنید.
`audio`	`Blob` اختیاری. این‌ها جریان ورودی صوتی هم‌زمان را تشکیل می‌دهند.
`video`	`Blob` اختیاری. این‌ها جریان ورودی ویدیو هم‌زمان را تشکیل می‌دهند.
`activityStart`	`ActivityStart` اختیاری. شروع فعالیت کاربر را علامت‌گذاری می‌کند. این گزارش فقط درصورتی می‌تواند ارسال شود که تشخیص فعالیت خودکار (یعنی سمت سرور) غیرفعال باشد.
`activityEnd`	`ActivityEnd` اختیاری. پایان فعالیت کاربر را علامت‌گذاری می‌کند. این گزارش فقط درصورتی می‌تواند ارسال شود که تشخیص فعالیت خودکار (یعنی سمت سرور) غیرفعال باشد.
`mediaResolution`	`MediaResolution` اختیاری. وضوح رسانه‌ای که باید استفاده شود. اگر مشخص نشده باشد، از `setup.generationConfig.mediaResolution` استفاده می‌شود یا اگر راه‌اندازی ارائه نشده باشد از پیش‌فرض استفاده می‌شود.
`audioStreamEnd`	`bool` اختیاری. نشان می‌دهد که جاری‌سازی صوتی به‌پایان رسیده است، برای مثال، چون میکروفون خاموش شده است. این باید فقط زمانی ارسال شود که تشخیص خودکار فعالیت فعال باشد (که حالت پیش‌فرض است). کارخواه می‌تواند با ارسال پیام صوتی جاری‌سازی را دوباره باز کند.
`text`	`string` اختیاری. این‌ها جریان ورودی نوشتار هم‌زمان را تشکیل می‌دهند.

BidiGenerateContentServerContent

به‌روزرسانی افزایشی سرور که مدل در پاسخ به پیام‌های کارخواه تولید کرده است.

محتوا در سریع‌ترین زمان ممکن تولید می‌شود، نه در زمان واقعی. کاربران می‌توانند انتخاب کنند که آن را بافر کنند و در زمان واقعی پخش کنند.

فیلدها
`generationComplete`	`bool` فقط برونداد. اگر درست باشد، نشان می‌دهد که مدل تولید را تمام کرده است. وقتی مدل درحین تولید وقفه ایجاد می‌کند، پیام «تولید_کامل» در نوبت وقفه‌دار وجود نخواهد داشت، بلکه از «وقفه > نوبت_کامل» عبور خواهد کرد. وقتی مدل بازپخش هم‌زمان را فرض می‌کند، بین generation_complete و turn_complete تأخیری وجود خواهد داشت که ناشی از انتظار مدل برای پایان یافتن بازپخش است.
`turnComplete`	`bool` فقط برونداد. اگر درست باشد، نشان می‌دهد که مدل نوبتش را تمام کرده است. تولید فقط در پاسخ به پیام‌های اضافی مشتری شروع خواهد شد. توجه داشته باشید که وقتی گزارش وضعیت بازپخش فعال باشد، این رویداد فقط زمانی منتشر می‌شود که وضعیت بازپخش نشان دهد بازپخش تمام شده است. وضعیت بازپخش آینده همان نسل نادیده گرفته خواهد شد.
`interrupted`	`bool` فقط برونداد. اگر درست باشد، نشان می‌دهد که پیام مشتری تولید مدل فعلی را قطع کرده است. اگر مشتری درحال پخش محتوا به‌صورت هم‌زمان است، این یک سیگنال خوب برای توقف و خالی کردن صف بازپخش فعلی است.
`groundingMetadata`	`GroundingMetadata` فقط برونداد. فراداده‌های زمینه‌ای برای محتوای تولیدشده.
`inputTranscription`	`BidiGenerateContentTranscription` فقط برونداد. ترانویسی صوتی را وارد کنید. ترانویسی به‌طور مستقل از سایر پیام‌های سرور ارسال می‌شود و ترتیب آن تضمین‌شده نیست.
`interimInputTranscription`	`BidiGenerateContentTranscription` فقط برونداد. ترانویسی با تأخیر کم درحالی‌که کاربر صحبت می‌کند به‌روز می‌شود. این فیلد مشمول به‌روزرسانی‌های مکرر است.
`outputTranscription`	`BidiGenerateContentTranscription` فقط برونداد. ترانویسی صوتی خروجی. این ترانویسی‌ها بخشی از برونداد «تولید» سرور است. ترانویسی برونداد نهایی این نوبت قبل‌از `generationComplete` یا `interrupted` ارسال می‌شود، که به‌نوبه خود با `turnComplete` دنبال می‌شود. ترتیب دقیق بین ترانویسی‌ها و دیگر بروندادهای `modelTurn` تضمین‌شده نیست، اما سرور تلاش می‌کند ترانویسی‌ها را نزدیک به برونداد صوتی مربوطه ارسال کند.
`urlContextMetadata`	`UrlContextMetadata`
`waitingForInput`	`bool` فقط برونداد. اگر درست باشد، نشان می‌دهد که مدل محتوا تولید نمی‌کند زیرا منتظر ورودی بیشتری از کاربر است، مثلاً انتظار دارد کاربر به صحبت ادامه دهد.
`interactionStatus`	`InteractionStatus` فقط برونداد. وضعیت فعالیت فعلی جلسه زنده. همیشه همراه با `turnComplete` ارسال می‌شود.
`modelTurn`	`Content` فقط برونداد. محتوایی که مدل به‌عنوان بخشی از مکالمه فعلی با کاربر تولید کرده است.

BidiGenerateContentServerMessage

پیام پاسخ برای تماس BidiGenerateContent.

فیلدها
`usageMetadata`	`UsageMetadata` فقط برونداد. فراداده‌های استفاده درباره پاسخ(ها).
`voiceActivity`	`VoiceActivity` فقط برونداد. فعالیت گفتاری در جاری‌سازی صوتی شناسایی شد.
فیلد اتحادیه `messageType`. نوع پیام. ‫`messageType` فقط می‌تواند یکی از موارد زیر باشد:
`setupComplete`	`BidiGenerateContentSetupComplete` فقط برونداد. وقتی راه‌اندازی کامل شد، در پاسخ به پیام `BidiGenerateContentSetup` از مشتری ارسال می‌شود.
`serverContent`	`BidiGenerateContentServerContent` فقط برونداد. محتوای تولیدشده توسط مدل در پاسخ به پیام‌های کارخواه.
`toolCall`	`BidiGenerateContentToolCall` فقط برونداد. درخواست از کارخواه برای اجرای `functionCalls` و برگرداندن پاسخ‌ها با `id`های منطبق.
`toolCallCancellation`	`BidiGenerateContentToolCallCancellation` فقط برونداد. اعلان به کارخواه مبنی بر اینکه `ToolCallMessage` قبلاً صادرشده با `id` مشخص‌شده باید لغو شود.
`goAway`	`GoAway` فقط برونداد. اعلامیه‌ای مبنی بر اینکه سرور به‌زودی قطع خواهد شد.
`sessionResumptionUpdate`	`SessionResumptionUpdate` فقط برونداد. به‌روزرسانی وضعیت ازسرگیری جلسه.

BidiGenerateContentSetup

پیام در اول (و فقط در BidiGenerateContentClientMessage اول) ارسال می‌شود. شامل پیکربندی‌ای است که برای مدت زمان جاری‌سازی RPC اعمال خواهد شد.

کاربران باید قبل‌از ارسال هرگونه پیام اضافی، منتظر پیام BidiGenerateContentSetupComplete بمانند.

فیلدها
`model`	`string` الزامی. نام منبع مدل. این به‌عنوان شناسه برای استفاده «مدل» عمل می‌کند. قالب: `models/{model}`
`generationConfig`	`GenerationConfig` اختیاری. پیکربندی تولید. از فیلدهای زیر پشتیبانی نمی‌شود: `responseLogprobs` `responseMimeType` `logprobs` `responseSchema` `responseJsonSchema` `stopSequence` `skipResponseCache` `routingConfig` `audioTimestamp`
`systemInstruction`	`Content` اختیاری. کاربر دستورالعمل‌های سیستم را برای مدل ارائه کرده است. توجه: فقط باید از نوشتار در بخش‌ها استفاده شود و محتوای هر بخش در پاراگراف جداگانه‌ای قرار خواهد گرفت.
`tools[]`	`Tool` اختیاری. فهرستی از `Tools` که مدل ممکن است برای تولید پاسخ بعدی استفاده کند. `Tool` بخشی از کد است که سیستم را قادر می‌سازد با سیستم‌های خارجی تعامل داشته باشد تا کنش یا مجموعه‌ای از کنش‌ها را خارج از دانش و محدوده مدل انجام دهد.
`realtimeInputConfig`	`RealtimeInputConfig` اختیاری. نحوه مدیریت ورودی هم‌زمان را پیکربندی می‌کند.
`sessionResumption`	`SessionResumptionConfig` اختیاری. سازوکار ازسرگیری جلسه را پیکربندی می‌کند. اگر اضافه شود، سرور `SessionResumptionUpdate` پیام ارسال خواهد کرد.
`contextWindowCompression`	`ContextWindowCompressionConfig` اختیاری. سازوکار فشرده‌سازی پنجره زمینه‌ای را پیکربندی می‌کند. اگر اضافه شود، سرور به‌طور خودکار اندازه زمینه‌ای را که از طول پیکربندی‌شده فراتر رفته است کاهش می‌دهد.
`inputAudioTranscription`	`AudioTranscriptionConfig` اختیاری. اگر تنظیم شده باشد، ترانویسی ورودی گفتاری را فعال می‌کند. آوانویسی با زبان صدای ورودی هماهنگ می‌شود، درصورتی‌که پیکربندی شده باشد.
`outputAudioTranscription`	`AudioTranscriptionConfig` اختیاری. اگر تنظیم شود، ترانویسی خروجی صوتی مدل را فعال می‌کند. ترانویسی با کد زبان مشخص‌شده برای صدای خروجی، درصورت پیکربندی، مطابقت دارد.
`proactivity`	`ProactivityConfig` اختیاری. فعال بودن مدل را پیکربندی می‌کند. این کار به مدل اجازه می‌دهد به‌صورت پیش‌کنش به ورودی پاسخ دهد و ورودی نامربوط را نادیده بگیرد.
`historyConfig`	`HistoryConfig` اختیاری. تبادل سابقه بین کارخواه و سرور را پیکربندی می‌کند.
`labels`	`map<string, string>` اختیاری. برچسب‌های دارای فراداده تعریف‌شده توسط کاربر برای درخواست. اختیاری. برچسب‌ها باید از الزامات استاندارد برچسب Cloud یکپارچه پیروی کنند: - کلیدهای برچسب باید با حروف الفبا شروع شوند. - کلیدها و مقادیر برچسب نباید بیشتر از ۶۳ نویسه (نقطه‌های کد یونیکد) باشند و فقط می‌توانند حاوی حروف کوچک، نویسه‌های عددی، زیرخط، و خط تیره باشند. - نویسه‌های بین‌المللی مجاز هستند. کاربرد: - شناسه‌های ایمنی از تجمیع‌کننده‌ها: از کلید `safety_identifier` استفاده کنید (برای نمونه `{"safety_identifier": "user_session_123"}`)

BidiGenerateContentSetupComplete

این نوع فیلدی ندارد.

در پاسخ به پیام BidiGenerateContentSetup از مشتری ارسال شده است.

BidiGenerateContentToolCall

درخواست از کارخواه برای اجرای functionCalls و برگرداندن پاسخ‌ها با idهای منطبق.

فیلدها

فیلدها
`functionCalls[]`	`FunctionCall` فقط برونداد. فراخوانی تابعی که باید اجرا شود.

functionCalls[]

FunctionCall

فقط برونداد. فراخوانی تابعی که باید اجرا شود.

BidiGenerateContentToolCallCancellation

اعلان به مشتری مبنی بر اینکه ToolCallMessage قبلاً صادرشده با id مشخص‌شده نباید اجرا می‌شد و باید لغو شود. اگر آن فراخوانی‌های ابزار عوارض جانبی داشته باشند، ممکن است مشتریان تلاش کنند فراخوانی‌های ابزار را واگرد کنند. این پیام فقط در مواردی رخ می‌دهد که کارخواه‌ها نوبت سرور را قطع می‌کنند.

فیلدها

فیلدها
`ids[]`	`string` فقط برونداد. شناسه‌های تماس‌های ابزار که باید لغو شوند.

ids[]

string

فقط برونداد. شناسه‌های تماس‌های ابزار که باید لغو شوند.

BidiGenerateContentToolResponse

کارخواه به ToolCall دریافتی از سرور پاسخ داد. اشیاء FunctionResponse تکی براساس فیلد id با اشیاء FunctionCall مربوطه مطابقت داده می‌شوند.

توجه داشته باشید که در «میاناهای برنامه‌سازی کاربردی» یک‌تایی و جاری‌سازی سرور GenerateContent، فراخوانی تابع با تبادل Content بخش انجام می‌شود، درحالی‌که در «میاناهای برنامه‌سازی کاربردی» دوطرفه GenerateContent، فراخوانی تابع ازطریق این مجموعه اختصاصی از پیام‌ها انجام می‌شود.

فیلدها

فیلدها
`functionResponses[]`	`FunctionResponse` اختیاری. پاسخ به فراخوانی‌های تابع.

functionResponses[]

FunctionResponse

اختیاری. پاسخ به فراخوانی‌های تابع.

BidiGenerateContentTranscription

ترانویسی صدا (ورودی یا خروجی).

فیلدها
`text`	`string` نوشتار ترانویسی.
`languageCode`	`string` کد زبان BCP-47 ترانویسی.
`startOffset`	`Duration` اختیاری. شروع افست زمانی ترانویسی نسبت‌به شروع صدا.
`endOffset`	`Duration` اختیاری. انتهای جبران زمان ترانویسی نسبت‌به شروع صدا.

ContextWindowCompressionConfig

فشرده‌سازی پنجره زمینه‌ای را فعال می‌کند — سازوکاری برای مدیریت پنجره زمینه‌ای مدل به‌طوری که از طول معینی فراتر نرود.

فیلدها

فیلدها
فیلد اتحادیه `compressionMechanism`. سازوکار فشرده‌سازی پنجره بافت استفاده‌شده. ‫`compressionMechanism` فقط می‌تواند یکی از موارد زیر باشد:
`slidingWindow`	`SlidingWindow` سازوکار پنجره لغزنده.
`triggerTokens`	`int64` تعداد نشانه‌هایی (قبل‌از اجرای نوبت) که برای راه‌اندازی فشرده‌سازی پنجره زمینه‌ای لازم است. از این تنظیم می‌توان برای ایجاد تعادل بین کیفیت و تأخیر استفاده کرد، زیرا پنجره‌های زمینه‌ای کوتاه‌تر ممکن است منجر به پاسخ‌های سریع‌تر مدل شود. بااین‌حال، هرگونه عملیات فشرده‌سازی باعث افزایش موقت تأخیر می‌شود، بنابراین نباید به‌طور مکرر راه‌اندازی شوند. اگر تنظیم نشده باشد، مقدار پیش‌فرض ۸۰٪ از حد پنجره زمینه‌ای مدل است. این کار باعث می‌شود ۲۰٪ برای درخواست کاربر/پاسخ مدل بعدی باقی بماند.

فیلد اتحادیه compressionMechanism. سازوکار فشرده‌سازی پنجره بافت استفاده‌شده. ‫compressionMechanism فقط می‌تواند یکی از موارد زیر باشد:

slidingWindow

SlidingWindow

سازوکار پنجره لغزنده.

triggerTokens

int64

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

از این تنظیم می‌توان برای ایجاد تعادل بین کیفیت و تأخیر استفاده کرد، زیرا پنجره‌های زمینه‌ای کوتاه‌تر ممکن است منجر به پاسخ‌های سریع‌تر مدل شود. بااین‌حال، هرگونه عملیات فشرده‌سازی باعث افزایش موقت تأخیر می‌شود، بنابراین نباید به‌طور مکرر راه‌اندازی شوند.

اگر تنظیم نشده باشد، مقدار پیش‌فرض ۸۰٪ از حد پنجره زمینه‌ای مدل است. این کار باعث می‌شود ۲۰٪ برای درخواست کاربر/پاسخ مدل بعدی باقی بماند.

EndSensitivity

نحوه تشخیص پایان گفتار را تعیین می‌کند.

شمارشی‌ها
`END_SENSITIVITY_UNSPECIFIED`	پیش‌فرض END_SENSITIVITY_HIGH است.
`END_SENSITIVITY_HIGH`	تشخیص خودکار اغلب باعث پایان یافتن گفتار می‌شود.
`END_SENSITIVITY_LOW`	تشخیص خودکار کمتر باعث پایان گفتار می‌شود.

GoAway

اعلامیه‌ای مبنی بر اینکه سرور به‌زودی قطع خواهد شد.

فیلدها

فیلدها
`timeLeft`	`Duration` زمان باقی‌مانده تا قطع شدن اتصال به‌عنوان «لغوشده». این مدت هرگز کمتر از حداقل مدل خاص نخواهد بود که همراه با محدودیت‌های نرخ برای مدل مشخص می‌شود.

timeLeft

Duration

زمان باقی‌مانده تا قطع شدن اتصال به‌عنوان «لغوشده».

این مدت هرگز کمتر از حداقل مدل خاص نخواهد بود که همراه با محدودیت‌های نرخ برای مدل مشخص می‌شود.

HistoryConfig

پیکربندی سابقه.

این پیام به‌عنوان BidiGenerateContentSetup.historyConfig در پیکربندی جلسه گنجانده شده است. تبادل پیام‌های سابقه را پیکربندی می‌کند.

فیلدها

فیلدها
`initialHistoryInClientContent`	`bool` اختیاری. اگر درست باشد، پس‌از ارسال `setupComplete`، سرور منتظر می‌ماند و در ابتدا `clientContent` پیام را تا زمانی‌که `turnComplete` به `true` برسد پردازش می‌کند. این سابقه اولیه باعث فراخوانی مدل نمی‌شود و ممکن است با نقش `MODEL` پایان یابد. پس‌از اینکه `turnComplete` `true` شد، مشتری می‌تواند مکالمه هم‌زمان را ازطریق `realtimeInput` شروع کند.

initialHistoryInClientContent

bool

اختیاری. اگر درست باشد، پس‌از ارسال setupComplete، سرور منتظر می‌ماند و در ابتدا clientContent پیام را تا زمانی‌که turnComplete به true برسد پردازش می‌کند. این سابقه اولیه باعث فراخوانی مدل نمی‌شود و ممکن است با نقش MODEL پایان یابد. پس‌از اینکه turnComplete true شد، مشتری می‌تواند مکالمه هم‌زمان را ازطریق realtimeInput شروع کند.

InteractionStatus

وضعیت‌های مختلف فعالیت جلسه زنده. این فیلد همیشه همراه با turnComplete ارسال می‌شود تا نشان دهد که آیا سرور همه پردازش‌ها را تمام کرده است یا نه.

شمارشی‌ها
`INTERACTION_STATUS_UNSPECIFIED`	وضعیت تعامل نامشخص.
`IN_PROGRESS`	کارساز همچنان به‌طور فعال درحال پردازش ورودی کاربر یا اجرای استدلال پس‌زمینه‌ای است. برونداد مدل بیشتری ممکن است در ادامه بیاید.
`REQUIRES_ACTION`	منسوخ‌شده: به‌جای آن از IDLE استفاده کنید. این مورد منسوخ شده است!
`IDLE`	سرور همه پردازش‌ها و استدلال‌های پس‌زمینه‌ای را تکمیل کرده است.

ProactivityConfig

پیکربندی برای ویژگی‌های پیش‌فعالی.

فیلدها

فیلدها
`proactiveAudio`	`bool` اختیاری. اگر فعال باشد، مدل می‌تواند از پاسخ دادن به پیام‌واره آخر خودداری کند. برای مثال، این کار به مدل امکان می‌دهد گفتار خارج از بافت را نادیده بگیرد یا اگر کاربر هنوز درخواستی نکرده است، سکوت کند.

proactiveAudio

bool

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

RealtimeInputConfig

عملکرد ورودی هم‌زمان را در BidiGenerateContent پیکربندی می‌کند.

فیلدها
`automaticActivityDetection`	`AutomaticActivityDetection` اختیاری. اگر تنظیم نشده باشد، تشخیص خودکار فعالیت به‌طور پیش‌فرض فعال است. اگر تشخیص خودکار صدا غیرفعال باشد، مشتری باید نشان‌های فعالیت ارسال کند.
`activityHandling`	`ActivityHandling` اختیاری. تعریف می‌کند که فعالیت چه تأثیری دارد.
`turnCoverage`	`TurnCoverage` اختیاری. تعریف می‌کند کدام ورودی در نوبت کاربر گنجانده شود.
`interimTranscriptTimestampEnabled`	`bool` اختیاری. مُهرهای زمان ترانویسی موقت را پیکربندی می‌کند.

SessionResumptionConfig

پیکربندی ازسرگیری جلسه.

این پیام به‌عنوان BidiGenerateContentSetup.sessionResumption در پیکربندی جلسه گنجانده شده است. اگر پیکربندی شده باشد، سرور SessionResumptionUpdate پیام ارسال خواهد کرد.

فیلدها

فیلدها
`handle`	`string` دستگیره جلسه قبلی. اگر وجود نداشته باشد، جلسه جدیدی ایجاد می‌شود. دستورات جلسه از مقادیر `SessionResumptionUpdate.token` در اتصالات قبلی می‌آید.

handle

string

دستگیره جلسه قبلی. اگر وجود نداشته باشد، جلسه جدیدی ایجاد می‌شود.

دستورات جلسه از مقادیر SessionResumptionUpdate.token در اتصالات قبلی می‌آید.

SessionResumptionUpdate

به‌روزرسانی وضعیت ازسرگیری جلسه.

فقط درصورتی ارسال می‌شود که BidiGenerateContentSetup.sessionResumption تنظیم شده باشد.

فیلدها

فیلدها
`newHandle`	`string` دستگیره جدیدی که نشان‌دهنده وضعیتی است که می‌تواند ازسر گرفته شود. اگر `resumable`=false، خالی است.
`resumable`	`bool` اگر جلسه کنونی در این نقطه بتواند ازسر گرفته شود، درست است. در برخی‌از نقاط جلسه، ازسرگیری امکان‌پذیر نیست. برای مثال، وقتی مدل درحال اجرای فراخوانی‌های تابع یا تولید است. ازسر گرفتن جلسه (بااستفاده از کد جلسه قبلی) در چنین وضعیتی منجر به ازدست رفتن برخی‌از داده‌ها خواهد شد. در این موارد، `newHandle` خالی خواهد بود و `resumable` نادرست خواهد بود.

newHandle

string

دستگیره جدیدی که نشان‌دهنده وضعیتی است که می‌تواند ازسر گرفته شود. اگر resumable=false، خالی است.

resumable

bool

اگر جلسه کنونی در این نقطه بتواند ازسر گرفته شود، درست است.

در برخی‌از نقاط جلسه، ازسرگیری امکان‌پذیر نیست. برای مثال، وقتی مدل درحال اجرای فراخوانی‌های تابع یا تولید است. ازسر گرفتن جلسه (بااستفاده از کد جلسه قبلی) در چنین وضعیتی منجر به ازدست رفتن برخی‌از داده‌ها خواهد شد. در این موارد، newHandle خالی خواهد بود و resumable نادرست خواهد بود.

SlidingWindow

روش SlidingWindow با کنار گذاشتن محتوا در ابتدای پنجره بافت عمل می‌کند. بافت حاصل همیشه از ابتدای نوبت نقش «کاربر» شروع می‌شود. دستورالعمل‌های سیستم و هرگونه BidiGenerateContentSetup.prefixTurns همیشه در ابتدای نتیجه باقی می‌ماند.

فیلدها

فیلدها
`targetTokens`	`int64` تعداد هدف کدها برای نگهداری. مقدار پیش‌فرض trigger_tokens/2 است. دور انداختن بخش‌هایی از پنجره زمینه‌ای باعث افزایش موقت تأخیر می‌شود، بنابراین این مقدار باید کالیبره شود تا از عملیات فشرده‌سازی مکرر جلوگیری شود.

targetTokens

int64

تعداد هدف کدها برای نگهداری. مقدار پیش‌فرض trigger_tokens/2 است.

دور انداختن بخش‌هایی از پنجره زمینه‌ای باعث افزایش موقت تأخیر می‌شود، بنابراین این مقدار باید کالیبره شود تا از عملیات فشرده‌سازی مکرر جلوگیری شود.

StartSensitivity

نحوه تشخیص شروع گفتار را تعیین می‌کند.

شمارشی‌ها
`START_SENSITIVITY_UNSPECIFIED`	پیش‌فرض START_SENSITIVITY_HIGH است.
`START_SENSITIVITY_HIGH`	تشخیص خودکار شروع گفتار را بیشتر تشخیص می‌دهد.
`START_SENSITIVITY_LOW`	تشخیص خودکار شروع گفتار را کمتر تشخیص می‌دهد.

TurnCoverage

گزینه‌های مربوط به اینکه کدام ورودی در نوبت کاربر گنجانده شود.

شمارشی‌ها
`TURN_COVERAGE_UNSPECIFIED`	اگر مشخص نشده باشد، عملکرد پیش‌فرضی براساس مدل انتخاب می‌شود. برای مثال، برای Gemini 2.5، پیش‌فرض `TURN_INCLUDES_ONLY_ACTIVITY` است، درحالی‌که برای Gemini 3.1 و نسخه‌های بعدی، پیش‌فرض `TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO` است.
`TURN_INCLUDES_ONLY_ACTIVITY`	شامل فعالیت از آخرین نوبت، به‌جز عدم فعالیت (مثلاً سکوت در جاری‌سازی صوتی).
`TURN_INCLUDES_ALL_INPUT`	شامل همه ورودی‌های هم‌زمان از نوبت قبلی، ازجمله عدم فعالیت (مثلاً سکوت در جاری‌سازی صوتی) می‌شود.
`TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`	شامل فعالیت صوتی و همه ویدیوها از آخرین نوبت می‌شود. با تشخیص خودکار فعالیت، فعالیت صوتی یعنی گفتار و شامل سکوت نمی‌شود.

TranslationConfig

پیکربندی برای ویژگی‌های ترجمه.

فیلدها

فیلدها
`targetLanguageCode`	`string` الزامی. زبان مقصد برای ترجمه. مقادیر پشتیبانی‌شده عبارت‌اند از کدهای زبان BCP-47 (مثلاً «en»،‏ «es»،‏ «fr»).
`echoTargetLanguage`	`bool` اختیاری. اگر درست باشد، مدل وقتی زبان مقصد صحبت می‌شود صدا تولید می‌کند، درواقع ورودی را طوطی‌وار تکرار می‌کند. اگر نادرست باشد، برای زبان مقصد صدا تولید نخواهیم کرد.

targetLanguageCode

string

الزامی. زبان مقصد برای ترجمه. مقادیر پشتیبانی‌شده عبارت‌اند از کدهای زبان BCP-47 (مثلاً «en»،‏ «es»،‏ «fr»).

echoTargetLanguage

bool

اختیاری. اگر درست باشد، مدل وقتی زبان مقصد صحبت می‌شود صدا تولید می‌کند، درواقع ورودی را طوطی‌وار تکرار می‌کند. اگر نادرست باشد، برای زبان مقصد صدا تولید نخواهیم کرد.

UrlContextMetadata

فراداده‌های مربوط به ابزار بازیابی بافت نشانی وب.

فیلدها

urlMetadata[]

UrlMetadata

فهرست بافت نشانی وب.

UsageMetadata

فراداده‌های استفاده درباره پاسخ(ها).

فیلدها
`promptTokenCount`	`int32` فقط برونداد. تعداد نشان‌ها در پیام‌واره. وقتی `cachedContent` تنظیم می‌شود، این همچنان اندازه کل پیام‌واره مؤثر است، یعنی شامل تعداد نشانه‌ها در محتوای ذخیره‌شده در حافظه نهان می‌شود.
`cachedContentTokenCount`	`int32` تعداد نشان‌ها در بخش ذخیره‌شده پیام‌واره (محتوای ذخیره‌شده)
`responseTokenCount`	`int32` فقط برونداد. تعداد کل نشان‌ها در همه نامزدهای پاسخ تولیدشده.
`toolUsePromptTokenCount`	`int32` فقط برونداد. تعداد نشان‌های موجود در پیام‌واره(های) استفاده از ابزار.
`thoughtsTokenCount`	`int32` فقط برونداد. تعداد نشانه‌های افکار برای مدل‌های اندیشگر.
`totalTokenCount`	`int32` فقط برونداد. تعداد کل داده‌واحد برای درخواست تولید (پیام‌واره + نامزدهای پاسخ).
`promptTokensDetails[]`	`ModalityTokenCount` فقط برونداد. فهرست روش‌هایی که در ورودی درخواست پردازش شده است.
`cacheTokensDetails[]`	`ModalityTokenCount` فقط برونداد. فهرست روش‌های محتوای ذخیره‌شده در ورودی درخواست.
`responseTokensDetails[]`	`ModalityTokenCount` فقط برونداد. فهرست روش‌هایی که در پاسخ برگردانده شده است.
`toolUsePromptTokensDetails[]`	`ModalityTokenCount` فقط برونداد. فهرست روش‌هایی که برای ورودی‌های درخواست استفاده از ابزار پردازش شده‌اند.

VoiceActivity

فعالیت گفتاری در جاری‌سازی صوتی شناسایی شد.

فیلدها

فیلدها
`type`	`Type` فقط برونداد. نوع سیگنال VAD(تشخیص فعالیت گفتاری).
`audioOffset`	`Duration` فقط برونداد. زمان تشخیص فعالیت گفتاری در زمان صدا، نسبت به شروع جاری‌سازی صدا.

type

Type

فقط برونداد. نوع سیگنال VAD(تشخیص فعالیت گفتاری).

audioOffset

Duration

فقط برونداد. زمان تشخیص فعالیت گفتاری در زمان صدا، نسبت به شروع جاری‌سازی صدا.

نوع

نوع سیگنال VAD.

شمارشی‌ها
`TYPE_UNSPECIFIED`	پیش‌فرض UNSPECIFIED است.
`ACTIVITY_START`	نشان شروع جمله.
`ACTIVITY_END`	نشان پایان جمله.

نمودافزارهای اصالت‌سنجی موقت

با فراخوانی AuthTokenService.CreateToken می‌توان نشان‌های اصالت‌سنجی موقت را دریافت کرد و سپس از آن‌ها با GenerativeService.BidiGenerateContentConstrained استفاده کرد، یا با انتقال نشان در پارامتر پُرسمان access_token، یا در سرایند HTTP Authorization با پیشوند «Token».

CreateAuthTokenRequest

یک نمودار اصالت‌سنجی موقت ایجاد کنید.

فیلدها

فیلدها
`authToken`	`AuthToken` الزامی. رمز برای ایجاد.

authToken

AuthToken

الزامی. رمز برای ایجاد.

AuthToken

درخواستی برای ایجاد یک کد درستی‌سنجی موقت.

فیلدها
`name`	`string` فقط برونداد. شناسه. خود کد.
`expireTime`	`Timestamp` اختیاری. فقط ورودی. تغییرناپذیر. زمان اختیاری‌ای که پس‌از آن، هنگام استفاده از نشان حاصل، پیام‌های جلسه‌های BidiGenerateContent رد خواهد شد. (Gemini ممکن است جلسه را پس‌از این زمان به‌صورت پیش‌دستانه ببندد.) اگر تنظیم نشده باشد، به‌طور پیش‌فرض ۳۰ دقیقه بعد تنظیم می‌شود. اگر تنظیم شده باشد، این مقدار باید کمتر از ۲۰ ساعت در آینده باشد.
`newSessionExpireTime`	`Timestamp` اختیاری. فقط ورودی. تغییرناپذیر. زمانی که پس‌از آن، جلسات جدید «میانای برنامه‌سازی کاربردی پخش زنده» که از کد حاصل از این درخواست استفاده می‌کنند رد خواهند شد. اگر تنظیم نشده باشد، این پیش‌فرض روی ۶۰ ثانیه در آینده تنظیم می‌شود. اگر تنظیم شده باشد، این مقدار باید کمتر از ۲۰ ساعت در آینده باشد.
`fieldMask`	`FieldMask` اختیاری. فقط ورودی. تغییرناپذیر. اگر field_mask خالی باشد و `bidiGenerateContentSetup` وجود نداشته باشد، پیام `BidiGenerateContentSetup` مؤثر از اتصال «میانای برنامه‌سازی کاربردی زنده» گرفته می‌شود. اگر field_mask خالی باشد و `bidiGenerateContentSetup` حضور داشته باشد، پیام `BidiGenerateContentSetup` مؤثر به‌طور کامل از `bidiGenerateContentSetup` در این درخواست گرفته می‌شود. پیام راه‌اندازی از اتصال «میانای برنامه‌سازی کاربردی زنده» نادیده گرفته می‌شود. اگر field_mask خالی نباشد، فیلدهای مربوطه از `bidiGenerateContentSetup` فیلدهای پیام راه‌اندازی را در اتصال «میانای برنامه‌سازی کاربردی زنده» ملغی می‌کند.
فیلد اتحادیه `config`. پیکربندی ویژه روش برای کد اصالت‌سنجی حاصل. ‫`config` فقط می‌تواند یکی از موارد زیر باشد:
`bidiGenerateContentSetup`	`BidiGenerateContentSetup` اختیاری. فقط ورودی. تغییرناپذیر. پیکربندی ویژه `BidiGenerateContent`.
`uses`	`int32` اختیاری. فقط ورودی. تغییرناپذیر. تعداد دفعاتی که می‌توان از رمز استفاده کرد. اگر این مقدار صفر باشد، هیچ محدودیتی اعمال نمی‌شود. ازسرگیری جلسه «میانای برنامه‌سازی کاربردی پخش زنده» به‌عنوان استفاده محسوب نمی‌شود. اگر مشخص نشده باشد، پیش‌فرض ۱ است.

اطلاعات بیشتر درباره انواع رایج

برای کسب اطلاعات بیشتر درباره انواع منابع API که معمولاً استفاده می‌شوند Blob، Content، FunctionCall، FunctionResponse، GenerationConfig، GroundingMetadata، ModalityTokenCount، و Tool، به تولید محتوا مراجعه کنید.