شروع به کار

این راهنما به شما کمک می‌کند تا با استفاده از Interactions API، کار با Gemini API را شروع کنید. شما اولین فراخوانی API خود را در کمتر از یک دقیقه انجام خواهید داد و تولید متن، درک چندوجهی، تولید تصویر، خروجی ساختاریافته، ابزارها، فراخوانی تابع، عامل‌ها و اجرای پس‌زمینه را بررسی خواهید کرد.

رابط برنامه‌نویسی کاربردی (API) تعاملات (Interactions) از طریق SDK های پایتون و جاوا اسکریپت و همچنین از طریق REST در دسترس است.

۱. دریافت کلید API

برای استفاده از رابط برنامه‌نویسی Gemini، به یک کلید API نیاز دارید تا درخواست‌هایتان را تأیید کنید، محدودیت‌های امنیتی را اعمال کنید و میزان استفاده از حسابتان را پیگیری کنید.

• گوگل هوش مصنوعی استودیو به طور خودکار یک پروژه و کلید API برای کاربران جدید ایجاد می‌کند. می‌توانید آن را از صفحه کلیدهای API کپی کنید.
• اگر به یک کلید جدید نیاز دارید، روی «ایجاد کلید API» در AI Studio کلیک کنید و پنجره را دنبال کنید تا یک جفت کلید-پروژه جدید اضافه کنید.

یک کلید API جمینی ایجاد کنید

کلید خود را به عنوان یک متغیر محیطی تنظیم کنید:

export GEMINI_API_KEY="YOUR_API_KEY"

ارتقا به سطح پولی

ارتقا به سطح پولی، محدودیت‌های نرخ شما را افزایش می‌دهد و نیاز به راه‌اندازی Cloud Billing دارد.

• روی تنظیم صورتحساب در صفحات کلیدهای API AI Studio یا پروژه‌ها کلیک کنید.
• برای ایجاد یا پیوند یک حساب پرداخت، افزودن روش پرداخت و پیش‌پرداخت حداقل 10 دلار (یا معادل ارزی) به صورت اعتبار پرداختی، از طریق پنجره‌ی Cloud Billing اقدام کنید.
• میزان استفاده از API خود را در Google AI Studio در قسمت Dashboard > Usage مشاهده کنید.

برای اطلاعات بیشتر به صفحه صورتحساب مراجعه کنید.

۲. SDK را نصب کنید و اولین تماس خود را برقرار کنید

SDK را نصب کنید و با یک فراخوانی API، متن تولید کنید.

pip install -U google-genai

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)

npm install @google/genai

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.7-flash",
  input: "Explain how AI works in a few words",
});
console.log(interaction.output_text);

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.7-flash",
    "input": "Explain how AI works in a few words"
  }'

پاسخ:

{
  "id": "v1_ChdpQUFvYXI...",
  "status": "completed",
  "usage": {
    "total_tokens": 197,
    "total_input_tokens": 8,
    "total_output_tokens": 12
  },
  "created": "2026-06-09T12:01:25Z",
  "steps": [
    {
      "type": "thought",
      "signature": "EvEFCu4FAQw..."
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "AI learns patterns from data, then uses those patterns to make predictions or decisions on new data."
        }
      ]
    }
  ],
  "object": "interaction",
  "model": "gemini-3.7-flash",
}

هنگام استفاده از REST، API منبع کامل Interaction را که شامل ابرداده، آمار استفاده و تاریخچه گام به گام نوبت است، برمی‌گرداند.

در حالی که SDKها پاسخ کامل را نمایش می‌دهند، ویژگی‌های راحتی مانند interaction.output_text و interaction.output_image را نیز برای دسترسی مستقیم به خروجی‌های نهایی ارائه می‌دهند. برای کسب اطلاعات بیشتر در مورد ساختار پاسخ، به مرور کلی Interactions مراجعه کنید یا برای جزئیات بیشتر در مورد دستورالعمل‌های سیستم و پیکربندی تولید، راهنمای تولید متن را مطالعه کنید.

۳. پاسخ را پخش کنید

برای تعاملات روان‌تر، پاسخ را همزمان با تولید، پخش کنید. هر رویداد step.delta بخشی از متن را ارائه می‌دهد که می‌توانید بلافاصله نمایش دهید.

from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.7-flash",
    input="Explain how AI works",
    stream=True
)
for event in stream:
    print(event)

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

const ai = new GoogleGenAI({});

const stream = await ai.interactions.create({
  model: "gemini-3.7-flash",
  input: "Explain how AI works",
  stream: true,
});

for await (const event of stream) {
  console.log(event);
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "model": "gemini-3.7-flash",
    "input": "Explain how AI works",
    "stream": true
  }'

هنگام پخش، سرور با جریانی از رویدادهای ارسالی از سرور (SSE) پاسخ می‌دهد. هر رویداد شامل یک نوع و داده‌های JSON است.

پاسخ:

event: interaction.created
data: {"interaction":{"id":"v1_Chd...","status":"in_progress","model":"gemini-3.7-flash"},"event_type":"interaction.created"}

event: step.start
data: {"index":0,"step":{"type":"thought"},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"signature":"EvEFCu4F...","type":"thought_signature"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: step.start
data: {"index":1,"step":{"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"text":"AI ","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":1,"delta":{"text":"works ","type":"text"},"event_type":"step.delta"}

event: step.stop
data: {"index":1,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"v1_Chd...","status":"completed","usage":{"total_tokens":197}},"event_type":"interaction.completed"}

برای بررسی دقیق‌تر مدیریت رویدادهای استریمینگ و انواع دلتا، به راهنمای تعاملات استریمینگ مراجعه کنید.

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

API تعاملات از مکالمات چند نوبتی با دو رویکرد پشتیبانی می‌کند:

• Stateful (توصیه می‌شود) : ادامه مکالمه روی سرور با استفاده از previous_interaction_id . ایده‌آل برای اکثر چت‌ها و گردش‌های کاری agentic که در آن‌ها می‌خواهید سرور تاریخچه را مدیریت و ذخیره‌سازی را بهینه کند.

• بدون وضعیت : با ارسال تمام نوبت‌های قبلی (شامل مراحل تفکر مدل میانی و ابزار) در هر درخواست، تاریخچه مکالمه را در کلاینت مدیریت کنید.

from google import genai

client = genai.Client()

# Server-side state (recommended)
interaction1 = client.interactions.create(
    model="gemini-3.7-flash",
    input="I have 2 dogs in my house.",
)
print("Response 1:", interaction1.output_text)

interaction2 = client.interactions.create(
    model="gemini-3.7-flash",
    input="How many paws are in my house?",
    previous_interaction_id=interaction1.id,
)
print("Response 2:", interaction2.output_text)

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

const ai = new GoogleGenAI({});

// Server-side state (recommended)
const interaction1 = await ai.interactions.