رابط برنامهنویسی کاربردی تعاملات (Interactions API) رابط کاربری جدید ما و سادهترین راه برای ساخت با مدلها و عاملهای Gemini است. از ژوئن ۲۰۲۶، این رابط کاربری به صورت عمومی در دسترس بوده و رابط کاربری پیشنهادی برای همه پروژههای جدید است.
اگرچه اکنون به عنوان یک میراث در نظر گرفته میشود، API اصلی generateContent همچنان به طور کامل پشتیبانی میشود.
چرا از API تعاملات استفاده کنیم؟
- قابلیتهای جدید از پیش آماده : حالت مکالمه سمت سرور اختیاری با استفاده از
previous_interaction_id، مراحل اجرای قابل مشاهده برای اشکالزدایی و رندر رابط کاربری، و اجرای پسزمینه برای وظایف طولانیمدت با استفاده ازbackground=true. - هزینه کمتر با نرخ موفقیت بالاتر در حافظه پنهان : مدیریت وضعیت سمت سرور، امکان ذخیرهسازی کارآمدتر محتوا در بین نوبتها را فراهم میکند و هزینههای توکن را برای مکالمات چند نوبتی کاهش میدهد.
- ساخته شده برای مدلها و عاملهای مرزی : به طور خاص برای مدلهای تفکر، استفاده از ابزار چند مرحلهای و جریانهای استدلال پیچیده ساخته شده است - سادهسازی فرآیند ساخت، اشکالزدایی و هماهنگسازی برنامههای عاملمحور.
- API واحد برای مدلها و عاملها : یک رابط یکپارچه برای فراخوانی مستقیم مدلها و عاملهای Gemini مانند Deep Research و عاملهای مدیریتشده سفارشی - بدون نقاط پایانی یا الگوهای جداگانه برای یادگیری.
- جایی که چیزهای جدید راهاندازی میشوند : در ادامه، مدلها و قابلیتهای جدیدی فراتر از خانواده اصلی، همراه با قابلیتها و ابزارهای جدید عاملیتی، در API تعاملات راهاندازی خواهند شد.
به طور پیشفرض، API تعاملات درخواستها را ذخیره میکند، بنابراین میتوانید با استفاده از previous_interaction_id از ویژگیهای مدیریت وضعیت سمت سرور استفاده کنید. میتوانید با تنظیم store=false ، رفتار بدون وضعیت را انتخاب کنید. برای جزئیات بیشتر به بخش نگهداری دادهها مراجعه کنید.
شروع کنید
- عامل کدنویسی خود را تنظیم کنید : به MCP اسناد Gemini متصل شوید و مهارت
gemini-interactions-apiرا نصب کنید تا دستیار شما مستقیماً به جدیدترین اسناد توسعهدهنده و بهترین شیوهها دسترسی داشته باشد. عامل کدنویسی خود را تنظیم کنید → - مهاجرت از
generateContent: اگر از قبل یکپارچهسازی دارید، برای انتقال به Interactions API، راهنمای مهاجرت را دنبال کنید. - شروع به کار : راهنمای شروع به کار با Interactions API .
راهنماهای ویژگی
قابلیتهای خاص Interactions API را از طریق این راهنماها بررسی کنید. میتوانید از دکمهی موجود در این صفحات برای جابجایی بین generateContent و Interactions API استفاده کنید:
- تولید متن
- تولید تصویر
- درک تصویر
- درک صوتی
- درک ویدیو
- پردازش اسناد
- فراخوانی تابع
- خروجی ساختاریافته
- نماینده تحقیقات عمیق
- استنتاج انعطافپذیر
- استنتاج اولویت
نحوه عملکرد API تعاملات
رابط برنامهنویسی کاربردی Interactions حول یک منبع اصلی متمرکز است: Interaction . یک Interaction نشاندهنده یک چرخش کامل در یک مکالمه یا وظیفه است. این رابط به عنوان یک رکورد جلسه عمل میکند و شامل کل تاریخچه یک تعامل به صورت یک توالی زمانی از مراحل اجرا است. این مراحل شامل افکار مدل، فراخوانیها و نتایج ابزار سمت سرور یا سمت کلاینت (مانند function_call و function_result ) و خروجی نهایی model_output است. منبع ذخیره شده (که از طریق interactions.get بازیابی میشود) همچنین شامل مراحل user_input برای متن کامل است، اگرچه پاسخ interactions.create فقط مراحل تولید شده توسط مدل را برمیگرداند.
وقتی که شما interactions.create را فراخوانی میکنید، در واقع یک منبع Interaction جدید ایجاد میکنید.
مدیریت وضعیت سمت سرور
شما میتوانید از id یک تعامل تکمیلشده در فراخوانی بعدی با استفاده از پارامتر previous_interaction_id برای ادامهی مکالمه استفاده کنید. سرور از این شناسه برای بازیابی تاریخچهی مکالمه استفاده میکند و شما را از ارسال مجدد کل تاریخچهی چت بینیاز میکند.
پارامتر previous_interaction_id فقط تاریخچه مکالمه (ورودیها و خروجیها) را با استفاده از previous_interaction_id حفظ میکند. پارامترهای دیگر در محدوده تعامل هستند و فقط برای تعامل خاصی که در حال حاضر ایجاد میکنید اعمال میشوند:
-
tools -
system_instruction -
generation_config(شاملthinking_level،temperatureو غیره)
این بدان معناست که اگر میخواهید این پارامترها اعمال شوند، باید آنها را در هر تعامل جدید دوباره مشخص کنید. این مدیریت وضعیت سمت سرور اختیاری است؛ همچنین میتوانید با ارسال تاریخچه کامل مکالمه در هر درخواست، در حالت بدون وضعیت (stateless) عمل کنید.
ذخیرهسازی و نگهداری دادهها
به طور پیشفرض، API تمام اشیاء Interaction ( store=true ) را ذخیره میکند تا استفاده از ویژگیهای مدیریت وضعیت سمت سرور (با previous_interaction_id )، اجرای پسزمینه (با استفاده از background=true ) و اهداف مشاهدهپذیری را ساده کند.
- سطح پولی : سیستم تعاملات را به مدت ۵۵ روز ذخیره میکند.
- ردیف رایگان : سیستم تعاملات را به مدت ۱ روز نگه میدارد.
اگر این را نمیخواهید، میتوانید در درخواست خود store=false را تنظیم کنید. این کنترل جدا از مدیریت وضعیت است؛ میتوانید از ذخیرهسازی برای هر تعاملی انصراف دهید. با این حال، توجه داشته باشید که store=false با background=true سازگار نیست و از استفاده previous_interaction_id برای نوبتهای بعدی جلوگیری میکند.
شما میتوانید تعاملات ذخیره شده را در هر زمانی با استفاده از متد delete که در مرجع API موجود است، حذف کنید. شما فقط در صورتی میتوانید تعاملات را حذف کنید که شناسه تعامل را بدانید.
پس از پایان دوره نگهداری، اطلاعات شما به طور خودکار حذف خواهد شد.
سیستم اشیاء تعامل را طبق شرایط پردازش میکند.
بهترین شیوهها
- نرخ موفقیت در حافظه پنهان (Cache hit rate ): استفاده از
previous_interaction_idبرای ادامه مکالمات به سیستم اجازه میدهد تا راحتتر از حافظه پنهان ضمنی (implicit caching) برای تاریخچه مکالمات استفاده کند، که این امر باعث بهبود عملکرد و کاهش هزینهها میشود. - ترکیب تعاملات : شما انعطافپذیری لازم برای ترکیب و تطبیق تعاملات عامل و مدل را در یک مکالمه دارید. به عنوان مثال، میتوانید از یک عامل تخصصی مانند عامل Deep Research برای جمعآوری دادههای اولیه استفاده کنید و سپس از یک مدل استاندارد Gemini برای کارهای بعدی مانند خلاصهسازی یا قالببندی مجدد استفاده کنید و این مراحل را با
previous_interaction_idمرتبط کنید.
مدلها و عاملهای پشتیبانیشده
| نام مدل | نوع | شناسه مدل |
|---|---|---|
| فلش جمینی ۳.۵ | مدل | gemini-3.5-flash |
| پیشنمایش Gemini 3.1 Pro | مدل | gemini-3.1-pro-preview |
| جمینی ۳.۱ فلش-لایت | مدل | gemini-3.1-flash-lite |
| پیشنمایش فلش جمینی ۳ | مدل | gemini-3-flash-preview |
| جمینی ۲.۵ پرو | مدل | gemini-2.5-pro |
| فلش جمینی ۲.۵ | مدل | gemini-2.5-flash |
| جمینی ۲.۵ فلش لایت | مدل | gemini-2.5-flash-lite |
| تصویر Gemini 3 Pro | مدل | gemini-3-pro-image |
| تصویر فلش Gemini 3.1 | مدل | gemini-3.1-flash-image |
| پیشنمایش TTS فلش جمینی ۳.۱ | مدل | gemini-3.1-flash-tts-preview |
| جما ۴ ۳۱ب آیتی | مدل | gemma-4-31b-it |
| جما ۴ ۲۶ب، وزارت آموزش و پرورش، فناوری اطلاعات | مدل | gemma-4-26b-a4b-it |
| پیشنمایش کلیپ لیریا ۳ | مدل | lyria-3-clip-preview |
| پیشنمایش Lyria 3 Pro | مدل | lyria-3-pro-preview |
| پیشنمایش تحقیقات عمیق | عامل | deep-research-preview-04-2026 |
| پیشنمایش تحقیقات عمیق | عامل | deep-research-max-preview-04-2026 |
| پیشنمایش ضدجاذبه | عامل | antigravity-preview-05-2026 |
SDK ها
برای دسترسی به API تعاملات میتوانید از آخرین نسخه Google GenAI SDKs استفاده کنید.
- در پایتون، این بسته
google-genaiاز نسخه2.3.0به بعد است. - در جاوا اسکریپت، این پکیج
@google/genaiاز نسخه2.3.0به بعد است.
میتوانید درباره نحوه نصب SDKها در صفحه کتابخانهها بیشتر بیاموزید.
محدودیتها
- کنترل از راه دور MCP : جمینی ۳ از کنترل از راه دور MCP پشتیبانی نمیکند، این قابلیت به زودی اضافه خواهد شد.
ویژگیهای زیر توسط generateContent API پشتیبانی میشوند اما هنوز در Interactions API در دسترس نیستند :
- فراداده ویدئو : فیلد
video_metadata، که برای تنظیم فواصل برش و نرخ فریم سفارشی برای درک ویدئو استفاده میشود. - API دستهای
- فراخوانی خودکار توابع (پایتون)
- ذخیره سازی ضمنی (Explicit caching ): توجه داشته باشید که ذخیره سازی ضمنی سمت سرور (Server-side caching) از طریق
previous_interaction_idدر Interactions API در دسترس است.
بازخورد
بازخورد شما برای توسعهی Interactions API بسیار مهم است. نظرات خود را به اشتراک بگذارید، اشکالات را گزارش دهید یا درخواست ویژگیها را در انجمن توسعهدهندگان Google AI ما داشته باشید.
قدم بعدی چیست؟
- دفترچه راهنمای شروع سریع Interactions API را امتحان کنید.
- درباره مامور تحقیقات عمیق جمینی بیشتر بدانید.