Gemini Deep Research is now available in preview with collaborative planning, visualization, MCP support, and more.

Gemini API

The Gemini Interactions API is an experimental API that allows developers to build generative AI applications using Gemini models. Gemini is our most capable model, built from the ground up to be multimodal. It can generalize and seamlessly understand, operate across, and combine different types of information including language, images, audio, video, and code. You can use the Gemini API for use cases like reasoning across text and images, content generation, dialogue agents, summarization and classification systems, and more.

View as markdown View the OpenAPI Spec

Creating an interaction

post https://generativelanguage.googleapis.com/v1beta/interactions

Creates a new interaction.

Request body
Response

Request body

The request body contains data with the following structure:

model ModelOption (optional)

The name of the `Model` used for generating the interaction.
Required if `agent` is not provided.

Possible values:

gemini-2.5-computer-use-preview-10-2025
An agentic capability model designed for direct interface interaction, allowing Gemini to perceive and navigate digital environments.
gemini-2.5-flash
Our first hybrid reasoning model which supports a 1M token context window and has thinking budgets.
gemini-2.5-flash-image
Our native image generation model, optimized for speed, flexibility, and contextual understanding. Text input and output is priced the same as 2.5 Flash.
gemini-2.5-flash-lite
Our smallest and most cost effective model, built for at scale usage.
gemini-2.5-flash-lite-preview-09-2025
The latest model based on Gemini 2.5 Flash lite optimized for cost-efficiency, high throughput and high quality.
gemini-2.5-flash-native-audio-preview-12-2025
Our native audio models optimized for higher quality audio outputs with better pacing, voice naturalness, verbosity, and mood.
gemini-2.5-flash-preview-09-2025
The latest model based on the 2.5 Flash model. 2.5 Flash Preview is best for large scale processing, low-latency, high volume tasks that require thinking, and agentic use cases.
gemini-2.5-flash-preview-tts
Our 2.5 Flash text-to-speech model optimized for powerful, low-latency controllable speech generation.
gemini-2.5-pro
Our state-of-the-art multipurpose model, which excels at coding and complex reasoning tasks.
gemini-2.5-pro-preview-tts
Our 2.5 Pro text-to-speech audio model optimized for powerful, low-latency speech generation for more natural outputs and easier to steer prompts.
gemini-3-flash-preview
Our most intelligent model built for speed, combining frontier intelligence with superior search and grounding.
gemini-3-pro-image-preview
State-of-the-art image generation and editing model.
gemini-3-pro-preview
Our most intelligent model with SOTA reasoning and multimodal understanding, and powerful agentic and vibe coding capabilities.
gemini-3.1-pro-preview
Our latest SOTA reasoning model with unprecedented depth and nuance, and powerful multimodal understanding and coding capabilities.
gemini-3.1-flash-image-preview
Pro-level visual intelligence with Flash-speed efficiency and reality-grounded generation capabilities.
gemini-3.1-flash-lite-preview
Our most cost-efficient model, optimized for high-volume agentic tasks, translation, and simple data processing.
gemini-3.1-flash-tts-preview
Gemini 3.1 Flash TTS: Powerful, low-latency speech generation. Enjoy natural outputs, steerable prompts, and new expressive audio tags for precise narration control.
lyria-3-clip-preview
Our low-latency, music generation model optimized for high-fidelity audio clips and precise rhythmic control.
lyria-3-pro-preview
Our advanced, full-song generative model with deep compositional understanding, optimized for precise structural control and complex transitions across diverse musical styles.

agent AgentOption (optional)

The name of the `Agent` used for generating the interaction.
Required if `model` is not provided.

Possible values:

deep-research-pro-preview-12-2025
Gemini Deep Research Agent
deep-research-preview-04-2026
Gemini Deep Research Agent
deep-research-max-preview-04-2026
Gemini Deep Research Max Agent

input Content or array (Content) or array (Step) or string (required)

The inputs for the interaction (common to both Model and Agent).

system_instruction string (optional)

System instruction for the interaction.

tools array (Tool) (optional)

A list of tool declarations the model may call during interaction.

response_format ResponseFormat or ResponseFormatList (optional)

Enforces that the generated response is a JSON object that complies with the JSON schema specified in this field.

response_mime_type string (optional)

The mime type of the response. This is required if response_format is set.

stream boolean (optional)

Input only. Whether the interaction will be streamed.

store boolean (optional)

Input only. Whether to store the response and request for later retrieval.

background boolean (optional)

Input only. Whether to run the model interaction in the background.

