Gemini API

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

مشاهده به صورت markdown مشاهده مشخصات OpenAPI

ایجاد تعامل

ارسال به آدرس https://generativelanguage.googleapis.com/v1beta/interactions

یک تعامل جدید ایجاد می‌کند.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

مدل ModelOption (اختیاری)

نام «مدل» مورد استفاده برای تولید تعامل.
در صورت عدم ارائه «عامل»، الزامی است.

مقادیر ممکن:

  • gemini-2.5-computer-use-preview-10-2025

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

  • gemini-2.5-flash

    اولین مدل استدلال ترکیبی ما که از یک پنجره زمینه ۱ میلیون توکنی پشتیبانی می‌کند و دارای بودجه‌های تفکر است.

  • gemini-2.5-flash-image

    مدل تولید تصویر بومی ما، که برای سرعت، انعطاف‌پذیری و درک متنی بهینه شده است. ورودی و خروجی متن با همان قیمت ۲.۵ فلش ارائه می‌شود.

  • gemini-2.5-flash-lite

    کوچکترین و مقرون به صرفه ترین مدل ما، ساخته شده برای استفاده در مقیاس بزرگ.

  • gemini-2.5-flash-lite-preview-09-2025

    جدیدترین مدل مبتنی بر Gemini 2.5 Flash lite که برای صرفه‌جویی در هزینه، توان عملیاتی بالا و کیفیت بالا بهینه شده است.

  • gemini-2.5-flash-native-audio-preview-12-2025

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

  • gemini-2.5-flash-preview-09-2025

    آخرین مدل مبتنی بر مدل فلش ۲.۵. پیش‌نمایش فلش ۲.۵ برای پردازش در مقیاس بزرگ، وظایف با تأخیر کم و حجم بالا که نیاز به تفکر دارند و موارد استفاده عامل‌محور بهترین گزینه است.

  • gemini-2.5-flash-preview-tts

    مدل تبدیل متن به گفتار ۲.۵ فلش ما برای تولید گفتار قابل کنترل قدرتمند و با تأخیر کم بهینه شده است.

  • gemini-2.5-pro

    مدل چندمنظوره پیشرفته ما، که در کدنویسی و کارهای استدلالی پیچیده عالی عمل می‌کند.

  • gemini-2.5-pro-preview-tts

    مدل صوتی متن به گفتار نسخه ۲.۵ پرو ما برای تولید گفتار قدرتمند و با تأخیر کم بهینه شده است تا خروجی‌های طبیعی‌تر و هدایت آسان‌تر دستورات را فراهم کند.

  • gemini-3-flash-preview

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

  • gemini-3-pro-image-preview

    مدل پیشرفته تولید و ویرایش تصویر.

  • gemini-3-pro-preview

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

  • gemini-3.1-pro-preview

    جدیدترین مدل استدلال SOTA ما با عمق و ظرافت بی‌سابقه و قابلیت‌های قدرتمند درک و کدنویسی چندوجهی.

  • gemini-3.1-flash-image-preview

    هوش بصری حرفه‌ای با کارایی فوق‌العاده و قابلیت‌های تولید محتوای مبتنی بر واقعیت.

  • gemini-3.1-flash-lite-preview

    مقرون‌به‌صرفه‌ترین مدل ما، بهینه‌شده برای وظایف عامل‌محور با حجم بالا، ترجمه و پردازش داده‌های ساده.

  • gemini-3.1-flash-tts-preview

    Gemini 3.1 Flash TTS: تولید گفتار قدرتمند و با تأخیر کم. از خروجی‌های طبیعی، دستورات قابل هدایت و برچسب‌های صوتی رسا برای کنترل دقیق روایت لذت ببرید.

  • lyria-3-clip-preview

    مدل تولید موسیقی با تأخیر کم ما برای کلیپ‌های صوتی با کیفیت بالا و کنترل دقیق ریتمیک بهینه شده است.

  • lyria-3-pro-preview

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

مدلی که اعلان شما را تکمیل می‌کند.\n\nبرای جزئیات بیشتر به [models](https://ai.google.dev/gemini-api/docs/models) مراجعه کنید.

گزینه عامل (اختیاری)

نام «عامل» مورد استفاده برای ایجاد تعامل.
در صورت عدم ارائه «مدل»، الزامی است.

مقادیر ممکن:

  • deep-research-pro-preview-12-2025

    نماینده تحقیقات عمیق جمینی

  • deep-research-preview-04-2026

    نماینده تحقیقات عمیق جمینی

  • deep-research-max-preview-04-2026

    مامور مکس تحقیقات عمیق جمینی

عاملی که باید با آن تعامل داشت.

ورودی محتوا یا آرایه ( Content ) یا آرایه ( Step ) یا رشته (الزامی)

ورودی‌های تعامل (مشترک برای مدل و عامل).

رشته system_instruction (اختیاری)

دستورالعمل سیستم برای تعامل.

آرایه ابزارها ( ابزار ) (اختیاری)

فهرستی از اعلان‌های ابزار که مدل ممکن است در طول تعامل فراخوانی کند.

قالب پاسخ یا فهرست قالب پاسخ (اختیاری)

تأکید می‌کند که پاسخ تولید شده یک شیء JSON است که با طرحواره JSON مشخص شده در این فیلد مطابقت دارد.

رشته response_mime_type (اختیاری)

نوع MIME پاسخ. در صورت تنظیم response_format، این مورد الزامی است.

جریان بولی (اختیاری)

فقط ورودی. اینکه آیا تعامل پخش زنده خواهد شد یا خیر.

ذخیره بولی (اختیاری)

فقط ورودی. آیا پاسخ و درخواست برای بازیابی بعدی ذخیره شود یا خیر.

مقدار بولی پس‌زمینه (اختیاری)

فقط ورودی. اینکه آیا تعامل مدل در پس‌زمینه اجرا شود یا خیر.

generation_config GenerationConfig (اختیاری)

پیکربندی مدل
پارامترهای پیکربندی برای تعامل مدل.
جایگزینی برای `agent_config`. فقط زمانی قابل اجرا است که `model` تنظیم شده باشد.

پارامترهای پیکربندی برای تعاملات مدل.

فیلدها

عدد دما (اختیاری)

تصادفی بودن خروجی را کنترل می‌کند.

شماره top_p (اختیاری)

حداکثر احتمال تجمعی توکن‌ها که باید هنگام نمونه‌گیری در نظر گرفته شود.

عدد صحیح اولیه (اختیاری)

بذر مورد استفاده در رمزگشایی برای تکرارپذیری.

آرایه stop_sequences (رشته) (اختیاری)

فهرستی از توالی‌های کاراکتری که تعامل خروجی را متوقف می‌کنند.

سطح_فکریسطح_فکری ( اختیاری )

سطح توکن‌های فکری که مدل باید تولید کند.

مقادیر ممکن:

  • minimal
  • low
  • medium
  • high

خلاصه‌های تفکر ( اختیاری)

اینکه آیا خلاصه نظرات در پاسخ گنجانده شود یا خیر.

مقادیر ممکن:

  • auto
  • none

عدد صحیح max_output_tokens (اختیاری)

حداکثر تعداد توکن‌هایی که باید در پاسخ گنجانده شوند.

speech_config SpeechConfig (اختیاری)

پیکربندی برای تعامل گفتاری.

پیکربندی برای تعامل گفتاری.

فیلدها

رشته صدا (اختیاری)

صدای گوینده.

رشته زبان (اختیاری)

زبان گفتار.

سیم بلندگو (اختیاری)

نام گوینده، باید با نام گوینده داده شده در سوال مطابقت داشته باشد.

image_config پیکربندی تصویر (اختیاری)

پیکربندی برای تعامل تصویر.

پیکربندی برای تعامل تصویر.

فیلدها

متغیر شمارشی aspect_ratio (رشته‌ای) (اختیاری)

هیچ توضیحی ارائه نشده است.

مقادیر ممکن:

  • 1:1
  • 2:3
  • 3:2
  • 3:4
  • 4:3
  • 4:5
  • 5:4
  • 9:16
  • 16:9
  • 21:9
  • 1:8
  • 8:1
  • 1:4
  • 4:1
متغیر شمارشی image_size (رشته‌ای) (اختیاری)

هیچ توضیحی ارائه نشده است.

مقادیر ممکن:

  • 1K
  • 2K
  • 4K
  • 512
tool_choice ToolChoiceConfig یا ToolChoiceType (اختیاری)

پیکربندی انتخاب ابزار.

شیء agent_config (اختیاری)

پیکربندی عامل
پیکربندی برای عامل.
جایگزینی برای `generation_config`. فقط زمانی قابل اجرا است که `agent` تنظیم شده باشد.

انواع ممکن

تفکیک‌کننده چندریختی: type

پیکربندی DynamicAgent

پیکربندی برای عامل‌های پویا

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "dynamic" تنظیم شود.

پیکربندی DeepResearchAgent

پیکربندی برای عامل تحقیقات عمیق.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "deep-research" تنظیم شود.

خلاصه‌های تفکر ( اختیاری)

اینکه آیا خلاصه نظرات در پاسخ گنجانده شود یا خیر.

مقادیر ممکن:

  • auto
  • none

تجسم enum (رشته) (اختیاری)

اینکه آیا باید از تصاویر در پاسخ استفاده کرد یا خیر.

مقادیر ممکن:

  • off
  • auto
نوع بولی collaboration_planning (اختیاری)

برنامه‌ریزی انسان در حلقه را برای عامل تحقیقات عمیق فعال می‌کند. اگر روی درست تنظیم شود، عامل تحقیقات عمیق در پاسخ خود یک طرح تحقیقاتی ارائه می‌دهد. سپس عامل تنها در صورتی ادامه می‌دهد که کاربر طرح را در نوبت بعدی تأیید کند.

رشته‌ی previous_interaction_id (اختیاری)

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

روش_پاسخ ( اختیاری )

روش‌های درخواستی برای پاسخ (متن، تصویر، صدا).

مقادیر ممکن:

  • text
  • image
  • audio
  • video
  • document

service_tier لایه سرویس (اختیاری)

لایه سرویس برای تعامل.

مقادیر ممکن:

  • flex
  • standard
  • priority

webhook_config پیکربندی وب هوک (اختیاری)

اختیاری. پیکربندی وب‌هوک برای دریافت اعلان‌ها پس از اتمام تعامل.

پیام مربوط به پیکربندی رویدادهای وب‌هوک برای یک درخواست.

فیلدها

آرایه uris (رشته) (اختیاری)

اختیاری. در صورت تنظیم، این URLهای وب‌هوک به جای وب‌هوک‌های ثبت‌شده، برای رویدادهای وب‌هوک استفاده خواهند شد.

شیء user_metadata (اختیاری)

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

پاسخ

یک منبع تعامل (Interaction) را برمی‌گرداند.

درخواست ساده

پاسخ نمونه 

{
  "created": "2025-11-26T12:25:15Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3-flash-preview",
  "object": "interaction",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Hello! I'm functioning perfectly and ready to assist you.\n\nHow are you doing today?"
        }
      ]
    }
  ],
  "status": "completed",
  "updated": "2025-11-26T12:25:15Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 7
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 7,
    "total_output_tokens": 20,
    "total_thought_tokens": 22,
    "total_tokens": 49,
    "total_tool_use_tokens": 0
  }
}

