API تعاملات

API تعاملات بهترین راه برای ساخت با مدل‌ها و عامل‌های Gemini است. از ژوئن ۲۰۲۶، این API به طور کلی در دسترس است و برای همه پروژه‌های جدید توصیه می‌شود. اگرچه اکنون به عنوان یک نسخه قدیمی در نظر گرفته می‌شود، API generateContent اصلی همچنان به طور کامل پشتیبانی می‌شود.

چرا از API تعاملات استفاده کنیم؟

• رابط کاربری جهانی برای همه برنامه‌ها : به عنوان رابط کاربری استاندارد برای هر مورد استفاده، از جمله تولید متن تک نوبتی، درک چندوجهی، خروجی‌های ساختاریافته، تنظیم ابزار و گردش‌های کاری عامل‌محور طراحی شده است.
• API واحد برای مدل‌ها و عامل‌ها : یک نقطه پایانی و الگوی یکپارچه برای فراخوانی مدل‌های استاندارد Gemini و همچنین عامل‌های تخصصی به طور مستقیم (مانند Deep Research و عامل‌های مدیریت‌شده سفارشی).
• قابلیت‌های جدید از پیش آماده : ویژگی‌هایی مانند وضعیت مکالمه سمت سرور اختیاری با استفاده از previous_interaction_id ، مراحل اجرای قابل مشاهده برای اشکال‌زدایی و رندر رابط کاربری، و اجرای پس‌زمینه برای وظایف طولانی‌مدت با استفاده از background=true .
• هزینه کمتر با نرخ موفقیت بالاتر در حافظه پنهان : هنگام استفاده از مکالمات چند نوبتی، مدیریت وضعیت سمت سرور اختیاری، امکان ذخیره‌سازی کارآمدتر متن در طول نوبت‌ها را فراهم می‌کند و هزینه‌های توکن را کاهش می‌دهد.
• جایی که ویژگی‌های جدید راه‌اندازی می‌شوند : از این به بعد، تمام مدل‌ها، قابلیت‌های چندوجهی، ابزارها و ویژگی‌های عامل‌محور جدید در API تعاملات راه‌اندازی خواهند شد.

به طور پیش‌فرض، API تعاملات درخواست‌ها را ذخیره می‌کند، بنابراین می‌توانید با استفاده از previous_interaction_id از ویژگی‌های مدیریت وضعیت سمت سرور استفاده کنید. می‌توانید با تنظیم store=false ، رفتار بدون وضعیت را انتخاب کنید. برای جزئیات بیشتر به بخش نگهداری داده‌ها مراجعه کنید.

شروع کنید

• عامل کدنویسی خود را تنظیم کنید : به Gemini Docs MCP متصل شوید و مهارت 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 با اجرای پس‌زمینه سازگار نیست و از استفاده previous_interaction_id برای نوبت‌های بعدی جلوگیری می‌کند.

برای پروژه‌های پولی، می‌توانید پنجره‌ی نگهداری اطلاعات را در AI Studio طوری تنظیم کنید که به‌طور خودکار گزارش‌ها را پس از ۷، ۱۴، ۲۸ یا ۵۵ روز از فضای ذخیره‌سازی پروژه حذف کند. نگهداری کوتاه‌تر ممکن است بر بازیابی مکالمات گذشته تأثیر بگذارد.

شما می‌توانید تعاملات ذخیره شده را در هر زمانی با استفاده از روش delete به صورت برنامه‌نویسی شده حذف کنید، که به شناسه تعامل (interaction ID) نیاز دارد. همچنین می‌توانید گزارش‌های تعاملات ذخیره شده، از جمله حذف از فضای ذخیره‌سازی پروژه، را در AI Studio مشاهده و مدیریت کنید.

پس از پایان دوره نگهداری، اطلاعات شما به طور خودکار حذف خواهد شد.

اشیاء تعاملی طبق شرایط پردازش می‌شوند.

مشاهده تعاملات در AI Studio

این API درخواست‌های API مربوط به تعاملات را که با store=true برای پروژه‌های سطح پولی اجرا می‌شوند، ذخیره می‌کند. می‌توانید آن‌ها را مستقیماً از صفحه Logs در Google AI Studio مشاهده کنید. برای اطلاعات بیشتر به راهنمای Logs مراجعه کنید.

بهترین شیوه‌ها

• نرخ موفقیت در حافظه پنهان : حافظه پنهان ضمنی در هر دو حالت با وضعیت و بدون وضعیت پشتیبانی می‌شود ( به شروع سریع مراجعه کنید). استفاده از previous_interaction_id (با وضعیت) برای ادامه مکالمات به سیستم اجازه می‌دهد تا راحت‌تر از حافظه پنهان ضمنی برای تاریخچه مکالمات استفاده کند، که این امر عملکرد را بهبود می‌بخشد و هزینه‌ها را کاهش می‌دهد.
• ترکیب تعاملات : شما انعطاف‌پذیری لازم برای ترکیب و تطبیق تعاملات عامل و مدل را در یک مکالمه دارید. به عنوان مثال، می‌توانید از یک عامل تخصصی مانند عامل Deep Research برای جمع‌آوری داده‌های اولیه استفاده کنید و سپس از یک مدل استاندارد Gemini برای کارهای بعدی مانند خلاصه‌سازی یا قالب‌بندی مجدد استفاده کنید و این مراحل را با previous_interaction_id مرتبط کنید.

مدل‌ها و عامل‌های پشتیبانی‌شده