generation_config GenerationConfig (optional)

Model Configuration
Configuration parameters for the model interaction.
Alternative to `agent_config`. Only applicable when `model` is set.

Fields

temperature number (optional)

Controls the randomness of the output.

top_p number (optional)

The maximum cumulative probability of tokens to consider when sampling.

seed integer (optional)

Seed used in decoding for reproducibility.

stop_sequences array (string) (optional)

A list of character sequences that will stop output interaction.

thinking_level ThinkingLevel (optional)

The level of thought tokens that the model should generate.

Possible values:

minimal
low
medium
high

thinking_summaries ThinkingSummaries (optional)

Whether to include thought summaries in the response.

Possible values:

auto
none

max_output_tokens integer (optional)

The maximum number of tokens to include in the response.

speech_config SpeechConfig (optional)

Configuration for speech interaction.

Fields

voice string (optional)

The voice of the speaker.

language string (optional)

The language of the speech.

speaker string (optional)

The speaker's name, it should match the speaker name given in the prompt.

image_config ImageConfig (optional)

Configuration for image interaction.

Fields

aspect_ratio enum (string) (optional)

No description provided.

Possible values:

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 enum (string) (optional)

No description provided.

Possible values:

1K
2K
4K
512

tool_choice ToolChoiceConfig or ToolChoiceType (optional)

The tool choice configuration.

agent_config object (optional)

Agent Configuration
Configuration for the agent.
Alternative to `generation_config`. Only applicable when `agent` is set.

Possible Types

Polymorphic discriminator: type

DynamicAgentConfig

Configuration for dynamic agents.

type object (required)

No description provided.

Always set to "dynamic".

DeepResearchAgentConfig

Configuration for the Deep Research agent.

type object (required)

No description provided.

Always set to "deep-research".

thinking_summaries ThinkingSummaries (optional)

Whether to include thought summaries in the response.

Possible values:

auto
none

visualization enum (string) (optional)

Whether to include visualizations in the response.

Possible values:

off
auto

collaborative_planning boolean (optional)

Enables human-in-the-loop planning for the Deep Research agent. If set to true, the Deep Research agent will provide a research plan in its response. The agent will then proceed only if the user confirms the plan in the next turn. .

previous_interaction_id string (optional)

The ID of the previous interaction, if any.

response_modalities ResponseModality (optional)

The requested modalities of the response (TEXT, IMAGE, AUDIO).

Possible values:

text
image
audio
video
document

service_tier enum (string) (optional)

The service tier for the interaction.

Possible values:

flex
standard
priority

webhook_config WebhookConfig (optional)

Optional. Webhook configuration for receiving notifications when the interaction completes.

Fields

uris array (string) (optional)

Optional. If set, these webhook URIs will be used for webhook events instead of the registered webhooks.

user_metadata object (optional)

Optional. The user metadata that will be returned on each event emission to the webhooks.

Response

Returns an Interaction resource.

Simple Request

Example Response

{
  "created": "2025-11-26T12:25:15Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3-flash-preview",
  "object": "interaction",
  "outputs": [
    {
      "text": "Hello! I'm functioning perfectly and ready to assist you.\n\nHow are you doing today?",
      "type": "text"
    }
  ],
  "role": "model",
  "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
  }
}

Multi-turn

Example Response

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3-flash-preview",
  "status": "completed",
  "object": "interaction",
  "created": "2025-11-26T12:22:47Z",
  "updated": "2025-11-26T12:22:47Z",
  "role": "model",
  "outputs": [
    {
      "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
  }
}

Image Input

Example Response

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3-flash-preview",
  "status": "completed",
  "object": "interaction",
  "created": "2025-11-26T12:22:47Z",
  "updated": "2025-11-26T12:22:47Z",
  "role": "model",
  "outputs": [
    {
      "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
  }
}

Function Calling

Example Response

