‫Interactions API (میانای برنامه‌سازی کاربردی تعاملات)

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

چرا باید از Interactions API استفاده کرد؟

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

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

شروع کنید

• عامل کدنویسی‌تان را راه‌اندازی کنید: به Gemini Docs MCP متصل شوید و مهارت gemini-api-dev را نصب کنید تا دستیارتان دسترسی مستقیم به جدیدترین اسناد توسعه‌دهنده و روال‌های مطلوب داشته باشد. برای مراحل دقیق، راهنمای راه‌اندازی عامل کدنویسی را ببینید
• انتقال از generateContent: اگر ادغام موجودی دارید، راهنمای انتقال را دنبال کنید تا به Interactions API منتقل شوید.
• شروع به کار: مراحل موجود در راهنمای شروع به کار Interactions API را دنبال کنید.

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

بااستفاده از این راهنماها، قابلیت‌های خاص Interactions API را کاوش کنید. می‌توانید از کلید روی این صفحه‌ها برای جابه‌جایی بین generateContent و Interactions API استفاده کنید:

• تولید نوشتار
• تولید تصویر
• درک تصویر
• درک صدا
• درک ویدیو
• پردازش سند
• فراخوانی تابع
• برونداد ساختاریافته
• کارگزار Deep Research
• استنتاج انعطاف‌پذیر
• استنتاج اولویت

نحوه عملکرد Interactions API

‫Interactions API حول یک منبع اصلی متمرکز است: Interaction. Interaction نشان‌دهنده یک نوبت کامل در مکالمه یا تکلیف است. این فایل به‌عنوان سابقه جلسه عمل می‌کند و حاوی کل سابقه تعامل به‌عنوان توالی زمانی مراحل اجرا است. این مراحل شامل افکار مدل، تماس‌ها و نتایج ابزار سمت سرور یا سمت مشتری (مثل function_call و function_result)، و model_output نهایی است. منبع ذخیره‌شده (که ازطریق interactions.get بازیابی شده است) همچنین شامل مراحل user_input برای بافت کامل است، اگرچه پاسخ interactions.create فقط مراحل تولیدشده توسط مدل را برمی‌گرداند.

وقتی با interactions.create تماس می‌گیرید، منبع Interaction جدیدی ایجاد می‌کنید:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'

مدیریت وضعیت سمت سرور

می‌توانید از id تعامل تکمیل‌شده در تماس بعدی بااستفاده از پارامتر previous_interaction_id برای ادامه مکالمه استفاده کنید. سرور از این شناسه برای بازیابی سابقه مکالمه استفاده می‌کند و شما را از ارسال مجدد کل سابقه گپ بی‌نیاز می‌کند:

from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}

# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID"
  }'

پارامتر previous_interaction_id فقط سابقه مکالمه (ورودی‌ها و خروجی‌ها) را بااستفاده از previous_interaction_id حفظ می‌کند. پارامترهای دیگر محدوده تعامل دارند و فقط برای تعامل خاصی که درحال تولید آن هستید اعمال می‌شوند:

• tools
• system_instruction
• generation_config (شامل thinking_level، temperature، و غیره)

این یعنی اگر می‌خواهید این پارامترها اعمال شوند، باید آن‌ها را در هر تعامل جدید دوباره مشخص کنید. این مدیریت وضعیت سمت سرور اختیاری است؛ همچنین می‌توانید با ارسال کامل سابقه مکالمه در هر درخواست، در حالت بدون وضعیت عمل کنید.

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

به‌طور پیش‌فرض، API همه «اشیا تعامل» (store=true) را ذخیره می‌کند تا استفاده از ویژگی‌های مدیریت وضعیت سمت سرور (با previous_interaction_id)، اجرای پس‌زمینه (بااستفاده از background=true)، و اهداف مشاهده‌پذیری را ساده کند.

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

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

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

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

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

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

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

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

روال‌های مطلوب

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

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

کیت‌های توسعه نرم‌افزار (SDK)

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

• در Python، این بسته google-genai از نسخه 2.3.0 به بعد است.
• در جاوا اسکریپت، این بسته @google/genai از نسخه 2.3.0 به بعد است.
• در Go، این بسته google.golang.org/genai است.
• در جاوا، این بسته com.google.genai:google-genai است.

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

محدودیت‌ها

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

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

• Batch API
• فراخوانی تابع خودکار (Python)
• ذخیره صریح در حافظه نهان: توجه داشته باشید که ذخیره ضمنی در حافظه نهان سمت سرور در «میانای برنامه‌سازی کاربردی تعامل‌ها» ازطریق previous_interaction_id دردسترس است.

بازخورد

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

قدم بعدی چیست

• دفترچه شروع سریع Interactions API را امتحان کنید.
• درباره عامل Gemini Deep Research بیشتر بدانید.