چند نوبتی

پاسخ نمونه 

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3-flash-preview",
  "status": "completed",
  "object": "interaction",
  "created": "2025-11-26T12:22:47Z",
  "updated": "2025-11-26T12:22:47Z",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The capital of France is Paris."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 50
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 50,
    "total_output_tokens": 10,
    "total_thought_tokens": 0,
    "total_tokens": 60,
    "total_tool_use_tokens": 0
  }
}

ورودی تصویر

پاسخ نمونه 

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3-flash-preview",
  "status": "completed",
  "object": "interaction",
  "created": "2025-11-26T12:22:47Z",
  "updated": "2025-11-26T12:22:47Z",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "A white humanoid robot with glowing blue eyes stands holding a red skateboard."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 10
      },
      {
        "modality": "image",
        "tokens": 258
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 268,
    "total_output_tokens": 20,
    "total_thought_tokens": 0,
    "total_tokens": 288,
    "total_tool_use_tokens": 0
  }
}

فراخوانی تابع

پاسخ نمونه 

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3-flash-preview",
  "status": "requires_action",
  "object": "interaction",
  "created": "2025-11-26T12:22:47Z",
  "updated": "2025-11-26T12:22:47Z",
  "steps": [
    {
      "type": "function_call",
      "id": "gth23981",
      "name": "get_weather",
      "arguments": {
        "location": "Boston, MA"
      }
    }
  ],
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 100
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 100,
    "total_output_tokens": 25,
    "total_thought_tokens": 0,
    "total_tokens": 125,
    "total_tool_use_tokens": 50
  }
}

تحقیقات عمیق

پاسخ نمونه 

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "agent": "deep-research-pro-preview-12-2025",
  "status": "completed",
  "object": "interaction",
  "created": "2025-11-26T12:22:47Z",
  "updated": "2025-11-26T12:22:47Z",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Here is a comprehensive research report on the current state of cancer research..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 20
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 20,
    "total_output_tokens": 1000,
    "total_thought_tokens": 500,
    "total_tokens": 1520,
    "total_tool_use_tokens": 0
  }
}

بازیابی یک تعامل

دریافت کنید https://generativelanguage.googleapis.com/v1beta/interactions/{id}

جزئیات کامل یک تعامل واحد را بر اساس `Interaction.id` آن بازیابی می‌کند.

پارامترهای مسیر/پرس‌وجو

رشته شناسه (الزامی)

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

جریان بولی (اختیاری)

اگر روی درست تنظیم شود، محتوای تولید شده به صورت تدریجی پخش می‌شود.

پیش‌فرض: False

رشته last_event_id (اختیاری)

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

مقدار بولی include_input (اختیاری)

اگر روی true تنظیم شود، ورودی را در پاسخ لحاظ می‌کند.

پیش‌فرض: False

رشته api_version (اختیاری)

از کدام نسخه API استفاده کنیم.

پاسخ

یک منبع تعامل (Interaction) را برمی‌گرداند.

تعامل دریافت کنید

پاسخ نمونه 

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3-flash-preview",
  "status": "completed",
  "object": "interaction",
  "created": "2025-11-26T12:25:15Z",
  "updated": "2025-11-26T12:25:15Z",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "I'm doing great, thank you for asking! How can I help you today?"
        }
      ]
    }
  ]
}

حذف یک تعامل

https://generativelanguage.googleapis.com/v1beta/interactions/{id} را حذف کنید

تعامل را بر اساس شناسه حذف می‌کند.

پارامترهای مسیر/پرس‌وجو

رشته شناسه (الزامی)

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

رشته api_version (اختیاری)

از کدام نسخه API استفاده کنیم.

پاسخ

در صورت موفقیت، پاسخ خالی است.

حذف تعامل

لغو یک تعامل

ارسال https://generativelanguage.googleapis.com/v1beta/interactions/{id}/cancel

یک تعامل را بر اساس شناسه لغو می‌کند. این فقط برای تعاملات پس‌زمینه‌ای که هنوز در حال اجرا هستند، اعمال می‌شود.

پارامترهای مسیر/پرس‌وجو

رشته شناسه (الزامی)

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

رشته api_version (اختیاری)

از کدام نسخه API استفاده کنیم.

پاسخ

یک منبع تعامل (Interaction) را برمی‌گرداند.

لغو تعامل

پاسخ نمونه 

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "agent": "deep-research-pro-preview-12-2025",
  "status": "cancelled",
  "object": "interaction",
  "created": "2025-11-26T12:25:15Z",
  "updated": "2025-11-26T12:25:15Z"
}

منابع

تعامل

منبع تعامل.

فیلدها

مدل ModelOption (اختیاری)

نام «مدل» مورد استفاده برای تولید تعامل.