{
  "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",
  "role": "model",
  "outputs": [
    {
      "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
  }
}

Deep Research

Example Response

{
  "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",
  "role": "agent",
  "outputs": [
    {
      "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
  }
}

Retrieving an interaction

get https://generativelanguage.googleapis.com/v1beta/interactions/{id}

Retrieves the full details of a single interaction based on its `Interaction.id`.

Path / Query parameters
Response

Path / Query Parameters

id string (required)

The unique identifier of the interaction to retrieve.

stream boolean (optional)

If set to true, the generated content will be streamed incrementally.

Defaults to: False

last_event_id string (optional)

Optional. If set, resumes the interaction stream from the next chunk after the event marked by the event id. Can only be used if `stream` is true.

include_input boolean (optional)

If set to true, includes the input in the response.

Defaults to: False

api_version string (optional)

Which version of the API to use.

Response

Returns an Interaction resource.

Get Interaction

Example Response

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

Deleting an interaction

delete https://generativelanguage.googleapis.com/v1beta/interactions/{id}

Deletes the interaction by id.

Path / Query parameters
Response

Path / Query Parameters

id string (required)

The unique identifier of the interaction to delete.

api_version string (optional)

Which version of the API to use.

Response

If successful, the response is empty.

Delete Interaction

Canceling an interaction

post https://generativelanguage.googleapis.com/v1beta/interactions/{id}/cancel

Cancels an interaction by id. This only applies to background interactions that are still running.

Path / Query parameters
Response

Path / Query Parameters

id string (required)

The unique identifier of the interaction to cancel.

api_version string (optional)

Which version of the API to use.

Response

Returns an Interaction resource.

Cancel Interaction

Example Response

{
  "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",
  "role": "agent"
}

CreateWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks

Creates a new Webhook.

Request body
Response

Request body

The request body contains data with the following structure:

name string (optional)

Optional. The user-provided name of the webhook.

uri string (required)

Required. The URI to which webhook events will be sent.

subscribed_events array (object or string) (required)

Required. The events that the webhook is subscribed to. Available events: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

Response

If successful, the response body contains data with the following structure:

name string (optional)

Optional. The user-provided name of the webhook.

uri string (optional)

Required. The URI to which webhook events will be sent.

subscribed_events array (object or string) (optional)

create_time string (optional)

Output only. The timestamp when the webhook was created.

update_time string (optional)

Output only. The timestamp when the webhook was last updated.

signing_secrets SigningSecret (optional)

Output only. The signing secrets associated with this webhook.

Fields

truncated_secret string (optional)

Output only. The truncated version of the signing secret.

expire_time string (optional)

Output only. The expiration date of the signing secret.

state enum (string) (optional)

Output only. The state of the webhook.

Possible values:

enabled
disabled
disabled_due_to_failed_deliveries

new_signing_secret string (optional)

Output only. The new signing secret for the webhook. Only populated on create.

id string (optional)

Output only. The ID of the webhook.

Example

Example Response

{
  "name": "string",
  "uri": "string",
  "subscribed_events": [
    "string"
  ],
  "create_time": "string",
  "update_time": "string",
  "signing_secrets": [
    {
      "truncated_secret": "string",
      "expire_time": "string"
    }
  ],
  "state": "enabled",
  "new_signing_secret": "string",
  "id": "string"
}

ListWebhooks

get https://generativelanguage.googleapis.com/v1beta/webhooks

Lists all Webhooks.

Path / Query parameters
Response

Path / Query Parameters

page_size integer (optional)

Optional. The maximum number of webhooks to return. The service may return fewer than this value. If unspecified, at most 50 webhooks will be returned. The maximum value is 1000.

page_token string (optional)

Optional. A page token, received from a previous `ListWebhooks` call. Provide this to retrieve the subsequent page.

Response

If successful, the response body contains data with the following structure:

webhooks Webhook (optional)

The webhooks.

Fields

name string (optional)

Optional. The user-provided name of the webhook.

uri string (optional)

Required. The URI to which webhook events will be sent.

subscribed_events array (object or string) (optional)

create_time string (optional)

Output only. The timestamp when the webhook was created.

update_time string (optional)

Output only. The timestamp when the webhook was last updated.

signing_secrets SigningSecret (optional)

Output only. The signing secrets associated with this webhook.

Fields

truncated_secret string (optional)

Output only. The truncated version of the signing secret.

expire_time string (optional)

Output only. The expiration date of the signing secret.

state enum (string) (optional)

Output only. The state of the webhook.

Possible values:

enabled
disabled
disabled_due_to_failed_deliveries

new_signing_secret string (optional)

Output only. The new signing secret for the webhook. Only populated on create.

id string (optional)

Output only. The ID of the webhook.

next_page_token string (optional)

A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.

Example

Example Response

{
  "webhooks": [
    {
      "name": "string",
      "uri": "string",
      "subscribed_events": [
        "string"
      ],
      "create_time": "string",
      "update_time": "string",
      "signing_secrets": [
        {
          "truncated_secret": "string",
          "expire_time": "string"
        }
      ],
      "state": "enabled",
      "new_signing_secret": "string",
      "id": "string"
    }
  ],
  "next_page_token": "string"
}

GetWebhook

get https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

Gets a specific Webhook.

Path / Query parameters
Response

Path / Query Parameters

id string (required)

Required. The ID of the webhook to retrieve.

Response

If successful, the response body contains data with the following structure:

name string (optional)

Optional. The user-provided name of the webhook.

uri string (optional)

Required. The URI to which webhook events will be sent.

subscribed_events array (object or string) (optional)

create_time string (optional)

Output only. The timestamp when the webhook was created.

update_time string (optional)

Output only. The timestamp when the webhook was last updated.

signing_secrets SigningSecret (optional)

Output only. The signing secrets associated with this webhook.

Fields

truncated_secret string (optional)

Output only. The truncated version of the signing secret.

expire_time string (optional)

Output only. The expiration date of the signing secret.

state enum (string) (optional)

Output only. The state of the webhook.

Possible values:

enabled
disabled
disabled_due_to_failed_deliveries

new_signing_secret string (optional)

Output only. The new signing secret for the webhook. Only populated on create.

id string (optional)

Output only. The ID of the webhook.

Example

Example Response

{
  "name": "string",
  "uri": "string",
  "subscribed_events": [
    "string"
  ],
  "create_time": "string",
  "update_time": "string",
  "signing_secrets": [
    {
      "truncated_secret": "string",
      "expire_time": "string"
    }
  ],
  "state": "enabled",
  "new_signing_secret": "string",
  "id": "string"
}

UpdateWebhook

patch https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

Updates an existing Webhook.

Path / Query parameters
Request body
Response

Path / Query Parameters

id string (required)

Required. The ID of the webhook to update.

update_mask string (optional)

Optional. The list of fields to update.

Request body

The request body contains data with the following structure:

name string (optional)

Optional. The user-provided name of the webhook.

uri string (optional)

Optional. The URI to which webhook events will be sent.

subscribed_events array (object or string) (optional)

Optional. The events that the webhook is subscribed to. Available events: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

state enum (string) (optional)

Optional. The state of the webhook.

Possible values:

enabled
disabled
disabled_due_to_failed_deliveries

Response

If successful, the response body contains data with the following structure:

name string (optional)

Optional. The user-provided name of the webhook.

uri string (optional)

Required. The URI to which webhook events will be sent.

subscribed_events array (object or string) (optional)

create_time string (optional)

Output only. The timestamp when the webhook was created.

update_time string (optional)

Output only. The timestamp when the webhook was last updated.

signing_secrets SigningSecret (optional)

Output only. The signing secrets associated with this webhook.

Fields

truncated_secret string (optional)

Output only. The truncated version of the signing secret.

expire_time string (optional)

Output only. The expiration date of the signing secret.

state enum (string) (optional)

Output only. The state of the webhook.

Possible values:

enabled
disabled
disabled_due_to_failed_deliveries

new_signing_secret string (optional)

Output only. The new signing secret for the webhook. Only populated on create.

id string (optional)

Output only. The ID of the webhook.

Example

Example Response

{
  "name": "string",
  "uri": "string",
  "subscribed_events": [
    "string"
  ],
  "create_time": "string",
  "update_time": "string",
  "signing_secrets": [
    {
      "truncated_secret": "string",
      "expire_time": "string"
    }
  ],
  "state": "enabled",
  "new_signing_secret": "string",
  "id": "string"
}

DeleteWebhook

delete https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

Deletes a Webhook.

Path / Query parameters
Response

Path / Query Parameters

id string (required)

Required. The ID of the webhook to delete. Format: `{webhook_id}`

Response

If successful, the response is empty.

Example

RotateSigningSecret

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:rotateSigningSecret

Generates a new signing secret for a Webhook.

Path / Query parameters
Request body
Response

Path / Query Parameters

id string (required)

Required. The ID of the webhook for which to generate a signing secret. Format: `{webhook_id}`

Request body

The request body contains data with the following structure:

revocation_behavior enum (string) (optional)

Optional. The revocation behavior for previous signing secrets.

Possible values:

revoke_previous_secrets_after_h24
revoke_previous_secrets_immediately

Response

If successful, the response body contains data with the following structure:

secret string (optional)

Output only. The newly generated signing secret.

Example

Example Response

{
  "secret": "string"
}

PingWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:ping

Sends a ping event to a Webhook.

Path / Query parameters
Request body
Response

Path / Query Parameters

id string (required)

Required. The ID of the webhook to ping. Format: `{webhook_id}`

Request body

The request body contains data with the following structure:

Response

If successful, the response is empty.

Example

Resources

Interaction

The Interaction resource.

Fields

model ModelOption (optional)

The name of the `Model` used for generating the interaction.

Possible values:

gemini-2.5-computer-use-preview-10-2025
An agentic capability model designed for direct interface interaction, allowing Gemini to perceive and navigate digital environments.
gemini-2.5-flash
Our first hybrid reasoning model which supports a 1M token context window and has thinking budgets.
gemini-2.5-flash-image
Our native image generation model, optimized for speed, flexibility, and contextual understanding. Text input and output is priced the same as 2.5 Flash.
gemini-2.5-flash-lite
Our smallest and most cost effective model, built for at scale usage.
gemini-2.5-flash-lite-preview-09-2025
The latest model based on Gemini 2.5 Flash lite optimized for cost-efficiency, high throughput and high quality.
gemini-2.5-flash-native-audio-preview-12-2025
Our native audio models optimized for higher quality audio outputs with better pacing, voice naturalness, verbosity, and mood.
gemini-2.5-flash-preview-09-2025
The latest model based on the 2.5 Flash model. 2.5 Flash Preview is best for large scale processing, low-latency, high volume tasks that require thinking, and agentic use cases.
gemini-2.5-flash-preview-tts
Our 2.5 Flash text-to-speech model optimized for powerful, low-latency controllable speech generation.
gemini-2.5-pro
Our state-of-the-art multipurpose model, which excels at coding and complex reasoning tasks.
gemini-2.5-pro-preview-tts
Our 2.5 Pro text-to-speech audio model optimized for powerful, low-latency speech generation for more natural outputs and easier to steer prompts.
gemini-3-flash-preview
Our most intelligent model built for speed, combining frontier intelligence with superior search and grounding.
gemini-3-pro-image-preview
State-of-the-art image generation and editing model.
gemini-3-pro-preview
Our most intelligent model with SOTA reasoning and multimodal understanding, and powerful agentic and vibe coding capabilities.
gemini-3.1-pro-preview
Our latest SOTA reasoning model with unprecedented depth and nuance, and powerful multimodal understanding and coding capabilities.
gemini-3.1-flash-image-preview
Pro-level visual intelligence with Flash-speed efficiency and reality-grounded generation capabilities.
gemini-3.1-flash-lite-preview
Our most cost-efficient model, optimized for high-volume agentic tasks, translation, and simple data processing.
gemini-3.1-flash-tts-preview
Gemini 3.1 Flash TTS: Powerful, low-latency speech generation. Enjoy natural outputs, steerable prompts, and new expressive audio tags for precise narration control.
lyria-3-clip-preview
Our low-latency, music generation model optimized for high-fidelity audio clips and precise rhythmic control.
lyria-3-pro-preview
Our advanced, full-song generative model with deep compositional understanding, optimized for precise structural control and complex transitions across diverse musical styles.

agent AgentOption (optional)

The name of the `Agent` used for generating the interaction.

Possible values:

deep-research-pro-preview-12-2025
Gemini Deep Research Agent
deep-research-preview-04-2026
Gemini Deep Research Agent
deep-research-max-preview-04-2026
Gemini Deep Research Max Agent

id string (optional)

Required. Output only. A unique identifier for the interaction completion.

status enum (string) (optional)

Required. Output only. The status of the interaction.

Possible values:

in_progress
requires_action
completed
failed
cancelled
incomplete

created string (optional)

Required. Output only. The time at which the response was created in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

updated string (optional)

Required. Output only. The time at which the response was last updated in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

role string (optional)

Output only. The role of the interaction.

system_instruction string (optional)

System instruction for the interaction.

tools array (Tool) (optional)

A list of tool declarations the model may call during interaction.

usage Usage (optional)

Output only. Statistics on the interaction request's token usage.

Fields

total_input_tokens integer (optional)

Number of tokens in the prompt (context).

input_tokens_by_modality ModalityTokens (optional)

A breakdown of input token usage by modality.

Fields

modality ResponseModality (optional)

The modality associated with the token count.

Possible values:

text
image
audio
video
document

tokens integer (optional)

Number of tokens for the modality.

total_cached_tokens integer (optional)

Number of tokens in the cached part of the prompt (the cached content).

cached_tokens_by_modality ModalityTokens (optional)

A breakdown of cached token usage by modality.

Fields

modality ResponseModality (optional)

The modality associated with the token count.

Possible values:

text
image
audio
video
document

tokens integer (optional)

Number of tokens for the modality.

total_output_tokens integer (optional)

Total number of tokens across all the generated responses.

output_tokens_by_modality ModalityTokens (optional)

A breakdown of output token usage by modality.

Fields

modality ResponseModality (optional)

The modality associated with the token count.

Possible values:

text
image
audio
video
document

tokens integer (optional)

Number of tokens for the modality.

total_tool_use_tokens integer (optional)

Number of tokens present in tool-use prompt(s).

tool_use_tokens_by_modality ModalityTokens (optional)

A breakdown of tool-use token usage by modality.

Fields

modality ResponseModality (optional)

The modality associated with the token count.

Possible values:

text
image
audio
video
document

tokens integer (optional)

Number of tokens for the modality.

total_thought_tokens integer (optional)

Number of tokens of thoughts for thinking models.

total_tokens integer (optional)

Total token count for the interaction request (prompt + responses + other internal tokens).

grounding_tool_count GroundingToolCount (optional)

Grounding tool count.

Fields

type enum (string) (optional)

The grounding tool type associated with the count.

Possible values:

google_search
google_maps
retrieval

count integer (optional)

The number of grounding tool counts.

response_modalities ResponseModality (optional)

The requested modalities of the response (TEXT, IMAGE, AUDIO).

Possible values:

text
image
audio
video
document

response_mime_type string (optional)

The mime type of the response. This is required if response_format is set.

previous_interaction_id string (optional)

The ID of the previous interaction, if any.

service_tier enum (string) (optional)

The service tier for the interaction.

Possible values:

flex
standard
priority

webhook_config WebhookConfig (optional)

Optional. Webhook configuration for receiving notifications when the interaction completes.

Fields

uris array (string) (optional)

Optional. If set, these webhook URIs will be used for webhook events instead of the registered webhooks.

user_metadata object (optional)

Optional. The user metadata that will be returned on each event emission to the webhooks.

steps Step (optional)

Output only. The steps that make up the interaction.

Possible Types

Polymorphic discriminator: type

UserInputStep

Input provided by the user.

type object (required)

No description provided.

Always set to "user_input".

content array (Content) (optional)

No description provided.

ModelOutputStep

Output generated by the model.

type object (required)

No description provided.

Always set to "model_output".

content array (Content) (optional)

No description provided.

ThoughtStep

A thought step.

type object (required)

No description provided.

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)

No description provided.

Always set to "text".

text string (required)

Required. The text content.

annotations Annotation (optional)

Citation information for model-generated content.

Possible Types

Polymorphic discriminator: type

UrlCitation

A URL citation annotation.

type object (required)

No description provided.

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)

