API تعاملات (Interactions API) سادهترین و بهترین روش ما برای ساخت با مدلها و عاملهای Gemini است. از ژوئن ۲۰۲۶، این API به طور کلی در دسترس است و برای همه پروژههای جدید توصیه میشود. اگرچه اکنون به عنوان یک نسخه قدیمی در نظر گرفته میشود، API اصلی generateContent همچنان به طور کامل پشتیبانی میشود.
چرا از API تعاملات استفاده کنیم؟
- رابط کاربری جهانی برای همه برنامهها : به عنوان رابط کاربری استاندارد برای هر مورد استفاده، از جمله تولید متن تک نوبتی، درک چندوجهی، خروجیهای ساختاریافته، تنظیم ابزار و گردشهای کاری عاملمحور طراحی شده است.
- API واحد برای مدلها و عاملها : یک نقطه پایانی و الگوی یکپارچه برای فراخوانی مدلهای استاندارد Gemini و همچنین عاملهای تخصصی به طور مستقیم (مانند Deep Research و عاملهای مدیریتشده سفارشی).
- قابلیتهای جدید از پیش آماده : ویژگیهایی مانند وضعیت مکالمه سمت سرور اختیاری با استفاده از
previous_interaction_id، مراحل اجرای قابل مشاهده برای اشکالزدایی و رندر رابط کاربری، و اجرای پسزمینه برای وظایف طولانیمدت با استفاده ازbackground=true. - هزینه کمتر با نرخ موفقیت بالاتر در حافظه پنهان : هنگام استفاده از مکالمات چند نوبتی، مدیریت وضعیت سمت سرور اختیاری، امکان ذخیرهسازی کارآمدتر متن در طول نوبتها را فراهم میکند و هزینههای توکن را کاهش میدهد.
- جایی که ویژگیهای جدید راهاندازی میشوند : از این به بعد، تمام مدلها، قابلیتهای چندوجهی، ابزارها و ویژگیهای عاملمحور جدید در API تعاملات راهاندازی خواهند شد.
به طور پیشفرض، API تعاملات درخواستها را ذخیره میکند، بنابراین میتوانید با استفاده از previous_interaction_id از ویژگیهای مدیریت وضعیت سمت سرور استفاده کنید. میتوانید با تنظیم store=false ، رفتار بدون وضعیت را انتخاب کنید. برای جزئیات بیشتر به بخش نگهداری دادهها مراجعه کنید.
شروع کنید
- عامل کدنویسی خود را تنظیم کنید : به MCP اسناد Gemini متصل شوید و مهارت
gemini-interactions-apiرا نصب کنید تا دستیار شما مستقیماً به جدیدترین اسناد توسعهدهنده و بهترین شیوهها دسترسی داشته باشد. عامل کدنویسی خود را تنظیم کنید → - مهاجرت از
generateContent: اگر از قبل یکپارچهسازی دارید، برای انتقال به Interactions API، راهنمای مهاجرت را دنبال کنید. - شروع به کار : راهنمای شروع به کار با 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 با اجرای پسزمینه سازگار نیست و از استفاده previous_interaction_id برای نوبتهای بعدی جلوگیری میکند.
شما میتوانید تعاملات ذخیره شده را در هر زمانی با استفاده از متد delete که در مرجع API موجود است، حذف کنید. شما فقط در صورتی میتوانید تعاملات را حذف کنید که شناسه تعامل را بدانید.
پس از پایان دوره نگهداری، اطلاعات شما به طور خودکار حذف خواهد شد.
سیستم اشیاء تعامل را طبق شرایط پردازش میکند.
بهترین شیوهها
- نرخ موفقیت در حافظه پنهان : حافظه پنهان ضمنی در هر دو حالت با وضعیت و بدون وضعیت پشتیبانی میشود ( به شروع سریع مراجعه کنید). استفاده از
previous_interaction_id(با وضعیت) برای ادامه مکالمات به سیستم اجازه میدهد تا راحتتر از حافظه پنهان ضمنی برای تاریخچه مکالمات استفاده کند، که این امر عملکرد را بهبود میبخشد و هزینهها را کاهش میدهد. - ترکیب تعاملات : شما انعطافپذیری لازم برای ترکیب و تطبیق تعاملات عامل و مدل را در یک مکالمه دارید. به عنوان مثال، میتوانید از یک عامل تخصصی مانند عامل 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-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 پشتیبانی نمیکند، این قابلیت به زودی اضافه خواهد شد.
- سازگاری مدل چند نوبتی : هنگام ترکیب مدلهای مختلف در یک مکالمه (چه با وضعیت و چه بدون وضعیت)، مدلهای بعدی باید از روشهای خروجی مدلهای قبلی به عنوان ورودی پشتیبانی کنند. برای مثال، اگر با استفاده از
gemini-3.1-flash-imageتصویری تولید میکنید، نمیتوانید آن مکالمه را با مدلی که ورودیهای تصویر را نمیپذیرد (مانند یک مدل فقط متن یا یک مدل تولید موسیقی مانند Lyria) ادامه دهید.
ویژگیهای زیر توسط generateContent API پشتیبانی میشوند اما هنوز در Interactions API در دسترس نیستند :
- فراداده ویدئو : فیلد
video_metadata، که برای تنظیم فواصل برش و نرخ فریم سفارشی برای درک ویدئو استفاده میشود. - API دستهای
- فراخوانی خودکار توابع (پایتون)
- ذخیره سازی ضمنی (Explicit caching ): توجه داشته باشید که ذخیره سازی ضمنی سمت سرور (Server-side caching) از طریق
previous_interaction_idدر Interactions API در دسترس است. - تنظیمات ایمنی : تنظیمات ایمنی سفارشی در Interactions API پشتیبانی نمیشوند.
بازخورد
بازخورد شما برای توسعهی Interactions API بسیار مهم است. نظرات خود را به اشتراک بگذارید، اشکالات را گزارش دهید یا درخواست ویژگیها را در انجمن توسعهدهندگان Google AI ما داشته باشید.
قدم بعدی چیست؟
- دفترچه راهنمای شروع سریع Interactions API را امتحان کنید.
- درباره مامور تحقیقات عمیق جمینی بیشتر بدانید.