مقادیر ممکن:

  • gemini-2.5-computer-use-preview-10-2025

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

  • gemini-2.5-flash

    اولین مدل استدلال ترکیبی ما که از یک پنجره زمینه ۱ میلیون توکنی پشتیبانی می‌کند و دارای بودجه‌های تفکر است.

  • gemini-2.5-flash-image

    مدل تولید تصویر بومی ما، که برای سرعت، انعطاف‌پذیری و درک متنی بهینه شده است. ورودی و خروجی متن با همان قیمت ۲.۵ فلش ارائه می‌شود.

  • gemini-2.5-flash-lite

    کوچکترین و مقرون به صرفه ترین مدل ما، ساخته شده برای استفاده در مقیاس بزرگ.

  • gemini-2.5-flash-lite-preview-09-2025

    جدیدترین مدل مبتنی بر Gemini 2.5 Flash lite که برای صرفه‌جویی در هزینه، توان عملیاتی بالا و کیفیت بالا بهینه شده است.

  • gemini-2.5-flash-native-audio-preview-12-2025

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

  • gemini-2.5-flash-preview-09-2025

    آخرین مدل مبتنی بر مدل فلش ۲.۵. پیش‌نمایش فلش ۲.۵ برای پردازش در مقیاس بزرگ، وظایف با تأخیر کم و حجم بالا که نیاز به تفکر دارند و موارد استفاده عامل‌محور بهترین گزینه است.

  • gemini-2.5-flash-preview-tts

    مدل تبدیل متن به گفتار ۲.۵ فلش ما برای تولید گفتار قابل کنترل قدرتمند و با تأخیر کم بهینه شده است.

  • gemini-2.5-pro

    مدل چندمنظوره پیشرفته ما، که در کدنویسی و کارهای استدلالی پیچیده عالی عمل می‌کند.

  • gemini-2.5-pro-preview-tts

    مدل صوتی متن به گفتار نسخه ۲.۵ پرو ما برای تولید گفتار قدرتمند و با تأخیر کم بهینه شده است تا خروجی‌های طبیعی‌تر و هدایت آسان‌تر دستورات را فراهم کند.

  • gemini-3-flash-preview

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

  • gemini-3-pro-image-preview

    مدل پیشرفته تولید و ویرایش تصویر.

  • gemini-3-pro-preview

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

  • gemini-3.1-pro-preview

    جدیدترین مدل استدلال SOTA ما با عمق و ظرافت بی‌سابقه و قابلیت‌های قدرتمند درک و کدنویسی چندوجهی.

  • gemini-3.1-flash-image-preview

    هوش بصری حرفه‌ای با کارایی فوق‌العاده و قابلیت‌های تولید محتوای مبتنی بر واقعیت.

  • gemini-3.1-flash-lite-preview

    مقرون‌به‌صرفه‌ترین مدل ما، بهینه‌شده برای وظایف عامل‌محور با حجم بالا، ترجمه و پردازش داده‌های ساده.

  • gemini-3.1-flash-tts-preview

    Gemini 3.1 Flash TTS: تولید گفتار قدرتمند و با تأخیر کم. از خروجی‌های طبیعی، دستورات قابل هدایت و برچسب‌های صوتی رسا برای کنترل دقیق روایت لذت ببرید.

  • lyria-3-clip-preview

    مدل تولید موسیقی با تأخیر کم ما برای کلیپ‌های صوتی با کیفیت بالا و کنترل دقیق ریتمیک بهینه شده است.

  • lyria-3-pro-preview

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