No description provided.

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)

No description provided.

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.

Fields

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)

No description provided.

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)

No description provided.

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)

No description provided.

Always set to "code_execution_call".

arguments CodeExecutionCallStepArguments (required)

Required. The arguments to pass to the code execution.

Fields

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)

No description provided.

Always set to "url_context_call".

arguments UrlContextCallStepArguments (required)

Required. The arguments to pass to the URL context.

Fields

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)

No description provided.

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)

No description provided.

Always set to "google_search_call".

arguments GoogleSearchCallStepArguments (required)

Required. The arguments to pass to Google Search.

Fields

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)

No description provided.

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)

No description provided.

Always set to "google_maps_call".

arguments GoogleMapsCallStepArguments (optional)

The arguments to pass to the Google Maps tool.

Fields

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)

No description provided.

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)

No description provided.

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)

No description provided.

Always set to "url_context_result".

result UrlContextResultItem (required)

Required. The results of the URL context.

Fields

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)

No description provided.

Always set to "google_search_result".

result GoogleSearchResultItem (required)

Required. The results of the Google Search.

Fields

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)

No description provided.

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)

No description provided.

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)

No description provided.

Always set to "google_maps_result".

result GoogleMapsResultItem (required)

No description provided.

Fields

places GoogleMapsResultPlaces (optional)

