# 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.
## Default
### Creating an interaction
`POST https://generativelanguage.googleapis.com/v1beta/interactions`
Creates a new interaction.
#### Request Body
- **model** (`ModelOption`) 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`) 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`) System instruction for the interaction.
- **tools** (`array (Tool)`) A list of tool declarations the model may call during interaction.
- **response_format** (`ResponseFormat or ResponseFormatList`) Enforces that the generated response is a JSON object that complies with the JSON schema specified in this field.
- **response_mime_type** (`string`) The mime type of the response. This is required if response_format is set.
- **stream** (`boolean`) Input only. Whether the interaction will be streamed.
- **store** (`boolean`) Input only. Whether to store the response and request for later retrieval.
- **background** (`boolean`) Input only. Whether to run the model interaction in the background.
- **generation_config** (`GenerationConfig`) Model Configuration
Configuration parameters for the model interaction.
Alternative to `agent_config`. Only applicable when `model` is set.
- **temperature** (`number`) Controls the randomness of the output.
- **top_p** (`number`) The maximum cumulative probability of tokens to consider when sampling.
- **seed** (`integer`) Seed used in decoding for reproducibility.
- **stop_sequences** (`array (string)`) A list of character sequences that will stop output interaction.
- **thinking_level** (`ThinkingLevel`) The level of thought tokens that the model should generate.
Possible values:
- `minimal` - `low` - `medium` - `high`
- **thinking_summaries** (`ThinkingSummaries`) Whether to include thought summaries in the response.
Possible values:
- `auto` - `none`
- **max_output_tokens** (`integer`) The maximum number of tokens to include in the response.
- **speech_config** (`array (SpeechConfig)`) Configuration for speech interaction.
- **voice** (`string`) The voice of the speaker.
- **language** (`string`) The language of the speech.
- **speaker** (`string`) The speaker's name, it should match the speaker name given in the prompt.
- **image_config** (`ImageConfig`) Configuration for image interaction.
- **aspect_ratio** (`enum (string)`)
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)`)
Possible values:
- `1K` - `2K` - `4K` - `512`
- **tool_choice** (`ToolChoiceConfig or ToolChoiceType`) The tool choice configuration.
- **agent_config** (`DeepResearchAgentConfig or DynamicAgentConfig`) Agent Configuration
Configuration for the agent.
Alternative to `generation_config`. Only applicable when `agent` is set.
**Possible Types:** (Discriminator: `type`) - **DynamicAgentConfig**: Configuration for dynamic agents.
- **type** (`object`) *(Required)*
Value: `dynamic`
- **DeepResearchAgentConfig**: Configuration for the Deep Research agent.
- **type** (`object`) *(Required)*
Value: `deep-research`
- **thinking_summaries** (`ThinkingSummaries`) Whether to include thought summaries in the response.
Possible values:
- `auto` - `none`
- **visualization** (`enum (string)`) Whether to include visualizations in the response.
Possible values:
- `off` - `auto`
- **collaborative_planning** (`boolean`) 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`) The ID of the previous interaction, if any.
- **response_modalities** (`array (ResponseModality)`) The requested modalities of the response (TEXT, IMAGE, AUDIO).
Possible values:
- `text` - `image` - `audio` - `video` - `document`
- **service_tier** (`enum (string)`) The service tier for the interaction.
Possible values:
- `flex` - `standard` - `priority`
- **webhook_config** (`WebhookConfig`) Optional. Webhook configuration for receiving notifications when the interaction completes.
- **uris** (`array (string)`) Optional. If set, these webhook URIs will be used for webhook events instead of the registered webhooks.
- **user_metadata** (`object`) Optional. The user metadata that will be returned on each event emission to the webhooks.
#### Response
Returns [Interaction](#interaction) resources.
#### Examples
**Simple Request**
**REST**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"input": "Hello, how are you?"
}'
```
**Python**
```python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Hello, how are you?",
)
print(interaction.outputs[-1].text)
```
**JavaScript**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Hello, how are you?',
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
```
Response:
```json
{
"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**
**REST**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"input": [
{
"role": "user",
"content": "Hello!"
},
{
"role": "model",
"content": "Hi there! How can I help you today?"
},
{
"role": "user",
"content": "What is the capital of France?"
}
]
}'
```
**Python**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{ "role": "user", "content": "Hello!" },
{ "role": "model", "content": "Hi there! How can I help you today?" },
{ "role": "user", "content": "What is the capital of France?" }
]
)
print(response.outputs[-1].text)
```
**JavaScript**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
input: [
{ role: 'user', content: 'Hello' },
{ role: 'model', content: 'Hi there! How can I help you today?' },
{ role: 'user', content: 'What is the capital of France?' }
]
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
```
Response:
```json
{
"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**
**REST**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"input": [
{
"type": "text",
"text": "What is in this picture?"
},
{
"type": "image",
"data": "BASE64_ENCODED_IMAGE",
"mime_type": "image/png"
}
]
}'
```
**Python**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{ "type": "text", "text": "What is in this picture?" },
{ "type": "image", "data": "BASE64_ENCODED_IMAGE", "mime_type": "image/png" }
]
)
print(response.outputs[-1].text)
```
**JavaScript**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
input: [
{ type: 'text', text: 'What is in this picture?' },
{ type: 'image', data: 'BASE64_ENCODED_IMAGE', mime_type: 'image/png' }
]
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
```
Response:
```json
{
"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**
**REST**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"tools": [
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": [
"location"
]
}
}
],
"input": "What is the weather like in Boston, MA?"
}'
```
**Python**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-3-flash-preview",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"]
}
}],
input="What is the weather like in Boston, MA?"
)
print(response.outputs[0])
```
**JavaScript**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
tools: [{
type: 'function',
name: 'get_weather',
description: 'Get the current weather in a given location',
parameters: {
type: 'object',
properties: {
location: {
type: 'string',
description: 'The city and state, e.g. San Francisco, CA'
}
},
required: ['location']
}
}],
input: 'What is the weather like in Boston, MA?'
});
console.log(interaction.outputs[0]);
```
Response:
```json
{
"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**
**REST**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": "deep-research-pro-preview-12-2025",
"input": "Find a cure to cancer",
"background": true
}'
```
**Python**
```python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
agent="deep-research-pro-preview-12-2025",
input="find a cure to cancer",
background=True,
)
print(interaction.status)
```
**JavaScript**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
agent: 'deep-research-pro-preview-12-2025',
input: 'find a cure to cancer',
background: true,
});
console.log(interaction.status);
```
Response:
```json
{
"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`.
#### Parameters
- **id** (`string`) *(Required)* The unique identifier of the interaction to retrieve.
- **stream** (`boolean`) If set to true, the generated content will be streamed incrementally.
Default: `False`
- **last_event_id** (`string`) 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`) If set to true, includes the input in the response.
Default: `False`
- **api_version** (`string`) Which version of the API to use.
#### Response
Returns [Interaction](#interaction) resources.
#### Examples
**Get Interaction**
**REST**
```sh
curl -X GET https://generativelanguage.googleapis.com/v1beta/interactions/v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
**Python**
```python
from google import genai
client = genai.Client()
interaction = client.interactions.get(id="v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg")
print(interaction.status)
```
**JavaScript**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.get('v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg');
console.log(interaction.status);
```
Response:
```json
{
"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.
#### Parameters
- **id** (`string`) *(Required)* The unique identifier of the interaction to delete.
- **api_version** (`string`) Which version of the API to use.
#### Response
#### Examples
**Delete Interaction**
**REST**
```sh
curl -X DELETE https://generativelanguage.googleapis.com/v1beta/interactions/v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
**Python**
```python
from google import genai
client = genai.Client()
client.interactions.delete(id="v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg")
print("Interaction deleted successfully.")
```
**JavaScript**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
await ai.interactions.delete('v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg');
console.log('Interaction deleted successfully.');
```
---
### 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.
#### Parameters
- **id** (`string`) *(Required)* The unique identifier of the interaction to cancel.
- **api_version** (`string`) Which version of the API to use.
#### Response
Returns [Interaction](#interaction) resources.
#### Examples
**Cancel Interaction**
**REST**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions/v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg/cancel \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
**Python**
```python
from google import genai
client = genai.Client()
interaction = client.interactions.cancel(id="v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg")
print(interaction.status)
```
**JavaScript**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.cancel('v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg');
console.log(interaction.status);
```
Response:
```json
{
"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
- **name** (`string`) 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
- **name** (`string`) Optional. The user-provided name of the webhook.
- **uri** (`string`) Required. The URI to which webhook events will be sent.
- **subscribed_events** (`array (object or string)`) 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
- **create_time** (`string`) Output only. The timestamp when the webhook was created.
- **update_time** (`string`) Output only. The timestamp when the webhook was last updated.
- **signing_secrets** (`array (SigningSecret)`) Output only. The signing secrets associated with this webhook.
- **truncated_secret** (`string`) Output only. The truncated version of the signing secret.
- **expire_time** (`string`) Output only. The expiration date of the signing secret.
- **state** (`enum (string)`) Output only. The state of the webhook.
Possible values:
- `enabled` - `disabled` - `disabled_due_to_failed_deliveries`
- **new_signing_secret** (`string`) Output only. The new signing secret for the webhook. Only populated on create.
- **id** (`string`) Output only. The ID of the webhook.
#### Examples
**Example**
**REST**
```sh
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/webhooks' \
-H 'Content-Type: application/json' \
-d '{
"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"
}'
```
Response:
```json
{
"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.
#### Parameters
- **page_size** (`integer`) 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. A page token, received from a previous `ListWebhooks` call. Provide this to retrieve the subsequent page.
#### Response
- **webhooks** (`array (Webhook)`) The webhooks.
- **name** (`string`) 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
- **create_time** (`string`) Output only. The timestamp when the webhook was created.
- **update_time** (`string`) Output only. The timestamp when the webhook was last updated.
- **signing_secrets** (`array (SigningSecret)`) Output only. The signing secrets associated with this webhook.
- **truncated_secret** (`string`) Output only. The truncated version of the signing secret.
- **expire_time** (`string`) Output only. The expiration date of the signing secret.
- **state** (`enum (string)`) Output only. The state of the webhook.
Possible values:
- `enabled` - `disabled` - `disabled_due_to_failed_deliveries`
- **new_signing_secret** (`string`) Output only. The new signing secret for the webhook. Only populated on create.
- **id** (`string`) Output only. The ID of the webhook.
- **next_page_token** (`string`) A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.
#### Examples
**Example**
**REST**
```sh
curl -X GET 'https://generativelanguage.googleapis.com/v1beta/webhooks' \
-H 'Content-Type: application/json' \
```
Response:
```json
{
"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.
#### Parameters
- **id** (`string`) *(Required)* Required. The ID of the webhook to retrieve.
#### Response
- **name** (`string`) Optional. The user-provided name of the webhook.
- **uri** (`string`) Required. The URI to which webhook events will be sent.
- **subscribed_events** (`array (object or string)`) 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
- **create_time** (`string`) Output only. The timestamp when the webhook was created.
- **update_time** (`string`) Output only. The timestamp when the webhook was last updated.
- **signing_secrets** (`array (SigningSecret)`) Output only. The signing secrets associated with this webhook.
- **truncated_secret** (`string`) Output only. The truncated version of the signing secret.
- **expire_time** (`string`) Output only. The expiration date of the signing secret.
- **state** (`enum (string)`) Output only. The state of the webhook.
Possible values:
- `enabled` - `disabled` - `disabled_due_to_failed_deliveries`
- **new_signing_secret** (`string`) Output only. The new signing secret for the webhook. Only populated on create.
- **id** (`string`) Output only. The ID of the webhook.
#### Examples
**Example**
**REST**
```sh
curl -X GET 'https://generativelanguage.googleapis.com/v1beta/webhooks/{id}' \
-H 'Content-Type: application/json' \
```
Response:
```json
{
"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.
#### Parameters
- **id** (`string`) *(Required)* Required. The ID of the webhook to update.
- **update_mask** (`string`) Optional. The list of fields to update.
#### Request Body
- **name** (`string`) Optional. The user-provided name of the webhook.
- **uri** (`string`) Optional. The URI to which webhook events will be sent.
- **subscribed_events** (`array (object or string)`) 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. The state of the webhook.
Possible values:
- `enabled` - `disabled` - `disabled_due_to_failed_deliveries`
#### Response
- **name** (`string`) Optional. The user-provided name of the webhook.
- **uri** (`string`) Required. The URI to which webhook events will be sent.
- **subscribed_events** (`array (object or string)`) 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
- **create_time** (`string`) Output only. The timestamp when the webhook was created.
- **update_time** (`string`) Output only. The timestamp when the webhook was last updated.
- **signing_secrets** (`array (SigningSecret)`) Output only. The signing secrets associated with this webhook.
- **truncated_secret** (`string`) Output only. The truncated version of the signing secret.
- **expire_time** (`string`) Output only. The expiration date of the signing secret.
- **state** (`enum (string)`) Output only. The state of the webhook.
Possible values:
- `enabled` - `disabled` - `disabled_due_to_failed_deliveries`
- **new_signing_secret** (`string`) Output only. The new signing secret for the webhook. Only populated on create.
- **id** (`string`) Output only. The ID of the webhook.
#### Examples
**Example**
**REST**
```sh
curl -X PATCH 'https://generativelanguage.googleapis.com/v1beta/webhooks/{id}' \
-H 'Content-Type: application/json' \
-d '{
"name": "string",
"uri": "string",
"subscribed_events": [
"string"
],
"state": "enabled"
}'
```
Response:
```json
{
"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.
#### Parameters
- **id** (`string`) *(Required)* Required. The ID of the webhook to delete. Format: `{webhook_id}`
#### Response
#### Examples
**Example**
**REST**
```sh
curl -X DELETE 'https://generativelanguage.googleapis.com/v1beta/webhooks/{id}' \
-H 'Content-Type: application/json' \
```
---
### RotateSigningSecret
`POST https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:rotateSigningSecret`
Generates a new signing secret for a Webhook.
#### Parameters
- **id** (`string`) *(Required)* Required. The ID of the webhook for which to generate a signing secret. Format: `{webhook_id}`
#### Request Body
- **revocation_behavior** (`enum (string)`) Optional. The revocation behavior for previous signing secrets.
Possible values:
- `revoke_previous_secrets_after_h24` - `revoke_previous_secrets_immediately`
#### Response
- **secret** (`string`) Output only. The newly generated signing secret.
#### Examples
**Example**
**REST**
```sh
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:rotateSigningSecret' \
-H 'Content-Type: application/json' \
-d '{
"revocation_behavior": "revoke_previous_secrets_after_h24"
}'
```
Response:
```json
{
"secret": "string"
}
```
---
### PingWebhook
`POST https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:ping`
Sends a ping event to a Webhook.
#### Parameters
- **id** (`string`) *(Required)* Required. The ID of the webhook to ping. Format: `{webhook_id}`
#### Request Body
#### Response
#### Examples
**Example**
**REST**
```sh
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:ping' \
-H 'Content-Type: application/json' \
```
---
## Resources
### Interaction
The Interaction resource.
**Properties:**
- **model** (`ModelOption`) 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`) 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`) *(Required)* Required. Output only. A unique identifier for the interaction completion.
- **status** (`enum (string)`) *(Required)* Required. Output only. The status of the interaction.
Possible values:
- `in_progress` - `requires_action` - `completed` - `failed` - `cancelled` - `incomplete`
- **created** (`string`) *(Required)* Required. Output only. The time at which the response was created in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
- **updated** (`string`) *(Required)* Required. Output only. The time at which the response was last updated in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
- **role** (`string`) Output only. The role of the interaction.
- **system_instruction** (`string`) System instruction for the interaction.
- **tools** (`array (Tool)`) A list of tool declarations the model may call during interaction.
- **usage** (`Usage`) Output only. Statistics on the interaction request's token usage.
- **total_input_tokens** (`integer`) Number of tokens in the prompt (context).
- **input_tokens_by_modality** (`array (ModalityTokens)`) A breakdown of input token usage by modality.
- **modality** (`ResponseModality`) The modality associated with the token count.
Possible values:
- `text` - `image` - `audio` - `video` - `document`
- **tokens** (`integer`) Number of tokens for the modality.
- **total_cached_tokens** (`integer`) Number of tokens in the cached part of the prompt (the cached content).
- **cached_tokens_by_modality** (`array (ModalityTokens)`) A breakdown of cached token usage by modality.
- **modality** (`ResponseModality`) The modality associated with the token count.
Possible values:
- `text` - `image` - `audio` - `video` - `document`
- **tokens** (`integer`) Number of tokens for the modality.
- **total_output_tokens** (`integer`) Total number of tokens across all the generated responses.
- **output_tokens_by_modality** (`array (ModalityTokens)`) A breakdown of output token usage by modality.
- **modality** (`ResponseModality`) The modality associated with the token count.
Possible values:
- `text` - `image` - `audio` - `video` - `document`
- **tokens** (`integer`) Number of tokens for the modality.
- **total_tool_use_tokens** (`integer`) Number of tokens present in tool-use prompt(s).
- **tool_use_tokens_by_modality** (`array (ModalityTokens)`) A breakdown of tool-use token usage by modality.
- **modality** (`ResponseModality`) The modality associated with the token count.
Possible values:
- `text` - `image` - `audio` - `video` - `document`
- **tokens** (`integer`) Number of tokens for the modality.
- **total_thought_tokens** (`integer`) Number of tokens of thoughts for thinking models.
- **total_tokens** (`integer`) Total token count for the interaction request (prompt + responses + other internal tokens).
- **grounding_tool_count** (`array (GroundingToolCount)`) Grounding tool count.
- **type** (`enum (string)`) The grounding tool type associated with the count.
Possible values:
- `google_search` - `google_maps` - `retrieval`
- **count** (`integer`) The number of grounding tool counts.
- **response_modalities** (`array (ResponseModality)`) The requested modalities of the response (TEXT, IMAGE, AUDIO).
Possible values:
- `text` - `image` - `audio` - `video` - `document`
- **response_mime_type** (`string`) The mime type of the response. This is required if response_format is set.
- **previous_interaction_id** (`string`) The ID of the previous interaction, if any.
- **service_tier** (`enum (string)`) The service tier for the interaction.
Possible values:
- `flex` - `standard` - `priority`
- **webhook_config** (`WebhookConfig`) Optional. Webhook configuration for receiving notifications when the interaction completes.
- **uris** (`array (string)`) Optional. If set, these webhook URIs will be used for webhook events instead of the registered webhooks.
- **user_metadata** (`object`) Optional. The user metadata that will be returned on each event emission to the webhooks.
- **steps** (`array (Step)`) Output only. The steps that make up the interaction.
- **input** (`Content or array (Content) or array (Step) or string`) The input for the interaction.
- **response_format** (`ResponseFormat or ResponseFormatList`) Enforces that the generated response is a JSON object that complies with the JSON schema specified in this field.
- **generation_config** (`GenerationConfig`) Input only. Configuration parameters for the model interaction.
- **temperature** (`number`) Controls the randomness of the output.
- **top_p** (`number`) The maximum cumulative probability of tokens to consider when sampling.
- **seed** (`integer`) Seed used in decoding for reproducibility.
- **stop_sequences** (`array (string)`) A list of character sequences that will stop output interaction.
- **thinking_level** (`ThinkingLevel`) The level of thought tokens that the model should generate.
Possible values:
- `minimal` - `low` - `medium` - `high`
- **thinking_summaries** (`ThinkingSummaries`) Whether to include thought summaries in the response.
Possible values:
- `auto` - `none`
- **max_output_tokens** (`integer`) The maximum number of tokens to include in the response.
- **speech_config** (`array (SpeechConfig)`) Configuration for speech interaction.
- **voice** (`string`) The voice of the speaker.
- **language** (`string`) The language of the speech.
- **speaker** (`string`) The speaker's name, it should match the speaker name given in the prompt.
- **image_config** (`ImageConfig`) Configuration for image interaction.
- **aspect_ratio** (`enum (string)`)
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)`)
Possible values:
- `1K` - `2K` - `4K` - `512`
- **tool_choice** (`ToolChoiceConfig or ToolChoiceType`) The tool choice configuration.
- **agent_config** (`DeepResearchAgentConfig or DynamicAgentConfig`) Configuration parameters for the agent interaction.
**Possible Types:** (Discriminator: `type`) - **DynamicAgentConfig**: Configuration for dynamic agents.
- **type** (`object`) *(Required)*
Value: `dynamic`
- **DeepResearchAgentConfig**: Configuration for the Deep Research agent.
- **type** (`object`) *(Required)*
Value: `deep-research`
- **thinking_summaries** (`ThinkingSummaries`) Whether to include thought summaries in the response.
Possible values:
- `auto` - `none`
- **visualization** (`enum (string)`) Whether to include visualizations in the response.
Possible values:
- `off` - `auto`
- **collaborative_planning** (`boolean`) 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. .
**JSON Representation:**
```json
{
"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
}
}
```
**Examples**
**Example**
```json
{
"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.
**Polymorphic Types:** (Discriminator: `type`)- **TextContent**
- A text content block.
- **type** (`object`) *(Required)*
Value: `text`
- **text** (`string`) *(Required)* Required. The text content.
- **annotations** (`array (Annotation)`) Citation information for model-generated content.
**Examples**
**Text**
```json
{
"type": "text",
"text": "Hello, how are you?"
}
```
- **ImageContent**
- An image content block.
- **type** (`object`) *(Required)*
Value: `image`
- **data** (`string`) The image content.
- **uri** (`string`) The URI of the image.
- **mime_type** (`enum (string)`) 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`) The resolution of the media.
Possible values:
- `low` - `medium` - `high` - `ultra_high`
**Examples**
**Image**
```json
{
"type": "image",
"data": "BASE64_ENCODED_IMAGE",
"mime_type": "image/png"
}
```
- **AudioContent**
- An audio content block.
- **type** (`object`) *(Required)*
Value: `audio`
- **data** (`string`) The audio content.
- **uri** (`string`) The URI of the audio.
- **mime_type** (`enum (string)`) 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`) The number of audio channels.
- **sample_rate** (`integer`) The sample rate of the audio.
**Examples**
**Audio**
```json
{
"type": "audio",
"data": "BASE64_ENCODED_AUDIO",
"mime_type": "audio/wav"
}
```
- **DocumentContent**
- A document content block.
- **type** (`object`) *(Required)*
Value: `document`
- **data** (`string`) The document content.
- **uri** (`string`) The URI of the document.
- **mime_type** (`enum (string)`) The mime type of the document.
Possible values:
- `application/pdf`
**Examples**
**Document**
```json
{
"type": "document",
"data": "BASE64_ENCODED_DOCUMENT",
"mime_type": "application/pdf"
}
```
- **VideoContent**
- A video content block.
- **type** (`object`) *(Required)*
Value: `video`
- **data** (`string`) The video content.
- **uri** (`string`) The URI of the video.
- **mime_type** (`enum (string)`) 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`) The resolution of the media.
Possible values:
- `low` - `medium` - `high` - `ultra_high`
**Examples**
**Video**
```json
{
"type": "video",
"uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
}
```
**JSON Representation:**
```json
{
"type": {},
"text": "string",
"annotations": [
{
"type": {},
"url": "string",
"title": "string",
"start_index": 0,
"end_index": 0
}
]
}
```
### Tool
A tool that can be used by the model.
**Polymorphic Types:** (Discriminator: `type`)- **Function**
- A tool that can be used by the model.
- **type** (`object`) *(Required)*
Value: `function`
- **name** (`string`) The name of the function.
- **description** (`string`) A description of the function.
- **parameters** (`object`) The JSON Schema for the function's parameters.
**Examples**
**function_calling**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"]
}
}],
"input": "What is the weather like in Boston, MA?"
}'
```
**function_calling**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-3-flash-preview",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"]
}
}],
input="What is the weather like in Boston?"
)
print(response.outputs[0])
```
**function_calling**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
tools: [{
type: 'function',
name: 'get_weather',
description: 'Get the current weather in a given location',
parameters: {
type: 'object',
properties: {
location: {
type: 'string',
description: 'The city and state, e.g. San Francisco, CA'
}
},
required: ['location']
}
}],
input: 'What is the weather like in Boston?'
});
console.log(interaction.outputs[0]);
```
- **CodeExecution**
- A tool that can be used by the model to execute code.
- **type** (`object`) *(Required)*
Value: `code_execution`
**Examples**
**code_execution**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"tools": [{
"type": "code_execution"
}],
"input": "Calculate the first 10 Fibonacci numbers"
}'
```
**code_execution**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-3-flash-preview",
tools=[{"type": "code_execution"}],
input="Calculate the first 10 Fibonacci numbers"
)
print(response.outputs[0])
```
**code_execution**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
tools: [{ type: 'code_execution' }],
input: 'Calculate the first 10 Fibonacci numbers'
});
console.log(interaction.outputs[0]);
```
- **UrlContext**
- A tool that can be used by the model to fetch URL context.
- **type** (`object`) *(Required)*
Value: `url_context`
**Examples**
**url_context**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"tools": [{
"type": "url_context"
}],
"input": "Summarize https://www.example.com"
}'
```
**url_context**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-3-flash-preview",
tools=[{"type": "url_context"}],
input="Summarize https://www.example.com"
)
print(response.outputs[0])
```
**url_context**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
tools: [{ type: 'url_context' }],
input: 'Summarize https://www.example.com'
});
console.log(interaction.outputs[0]);
```
- **ComputerUse**
- A tool that can be used by the model to interact with the computer.
- **type** (`object`) *(Required)*
Value: `computer_use`
- **environment** (`enum (string)`) The environment being operated.
Possible values:
- `browser`
- **excludedPredefinedFunctions** (`array (string)`) The list of predefined functions that are excluded from the model call.
**Examples**
**computer_use**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-2.5-computer-use-preview-10-2025",
"tools": [{
"type": "computer_use",
}],
"input": "Find a flight to Tokyo"
}'
```
**computer_use**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-2.5-computer-use-preview-10-2025",
tools=[{"type": "computer_use"}],
input="Find a flight to Tokyo"
)
print(response.outputs[0])
```
**computer_use**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-2.5-computer-use-preview-10-2025',
tools: [{ type: 'computer_use'}],
input: 'Find a flight to Tokyo'
});
console.log(interaction.outputs[0]);
```
- **McpServer**
- A MCPServer is a server that can be called by the model to perform actions.
- **type** (`object`) *(Required)*
Value: `mcp_server`
- **name** (`string`) The name of the MCPServer.
- **url** (`string`) The full URL for the MCPServer endpoint. Example: "https://api.example.com/mcp"
- **headers** (`object`) Optional: Fields for authentication headers, timeouts, etc., if needed.
- **allowed_tools** (`array (AllowedTools)`) The allowed tools.
- **mode** (`ToolChoiceType`) The mode of the tool choice.
Possible values:
- `auto` - `any` - `none` - `validated`
- **tools** (`array (string)`) The names of the allowed tools.
**Examples**
**mcp_server**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"tools": [{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp"
}],
"input": "Today is 12-05-2025, what is the temperature today in London?"
}'
```
**mcp_server**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-3-flash-preview",
tools=[{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp"
}],
input="Today is 12-05-2025, what is the temperature today in London?"
)
print(response.outputs[0])
```
**mcp_server**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
tools: [{
type: 'mcp_server',
name: 'weather_service',
url: 'https://gemini-api-demos.uc.r.appspot.com/mcp'
}],
input: 'Today is 12-05-2025, what is the temperature today in London?'
});
console.log(interaction.outputs[0]);
```
- **GoogleSearch**
- A tool that can be used by the model to search Google.
- **type** (`object`) *(Required)*
Value: `google_search`
- **search_types** (`array (enum (string))`) The types of search grounding to enable.
Possible values:
- `web_search` - `image_search` - `enterprise_web_search`
**Examples**
**google_search**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"tools": [{
"type": "google_search"
}],
"input": "Who is the current president of France?"
}'
```
**google_search**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-3-flash-preview",
tools=[{"type": "google_search"}],
input="Who is the current president of France?"
)
print(response.outputs[0])
```
**google_search**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
tools: [{ type: 'google_search' }],
input: 'Who is the current president of France?'
});
console.log(interaction.outputs[0]);
```
- **FileSearch**
- A tool that can be used by the model to search files.
- **type** (`object`) *(Required)*
Value: `file_search`
- **file_search_store_names** (`array (string)`) The file search store names to search.
- **top_k** (`integer`) The number of semantic retrieval chunks to retrieve.
- **metadata_filter** (`string`) Metadata filter to apply to the semantic retrieval documents and chunks.
**Examples**
**file_search**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"tools": [{
"type": "file_search",
"file_search_store_names": ["fileSearchStores/m64d1sevsr4y-xfyawui3fxqg"]
}],
"input": "Who is the author of the book?"
}'
```
**file_search**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-3-flash-preview",
tools=[{
"type": "file_search",
"file_search_store_names": ["fileSearchStores/m64d1sevsr4y-xfyawui3fxqg"]
}],
input="Who is the author of the book?"
)
print(response.outputs[0])
```
**file_search**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
tools: [{
type: 'file_search',
file_search_store_names: ['fileSearchStores/m64d1sevsr4y-xfyawui3fxqg']
}],
input: 'Who is the author of the book?'
});
console.log(interaction.outputs[0]);
```
- **GoogleMaps**
- A tool that can be used by the model to call Google Maps.
- **type** (`object`) *(Required)*
Value: `google_maps`
- **enable_widget** (`boolean`) Whether to return a widget context token in the tool call result of the response.
- **latitude** (`number`) The latitude of the user's location.
- **longitude** (`number`) The longitude of the user's location.
**Examples**
**google_maps**
```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"tools": [{
"type": "google_maps",
"latitude": 37.7749,
"longitude": -122.4194
}],
"input": "What is the best food near me?"
}'
```
**google_maps**
```python
from google import genai
client = genai.Client()
response = client.interactions.create(
model="gemini-3-flash-preview",
tools=[{
"type": "google_maps",
"latitude": 37.7749,
"longitude": -122.4194
}],
input="What is the best food near me?"
)
print(response.outputs[0])
```
**google_maps**
```javascript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
tools: [{
type: 'google_maps',
latitude: 37.7749,
longitude: -122.4194
}],
input: 'What is the best food near me?'
});
console.log(interaction.outputs[0]);
```
- **Retrieval**
- A tool that can be used by the model to retrieve files.
- **type** (`object`) *(Required)*
Value: `retrieval`
- **retrieval_types** (`array (enum (string))`) The types of file retrieval to enable.
Possible values:
- `vertex_ai_search`
- **vertex_ai_search_config** (`VertexAISearchConfig`) Used to specify configuration for VertexAISearch.
- **engine** (`string`) Optional. Used to specify Vertex AI Search engine.
- **datastores** (`array (string)`) Optional. Used to specify Vertex AI Search datastores.
**JSON Representation:**
```json
{
"type": {},
"name": "string",
"description": "string",
"parameters": {}
}
```
### Turn
**Properties:**
- **role** (`string`) The originator of this turn. Must be user for input or model for model output.
- **content** (`array (Content) or string`)
**JSON Representation:**
```json
{
"role": "string",
"content": [
{
"type": {},
"text": "string",
"annotations": [
{
"type": {},
"url": "string",
"title": "string",
"start_index": 0,
"end_index": 0
}
]
}
]
}
```
**Examples**
**User Turn**
```json
{
"role": "user",
"content": [
{
"type": "text",
"text": "user turn"
}
]
}
```
**Model Turn**
```json
{
"role": "model",
"content": [
{
"type": "text",
"text": "model turn"
}
]
}
```
### InteractionSseEvent
**Polymorphic Types:** (Discriminator: `event_type`)- **InteractionCreatedEvent**
-
- **event_type** (`object`) *(Required)*
Value: `interaction.created`
- **interaction** (`Interaction`) *(Required)*
- **event_id** (`string`) The event_id token to be used to resume the interaction stream, from this event.
- **InteractionCompletedEvent**
-
- **event_type** (`object`) *(Required)*
Value: `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`) The event_id token to be used to resume the interaction stream, from this event.
- **InteractionStatusUpdate**
-
- **event_type** (`object`) *(Required)*
Value: `interaction.status_update`
- **interaction_id** (`string`) *(Required)*
- **status** (`enum (string)`) *(Required)*
Possible values:
- `in_progress` - `requires_action` - `completed` - `failed` - `cancelled` - `incomplete`
- **event_id** (`string`) The event_id token to be used to resume the interaction stream, from this event.
**Examples**
**Interaction Status Update**
```json
{
"event_type": "interaction.status_update",
"interaction_id": "v1_ChdTMjQ0YWJ5TUF1TzcxZThQdjRpcnFRcxIXUzI0NGFieU1BdU83MWU4UHY0aXJxUXM",
"status": "in_progress"
}
```
- **ErrorEvent**
-
- **event_type** (`object`) *(Required)*
Value: `error`
- **error** (`Error`)
- **code** (`string`) A URI that identifies the error type.
- **message** (`string`) A human-readable error message.
- **event_id** (`string`) The event_id token to be used to resume the interaction stream, from this event.
**Examples**
**Error Event**
```json
{
"event_type": "error",
"error": {
"message": "Failed to get completed interaction: Result not found.",
"code": "not_found"
}
}
```
- **StepStart**
-
- **event_type** (`object`) *(Required)*
Value: `step.start`
- **index** (`integer`) *(Required)*
- **step** (`Step`) *(Required)*
- **event_id** (`string`) The event_id token to be used to resume the interaction stream, from this event.
- **StepDelta**
-
- **event_type** (`object`) *(Required)*
Value: `step.delta`
- **index** (`integer`) *(Required)*
- **delta** (`StepDeltaData`) *(Required)*
- **event_id** (`string`) The event_id token to be used to resume the interaction stream, from this event.
- **StepStop**
-
- **event_type** (`object`) *(Required)*
Value: `step.stop`
- **index** (`integer`) *(Required)*
- **event_id** (`string`) The event_id token to be used to resume the interaction stream, from this event.
**JSON Representation:**
```json
{
"event_type": {},
"interaction": {
"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
}
},
"event_id": "string"
}
```