مهاجرت به API تعاملات

این راهنما به شما کمک می‌کند تا از generateContent API به Interactions API مهاجرت کنید.

رابط برنامه‌نویسی کاربردی تعاملات (Interactions API) ساده‌ترین و بهترین روش ما برای ساخت با مدل‌ها و عامل‌های Gemini است. در حالی که generateContent همچنان به طور کامل پشتیبانی می‌شود، ما رابط برنامه‌نویسی کاربردی تعاملات (Interactions API) را برای همه توسعه‌های جدید توصیه می‌کنیم.

چرا مهاجرت کنیم؟

رابط برنامه‌نویسی کاربردی (API) تعاملات (Interactions) ساده‌ترین و بهترین روش ما برای ساخت مدل‌ها و عامل‌های Gemini است:

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

ورودی/خروجی پایه

این بخش نحوه‌ی انتقال یک درخواست تولید متن ساده را نشان می‌دهد.

قبل از ( generateContent )

API generateContent بدون وضعیت (stateless) است و پاسخ را مستقیماً برمی‌گرداند. ساختار پاسخ، خروجی را در فهرستی از candidates قرار می‌دهد که هر کدام شامل content به همراه فهرستی از parts برای تجزیه هستند.

پایتون

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash-lite", contents="Tell me a joke."
)
print(response.text)

جاوا اسکریپت

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

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash-lite",
  contents: "Tell me a joke.",
});
console.log(response.text);

استراحت

# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "contents": [{
        "parts": [{
            "text": "Tell me a joke."
        }]
    }]
}'

# Response
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Why did the chicken cross the road? To get to the other side!"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 12,
    "totalTokenCount": 16
  }
}

API تعاملات، یک منبع تعاملی ذخیره شده را به همراه یک جدول زمانی steps timeline) برمی‌گرداند. در حالی که می‌توانید آرایه مراحل ( steps array) را به صورت دستی بررسی کنید تا رویدادهای میانی را پیدا کنید، SDK های Google GenAI ویژگی‌های راحتی را مستقیماً روی شیء Interaction object) برگردانده شده ارائه می‌دهند تا به خروجی نهایی دسترسی داشته باشید.

رایج‌ترین ویژگی مناسب، .output_text (رشته)‎ است که به طور خودکار بلوک‌های متوالی TextContent را در انتهای پاسخ مدل استخراج و به هم متصل می‌کند. اگرچه این برای پاسخ‌های ساده کاملاً کار می‌کند، اما شامل بلوک‌های متنی قبلی که توسط محتوای غیرمتنی (مانند افکار، تصاویر، صدا یا فراخوانی‌های ابزار) از هم جدا شده‌اند، نمی‌شود. برای پاسخ‌های چندوجهی پیچیده یا درهم‌تنیده، باید به جای آن، steps را به صورت دستی تکرار کنید.

پایتون

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash", input="Tell me a joke."
)

print(interaction.output_text)

جاوا اسکریپت

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

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
    model: 'gemini-3.7-flash',
    input: 'Tell me a joke.'
});

console.log(interaction.output_text);

استراحت

# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta2/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.7-flash",
    "input": "Tell me a joke."
}'

# Response
{
  "id": "int_123",
  "status": "completed",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Tell me a joke."
        }
      ]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

مکالمات چند نوبتی

API تعاملات به طور پیش‌فرض تعاملات را ذخیره می‌کند و مدیریت وضعیت سمت سرور را برای مکالمات چند نوبتی فعال می‌کند.

قبل از ( generateContent )

در generateContent ، شما باید تاریخچه مکالمات را به صورت دستی با استفاده از آرایه contents یا یک تابع کمکی چت سمت کلاینت مدیریت کنید.

پایتون

استفاده از دستیار چت (توصیه می‌شود)

from google import genai

client = genai.Client()

chat = client.chats.create(model="gemini-2.5-flash-lite")
response1 = chat.send_message("Hi, my name is Phil.")
print(response1.text)

response2 = chat.send_message("What is my name?")
print(response2.text)

مدیریت دستی تاریخچه

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash-lite",
    contents=[
        types.Content(
            role="user", parts=[types.Part.from_text(text="Hi, my name is Phil.")]
        ),
        types.Content(
            role="model",
            parts=[types.Part.from_text(text="Hi Phil, how can I help you?")],
        ),
        types.Content(
            role="user", parts=[types.Part.from_text(text="What is my name?")]
        ),
    ],
)
print(response.text)

جاوا اسکریپت

استفاده از دستیار چت (توصیه می‌شود)

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

const client = new GoogleGenAI({});

const chat = client.chats.create({ model: 'gemini-2.5-flash-lite' });
let response = await chat.sendMessage({ message: 'Hi, my name is Phil.' });
console.log(response.text);

response = await chat.sendMessage({ message: 'What is my name?' });
console.log(response.text);

مدیریت دستی تاریخچه

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

const client = new GoogleGenAI({});

const response = await client.models.generateContent({
    model: 'gemini-2.5-flash-lite',
    contents: [
        { role: 'user', parts: [{ text: 'Hi, my name is Phil.' }] },
        { role: 'model', parts: [{ text: 'Hi Phil, how can I help you?' }] },
        { role: 'user', parts: [{ text: 'What is my name?' }] }
    ]
});
console.log(response.text);

استراحت

# Request (the second turn requires sending the entire history)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "contents": [
        {"role": "user", "parts": [{"text": "Hi, my name is Phil."}]},
        {"role": "model", "parts": [{"text": "Hi Phil, how can I help you?"}]},
        {"role": "user", "parts": [{"text": "What is my name?"}]}