No description provided.

Fields

place_id string (optional)

No description provided.

name string (optional)

No description provided.

url string (optional)

No description provided.

review_snippets ReviewSnippet (optional)

No description provided.

Fields

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)

No description provided.

call_id string (required)

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

signature string (optional)

A signature hash for backend validation.

input Content or array (Content) or array (Step) or string (optional)

The input for the interaction.

response_format ResponseFormat or ResponseFormatList (optional)

Enforces that the generated response is a JSON object that complies with the JSON schema specified in this field.

agent_config object (optional)

Configuration parameters for the agent interaction.

Possible Types

Polymorphic discriminator: type

DynamicAgentConfig

Configuration for dynamic agents.

type object (required)

No description provided.

Always set to "dynamic".

DeepResearchAgentConfig

Configuration for the Deep Research agent.

type object (required)

No description provided.

Always set to "deep-research".

thinking_summaries ThinkingSummaries (optional)

Whether to include thought summaries in the response.

Possible values:

auto
none

visualization enum (string) (optional)

Whether to include visualizations in the response.

Possible values:

off
auto

collaborative_planning boolean (optional)

Examples

Example

{
  "created": "2025-12-04T15:01:45Z",
  "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
  "model": "gemini-3-flash-preview",
  "object": "interaction",
  "outputs": [
    {
      "text": "Hello! I'm doing well, functioning as expected. Thank you for asking! How are you doing today?",
      "type": "text"
    }
  ],
  "role": "model",
  "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
  }
}

