API تعاملات

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

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

  • رابط کاربری جهانی برای همه برنامه‌ها : به عنوان رابط کاربری استاندارد برای هر مورد استفاده، از جمله تولید متن تک نوبتی، درک چندوجهی، خروجی‌های ساختاریافته، تنظیم ابزار و گردش‌های کاری عامل‌محور طراحی شده است.
  • API واحد برای مدل‌ها و عامل‌ها : یک نقطه پایانی و الگوی یکپارچه برای فراخوانی مدل‌های استاندارد Gemini و همچنین عامل‌های تخصصی به طور مستقیم (مانند Deep Research و عامل‌های مدیریت‌شده سفارشی).
  • New capabilities out of the box : Features like optional server-side conversation state using previous_interaction_id , observable execution steps for debugging and UI rendering, and background execution for long-running tasks using background=true .
  • هزینه کمتر با نرخ موفقیت بالاتر در حافظه پنهان : هنگام استفاده از مکالمات چند نوبتی، مدیریت وضعیت سمت سرور اختیاری، امکان ذخیره‌سازی کارآمدتر متن در طول نوبت‌ها را فراهم می‌کند و هزینه‌های توکن را کاهش می‌دهد.
  • جایی که ویژگی‌های جدید راه‌اندازی می‌شوند : از این به بعد، تمام مدل‌ها، قابلیت‌های چندوجهی، ابزارها و ویژگی‌های عامل‌محور جدید در API تعاملات راه‌اندازی خواهند شد.

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

شروع کنید

راهنماهای ویژگی

قابلیت‌های خاص 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) عمل کنید.

ذخیره‌سازی و نگهداری داده‌ها

By default, the API stores all Interaction objects ( store=true ) in order to simplify use of server-side state management features (with previous_interaction_id ), background execution (using background=true ) and observability purposes.

  • سطح پولی : سیستم تعاملات را به مدت ۵۵ روز ذخیره می‌کند.
  • ردیف رایگان : سیستم تعاملات را به مدت ۱ روز نگه می‌دارد.

اگر این را نمی‌خواهید، می‌توانید در درخواست خود 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 مرتبط کنید.

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

نام مدل نوع شناسه مدل
فلش جمینی ۳.۵ مدل 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 استفاده کنید.

  • On Python, this is google-genai package from 2.3.0 version onwards.
  • در جاوا اسکریپت، این پکیج @google/genai از نسخه 2.3.0 به بعد است.

می‌توانید درباره نحوه نصب SDKها در صفحه کتابخانه‌ها بیشتر بیاموزید.

محدودیت‌ها

  • کنترل از راه دور MCP : جمینی ۳ از کنترل از راه دور MCP پشتیبانی نمی‌کند، این قابلیت به زودی اضافه خواهد شد.
  • سازگاری مدل چند نوبتی : هنگام ترکیب مدل‌های مختلف در یک مکالمه (چه با وضعیت و چه بدون وضعیت)، مدل‌های بعدی باید از روش‌های خروجی مدل‌های قبلی به عنوان ورودی پشتیبانی کنند. برای مثال، اگر با استفاده از gemini-3.1-flash-image تصویری تولید می‌کنید، نمی‌توانید آن مکالمه را با مدلی که ورودی‌های تصویر را نمی‌پذیرد (مانند یک مدل فقط متنی یا یک مدل تولید موسیقی مانند Lyria) ادامه دهید.

ویژگی‌های زیر توسط generateContent API پشتیبانی می‌شوند اما هنوز در Interactions API در دسترس نیستند :

بازخورد

بازخورد شما برای توسعه‌ی Interactions API بسیار مهم است. نظرات خود را به اشتراک بگذارید، اشکالات را گزارش دهید یا درخواست ویژگی‌ها را در انجمن توسعه‌دهندگان Google AI ما داشته باشید.

قدم بعدی چیست؟