API تعاملات اکنون به طور عمومی در دسترس است. توصیه می‌کنیم برای دسترسی به جدیدترین ویژگی‌ها و مدل‌ها از این API استفاده کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

تعاملات استریمینگ

هنگام ایجاد یک تعامل، می‌توانید stream: true را تنظیم کنید تا پاسخ با استفاده از رویدادهای ارسالی از سرور (SSE) به صورت تدریجی پخش شود.

پایتون

from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.7-flash",
    input="Count from 1 to 25.",
    stream=True,
)
for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)

جاوا اسکریپت

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

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    model: "gemini-3.7-flash",
    input: "Count from 1 to 25.",
    stream: true,
});
for await (const event of stream) {
    if (event.event_type === "step.delta") {
        if (event.delta.type === "text") {
            process.stdout.write(event.delta.text);
        }
    }
}

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-3.7-flash",
    "input": "Count from 1 to 25.",
    "stream": true
  }'

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

event: interaction.status_update
data: {"interaction_id":"v1_...","status":"in_progress","event_type":"interaction.status_update"}

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

event: step.delta
data: {"index":0,"delta":{"signature":"...","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":"1, 2, 3, 4, 5, 6, ","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":1,"delta":{"text":"7, 8, 9, 10, 11, 12, 13,","type":"text"},"event_type":"step.delta"}

...

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

event: interaction.completed
data: {"interaction":{"id":"v1_...","status":"completed","usage":{"total_tokens":346,"total_input_tokens":11,"input_tokens_by_modality":[{"modality":"text","tokens":11}],"total_cached_tokens":0,"total_output_tokens":90,"total_tool_use_tokens":0,"total_thought_tokens":245},"created":"2026-05-12T18:44:51Z","updated":"2026-05-12T18:44:51Z","service_tier":"standard","object":"interaction","model":"gemini-3.7-flash"},"event_type":"interaction.completed"}

event: done
data: [DONE]

انواع رویداد

هر رویداد ارسالی از سرور شامل یک event_type نامگذاری شده و داده‌های JSON مرتبط است. API تعاملات از یک مدل جریان متقارن استفاده می‌کند که در آن تمام محتوا - متن، فراخوانی ابزار، تفکر - از طریق یک رویداد مبتنی بر مرحله ثابت جریان می‌یابد.

هر جریان از این جریان رویداد پیروی می‌کند:

interaction.created : تعاملی که ایجاد شده است، شامل فراداده (ID، مدل، وضعیت) می‌شود.
یک سری مراحل که هر کدام شامل موارد زیر است:
- یک رویداد step.start که نوع مرحله را نشان می‌دهد (مثلاً model_output ، thought ، function_call ).
- یک یا چند رویداد step.delta با داده‌های افزایشی برای آن مرحله.
- یک رویداد step.stop که مرحله را به عنوان کامل شده علامت گذاری می کند.
یک رویداد interaction.completed به همراه آمار نهایی usage .

وقتی stream: false تنظیم می‌کنید، API یک شیء interaction واحد با آرایه steps را برمی‌گرداند. هر عنصر در steps نسخه کاملاً مونتاژ شده یک چرخه step.start → step.delta (s) → step.stop است.

`interaction.created`

هنگام ایجاد اولیه‌ی تعامل ارسال می‌شود. شامل شناسه‌ی تعامل، مدل و وضعیت اولیه است.

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

`interaction.status_update`

سیگنال‌های انتقال وضعیت در سطح تعامل. ممکن است بین مراحل ظاهر شود.

event: interaction.status_update
data: {"interaction_id": "...", "status": "in_progress", "event_type": "interaction.status_update"}

`step.start`

شروع یک مرحله جدید را نشان می‌دهد. شامل type مرحله و index است. نوع مرحله تعیین می‌کند که کدام نوع دلتا مورد انتظار است و مرحله چگونه در یک پاسخ غیر استریمینگ ظاهر می‌شود:

نوع پله	انواع دلتاهای مورد انتظار	توضیحات
`model_output`	`text` ، `image` ، `audio`	محتوای پاسخ نهایی مدل.
`thought`	`thought_signature` ، `thought_summary`	`summary` استدلال زنجیره‌ای فقط زمانی وجود دارد که `thinking_summaries` فعال باشد.
`function_call`	`arguments_delta`	درخواستی برای کلاینت جهت اجرای یک تابع. وضعیت تعامل را روی `requires_action` تنظیم می‌کند.
ابزارهای سمت سرور	بسته به ابزار متفاوت است	ابزارهایی که توسط API اجرا می‌شوند (مثلاً `google_search_call` ، `google_search_result` ، `code_execution_call` ، `code_execution_result` ).

برای فهرست کامل، به مرجع API تعاملات مراجعه کنید.

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

برای فراخوانی توابع، این مرحله شامل نام تابع، شناسه (id) و آرگومان‌های خالی {} می‌شود.

event: step.start
data: {"index": 0, "step": {"type": "function_call", "id":"un6k8t18", "name": "get_weather", "arguments":{}}, "event_type": "step.start"}

`step.delta`

داده‌های افزایشی برای مرحله فعلی. شیء delta حاوی یک فیلد type است که شکل آن را تعیین می‌کند.

مثال‌ها:

text : توکن متنی افزایشی از مرحله model_output :

event: step.delta
data: {"index": 0, "delta": {"type": "text", "text": "Hello, my name is Phil"}, "event_type": "step.delta"}

event: step.delta
data: {"index": 0, "delta": {"type": "text", "text": ", and I live in Germany." }, "event_type": "step.delta"}

image : داده‌های تصویر کدگذاری شده با Base64 از مرحله model_output :

event: step.delta
data: {"index": 0, "delta": {"type": "image", "mime_type": "image/jpeg", "data": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAoHBwgHBgoICAgLCg..."}, "event_type": "step.delta"}

thought_summary : خلاصه محتوای تفکر از یک مرحله thought :

event: step.delta
data: {"index": 0, "delta": {"type": "thought_summary", "content": {"type": "text", "text": "I need to find the GCD..."}}, "event_type": "step.delta"}

arguments_delta : رشته JSON (جزئی) برای آرگومان‌های فراخوانی تابع. باید در دلتاها جمع شود:

event: step.delta
data: {"index": 0, "delta": {"type": "arguments_delta", "arguments": "{\"location\": \"San Francisco, CA\"}"}, "event_type": "step.delta"}

اینها برخی از رایج‌ترین انواع دلتا هستند. برای لیست کامل همه انواع دلتا، به مرجع Interactions API مراجعه کنید.

`step.stop`

پایان یک مرحله را مشخص می‌کند. شامل index مرحله است.

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

هنگام استفاده از Antigravity Agent ، رویداد step.stop ممکن است شامل آمار استفاده نیز باشد:

usage : میزان استفاده انباشته (کل در حال اجرا) از زمان شروع تعامل.
step_usage : میزان استفاده از این مرحله خاص.

event: step.stop
data: {"index": 2, "event_type": "step.stop", "usage": {"total_tokens": 4650, "total_input_tokens": 3577, "total_output_tokens": 305, "total_cached_tokens": 0}, "step_usage": {"total_tokens": 303, "total_input_tokens": 31, "total_output_tokens": 3, "total_cached_tokens": 0}}

`interaction.completed`

پس از پایان تعامل ارسال می‌شود. شامل شیء تعامل نهایی به همراه آمار usage است. در حالت غیر استریمینگ، این خود شیء پاسخ سطح بالا است. شامل steps پاسخ نمی‌شود.

event: interaction.completed
data: {"interaction": {"id": "v1_abc123", "status": "completed", "usage": {"total_input_tokens": 7, "total_output_tokens": 12, "total_tokens": 19}}, "event_type": "interaction.completed"}

`error`

زمانی ارسال می‌شود که در طول تعامل خطایی رخ دهد. حاوی یک شیء خطا به همراه یک پیام و کد است.

event: error
data: {"error":{"message":"Deadline expired before operation could complete.","code":"gateway_timeout"},"event_type":"error"}