Data Models

Content

The content of the response.

Possible Types

Polymorphic discriminator: type

TextContent

A text content block.

type object (required)

No description provided.

Always set to "text".

text string (required)

Required. The text content.

annotations Annotation (optional)

Citation information for model-generated content.

Possible Types

Polymorphic discriminator: type

UrlCitation

A URL citation annotation.

type object (required)

No description provided.

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)

No description provided.

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)

No description provided.

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.

Fields

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)

No description provided.

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

AudioContent

An audio content block.

type object (required)

No description provided.

Always set to "audio".

data string (optional)

The audio content.

uri string (optional)

The URI of the audio.

mime_type enum (string) (optional)

The mime type of the audio.

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

channels integer (optional)

The number of audio channels.

sample_rate integer (optional)

The sample rate of the audio.

DocumentContent

A document content block.

type object (required)

No description provided.

Always set to "document".

data string (optional)

The document content.

uri string (optional)

The URI of the document.

mime_type enum (string) (optional)

The mime type of the document.

Possible values:

application/pdf

VideoContent

A video content block.

type object (required)

No description provided.

Always set to "video".

data string (optional)

The video content.

uri string (optional)

The URI of the video.

mime_type enum (string) (optional)

The mime type of the video.

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

Examples

Text

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

Image

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