مدلی که اعلان شما را تکمیل می‌کند.\n\nبرای جزئیات بیشتر به [models](https://ai.google.dev/gemini-api/docs/models) مراجعه کنید.

گزینه عامل (اختیاری)

نام «عامل» مورد استفاده برای ایجاد تعامل.

مقادیر ممکن:

  • deep-research-pro-preview-12-2025

    نماینده تحقیقات عمیق جمینی

  • deep-research-preview-04-2026

    نماینده تحقیقات عمیق جمینی

  • deep-research-max-preview-04-2026

    مامور مکس تحقیقات عمیق جمینی

عاملی که باید با آن تعامل داشت.

رشته شناسه (اختیاری)

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

شمارش وضعیت (رشته) (اختیاری)

الزامی. فقط خروجی. وضعیت تعامل.

مقادیر ممکن:

  • in_progress
  • requires_action
  • completed
  • failed
  • cancelled
  • incomplete
رشته ایجاد شده (اختیاری)

الزامی. فقط خروجی. زمانی که پاسخ در قالب ISO 8601 (YYYY-MM-DDThh:mm:ssZ) ایجاد شده است.

رشته به‌روزرسانی‌شده (اختیاری)

الزامی. فقط خروجی. زمانی که پاسخ آخرین بار در قالب ISO 8601 (YYYY-MM-DDThh:mm:ssZ) به‌روزرسانی شده است.

رشته نقش (اختیاری)

فقط خروجی. نقش تعامل.

رشته system_instruction (اختیاری)

دستورالعمل سیستم برای تعامل.

آرایه ابزارها ( ابزار ) (اختیاری)

فهرستی از اعلان‌های ابزار که مدل ممکن است در طول تعامل فراخوانی کند.

کاربرد (اختیاری )

فقط خروجی. آمار مربوط به میزان استفاده از توکن درخواست تعامل.

آمار مربوط به میزان استفاده از توکن درخواست تعامل.

فیلدها

عدد صحیح total_input_tokens (اختیاری)

تعداد توکن‌ها در اعلان (زمینه).

ورودی_توکن‌ها_براساس_مودالیتی توکن‌های مودالیتی (اختیاری)

تفکیک استفاده از توکن ورودی بر اساس روش.

تعداد توکن‌ها برای یک روش پاسخ واحد.

فیلدها

روش پاسخ (اختیاری)

روش مرتبط با شمارش توکن‌ها.

مقادیر ممکن:

  • text
  • image
  • audio
  • video
  • document

عدد صحیح توکن (اختیاری)

تعداد توکن‌ها برای روش.

عدد صحیح total_cached_tokens (اختیاری)

تعداد توکن‌ها در بخش ذخیره‌شده‌ی اعلان (محتوای ذخیره‌شده).

cached_tokens_by_modality توکن‌های مودالیتی (اختیاری)

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

تعداد توکن‌ها برای یک روش پاسخ واحد.

فیلدها

روش پاسخ (اختیاری)

روش مرتبط با شمارش توکن‌ها.

مقادیر ممکن:

  • text
  • image
  • audio
  • video
  • document

عدد صحیح توکن (اختیاری)

تعداد توکن‌ها برای روش.

total_output_tokens عدد صحیح (اختیاری)

تعداد کل توکن‌ها در تمام پاسخ‌های تولید شده.

خروجی_توکن‌ها_براساس_مودالیتی توکن‌های مودالیتی (اختیاری)

تفکیک استفاده از توکن خروجی بر اساس روش.

تعداد توکن‌ها برای یک روش پاسخ واحد.

فیلدها

روش پاسخ (اختیاری)

روش مرتبط با شمارش توکن‌ها.

مقادیر ممکن:

  • text
  • image
  • audio
  • video
  • document

عدد صحیح توکن (اختیاری)

تعداد توکن‌ها برای روش.

عدد صحیح total_tool_use_tokens (اختیاری)

تعداد توکن‌های موجود در اعلان(های) استفاده از ابزار.

ابزار_استفاده_از_توکن‌ها_توسط_مودالیتی توکن‌های مودالیتی (اختیاری)

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

تعداد توکن‌ها برای یک روش پاسخ واحد.

فیلدها

روش پاسخ (اختیاری)

روش مرتبط با شمارش توکن‌ها.

مقادیر ممکن:

  • text
  • image
  • audio
  • video
  • document

عدد صحیح توکن (اختیاری)

تعداد توکن‌ها برای روش.

total_thought_tokens عدد صحیح (اختیاری)

تعداد توکن‌های افکار برای مدل‌های تفکر.

عدد صحیح total_tokens (اختیاری)

تعداد کل توکن‌ها برای درخواست تعامل (درخواست + پاسخ‌ها + سایر توکن‌های داخلی).

grounding_tool_count تعداد ابزار زمینی (اختیاری)

تعداد ابزار اتصال به زمین

تعداد ابزار اتصال به زمین مهم است.

فیلدها

نوع enum (رشته) (اختیاری)

نوع ابزار اتصال زمین مرتبط با شمارش.

مقادیر ممکن:

  • google_search
  • google_maps
  • retrieval
شمارش عدد صحیح (اختیاری)

تعداد ابزار اتصال به زمین مهم است.

روش_پاسخ ( اختیاری )

روش‌های درخواستی برای پاسخ (متن، تصویر، صدا).

مقادیر ممکن:

  • text
  • image
  • audio
  • video
  • document

رشته response_mime_type (اختیاری)

نوع MIME پاسخ. در صورت تنظیم response_format، این مورد الزامی است.

رشته‌ی previous_interaction_id (اختیاری)

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

service_tier لایه سرویس (اختیاری)

لایه سرویس برای تعامل.

مقادیر ممکن:

  • flex
  • standard
  • priority

webhook_config پیکربندی وب هوک (اختیاری)

اختیاری. پیکربندی وب‌هوک برای دریافت اعلان‌ها پس از اتمام تعامل.

پیام مربوط به پیکربندی رویدادهای وب‌هوک برای یک درخواست.

فیلدها

آرایه uris (رشته) (اختیاری)

اختیاری. در صورت تنظیم، این URLهای وب‌هوک به جای وب‌هوک‌های ثبت‌شده، برای رویدادهای وب‌هوک استفاده خواهند شد.

شیء user_metadata (اختیاری)

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

مراحل ( اختیاری )

فقط خروجی. مراحلی که تعامل را تشکیل می‌دهند.

گامی در تعامل.

انواع ممکن

تفکیک‌کننده چندریختی: type

مرحله ورودی کاربر

ورودی ارائه شده توسط کاربر.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "user_input" تنظیم شود.

آرایه محتوا ( محتوا ) (اختیاری)

هیچ توضیحی ارائه نشده است.

مرحله خروجی مدل

خروجی تولید شده توسط مدل.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "model_output" تنظیم شود.

آرایه محتوا ( محتوا ) (اختیاری)

هیچ توضیحی ارائه نشده است.

اندیشه گام

یک گام فکری.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "thought" تنظیم شود.

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

خلاصه محتوای خلاصه اندیشه (اختیاری)

خلاصه‌ای از اندیشه.

انواع ممکن

تفکیک‌کننده چندریختی: type

محتوای متن

یک بلوک محتوای متنی.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "text" تنظیم شود.

رشته متن (الزامی)

محتوای متن الزامی است.

حاشیه‌نویسی‌ها ( اختیاری )

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

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

انواع ممکن

تفکیک‌کننده چندریختی: type

استناد به آدرس اینترنتی

حاشیه‌نویسی استناد URL.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "url_citation" تنظیم شود.

رشته آدرس اینترنتی (اختیاری)

آدرس اینترنتی (URL).

رشته عنوان (اختیاری)

عنوان URL.

عدد صحیح start_index (اختیاری)

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

عدد صحیح end_index (اختیاری)

پایان بخش منسوب، منحصر به فرد.

استناد به فایل

حاشیه‌نویسی استناد به فایل.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "file_citation" تنظیم شود.

رشته document_uri (اختیاری)

آدرس اینترنتی (URI) فایل.

رشته نام فایل (اختیاری)

نام فایل.

رشته منبع (اختیاری)

منبع برای بخشی از متن ذکر شده است.

شیء custom_metadata (اختیاری)

فراداده‌های ارائه شده توسط کاربر در مورد متن بازیابی شده.

عدد صحیح شماره صفحه (اختیاری)

شماره صفحه سند ذکر شده، در صورت وجود.

رشته media_id (اختیاری)

شناسه رسانه در صورت استناد به تصویر، در صورت لزوم.

عدد صحیح start_index (اختیاری)

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

عدد صحیح end_index (اختیاری)

پایان بخش منسوب، منحصر به فرد.

استناد به مکان

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

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "place_citation" تنظیم شود.

رشته place_id (اختیاری)

شناسه مکان، با فرمت `places/{place_id}`.

رشته نام (اختیاری)

عنوان مکان.

رشته آدرس اینترنتی (اختیاری)

مرجع URI آن مکان.

review_snippets قطعه کد نقد و بررسی (اختیاری)

گزیده‌هایی از نظرات که برای تولید پاسخ در مورد ویژگی‌های یک مکان مشخص در نقشه‌های گوگل استفاده می‌شوند.

بخشی از نقد کاربر را که به سوالی در مورد ویژگی‌های یک مکان خاص در نقشه‌های گوگل پاسخ می‌دهد، در بر می‌گیرد.

فیلدها

رشته عنوان (اختیاری)

عنوان نقد.

رشته آدرس اینترنتی (اختیاری)

لینکی که مربوط به نظر کاربر در نقشه گوگل باشد.

رشته review_id (اختیاری)

شناسه‌ی قطعه نقد و بررسی.

عدد صحیح start_index (اختیاری)

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

عدد صحیح end_index (اختیاری)

پایان بخش منسوب، منحصر به فرد.

محتوای تصویر

یک بلوک محتوای تصویر.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "image" تنظیم شود.

رشته داده (اختیاری)

محتوای تصویر.

رشته uri (اختیاری)

آدرس اینترنتی (URI) تصویر.

mime_type enum (رشته) (اختیاری)

نوع مایم تصویر.

مقادیر ممکن:

  • image/png
  • image/jpeg
  • image/webp
  • image/heic
  • image/heif
  • image/gif
  • image/bmp
  • image/tiff
وضوح تصویر MediaResolution (اختیاری)

قطعنامه رسانه‌ها.

مقادیر ممکن:

  • low
  • medium
  • high
  • ultra_high

مرحله فراخوانی تابع

مرحله فراخوانی ابزار تابع.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "function_call" تنظیم شود.

رشته نام (الزامی)

الزامی. نام ابزاری که باید فراخوانی شود.

شیء آرگومان‌ها (الزامی)

آرگومان‌هایی که باید به تابع ارسال شوند.

رشته شناسه (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

مرحله فراخوانی کد (CodeExecutionCallStep)

مرحله فراخوانی اجرای کد.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "code_execution_call" تنظیم شود.

آرگومان‌های CodeExecutionCallStepArgumentها (الزامی)

الزامی. آرگومان‌هایی که برای اجرای کد ارسال می‌شوند.

آرگومان‌هایی که باید به اجرای کد ارسال شوند.

فیلدها

شمارش زبان (رشته) (اختیاری)

زبان برنامه‌نویسی «کد».

مقادیر ممکن:

  • python
رشته کد (اختیاری)

کدی که قرار است اجرا شود.

رشته شناسه (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

مرحله فراخوانی متن (UrlContextCallStep)

مرحله فراخوانی زمینه URL.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "url_context_call" تنظیم شود.

آرگومان‌های UrlContextCallStepArgument (الزامی)

آرگومان‌هایی که باید به متن URL ارسال شوند.

آرگومان‌هایی که باید به متن URL ارسال شوند.

فیلدها

آرایه آدرس‌های اینترنتی (رشته‌ای) (اختیاری)

آدرس‌های اینترنتی (URL) برای دریافت.

رشته شناسه (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

ابزار فراخوانی مک‌پ‌سرور (McpServerToolCallStep)

مرحله فراخوانی ابزار MCPServer.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "mcp_server_tool_call" تنظیم شود.

رشته نام (الزامی)

الزامی. نام ابزاری که فراخوانی شده است.

رشته نام سرور (الزامی)

الزامی. نام سرور MCP مورد استفاده.

شیء آرگومان‌ها (الزامی)

الزامی. شیء JSON آرگومان‌های تابع.

رشته شناسه (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

جستجوی گوگل

مرحله تماس جستجوی گوگل.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "google_search_call" تنظیم شود.

آرگومان‌های GoogleSearchCallStepArguments (الزامی)

الزامی. آرگومان‌هایی که باید به جستجوی گوگل ارسال شوند.

آرگومان‌هایی که باید به جستجوی گوگل ارسال شوند.

فیلدها

آرایه کوئری‌ها (رشته) (اختیاری)

عبارت‌های جستجوی وب برای جستجوی وب بعدی.

تابع search_type enum (رشته‌ای) (اختیاری)

نوع اتصال زمینی جستجو فعال شده.

مقادیر ممکن:

  • web_search
  • image_search
  • enterprise_web_search
رشته شناسه (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

جستجوی فایلفراخوانیمرحله

مرحله فراخوانی جستجوی فایل.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "file_search_call" تنظیم شود.

رشته شناسه (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

گوگل مپ کال استپ

مرحله تماس با نقشه گوگل

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "google_maps_call" تنظیم شود.

آرگومان‌های GoogleMapsCallStepArguments (اختیاری)

آرگومان‌هایی که باید به ابزار نقشه‌های گوگل ارسال شوند.

آرگومان‌هایی که باید به ابزار نقشه‌های گوگل ارسال شوند.

فیلدها

آرایه کوئری‌ها (رشته) (اختیاری)

کوئری‌هایی که باید اجرا شوند.

رشته شناسه (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

تابعنتیجهمرحله

نتیجه‌ی فراخوانی ابزار تابع.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "function_result" تنظیم شود.

رشته نام (اختیاری)

نام ابزاری که نامیده شد.

is_error نوع داده بولی (اختیاری)

اینکه آیا فراخوانی ابزار منجر به خطا شده است یا خیر.

رشته call_id (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

آرایه نتیجه ( FunctionResultSubcontent ) یا رشته (الزامی)

نتیجه فراخوانی ابزار.

مرحله اجرای کد (CodeExecutionResultStep)

مرحله نتیجه اجرای کد.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "code_execution_result" تنظیم شود.

رشته نتیجه (الزامی)

خروجی اجرای کد. الزامی.

is_error نوع داده بولی (اختیاری)

اینکه آیا اجرای کد منجر به خطا شده است یا خیر.

رشته call_id (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

مرحله نتیجه گیری UrlContext

مرحله نتیجه زمینه URL.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "url_context_result" تنظیم شود.

نتیجه UrlContextResultItem (الزامی)

الزامی. نتایج زمینه URL.

نتیجه‌ی زمینه‌ی URL.

فیلدها

رشته آدرس اینترنتی (اختیاری)

آدرس اینترنتی (URL) که دریافت شده است.

شمارش وضعیت (رشته) (اختیاری)

وضعیت بازیابی URL.

مقادیر ممکن:

  • success
  • error
  • paywall
  • unsafe
is_error نوع داده بولی (اختیاری)

اینکه آیا زمینه URL منجر به خطا شده است یا خیر.

رشته call_id (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

مرحله نتایج جستجوی گوگل

مرحله نتیجه جستجوی گوگل

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "google_search_result" تنظیم شود.

نتیجه جستجوی گوگل (الزامی)

الزامی. نتایج جستجوی گوگل.

نتیجه جستجوی گوگل.

فیلدها

رشته‌ی search_suggestions (اختیاری)

قطعه محتوای وب که می‌تواند در یک صفحه وب یا نمای وب یک برنامه تعبیه شود.

is_error نوع داده بولی (اختیاری)

اینکه آیا جستجوی گوگل منجر به خطا شده است یا خیر.

رشته call_id (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

ابزار نتیجه McpServerTool

مرحله نتیجه ابزار MCPServer.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "mcp_server_tool_result" تنظیم شود.

رشته نام (اختیاری)

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

رشته server_name (اختیاری)

نام سرور MCP مورد استفاده.

رشته call_id (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

آرایه نتیجه ( FunctionResultSubcontent ) یا رشته (الزامی)

خروجی حاصل از فراخوانی سرور MCP. می‌تواند متن ساده یا محتوای غنی باشد.

مرحله‌ی جستجوی فایل

مرحله نتیجه جستجوی فایل

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "file_search_result" تنظیم شود.

رشته call_id (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

مرحله نتیجه گوگل مپ

مرحله نتایج نقشه گوگل

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "google_maps_result" تنظیم شود.

نتیجه GoogleMapsResultItem (الزامی)

هیچ توضیحی ارائه نشده است.

نتیجه نقشه‌های گوگل.

فیلدها

مکان‌ها GoogleMapsResultPlaces (اختیاری)

هیچ توضیحی ارائه نشده است.

فیلدها

رشته place_id (اختیاری)

هیچ توضیحی ارائه نشده است.

رشته نام (اختیاری)

هیچ توضیحی ارائه نشده است.

رشته آدرس اینترنتی (اختیاری)

هیچ توضیحی ارائه نشده است.

review_snippets قطعه کد نقد و بررسی (اختیاری)

هیچ توضیحی ارائه نشده است.

بخشی از نقد کاربر را که به سوالی در مورد ویژگی‌های یک مکان خاص در نقشه‌های گوگل پاسخ می‌دهد، در بر می‌گیرد.

فیلدها

رشته عنوان (اختیاری)

عنوان نقد.

رشته آدرس اینترنتی (اختیاری)

لینکی که مربوط به نظر کاربر در نقشه گوگل باشد.

رشته review_id (اختیاری)

شناسه‌ی قطعه نقد و بررسی.

رشته widget_context_token (اختیاری)

هیچ توضیحی ارائه نشده است.

رشته call_id (الزامی)

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

رشته امضا (اختیاری)

یک هش امضا برای اعتبارسنجی backend.

ورودی محتوا یا آرایه ( Content ) یا آرایه ( Step ) یا رشته (اختیاری)

ورودی برای تعامل.

قالب پاسخ یا فهرست قالب پاسخ (اختیاری)

تأکید می‌کند که پاسخ تولید شده یک شیء JSON است که با طرحواره JSON مشخص شده در این فیلد مطابقت دارد.

شیء agent_config (اختیاری)

پارامترهای پیکربندی برای تعامل عامل.

انواع ممکن

تفکیک‌کننده چندریختی: type

پیکربندی DynamicAgent

پیکربندی برای عامل‌های پویا

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "dynamic" تنظیم شود.

پیکربندی DeepResearchAgent

پیکربندی برای عامل تحقیقات عمیق.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "deep-research" تنظیم شود.

خلاصه‌های تفکر ( اختیاری)

اینکه آیا خلاصه نظرات در پاسخ گنجانده شود یا خیر.

مقادیر ممکن:

  • auto
  • none

تجسم enum (رشته) (اختیاری)

اینکه آیا باید از تصاویر در پاسخ استفاده کرد یا خیر.

مقادیر ممکن:

  • off
  • auto
نوع بولی collaboration_planning (اختیاری)

برنامه‌ریزی انسان در حلقه را برای عامل تحقیقات عمیق فعال می‌کند. اگر روی درست تنظیم شود، عامل تحقیقات عمیق در پاسخ خود یک طرح تحقیقاتی ارائه می‌دهد. سپس عامل تنها در صورتی ادامه می‌دهد که کاربر طرح را در نوبت بعدی تأیید کند.

مثال‌ها

مثال 

{
  "created": "2025-12-04T15:01:45Z",
  "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
  "model": "gemini-3-flash-preview",
  "object": "interaction",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Hello! I'm doing well, functioning as expected. Thank you for asking! How are you doing today?"
        }
      ]
    }
  ],
  "status": "completed",
  "updated": "2025-12-04T15:01:45Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 7
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 7,
    "total_output_tokens": 23,
    "total_thought_tokens": 49,
    "total_tokens": 79,
    "total_tool_use_tokens": 0
  }
}

مدل‌های داده

محتوا

محتوای پاسخ.

انواع ممکن

تفکیک‌کننده چندریختی: type

محتوای متن

یک بلوک محتوای متنی.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "text" تنظیم شود.

رشته متن (الزامی)

محتوای متن الزامی است.

حاشیه‌نویسی‌ها ( اختیاری )

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

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

انواع ممکن

تفکیک‌کننده چندریختی: type

استناد به آدرس اینترنتی

حاشیه‌نویسی استناد URL.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "url_citation" تنظیم شود.

رشته آدرس اینترنتی (اختیاری)

آدرس اینترنتی (URL).

رشته عنوان (اختیاری)

عنوان URL.

عدد صحیح start_index (اختیاری)

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

عدد صحیح end_index (اختیاری)

پایان بخش منسوب، منحصر به فرد.

استناد به فایل

حاشیه‌نویسی استناد به فایل.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "file_citation" تنظیم شود.

رشته document_uri (اختیاری)

آدرس اینترنتی (URI) فایل.

رشته نام فایل (اختیاری)

نام فایل.

رشته منبع (اختیاری)

منبع برای بخشی از متن ذکر شده است.

شیء custom_metadata (اختیاری)

فراداده‌های ارائه شده توسط کاربر در مورد متن بازیابی شده.

عدد صحیح شماره صفحه (اختیاری)

شماره صفحه سند ذکر شده، در صورت وجود.

رشته media_id (اختیاری)

شناسه رسانه در صورت استناد به تصویر، در صورت لزوم.

عدد صحیح start_index (اختیاری)

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

عدد صحیح end_index (اختیاری)

پایان بخش منسوب، منحصر به فرد.

استناد به مکان

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

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "place_citation" تنظیم شود.

رشته place_id (اختیاری)

شناسه مکان، با فرمت `places/{place_id}`.

رشته نام (اختیاری)

عنوان مکان.

رشته آدرس اینترنتی (اختیاری)

مرجع URI آن مکان.

review_snippets قطعه کد نقد و بررسی (اختیاری)

گزیده‌هایی از نظرات که برای تولید پاسخ در مورد ویژگی‌های یک مکان مشخص در نقشه‌های گوگل استفاده می‌شوند.

بخشی از نقد کاربر را که به سوالی در مورد ویژگی‌های یک مکان خاص در نقشه‌های گوگل پاسخ می‌دهد، در بر می‌گیرد.

فیلدها

رشته عنوان (اختیاری)

عنوان نقد.

رشته آدرس اینترنتی (اختیاری)

لینکی که مربوط به نظر کاربر در نقشه گوگل باشد.

رشته review_id (اختیاری)

شناسه‌ی قطعه نقد و بررسی.

عدد صحیح start_index (اختیاری)

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

عدد صحیح end_index (اختیاری)

پایان بخش منسوب، منحصر به فرد.

محتوای تصویر

یک بلوک محتوای تصویر.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "image" تنظیم شود.

رشته داده (اختیاری)

محتوای تصویر.

رشته uri (اختیاری)

آدرس اینترنتی (URI) تصویر.

mime_type enum (رشته) (اختیاری)

نوع مایم تصویر.

مقادیر ممکن:

  • image/png
  • image/jpeg
  • image/webp
  • image/heic
  • image/heif
  • image/gif
  • image/bmp
  • image/tiff
وضوح تصویر MediaResolution (اختیاری)

قطعنامه رسانه‌ها.

مقادیر ممکن:

  • low
  • medium
  • high
  • ultra_high

محتوای صوتی

یک بلوک محتوای صوتی.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "audio" تنظیم شود.

رشته داده (اختیاری)

محتوای صوتی.

رشته uri (اختیاری)

آدرس اینترنتی (URI) فایل صوتی.

mime_type enum (رشته) (اختیاری)

نوع مایم صدا.

مقادیر ممکن:

  • audio/wav
  • audio/mp3
  • audio/aiff
  • audio/aac
  • audio/ogg
  • audio/flac
  • audio/mpeg
  • audio/m4a
  • audio/l16
  • audio/opus
  • audio/alaw
  • audio/mulaw
عدد صحیح کانال‌ها (اختیاری)

تعداد کانال‌های صوتی

عدد صحیح sample_rate (اختیاری)

نرخ نمونه‌برداری صدا.

محتوای سند

یک بلوک محتوای سند.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "document" تنظیم شود.

رشته داده (اختیاری)

محتوای سند.

رشته uri (اختیاری)

آدرس اینترنتی (URI) سند.

mime_type enum (رشته) (اختیاری)

نوع MIME سند.

مقادیر ممکن:

  • application/pdf
محتوای ویدیویی

یک بلوک محتوای ویدیویی.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "video" تنظیم شود.

رشته داده (اختیاری)

محتوای ویدیویی.

رشته uri (اختیاری)

آدرس اینترنتی (URI) ویدیو.

mime_type enum (رشته) (اختیاری)

نوع میم (شبیه‌سازی) ویدیو.

مقادیر ممکن:

  • video/mp4
  • video/mpeg
  • video/mpg
  • video/mov
  • video/avi
  • video/x-flv
  • video/webm
  • video/wmv
  • video/3gpp
وضوح تصویر MediaResolution (اختیاری)

قطعنامه رسانه‌ها.

مقادیر ممکن:

  • low
  • medium
  • high
  • ultra_high

مثال‌ها

متن 

{
  "type": "text",
  "text": "Hello, how are you?"
}

تصویر 

{
  "type": "image",
  "data": "BASE64_ENCODED_IMAGE",
  "mime_type": "image/png"
}

صوتی 

{
  "type": "audio",
  "data": "BASE64_ENCODED_AUDIO",
  "mime_type": "audio/wav"
}

سند 

{
  "type": "document",
  "data": "BASE64_ENCODED_DOCUMENT",
  "mime_type": "application/pdf"
}

ویدئو 

{
  "type": "video",
  "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
}

ابزار

ابزاری که می‌تواند توسط مدل مورد استفاده قرار گیرد.

انواع ممکن

تفکیک‌کننده چندریختی: type

عملکرد

ابزاری که می‌تواند توسط مدل مورد استفاده قرار گیرد.

نوع شیء (الزامی)

هیچ توضیحی ارائه نشده است.

همیشه روی "function" تنظیم شود.

رشته نام (اختیاری)

نام تابع.

رشته توضیحات (اختیاری)

شرحی از تابع.

پارامتر شیء (اختیاری)

طرحواره JSON برای پارامترهای تابع.

CodeExecution

A tool that can be used by the model to execute code.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "code_execution" .

UrlContext

A tool that can be used by the model to fetch URL context.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "url_context" .

ComputerUse

A tool that can be used by the model to interact with the computer.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "computer_use" .

environment enum (string) (optional)

The environment being operated.

Possible values:

  • browser
excluded_predefined_functions array (string) (optional)

The list of predefined functions that are excluded from the model call.

McpServer

A MCPServer is a server that can be called by the model to perform actions.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "mcp_server" .

name string (optional)

The name of the MCPServer.

url string (optional)

The full URL for the MCPServer endpoint. Example: "https://api.example.com/mcp"

headers object (optional)

Optional: Fields for authentication headers, timeouts, etc., if needed.

allowed_tools AllowedTools (optional)

The allowed tools.

The configuration for allowed tools.

فیلدها

mode ToolChoiceType (optional)

The mode of the tool choice.

Possible values:

  • auto
  • any
  • none
  • validated

tools array (string) (optional)

The names of the allowed tools.

GoogleSearch

A tool that can be used by the model to search Google.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "google_search" .

search_types array (enum (string)) (optional)

The types of search grounding to enable.

Possible values:

  • web_search
  • image_search
  • enterprise_web_search
FileSearch

A tool that can be used by the model to search files.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "file_search" .

file_search_store_names array (string) (optional)

The file search store names to search.

top_k integer (optional)

The number of semantic retrieval chunks to retrieve.

metadata_filter string (optional)

Metadata filter to apply to the semantic retrieval documents and chunks.

GoogleMaps

A tool that can be used by the model to call Google Maps.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "google_maps" .

enable_widget boolean (optional)

Whether to return a widget context token in the tool call result of the response.

latitude number (optional)

The latitude of the user's location.

longitude number (optional)

The longitude of the user's location.

Retrieval

A tool that can be used by the model to retrieve files.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "retrieval" .

retrieval_types array (enum (string)) (optional)

The types of file retrieval to enable.

Possible values:

  • vertex_ai_search
vertex_ai_search_config VertexAISearchConfig (optional)

Used to specify configuration for VertexAISearch.

Used to specify configuration for VertexAISearch.

فیلدها

engine string (optional)

Optional. Used to specify Vertex AI Search engine.

datastores array (string) (optional)

Optional. Used to specify Vertex AI Search datastores.

مثال‌ها

عملکرد

CodeExecution

UrlContext

ComputerUse

McpServer

GoogleSearch

FileSearch

GoogleMaps

Retrieval

No examples available for this type.

InteractionSseEvent

Possible Types

Polymorphic discriminator: event_type

InteractionCreatedEvent

event_type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "interaction.created" .

interaction Interaction (required)

هیچ توضیحی ارائه نشده است.

event_id string (optional)

The event_id token to be used to resume the interaction stream, from this event.

InteractionCompletedEvent

event_type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "interaction.completed" .

interaction Interaction (required)

Required. The completed interaction with empty outputs to reduce the payload size. Use the preceding ContentDelta events for the actual output.

event_id string (optional)

The event_id token to be used to resume the interaction stream, from this event.

InteractionStatusUpdate

event_type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "interaction.status_update" .

interaction_id string (required)

هیچ توضیحی ارائه نشده است.

status enum (string) (required)

هیچ توضیحی ارائه نشده است.

Possible values:

  • in_progress
  • requires_action
  • completed
  • failed
  • cancelled
  • incomplete
event_id string (optional)

The event_id token to be used to resume the interaction stream, from this event.

ErrorEvent

event_type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "error" .

error Error (optional)

هیچ توضیحی ارائه نشده است.

Error message from an interaction.

فیلدها

code string (optional)

A URI that identifies the error type.

message string (optional)

A human-readable error message.

event_id string (optional)

The event_id token to be used to resume the interaction stream, from this event.

StepStart

event_type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "step.start" .

index integer (required)

هیچ توضیحی ارائه نشده است.

step Step (required)

هیچ توضیحی ارائه نشده است.

A step in the interaction.

Possible Types

Polymorphic discriminator: type

UserInputStep

Input provided by the user.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "user_input" .

content array ( Content ) (optional)

هیچ توضیحی ارائه نشده است.

ModelOutputStep

Output generated by the model.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "model_output" .

content array ( Content ) (optional)

هیچ توضیحی ارائه نشده است.

ThoughtStep

A thought step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "thought" .

signature string (optional)

A signature hash for backend validation.

summary ThoughtSummaryContent (optional)

A summary of the thought.

Possible Types

Polymorphic discriminator: type

TextContent

A text content block.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "text" .

text string (required)

Required. The text content.

annotations Annotation (optional)

Citation information for model-generated content.

Citation information for model-generated content.

Possible Types

Polymorphic discriminator: type

UrlCitation

A URL citation annotation.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "url_citation" .

url string (optional)

The URL.

title string (optional)

The title of the URL.

start_index integer (optional)

Start of segment of the response that is attributed to this source. Index indicates the start of the segment, measured in bytes.

end_index integer (optional)

End of the attributed segment, exclusive.

FileCitation

A file citation annotation.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "file_citation" .

document_uri string (optional)

The URI of the file.

file_name string (optional)

The name of the file.

source string (optional)

Source attributed for a portion of the text.

custom_metadata object (optional)

User provided metadata about the retrieved context.

page_number integer (optional)

Page number of the cited document, if applicable.

media_id string (optional)

Media ID in-case of image citations, if applicable.

start_index integer (optional)

Start of segment of the response that is attributed to this source. Index indicates the start of the segment, measured in bytes.

end_index integer (optional)

End of the attributed segment, exclusive.

PlaceCitation

A place citation annotation.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "place_citation" .

place_id string (optional)

The ID of the place, in `places/{place_id}` format.

name string (optional)

Title of the place.

url string (optional)

URI reference of the place.

review_snippets ReviewSnippet (optional)

Snippets of reviews that are used to generate answers about the features of a given place in Google Maps.

Encapsulates a snippet of a user review that answers a question about the features of a specific place in Google Maps.

فیلدها

title string (optional)

Title of the review.

url string (optional)

A link that corresponds to the user review on Google Maps.

review_id string (optional)

The ID of the review snippet.

start_index integer (optional)

Start of segment of the response that is attributed to this source. Index indicates the start of the segment, measured in bytes.

end_index integer (optional)

End of the attributed segment, exclusive.

ImageContent

An image content block.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "image" .

data string (optional)

The image content.

uri string (optional)

The URI of the image.

mime_type enum (string) (optional)

The mime type of the image.

Possible values:

  • image/png
  • image/jpeg
  • image/webp
  • image/heic
  • image/heif
  • image/gif
  • image/bmp
  • image/tiff
resolution MediaResolution (optional)

The resolution of the media.

Possible values:

  • low
  • medium
  • high
  • ultra_high

FunctionCallStep

A function tool call step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "function_call" .

name string (required)

Required. The name of the tool to call.

arguments object (required)

Required. The arguments to pass to the function.

id string (required)

Required. A unique ID for this specific tool call.

signature string (optional)

A signature hash for backend validation.

CodeExecutionCallStep

Code execution call step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "code_execution_call" .

arguments CodeExecutionCallStepArguments (required)

Required. The arguments to pass to the code execution.

The arguments to pass to the code execution.

فیلدها

language enum (string) (optional)

Programming language of the `code`.

Possible values:

  • python
code string (optional)

The code to be executed.

id string (required)

Required. A unique ID for this specific tool call.

signature string (optional)

A signature hash for backend validation.

UrlContextCallStep

URL context call step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "url_context_call" .

arguments UrlContextCallStepArguments (required)

Required. The arguments to pass to the URL context.

The arguments to pass to the URL context.

فیلدها

urls array (string) (optional)

The URLs to fetch.

id string (required)

Required. A unique ID for this specific tool call.

signature string (optional)

A signature hash for backend validation.

McpServerToolCallStep

MCPServer tool call step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "mcp_server_tool_call" .

name string (required)

Required. The name of the tool which was called.

server_name string (required)

Required. The name of the used MCP server.

arguments object (required)

Required. The JSON object of arguments for the function.

id string (required)

Required. A unique ID for this specific tool call.

signature string (optional)

A signature hash for backend validation.

GoogleSearchCallStep

Google Search call step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "google_search_call" .

arguments GoogleSearchCallStepArguments (required)

Required. The arguments to pass to Google Search.

The arguments to pass to Google Search.

فیلدها

queries array (string) (optional)

Web search queries for the following-up web search.

search_type enum (string) (optional)

The type of search grounding enabled.

Possible values:

  • web_search
  • image_search
  • enterprise_web_search
id string (required)

Required. A unique ID for this specific tool call.

signature string (optional)

A signature hash for backend validation.

FileSearchCallStep

File Search call step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "file_search_call" .

id string (required)

Required. A unique ID for this specific tool call.

signature string (optional)

A signature hash for backend validation.

GoogleMapsCallStep

Google Maps call step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "google_maps_call" .

arguments GoogleMapsCallStepArguments (optional)

The arguments to pass to the Google Maps tool.

The arguments to pass to the Google Maps tool.

فیلدها

queries array (string) (optional)

The queries to be executed.

id string (required)

Required. A unique ID for this specific tool call.

signature string (optional)

A signature hash for backend validation.

FunctionResultStep

Result of a function tool call.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "function_result" .

name string (optional)

The name of the tool that was called.

is_error boolean (optional)

Whether the tool call resulted in an error.

call_id string (required)

Required. ID to match the ID from the function call block.

signature string (optional)

A signature hash for backend validation.

result array ( FunctionResultSubcontent ) or string (required)

The result of the tool call.

CodeExecutionResultStep

Code execution result step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "code_execution_result" .

result string (required)

Required. The output of the code execution.

is_error boolean (optional)

Whether the code execution resulted in an error.

call_id string (required)

Required. ID to match the ID from the function call block.

signature string (optional)

A signature hash for backend validation.

UrlContextResultStep

URL context result step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "url_context_result" .

result UrlContextResultItem (required)

Required. The results of the URL context.

The result of the URL context.

فیلدها

url string (optional)

The URL that was fetched.

status enum (string) (optional)

The status of the URL retrieval.

Possible values:

  • success
  • error
  • paywall
  • unsafe
is_error boolean (optional)

Whether the URL context resulted in an error.

call_id string (required)

Required. ID to match the ID from the function call block.

signature string (optional)

A signature hash for backend validation.

GoogleSearchResultStep

Google Search result step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "google_search_result" .

result GoogleSearchResultItem (required)

Required. The results of the Google Search.

The result of the Google Search.

فیلدها

search_suggestions string (optional)

Web content snippet that can be embedded in a web page or an app webview.

is_error boolean (optional)

Whether the Google Search resulted in an error.

call_id string (required)

Required. ID to match the ID from the function call block.

signature string (optional)

A signature hash for backend validation.

McpServerToolResultStep

MCPServer tool result step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "mcp_server_tool_result" .

name string (optional)

Name of the tool which is called for this specific tool call.

server_name string (optional)

The name of the used MCP server.

call_id string (required)

Required. ID to match the ID from the function call block.

signature string (optional)

A signature hash for backend validation.

result array ( FunctionResultSubcontent ) or string (required)

The output from the MCP server call. Can be simple text or rich content.

FileSearchResultStep

File Search result step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "file_search_result" .

call_id string (required)

Required. ID to match the ID from the function call block.

signature string (optional)

A signature hash for backend validation.

GoogleMapsResultStep

Google Maps result step.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "google_maps_result" .

result GoogleMapsResultItem (required)

هیچ توضیحی ارائه نشده است.

The result of the Google Maps.

فیلدها

places GoogleMapsResultPlaces (optional)

هیچ توضیحی ارائه نشده است.

فیلدها

place_id string (optional)

هیچ توضیحی ارائه نشده است.

name string (optional)

هیچ توضیحی ارائه نشده است.

url string (optional)

هیچ توضیحی ارائه نشده است.

review_snippets ReviewSnippet (optional)

هیچ توضیحی ارائه نشده است.

Encapsulates a snippet of a user review that answers a question about the features of a specific place in Google Maps.

فیلدها

title string (optional)

Title of the review.

url string (optional)

A link that corresponds to the user review on Google Maps.

review_id string (optional)

The ID of the review snippet.

widget_context_token string (optional)

هیچ توضیحی ارائه نشده است.

call_id string (required)

Required. ID to match the ID from the function call block.

signature string (optional)

A signature hash for backend validation.

event_id string (optional)

The event_id token to be used to resume the interaction stream, from this event.

StepDelta

event_type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "step.delta" .

index integer (required)

هیچ توضیحی ارائه نشده است.

delta StepDeltaData (required)

هیچ توضیحی ارائه نشده است.

Possible Types

Polymorphic discriminator: type

TextDelta

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "text" .

text string (required)

هیچ توضیحی ارائه نشده است.

ImageDelta

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "image" .

data string (optional)

هیچ توضیحی ارائه نشده است.

uri string (optional)

هیچ توضیحی ارائه نشده است.

mime_type enum (string) (optional)

هیچ توضیحی ارائه نشده است.

Possible values:

  • image/png
  • image/jpeg
  • image/webp
  • image/heic
  • image/heif
  • image/gif
  • image/bmp
  • image/tiff
resolution MediaResolution (optional)

The resolution of the media.

Possible values:

  • low
  • medium
  • high
  • ultra_high

AudioDelta

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "audio" .

data string (optional)

هیچ توضیحی ارائه نشده است.

uri string (optional)

هیچ توضیحی ارائه نشده است.

mime_type enum (string) (optional)

هیچ توضیحی ارائه نشده است.

Possible values:

  • audio/wav
  • audio/mp3
  • audio/aiff
  • audio/aac
  • audio/ogg
  • audio/flac
  • audio/mpeg
  • audio/m4a
  • audio/l16
  • audio/opus
  • audio/alaw
  • audio/mulaw
rate integer (optional)

Deprecated. Use sample_rate instead. The value is ignored.

sample_rate integer (optional)

The sample rate of the audio.

channels integer (optional)

The number of audio channels.

DocumentDelta

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "document" .

data string (optional)

هیچ توضیحی ارائه نشده است.

uri string (optional)

هیچ توضیحی ارائه نشده است.

mime_type enum (string) (optional)

هیچ توضیحی ارائه نشده است.

Possible values:

  • application/pdf
VideoDelta

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "video" .

data string (optional)

هیچ توضیحی ارائه نشده است.

uri string (optional)

هیچ توضیحی ارائه نشده است.

mime_type enum (string) (optional)

هیچ توضیحی ارائه نشده است.

Possible values:

  • video/mp4
  • video/mpeg
  • video/mpg
  • video/mov
  • video/avi
  • video/x-flv
  • video/webm
  • video/wmv
  • video/3gpp
resolution MediaResolution (optional)

The resolution of the media.

Possible values:

  • low
  • medium
  • high
  • ultra_high

ThoughtSummaryDelta

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "thought_summary" .

content ThoughtSummaryContent (optional)

A new summary item to be added to the thought.

Possible Types

Polymorphic discriminator: type

TextContent

A text content block.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "text" .

text string (required)

Required. The text content.

annotations Annotation (optional)

Citation information for model-generated content.

Citation information for model-generated content.

Possible Types

Polymorphic discriminator: type

UrlCitation

A URL citation annotation.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "url_citation" .

url string (optional)

The URL.

title string (optional)

The title of the URL.

start_index integer (optional)

Start of segment of the response that is attributed to this source. Index indicates the start of the segment, measured in bytes.

end_index integer (optional)

End of the attributed segment, exclusive.

FileCitation

A file citation annotation.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "file_citation" .

document_uri string (optional)

The URI of the file.

file_name string (optional)

The name of the file.

source string (optional)

Source attributed for a portion of the text.

custom_metadata object (optional)

User provided metadata about the retrieved context.

page_number integer (optional)

Page number of the cited document, if applicable.

media_id string (optional)

Media ID in-case of image citations, if applicable.

start_index integer (optional)

Start of segment of the response that is attributed to this source. Index indicates the start of the segment, measured in bytes.

end_index integer (optional)

End of the attributed segment, exclusive.

PlaceCitation

A place citation annotation.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "place_citation" .

place_id string (optional)

The ID of the place, in `places/{place_id}` format.

name string (optional)

Title of the place.

url string (optional)

URI reference of the place.

review_snippets ReviewSnippet (optional)

Snippets of reviews that are used to generate answers about the features of a given place in Google Maps.

Encapsulates a snippet of a user review that answers a question about the features of a specific place in Google Maps.

فیلدها

title string (optional)

Title of the review.

url string (optional)

A link that corresponds to the user review on Google Maps.

review_id string (optional)

The ID of the review snippet.

start_index integer (optional)

Start of segment of the response that is attributed to this source. Index indicates the start of the segment, measured in bytes.

end_index integer (optional)

End of the attributed segment, exclusive.

ImageContent

An image content block.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "image" .

data string (optional)

The image content.

uri string (optional)

The URI of the image.

mime_type enum (string) (optional)

The mime type of the image.

Possible values:

  • image/png
  • image/jpeg
  • image/webp
  • image/heic
  • image/heif
  • image/gif
  • image/bmp
  • image/tiff
resolution MediaResolution (optional)

The resolution of the media.

Possible values:

  • low
  • medium
  • high
  • ultra_high

ThoughtSignatureDelta

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "thought_signature" .

signature string (optional)

Signature to match the backend source to be part of the generation.

TextAnnotationDelta

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "text_annotation_delta" .

annotations Annotation (optional)

Citation information for model-generated content.

Citation information for model-generated content.

Possible Types

Polymorphic discriminator: type

UrlCitation

A URL citation annotation.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "url_citation" .

url string (optional)

The URL.

title string (optional)

The title of the URL.

start_index integer (optional)

Start of segment of the response that is attributed to this source. Index indicates the start of the segment, measured in bytes.

end_index integer (optional)

End of the attributed segment, exclusive.

FileCitation

A file citation annotation.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "file_citation" .

document_uri string (optional)

The URI of the file.

file_name string (optional)

The name of the file.

source string (optional)

Source attributed for a portion of the text.

custom_metadata object (optional)

User provided metadata about the retrieved context.

page_number integer (optional)

Page number of the cited document, if applicable.

media_id string (optional)

Media ID in-case of image citations, if applicable.

start_index integer (optional)

Start of segment of the response that is attributed to this source. Index indicates the start of the segment, measured in bytes.

end_index integer (optional)

End of the attributed segment, exclusive.

PlaceCitation

A place citation annotation.

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "place_citation" .

place_id string (optional)

The ID of the place, in `places/{place_id}` format.

name string (optional)

Title of the place.

url string (optional)

URI reference of the place.

review_snippets ReviewSnippet (optional)

Snippets of reviews that are used to generate answers about the features of a given place in Google Maps.

Encapsulates a snippet of a user review that answers a question about the features of a specific place in Google Maps.

فیلدها

title string (optional)

Title of the review.

url string (optional)

A link that corresponds to the user review on Google Maps.

review_id string (optional)

The ID of the review snippet.

start_index integer (optional)

Start of segment of the response that is attributed to this source. Index indicates the start of the segment, measured in bytes.

end_index integer (optional)

End of the attributed segment, exclusive.

ArgumentsDelta

type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "arguments_delta" .

partial_arguments string (optional)

هیچ توضیحی ارائه نشده است.

event_id string (optional)

The event_id token to be used to resume the interaction stream, from this event.

StepStop

event_type object (required)

هیچ توضیحی ارائه نشده است.

Always set to "step.stop" .

index integer (required)

هیچ توضیحی ارائه نشده است.

event_id string (optional)

The event_id token to be used to resume the interaction stream, from this event.

مثال‌ها

Interaction Created 

{
  "event_type": "interaction.created",
  "interaction": {
    "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
    "model": "gemini-3-flash-preview",
    "status": "in_progress",
    "created": "2025-12-04T15:01:45Z",
    "updated": "2025-12-04T15:01:45Z"
  },
  "event_id": "evt_123"
}

Interaction Completed 

{
  "event_type": "interaction.completed",
  "interaction": {
    "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
    "model": "gemini-3-flash-preview",
    "status": "completed",
    "created": "2025-12-04T15:01:45Z",
    "updated": "2025-12-04T15:01:45Z"
  },
  "event_id": "evt_123"
}

Interaction Status Update 

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

Error Event 

{
  "event_type": "error",
  "error": {
    "message": "Failed to get completed interaction: Result not found.",
    "code": "not_found"
  }
}

Step Start 

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

Step Delta 

{
  "event_type": "step.delta",
  "index": 0,
  "delta": {
    "type": "text",
    "text": "Hello"
  }
}

Step Stop 

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