Audio

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

Document

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

Video

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

Tool

A tool that can be used by the model.

Possible Types

Polymorphic discriminator: type

Function

A tool that can be used by the model.

type object (required)

No description provided.

Always set to "function".

name string (optional)

The name of the function.

description string (optional)

A description of the function.

parameters object (optional)

The JSON Schema for the function's parameters.

CodeExecution

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

type object (required)

No description provided.

Always set to "code_execution".

UrlContext

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

type object (required)

No description provided.

Always set to "url_context".

ComputerUse

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

type object (required)

No description provided.

Always set to "computer_use".

environment enum (string) (optional)

The environment being operated.

Possible values:

browser

excludedPredefinedFunctions 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)

No description provided.

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.

Fields

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)

No description provided.

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)

No description provided.

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)

No description provided.

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)

No description provided.

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.

Fields

engine string (optional)

Optional. Used to specify Vertex AI Search engine.

datastores array (string) (optional)

Optional. Used to specify Vertex AI Search datastores.

Examples

Function

CodeExecution

UrlContext

ComputerUse

McpServer

GoogleSearch

FileSearch

GoogleMaps

Retrieval

No examples available for this type.

Turn

Fields

role string (optional)

The originator of this turn. Must be user for input or model for model output.

content array (Content) or string (optional)

No description provided.

Examples

User Turn

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "user turn"
    }
  ]
}

Model Turn

{
  "role": "model",
  "content": [
    {
      "type": "text",
      "text": "model turn"
    }
  ]
}

InteractionSseEvent

Possible Types

Polymorphic discriminator: event_type

InteractionCreatedEvent

event_type object (required)

No description provided.

Always set to "interaction.created".

interaction Interaction (required)

No description provided.

event_id string (optional)

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

InteractionCompletedEvent

event_type object (required)

No description provided.

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)

No description provided.

Always set to "interaction.status_update".

interaction_id string (required)

No description provided.

status enum (string) (required)

No description provided.

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)

No description provided.

Always set to "error".

error Error (optional)

No description provided.

Fields

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)

No description provided.

Always set to "step.start".

index integer (required)

No description provided.

step Step (required)

No description provided.

Possible Types

Polymorphic discriminator: type

UserInputStep

Input provided by the user.

type object (required)

No description provided.

Always set to "user_input".

content array (Content) (optional)

No description provided.

ModelOutputStep

Output generated by the model.

type object (required)

No description provided.

Always set to "model_output".

content array (Content) (optional)

No description provided.

ThoughtStep

A thought step.

type object (required)

No description provided.

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)

No description provided.

Always set to "text".

text string (required)

Required. The text content.

annotations Annotation (optional)

Citation information for model-generated content.

Possible Types

Polymorphic discriminator: type

UrlCitation

A URL citation annotation.

type object (required)

No description provided.

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)

No description provided.

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)

No description provided.

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.

Fields

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)

No description provided.

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)

No description provided.

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)

No description provided.

Always set to "code_execution_call".

arguments CodeExecutionCallStepArguments (required)

Required. The arguments to pass to the code execution.

Fields

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)

No description provided.

Always set to "url_context_call".

arguments UrlContextCallStepArguments (required)

Required. The arguments to pass to the URL context.

Fields

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)

No description provided.

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)

No description provided.

Always set to "google_search_call".

arguments GoogleSearchCallStepArguments (required)

Required. The arguments to pass to Google Search.

Fields

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)

No description provided.

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)

No description provided.

Always set to "google_maps_call".

arguments GoogleMapsCallStepArguments (optional)

The arguments to pass to the Google Maps tool.

Fields

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)

No description provided.

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)

No description provided.

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)

No description provided.

Always set to "url_context_result".

result UrlContextResultItem (required)

Required. The results of the URL context.

Fields

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)

No description provided.

Always set to "google_search_result".

result GoogleSearchResultItem (required)

Required. The results of the Google Search.

Fields

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)

No description provided.

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)

No description provided.

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)

No description provided.

Always set to "google_maps_result".

result GoogleMapsResultItem (required)

No description provided.

Fields

places GoogleMapsResultPlaces (optional)

No description provided.

Fields

place_id string (optional)

No description provided.

name string (optional)

No description provided.

url string (optional)

No description provided.

review_snippets ReviewSnippet (optional)

No description provided.

Fields

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)

No description provided.

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)

No description provided.

Always set to "step.delta".

index integer (required)

No description provided.

delta StepDeltaData (required)

No description provided.

Possible Types

Polymorphic discriminator: type

TextDelta

type object (required)

No description provided.

Always set to "text".

text string (required)

No description provided.

ImageDelta

type object (required)

No description provided.

Always set to "image".

data string (optional)

No description provided.

uri string (optional)

No description provided.

mime_type enum (string) (optional)

No description provided.

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)

No description provided.

Always set to "audio".

data string (optional)

No description provided.

uri string (optional)

No description provided.

mime_type enum (string) (optional)

No description provided.

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)

No description provided.

Always set to "document".

data string (optional)

No description provided.

uri string (optional)

No description provided.

mime_type enum (string) (optional)

No description provided.

Possible values:

application/pdf

VideoDelta

type object (required)

No description provided.

Always set to "video".

data string (optional)

No description provided.

uri string (optional)

No description provided.

mime_type enum (string) (optional)

No description provided.

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)

No description provided.

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)

No description provided.

Always set to "text".

text string (required)

Required. The text content.

annotations Annotation (optional)

Citation information for model-generated content.

Possible Types

Polymorphic discriminator: type

UrlCitation

A URL citation annotation.

type object (required)

No description provided.

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)

No description provided.

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)

No description provided.

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.

Fields

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)

No description provided.

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)

No description provided.

Always set to "thought_signature".

signature string (optional)

Signature to match the backend source to be part of the generation.

TextAnnotationDelta

type object (required)

No description provided.

Always set to "text_annotation_delta".

annotations Annotation (optional)

Citation information for model-generated content.

Possible Types

Polymorphic discriminator: type

UrlCitation

A URL citation annotation.

type object (required)

No description provided.

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)

No description provided.

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)

No description provided.

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.

Fields

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)

No description provided.

Always set to "arguments_delta".

partial_arguments string (optional)

No description provided.

event_id string (optional)

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

StepStop

event_type object (required)

No description provided.

Always set to "step.stop".

index integer (required)

No description provided.

event_id string (optional)

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

Examples

InteractionCreatedEvent

No examples available for this type.

InteractionCompletedEvent

No examples available for this type.

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"
  }
}

StepStart

No examples available for this type.

StepDelta

No examples available for this type.

StepStop

No examples available for this type.