# Gemini API
Source: https://aistudio.google.com/docs
Description: Build apps and agents with Gemini, Nano Banana, Gemini Omni, and Lyria using the Gemini API documentation and reference.

{% two-column-layout %}

{% left-column %}

# Welcome to Gemini API {% class="h0" %}

Go from a quick prompt to production apps and agents with the Gemini API.
Tackle complex coding and multimodal reasoning with Gemini, or hand multi-step
work to a managed agent. Stream voice and video with the Live API, or generate
images with Nano Banana, video with Gemini Omni, and music with Lyria.

{% button href="/docs/get-started" variant="ais" size="large" %}Get Started{% /button %} {% button href="https://aistudio.google.com/apikey" variant="primary" size="large" %}Create API Key{% /button %}

{% /left-column %}

{% right-column %}

{% tabs %}

{% tab label="Agents" %}

```bash
# Connect the Gemini Docs MCP server
npx add-mcp "https://gemini-api-docs-mcp.dev"

# Install Gemini API agent skills
npx skills add google-gemini/gemini-skills --skill gemini-api-dev

# Or install the Antigravity plugin (MCP + skills)
agy plugin install https://github.com/google-gemini/gemini-skills

# Install the experimental Gemini API CLI on macOS and Linux
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash
```

{% /tab %}

{% tab label="Python" filename="main.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Explain how AI works in a few words"
)

print(interaction.output_text)
```

{% /tab %}

{% tab label="JavaScript" filename="index.js" %}

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

const ai = new GoogleGenAI({});

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

console.log(interaction.output_text);
```

{% /tab %}

{% tab label="REST" %}

```bash
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-4-argon",
    "input": "Explain how AI works in a few words"
  }'
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-4-argon"))
        .input(InteractionsInput.of("Explain how AI works in a few words"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-4-argon"),
            Input: interactions.NewInteractionsInput("Explain how AI works in a few words"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Meet the models {% class="hide-from-toc" id="meet-the-models" %}

{% card-grid columns="3" %}

{% card title="Gemini 4 Argon" description="Our flagship reasoning model with a shared 1M context window and long decodes up to 1M tokens." variant="model-card" %}

{% section class="model-specs" %}

*   *Model code* **gemini-4-argon**
*   *Context* **1M tokens**
*   *Max output* **65K / 1M tokens**
*   *Modalities* **Text, Image, Audio, Video, PDF**

{% /section %}

{% section class="card-actions" %}

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-4-argon" variant="primary" tooltip="Try Gemini 4 Argon in AI Studio" %}Try in AI Studio{% /button %} {% button href="/docs/models/gemini-4-argon" variant="icon-primary" icon="arrow_forward" tooltip="View Gemini 4 Argon model details" %}{% /button %}

{% /section %}

{% /card %}

{% card title="Gemini 3.8 Flash" description="Our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows." variant="model-card" %}

{% section class="model-specs" %}

*   *Model code* **gemini-3.8-flash**
*   *Context* **1M tokens**
*   *Max output* **65K tokens**
*   *Modalities* **Text, Image, Audio, Video, PDF**

{% /section %}

{% section class="card-actions" %}

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.8-flash" variant="primary" tooltip="Try Gemini 3.8 Flash in AI Studio" %}Try in AI Studio{% /button %} {% button href="/docs/models/gemini-3.8-flash" variant="icon-primary" icon="arrow_forward" tooltip="View Gemini 3.8 Flash model details" %}{% /button %}

{% /section %}

{% /card %}

{% card title="Gemini 3.8 Live" description="Default Live API model for low-latency, bidirectional voice and video agent experiences without reasoning delays." variant="model-card" %}

{% section class="model-specs" %}

*   *Model code* **gemini-3.8-live**
*   *Context* **128K tokens**
*   *Max output* **8K tokens**
*   *Modalities* **Audio, Video, Text → Audio, Text**

{% /section %}

{% section class="card-actions" %}

{% button href="https://aistudio.google.com/live" variant="primary" tooltip="Try Gemini 3.8 Live in AI Studio" %}Try in AI Studio{% /button %} {% button href="/docs/models/gemini-3.8-live" variant="icon-primary" icon="arrow_forward" tooltip="View Gemini 3.8 Live model details" %}{% /button %}

{% /section %}

{% /card %}

{% card title="Gemini 3.8 Flash TTS" description="Flagship creative text-to-speech model for studio-grade voice fidelity, expressive acting, Voice design, and Voice replication." variant="model-card" %}

{% section class="model-specs" %}

*   *Model code* **gemini-3.8-flash-tts**
*   *Context* **8K tokens**
*   *Max output* **16K tokens**
*   *Modalities* **Text → Audio**

{% /section %}

{% section class="card-actions" %}

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.8-flash-tts" variant="primary" tooltip="Try Gemini 3.8 Flash TTS in AI Studio" %}Try in AI Studio{% /button %} {% button href="/docs/models/gemini-3.8-flash-tts" variant="icon-primary" icon="arrow_forward" tooltip="View Gemini 3.8 Flash TTS model details" %}{% /button %}

{% /section %}

{% /card %}

{% card title="Nano Banana Pro" description="State-of-the-art image generation and editing model for studio-quality precision, accurate text rendering, and complex visual creation." variant="model-card" %}

{% section class="model-specs" %}

*   *Model code* **gemini-3-pro-image**
*   *Context* **65K tokens**
*   *Max output* **32K tokens**
*   *Modalities* **Text, Image → Image, Text**

{% /section %}

{% section class="card-actions" %}

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-3-pro-image" variant="primary" tooltip="Try Nano Banana Pro in AI Studio" %}Try in AI Studio{% /button %} {% button href="/docs/models/gemini-3-pro-image" variant="icon-primary" icon="arrow_forward" tooltip="View Nano Banana Pro model details" %}{% /button %}

{% /section %}

{% /card %}

{% card title="View all models" href="/docs/models" variant="view-more" %}

{% /card %}

{% /card-grid %}

## Explore Capabilities {% class="hide-from-toc" id="explore-capabilities" %}

{% tabs variant="showcase" %}

{% tab label="Image" %}

{% two-column-layout class="capability-panel" %}

{% left-column %}

{% tabs %}

{% tab label="Python" filename="image_gen.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-flash-image-preview",
    input="Generate an image of a nano banana dish in a fancy restaurant",
    generation_config={
        "image_config": {"aspect_ratio": "16:9", "image_size": "2k"}
    },
)

for output in interaction.outputs:
    if output.type == "image":
        with open("nano_banana.png", "wb") as f:
            f.write(output.image_bytes)
```

{% /tab %}

{% tab label="JavaScript" filename="image_gen.js" %}

```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.1-flash-image-preview",
  input: "Generate an image of a nano banana dish in a fancy restaurant",
  generationConfig: {
    imageConfig: { aspectRatio: "16:9", imageSize: "2k" },
  },
});

for (const output of interaction.outputs) {
  if (output.type === "image") {
    fs.writeFileSync("nano_banana.png", Buffer.from(output.data, "base64"));
  }
}
```

{% /tab %}

{% /tabs %}

{% /left-column %}

{% right-column class="capability-details" %}

### Image generation

Generate and edit highly contextual images natively with Nano Banana models
using text, image, or interleaved multimodal prompts.

{% section class="capability-highlights" %}

*   {% icon name="check" /%} **Up to 4K resolution** with flexible aspect ratios
*   {% icon name="check" /%} **Multi-turn editing** and character consistency
*   {% icon name="check" /%} **Search-grounded** visual accuracy and text
    rendering

{% /section %}

{% button href="/docs/image-generation" variant="ais" tooltip="Read Image generation docs" %}Read docs{% /button %}

{% /right-column %}

{% /two-column-layout %}

{% /tab %}

{% tab label="Video" %}

{% two-column-layout class="capability-panel" %}

{% left-column %}

{% tabs %}

{% tab label="Python" filename="video_gen.py" %}

```python
import time
from google import genai

client = genai.Client()

operation = client.models.generate_videos(
    model="gemini-omni-1.1-flash",
    prompt="A cinematic close-up of two people talking by a window in the rain",
)

while not operation.done:
    time.sleep(10)
    operation = client.operations.get(operation)

video = operation.response.generated_videos[0]
client.files.download(file=video.video)
video.video.save("dialogue_example.mp4")
```

{% /tab %}

{% tab label="JavaScript" filename="video_gen.js" %}

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

const ai = new GoogleGenAI({});

let operation = await ai.models.generateVideos({
  model: "gemini-omni-1.1-flash",
  prompt: "A cinematic close-up of two people talking by a window in the rain",
});

while (!operation.done) {
  await new Promise((resolve) => setTimeout(resolve, 10000));
  operation = await ai.operations.getVideosOperation({ operation });
}

await ai.files.download({
  file: operation.response.generatedVideos[0].video,
  downloadPath: "dialogue_example.mp4",
});
```

{% /tab %}

{% /tabs %}

{% /left-column %}

{% right-column class="capability-details" %}

### Video generation

Create high-definition video with natively synchronized dialogue, sound effects,
and ambient audio from text or image prompts.

{% section class="capability-highlights" %}

*   {% icon name="check" /%} **Native audio & dialogue** synchronized to motion
*   {% icon name="check" /%} **Frame interpolation** with first and last frame
    control
*   {% icon name="check" /%} **Reference images** to preserve character and
    style

{% /section %}

{% button href="/docs/video" variant="ais" tooltip="Read Video generation docs" %}Read docs{% /button %}

{% /right-column %}

{% /two-column-layout %}

{% /tab %}

{% tab label="Voice" %}

{% two-column-layout class="capability-panel" %}

{% left-column %}

{% tabs %}

{% tab label="Python" filename="live_agent.py" %}

```python
import asyncio
from google import genai
from google.genai import types

client = genai.Client()

async def main():
    config = types.LiveConnectConfig(response_modalities=["AUDIO"])
    async with client.aio.live.connect(
        model="gemini-3.8-live-preview", config=config
    ) as session:
        await session.send_client_content(
            turns={"parts": [{"text": "Hello! Tell me a quick fun fact."}]}
        )
        async for response in session.receive():
            if response.data is not None:
                # Stream raw PCM audio bytes to speaker
                pass

asyncio.run(main())
```

{% /tab %}

{% tab label="JavaScript" filename="live_agent.js" %}

```javascript
import { GoogleGenAI, Modality } from "@google/genai";

const ai = new GoogleGenAI({});

const session = await ai.live.connect({
  model: "gemini-3.8-live-preview",
  config: { responseModalities: [Modality.AUDIO] },
  callbacks: {
    onmessage: (message) => {
      if (message.serverContent?.modelTurn) {
        // Handle low-latency streaming audio chunks
      }
    },
  },
});

session.sendClientContent({
  turns: [{ parts: [{ text: "Hello! Tell me a quick fun fact." }] }],
});
```

{% /tab %}

{% /tabs %}

{% /left-column %}

{% right-column class="capability-details" %}

### Voice agents with Live API

Build real-time, bidirectional voice and video agents with sub-second latency,
natural barge-in, and live tool calling.

{% section class="capability-highlights" %}

*   {% icon name="check" /%} **Real-time WebSocket streaming** for audio and
    video
*   {% icon name="check" /%} **Natural voice activity detection** and
    interruption handling
*   {% icon name="check" /%} **Expressive multilingual voices** with affective
    dialogue

{% /section %}

{% button href="/docs/live-api" variant="ais" tooltip="Read Live API docs" %}Read docs{% /button %}

{% /right-column %}

{% /two-column-layout %}

{% /tab %}

{% tab label="Thinking" %}

{% two-column-layout class="capability-panel" %}

{% left-column %}

{% tabs %}

{% tab label="Python" filename="thinking.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Find the flaw in this distributed lock protocol and fix it.",
    generation_config={
        "thinking_level": "high",
        "thinking_summaries": "auto",
    },
)

for output in interaction.outputs:
    if output.type == "thought":
        print("Thought summary:", output.summary)
    elif output.type == "text":
        print("Answer:", output.text)
```

{% /tab %}

{% tab label="JavaScript" filename="thinking.js" %}

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "Find the flaw in this distributed lock protocol and fix it.",
  generationConfig: {
    thinkingLevel: "high",
    thinkingSummaries: "auto",
  },
});

for (const output of interaction.outputs) {
  if (output.type === "thought") {
    console.log("Thought summary:", output.summary);
  } else if (output.type === "text") {
    console.log("Answer:", output.text);
  }
}
```

{% /tab %}

{% /tabs %}

{% /left-column %}

{% right-column class="capability-details" %}

### Adaptive thinking

Control how deeply Gemini reasons before responding—from zero-latency `minimal`
thinking to deep multi-step `high` reasoning.

{% section class="capability-highlights" %}

*   {% icon name="check" /%} **Configurable thinking levels** (minimal, low,
    medium, high)
*   {% icon name="check" /%} **Transparent thought summaries** streamed in real
    time
*   {% icon name="check" /%} **Interleaved reasoning** across tool calls and
    code execution

{% /section %}

{% button href="/docs/thinking" variant="ais" tooltip="Read Adaptive thinking docs" %}Read docs{% /button %}

{% /right-column %}

{% /two-column-layout %}

{% /tab %}

{% tab label="Tools" %}

{% two-column-layout class="capability-panel" %}

{% left-column %}

{% tabs %}

{% tab label="Python" filename="tools.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Who won the latest F1 Grand Prix and what were the lap times?",
    tools=[{"type": "google_search"}, {"type": "code_execution"}],
)

for output in interaction.outputs:
    if output.type == "text":
        print(output.text)
```

{% /tab %}

{% tab label="JavaScript" filename="tools.js" %}

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "Who won the latest F1 Grand Prix and what were the lap times?",
  tools: [{ type: "google_search" }, { type: "code_execution" }],
});

const textOutput = interaction.outputs.find((o) => o.type === "text");
console.log(textOutput?.text);
```

{% /tab %}

{% /tabs %}

{% /left-column %}

{% right-column class="capability-details" %}

### Built-in tools & function calling

Connect Gemini to live information, computation, and your own backend APIs with
hosted tools and custom function declarations.

{% section class="capability-highlights" %}

*   {% icon name="check" /%} **Google Search & URL Context** for live web
    grounding
*   {% icon name="check" /%} **Code Execution** in a secure Python sandbox
*   {% icon name="check" /%} **Custom Function Calling** for parallel multi-tool
    orchestration

{% /section %}

{% button href="/docs/tools" variant="ais" tooltip="Read Tools and function calling docs" %}Read docs{% /button %}

{% /right-column %}

{% /two-column-layout %}

{% /tab %}

{% tab label="Structured" %}

{% two-column-layout class="capability-panel" %}

{% left-column %}

{% tabs %}

{% tab label="Python" filename="structured.py" %}

```python
from google import genai
from pydantic import BaseModel, Field

class FeedbackAnalysis(BaseModel):
    sentiment: str = Field(description="positive, neutral, or negative")
    summary: str = Field(description="One-sentence summary of the feedback.")
    action_items: list[str]

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="The new dashboard is fast, but exporting CSVs fails on mobile.",
    response_format=FeedbackAnalysis.model_json_schema(),
)

print(interaction.output_text)
```

{% /tab %}

{% tab label="JavaScript" filename="structured.js" %}

```javascript
import { GoogleGenAI } from "@google/genai";
import { z } from "zod";

const FeedbackSchema = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  summary: z.string(),
  actionItems: z.array(z.string()),
});

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "The new dashboard is fast, but exporting CSVs fails on mobile.",
  response_format: z.toJSONSchema(FeedbackSchema),
});

console.log(JSON.parse(interaction.output_text));
```

{% /tab %}

{% /tabs %}

{% /left-column %}

{% right-column class="capability-details" %}

### Structured outputs

Constrain Gemini responses to follow a strict JSON Schema, Pydantic model, or
Zod type for reliable downstream automation.

{% section class="capability-highlights" %}

*   {% icon name="check" /%} **Guaranteed JSON Schema** compliance on every
    response
*   {% icon name="check" /%} **Native Pydantic & Zod** schema integration
*   {% icon name="check" /%} **Compatible with tools** like Google Search and
    Code Execution

{% /section %}

{% button href="/docs/structured-output" variant="ais" tooltip="Read Structured outputs docs" %}Read docs{% /button %}

{% /right-column %}

{% /two-column-layout %}

{% /tab %}

{% tab label="Long context" %}

{% two-column-layout class="capability-panel" %}

{% left-column %}

{% tabs %}

{% tab label="Python" filename="long_context.py" %}

```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="full_codebase_archive.txt")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "file", "file_uri": uploaded_file.uri},
        {
            "type": "text",
            "text": "Trace how authentication tokens are refreshed across all services.",
        },
    ],
)

print(interaction.output_text)
```

{% /tab %}

{% tab label="JavaScript" filename="long_context.js" %}

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

const ai = new GoogleGenAI({});

const uploadedFile = await ai.files.upload({
  file: "full_codebase_archive.txt",
});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "file", fileUri: uploadedFile.uri },
    {
      type: "text",
      text: "Trace how authentication tokens are refreshed across all services.",
    },
  ],
});

console.log(interaction.output_text);
```

{% /tab %}

{% /tabs %}

{% /left-column %}

{% right-column class="capability-details" %}

### Long context

Input up to 1 million tokens of code, video, audio, or documents in a single
prompt for deep cross-file reasoning and in-context learning.

{% section class="capability-highlights" %}

*   {% icon name="check" /%} **1M+ token context window** (~50,000 lines of code
    or 8 novels)
*   {% icon name="check" /%} **Near-perfect recall** across long multimodal
    inputs
*   {% icon name="check" /%} **Context caching** to reduce cost and latency on
    repeated prompts

{% /section %}

{% button href="/docs/long-context" variant="ais" tooltip="Read Long context docs" %}Read docs{% /button %}

{% /right-column %}

{% /two-column-layout %}

{% /tab %}

{% tab label="Function calling" %}

{% two-column-layout class="capability-panel" %}

{% left-column %}

{% tabs %}

{% tab label="Python" filename="function_calling.py" %}

```python
from google import genai

schedule_meeting = {
    "type": "function",
    "name": "schedule_meeting",
    "description": "Schedules a meeting with attendees at a given date and time.",
    "parameters": {
        "type": "object",
        "properties": {
            "attendees": {"type": "array", "items": {"type": "string"}},
            "date": {"type": "string"},
            "time": {"type": "string"},
            "topic": {"type": "string"},
        },
        "required": ["attendees", "date", "time", "topic"],
    },
}

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Schedule a meeting with Bob and Alice tomorrow at 10:00 AM about Q3 planning.",
    tools=[schedule_meeting],
)

for output in interaction.outputs:
    if output.type == "function_call":
        print(output.name, output.arguments)
```

{% /tab %}

{% tab label="JavaScript" filename="function_calling.js" %}

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

const ai = new GoogleGenAI({});

const scheduleMeeting = {
  type: "function",
  name: "schedule_meeting",
  description: "Schedules a meeting with attendees at a given date and time.",
  parameters: {
    type: "object",
    properties: {
      attendees: { type: "array", items: { type: "string" } },
      date: { type: "string" },
      time: { type: "string" },
      topic: { type: "string" },
    },
    required: ["attendees", "date", "time", "topic"],
  },
};

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "Schedule a meeting with Bob and Alice tomorrow at 10:00 AM about Q3 planning.",
  tools: [scheduleMeeting],
});

for (const output of interaction.outputs) {
  if (output.type === "function_call") {
    console.log(output.name, output.arguments);
  }
}
```

{% /tab %}

{% /tabs %}

{% /left-column %}

{% right-column class="capability-details" %}

### Function calling

Connect Gemini to your own APIs, databases, and backend services with structured
function declarations and automatic argument extraction.

{% section class="capability-highlights" %}

*   {% icon name="check" /%} **Parallel & compositional** multi-step function
    calls
*   {% icon name="check" /%} **Strict schema adherence** for tool arguments
*   {% icon name="check" /%} **Seamless integration** with built-in tools and
    thinking

{% /section %}

{% button href="/docs/function-calling" variant="ais" tooltip="Read Function calling docs" %}Read docs{% /button %}

{% /right-column %}

{% /two-column-layout %}

{% /tab %}

{% tab label="Document understanding" %}

{% two-column-layout class="capability-panel" %}

{% left-column %}

{% tabs %}

{% tab label="Python" filename="document_understanding.py" %}

```python
import base64
from google import genai

client = genai.Client()

with open("financial_report.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "document",
            "data": pdf_base64,
            "mime_type": "application/pdf",
        },
        {
            "type": "text",
            "text": "Summarize the key revenue drivers and extract the Q4 table.",
        },
    ],
)

print(interaction.output_text)
```

{% /tab %}

{% tab label="JavaScript" filename="document_understanding.js" %}

```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

const pdfData = fs.readFileSync("financial_report.pdf", {
  encoding: "base64",
});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "document",
      data: pdfData,
      mime_type: "application/pdf",
    },
    {
      type: "text",
      text: "Summarize the key revenue drivers and extract the Q4 table.",
    },
  ],
});

console.log(interaction.output_text);
```

{% /tab %}

{% /tabs %}

{% /left-column %}

{% right-column class="capability-details" %}

### Document understanding

Process up to 1,000 pages of PDFs with native visual and textual comprehension
across tables, charts, diagrams, and layouts.

{% section class="capability-highlights" %}

*   {% icon name="check" /%} **Native vision-based PDF parsing** beyond plain
    OCR
*   {% icon name="check" /%} **Up to 1,000 pages** per document in a single
    request
*   {% icon name="check" /%} **Structured extraction** of complex tables, forms,
    and figures

{% /section %}

{% button href="/docs/document-processing" variant="ais" tooltip="Read Document understanding docs" %}Read docs{% /button %}

{% /right-column %}

{% /two-column-layout %}

{% /tab %}

{% /tabs %}

## Create agents {% class="hide-from-toc" id="create-agents" %}

{% two-column-layout %}

{% left-column %}

Managed Agents give Gemini a workspace to plan and complete tasks on its own. In
a single request, Gemini can write and run code, search the web, and create
files in a hosted sandbox environment. Start with our prebuilt Antigravity
agent, or customize it with your own instructions and tools.

{% button href="/docs/managed-agents-quickstart" variant="ais" %}Agents quickstart{% /button %} {% button href="https://aistudio.google.com/prompts/new_chat?model=antigravity-preview-09-2026" variant="primary" tooltip="Try Managed Agents in AI Studio" %}Try in AI Studio{% /button %}

{% /left-column %}

{% right-column %}

{% tabs %}

{% tab label="Python" filename="agent.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input=(
        "Research the top 5 sustainable fashion brands, "
        "compare their materials and pricing tiers, and "
        "build an interactive dashboard in analysis.html."
    ),
    environment="remote"
)

print(interaction.output_text)
```

{% /tab %}

{% tab label="JavaScript" filename="agent.js" %}

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  agent: "antigravity-preview-09-2026",
  input:
    "Research the top 5 sustainable fashion brands, " +
    "compare their materials and pricing tiers, and " +
    "build an interactive dashboard in analysis.html.",
  environment: "remote",
});

console.log(interaction.output_text);
```

{% /tab %}

{% tab label="REST" filename="agent.sh" %}

```bash
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Research the top 5 sustainable fashion brands, compare their materials and pricing tiers, and build an interactive dashboard in analysis.html.",
    "environment": "remote"
  }'
```

{% /tab %}

{% tab label="Java" filename="AgentQuickstart.java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent(AgentOption.of("antigravity-preview-09-2026"))
        .input(
            InteractionsInput.of(
                "Research the top 5 sustainable fashion brands, "
                    + "compare their materials and pricing tiers, and "
                    + "build an interactive dashboard in analysis.html."))
        .environment(CreateAgentInteractionEnvironment.of("remote"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params))
        .interaction()
        .get();

System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("antigravity-preview-09-2026"),
            Input: interactions.NewInteractionsInput(
                "Research the top 5 sustainable fashion brands, " +
                    "compare their materials and pricing tiers, and " +
                    "build an interactive dashboard in analysis.html.",
            ),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Interactions API {% class="hide-from-toc" id="interactions-api" %}

The **Interactions API** has become our default interface as of June 2026 and is
the best way to build with Gemini models and agents going forward. If you're
starting a new project, you should use the Interactions API. While it remains
supported, the `generateContent` API is now considered legacy.

{% card-grid columns="3" %}

{% card href="/docs/interactions-overview" title="Interactions Overview" description="Learn how the Interactions API manages conversation state, messages, and output formats." icon="hub" variant="stacked-icon" %}

{% /card %}

{% card href="/docs/migrate-to-interactions" title="Migration Guide" description="Step-by-step guide to transition your code from generateContent to the Interactions API." icon="swap_horiz" variant="stacked-icon" %}

{% /card %}

{% card href="/docs/streaming" title="Streaming" description="Stream real-time tokens, incremental thoughts, and tool call events." icon="sensors" variant="stacked-icon" %}

{% /card %}

{% /card-grid %}

# Getting started
Source: https://aistudio.google.com/docs/get-started
Description: Get started with the Gemini API for Developers using the Interactions API

This guide gets you started with the Gemini API using the [Interactions
API](/docs/interactions-overview). You'll make your first API call in under a
minute and explore text generation, multimodal understanding, image generation,
structured output, tools, function calling, agents, and background execution.

The Interactions API is available through the
[Python](https://github.com/googleapis/python-genai) and
[JavaScript](https://github.com/googleapis/js-genai) SDKs, as well as through
REST.

## Choose the right Gemini tool {% id="choose-tool" %}

Use the [Google GenAI SDKs](/docs/libraries) and [coding agent setup](/docs/coding-agents) when you are **building** Gemini into an application. Use the [Gemini API CLI](/docs/cli) (`gemini-api`) when an agent or script needs to **call** Gemini directly from the shell without adding SDK code to your project:

| Tool | What it does | When to use it |
| :--- | :--- | :--- |
| **[Google GenAI SDKs](/docs/libraries)** | Imports Gemini client libraries into Python, TypeScript, JavaScript, Go, Java, or C# code. | You are building Gemini features into your application, backend service, or real-time [Live API](/docs/live-api) session. |
| **[Gemini Docs MCP & skills](/docs/coding-agents)** | Gives coding agents live documentation search and current SDK rules. | Your coding agent is writing application code that imports a Google GenAI SDK. |
| **[Gemini API CLI](/docs/cli)** (`gemini-api`) | Calls Gemini models and managed agents from any shell. | Your coding agent, shell script, or CI job needs to generate media, analyze files, or run a background research agent with zero project dependencies. |

{% callout type="note" %}
`gemini-api` is a stateless API client, not an interactive coding agent like `@google/gemini-cli`. You can run `gemini-api` inside any coding agent.
{% /callout %}

## 1. Get an API key {% id="get-api-key" %}

To use the Gemini API, you need to have an API key to authenticate your
requests, enforce security limits, and track usage to your account.

*   Google AI Studio automatically creates a project and API key for new users.
    You can copy it from the [API keys
    page](https://aistudio.google.com/api-keys).
*   If you need a new key, click **Create API key** in AI Studio and follow the
    dialog to add a new key-project pair.

{% button href="https://aistudio.google.com/apikey" variant="ais" %}Create a Gemini API Key{% /button %}

Set your key as an environment variable:

```bash
export GEMINI_API_KEY="YOUR_API_KEY"
```

### Upgrade to the paid tier {% id="upgrade-paid-tier" %}

Upgrading to the paid tier increases your rate limits and requires setting up
Cloud Billing.

*   Click **Set up billing** on the AI Studio [API
    keys](https://aistudio.google.com/api-keys) or
    [Projects](https://aistudio.google.com/projects) pages.
*   Follow the Cloud Billing dialog to create or link a billing account, add a
    payment method, and prepay a minimum of $5 (or currency equivalent) in paid
    credits.
*   View your API usage in [Google AI Studio](https://aistudio.google.com/usage)
    under **Dashboard** > **Usage**.

See the [Billing page](/docs/billing) for more information.

## 2. Install the SDK and make your first call {% id="2-install-the-sdk-and-make-your-first-call" %}

Install the SDK and generate text with a single API call.

{% tabs %}
{% tab label="Python" %}
Install the SDK:

```bash
pip install -U google-genai
```

Initialize the client and make a request:

```python
from google import genai

client = genai.Client()

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

{% /tab %}
{% tab label="JavaScript" %}
Install the SDK:

```bash
npm install @google/genai
```

Initialize the client and make a request:

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

const ai = new GoogleGenAI({});

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

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain how AI works in a few words"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Explain how AI works in a few words."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain how AI works in a few words"
  }'
```

**Response:**

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

When using REST, the API returns the full `Interaction` resource containing
metadata, usage statistics, and the step-by-step history of the turn.
{% /tab %}
{% /tabs %}

While the SDKs expose the full response, they also provide convenience
properties like `interaction.output_text` and `interaction.output_image` to
access final outputs directly. Learn more about the response structure in the
[Interactions overview](/docs/interactions-overview) or read the [text
generation guide](/docs/text-generation) for details on system instructions and
generation config.

{% callout type="info" %}
**Building with an AI coding agent?** Install the skill and then paste the
prompt to get started with the Gemini API using Interactions:
{% /callout %}

{% tabs %}
{% tab label="Install" %}
```bash
npx skills add google-gemini/gemini-skills --skill gemini-api-dev
```
{% /tab %}
{% tab label="Prompt" %}
```none
Based on what you know about me and my learning style, interactively guide me through the concepts Getting Started for the Gemini API at https://aistudio.google.com/docs/get-started.md using the Interactions API
```
{% /tab %}
{% /tabs %}

## 3. Stream the response {% id="3-stream-the-response" %}

For more fluid interactions, stream the response as it's generated. Each
`step.delta` event delivers a chunk of text you can display immediately.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

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

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

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

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

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain how AI works"))
        .stream(true)
        .build();

CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));

try (EventStream<InteractionSSEStreamEvent> stream = response.events()) {
  for (InteractionSSEStreamEvent event : stream) {
    System.out.println(event);
  }
}
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Write a haiku about coding."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain how AI works",
    "stream": true
  }'
```

When streaming, the server responds with a stream of server-sent events (SSE).
Each event includes a type and JSON data.

**Response:**

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

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

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

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

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

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

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

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

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

{% /tab %}
{% /tabs %}

For a detailed look at handling streaming events and delta types, see the
[streaming interactions guide](/docs/streaming).

## 4. Multi-turn conversations {% id="4-multi-turn-conversations" %}

The Interactions API supports multi-turn conversations with two approaches:

*   **Stateful (recommended)**: Continue a conversation on the server using
    `previous_interaction_id`. Ideal for most chat and agentic workflows where
    you want the server to manage history and optimize caching.
*   **Stateless**: Manage the conversation history on the client by passing all
  previous turns (including intermediate model thought and tool steps) in each
    request.

{% tabs %}
{% tab title="Stateful (recommended)" %}
Chain interactions by passing `previous_interaction_id`. The server manages the
full conversation history for you.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

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

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

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

// Server-side state (recommended)
const interaction1 = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "I have 2 dogs in my house.",
});
console.log("Response 1:", interaction1.output_text);

const interaction2 = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "How many paws are in my house?",
  previous_interaction_id: interaction1.id,
});
console.log("Response 2:", interaction2.output_text);
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// Server-side state (recommended)
CreateModelInteraction params1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("I have 2 dogs in my house."))
        .build();

Interaction interaction1 =
    client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
System.out.println("Response 1: " + interaction1.outputText().orElse(""));

CreateModelInteraction params2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("How many paws are in my house?"))
        .previousInteractionId(interaction1.id().orElse(""))
        .build();

Interaction interaction2 =
    client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();
System.out.println("Response 2: " + interaction2.outputText().orElse(""));
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:  interactions.Model("gemini-3.8-flash"),
            Input:  interactions.NewInteractionsInput("Explain quantum computing in simple terms."),
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "I have 2 dogs in my house."
  }')

INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')
echo "Interaction 1 ID: $INTERACTION_ID"

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "How many paws are in my house?",
    "previous_interaction_id": "'$INTERACTION_ID'"
  }'
```

{% /tab %}
{% /tabs %}

{% /tab %}
{% tab title="Stateless" %}
Set `store=false` and manage conversation history on the client side. You must
preserve and resend all model-generated steps (including `thought` and
`function_call` steps) exactly as received.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

history = [
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "I have 2 dogs in my house."}]
    }
]

interaction1 = client.interactions.create(
    model="gemini-3.8-flash",
    store=False,
    input=history
)
print("Response 1:", interaction1.steps[-1].content[0].text)

for step in interaction1.steps:
    history.append(step.model_dump())

history.append({
    "type": "user_input",
    "content": [{"type": "text", "text": "How many paws are in my house?"}]
})

interaction2 = client.interactions.create(
    model="gemini-3.8-flash",
    store=False,
    input=history
)
print("Response 2:", interaction2.steps[-1].content[0].text)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const history = [
  {
    type: "user_input",
    content: [{ type: "text", text: "I have 2 dogs in my house." }]
  }
];

const interaction1 = await ai.interactions.create({
  model: "gemini-3.8-flash",
  store: false,
  input: history
});
console.log("Response 1:", interaction1.steps.at(-1).content[0].text);

history.push(...interaction1.steps);

history.push({
  type: "user_input",
  content: [{ type: "text", text: "How many paws are in my house?" }]
});

const interaction2 = await ai.interactions.create({
  model: "gemini-3.8-flash",
  store: false,
  input: history
});
console.log("Response 2:", interaction2.steps.at(-1).content[0].text);
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.UserInputStep;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

List<Step> history = new ArrayList<>();
history.add(
    UserInputStep.builder()
        .content(Arrays.asList(TextContent.builder().text("I have 2 dogs in my house.").build()))
        .build());

CreateModelInteraction params1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .store(false)
        .input(InteractionsInput.ofStep(history))
        .build();

Interaction interaction1 =
    client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
System.out.println("Response 1: " + interaction1.outputText().orElse(""));

interaction1.steps().ifPresent(history::addAll);

history.add(
    UserInputStep.builder()
        .content(Arrays.asList(TextContent.builder().text("How many paws are in my house?").build()))
        .build());

CreateModelInteraction params2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .store(false)
        .input(InteractionsInput.ofStep(history))
        .build();

Interaction interaction2 =
    client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();
System.out.println("Response 2: " + interaction2.outputText().orElse(""));
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Alex."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res1.Interaction.OutputText != nil {
        fmt.Println(*res1.Interaction.OutputText)
    }

    // 2. Second turn (passing PreviousInteractionID)
    res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What's my name?"),
            PreviousInteractionID: res1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res2.Interaction.OutputText != nil {
        fmt.Println(*res2.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# Turn 1: Send with store: false
RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "store": false,
    "input": [
      {
        "type": "user_input",
        "content": "I have 2 dogs in my house."
      }
    ]
  }')

MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')

# Turn 2: Build full history
HISTORY=$(jq -n \
  --argjson first_input '[{"type": "user_input", "content": "I have 2 dogs in my house."}]' \
  --argjson model_steps "$MODEL_STEPS" \
  --argjson second_input '[{"type": "user_input", "content": "How many paws are in my house?"}]' \
  '$first_input + $model_steps + $second_input')

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d "{
    \"model\": \"gemini-3.8-flash\",
    \"store\": false,
    \"input\": $HISTORY
  }"
```

**Response:**

```json
{
  "id": "v2_Chd...",
  "status": "completed",
  "usage": {
    "total_tokens": 240,
    "total_input_tokens": 60,
    "total_output_tokens": 20
  },
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "There are 8 paws in your house. 2 dogs \u00d7 4 paws = 8 paws."
        }
      ]
    }
  ],
  "object": "interaction",
  "model": "gemini-3.8-flash"
}
```

The second interaction returns a complete response object that includes only the
new steps, but is grounded in the previous turn's context. Learn more about
maintaining state in the [multi-turn conversations
guide](/docs/text-generation#multi-turn-conversations), or explore [stateless
mode](/docs/text-generation#stateless-conversations) for client-side history
management.
{% /tab %}
{% /tabs %}

{% /tab %}
{% /tabs %}

## 5. Multimodal understanding {% id="5-multimodal-understanding" %}

Gemini models understand images, audio, video, and documents natively. Pass
media alongside text in a single request.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

# Load a local image
with open("sample.jpg", "rb") as f:
    image_bytes = f.read()
image_b64 = base64.b64encode(image_bytes).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Compare this local image and this remote audio file."},
        {
            "type": "image",
            "data": image_b64,
            "mime_type": "image/jpeg"
        },
        {
            "type": "audio",
            "uri": "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",
            "mime_type": "audio/mp3"
        }
    ]
)
print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import fs from "fs";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

// Load a local image
const imageBytes = fs.readFileSync("sample.jpg");
const imageB64 = imageBytes.toString("base64");

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Compare this local image and this remote audio file." },
    {
      type: "image",
      data: imageB64,
      mime_type: "image/jpeg"
    },
    {
      type: "audio",
      uri: "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",
      mime_type: "audio/mp3"
    }
  ],
});
console.log(interaction.output_text);
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AudioContent;
import com.google.genai.gaos.models.interactions.AudioContentMimeType;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Arrays;
import java.util.Base64;

Client client = new Client();

// Load a local image
byte[] imageBytes = Files.readAllBytes(Path.of("sample.jpg"));
String imageB64 = Base64.getEncoder().encodeToString(imageBytes);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    TextContent.builder()
                        .text("Compare this local image and this remote audio file.")
                        .build(),
                    ImageContent.builder()
                        .data(imageB64)
                        .mimeType(ImageContentMimeType.IMAGE_JPEG)
                        .build(),
                    AudioContent.builder()
                        .uri("https://storage.googleapis.com/generativeai-downloads/data/sample.mp3")
                        .mimeType(AudioContentMimeType.AUDIO_MP3)
                        .build())))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("path/to/organ.jpg")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "What is in this image?",
                }),
                interactions.NewContent(interactions.ImageContent{
                    Data:     genai.Ptr(base64Image),
                    MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# Base64-encode local image
BASE64_IMAGE=$(base64 -w 0 sample.jpg)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "text",
        "text": "Compare this local image and this remote audio file."
      },
      {
        "type": "image",
        "data": "'$BASE64_IMAGE'",
        "mime_type": "image/jpeg"
      },
      {
        "type": "audio",
        "uri": "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",
        "mime_type": "audio/mp3"
      }
    ]
  }'
```

**Response:**

```json
{
  "id": "v1_Chd...",
  "status": "completed",
  "usage": {
    "total_tokens": 300
  },
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The local image displays a pipe organ while the remote audio file is a sample MP3 clip..."
        }
      ]
    }
  ],
  "object": "interaction",
  "model": "gemini-3.8-flash",
}
```

{% /tab %}
{% /tabs %}

Explore how to pass images, video, and audio files in the [image understanding
guide](/docs/image-understanding).

{% card-grid %}
{% card href="/docs/audio" title="Audio understanding" description="Transcribe, summarize, or answer questions about audio files." icon="hearing" %}{% /card %}
{% card href="/docs/video-understanding" title="Video understanding" description="Analyze video content, locate events, and describe actions." icon="videocam" %}{% /card %}
{% card href="/docs/document-processing" title="Document processing" description="Extract information from PDFs and other document formats." icon="description" %}{% /card %}
{% /card-grid %}

## 6. Multimodal generation {% id="6-multimodal-generation" %}

Gemini can generate images natively using the [Nano
Banana](/docs/image-generation) image models.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input="Generate an image of a futuristic city skyline at sunset",
)

with open("generated_image.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.1-flash-image",
  input: "Generate an image of a futuristic city skyline at sunset",
});

const generatedImage = interaction.output_image;
if (generatedImage && generatedImage.data) {
  const buffer = Buffer.from(generatedImage.data, "base64");
  fs.writeFileSync("generated_image.png", buffer);
}
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.1-flash-image"))
        .input(InteractionsInput.of("Generate an image of a futuristic city skyline at sunset"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputImage().isPresent()) {
  ImageContent generatedImage = interaction.outputImage().get();
  if (generatedImage.data().isPresent()) {
    byte[] imageBytes = Base64.getDecoder().decode(generatedImage.data().get());
    Files.write(Path.of("generated_image.png"), imageBytes);
  }
}
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    weatherTool := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_current_weather"),
        Description: genai.Ptr("Gets the current weather for a given location."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{
                    "type":        "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                },
            },
            "required": []string{"location"},
        },
    })

    // 1. Send prompt with tool declaration
    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("What is the weather like in Boston?"),
            Tools: []interactions.Tool{weatherTool},
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Check if the model requested a function call
    for _, step := range res.Interaction.Steps {
        if call := step.FunctionCallStep; call != nil {
            fmt.Printf("Function to call: %s\n", call.Name)
            fmt.Printf("Arguments: %v\n", call.Arguments)

            // 3. Execute your local function and send the result back
            finalRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
                Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
                    Model:                 interactions.Model("gemini-3.8-flash"),
                    PreviousInteractionID: res.Interaction.ID,
                    Input: interactions.NewInteractionsInput([]interactions.Step{
                        interactions.NewStep(interactions.FunctionResultStep{
                            Name:   genai.Ptr(call.Name),
                            CallID: call.ID,
                            Result: interactions.NewFunctionResultStepResultUnion(`{"temperature": "72F", "condition": "Sunny"}`),
                        }),
                    }),
                }),
            })
            if err != nil {
                log.Fatal(err)
            }

            if finalRes.Interaction.OutputText != nil {
                fmt.Println(*finalRes.Interaction.OutputText)
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "input": [
      {"type": "text", "text": "Generate an image of a futuristic city skyline at sunset"}
    ]
  }'
```

**Response:**

```json
{
  "id": "v1_Chd...",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "image",
          "data": "BASE64_ENCODED_IMAGE",
          "mime_type": "image/png"
        }
      ]
    }
  ],
  "object": "interaction",
  "model": "gemini-3.1-flash-image",
}
```

{% /tab %}
{% /tabs %}

When the model generates an image, it returns the base64-encoded image data in a
step within the `steps` array, as well as via the `output_image` convenience
property. Check out the [image generation guide](/docs/image-generation) to
learn about aspect ratios, image editing, and references.

{% card-grid %}
{% card href="/docs/speech-generation" title="Speech generation" description="Generate expressive, multi-speaker speech with Gemini 3.1 Flash TTS." icon="record_voice_over" %}{% /card %}
{% card href="/docs/music-generation" title="Music generation" description="Create clips and full-length songs with Lyria 3.5." icon="music_note" %}{% /card %}
{% /card-grid %}

## 7. Use structured output {% id="7-use-structured-output" %}

Configure the model to return JSON that matches a schema you define. Structured
output works with [Pydantic](https://docs.pydantic.dev/latest/) (Python) and
[Zod](https://zod.dev/) (JavaScript).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional

class Recipe(BaseModel):
    recipe_name: str = Field(description="Name of the recipe.")
    ingredients: List[str] = Field(description="List of ingredients.")
    prep_time_minutes: Optional[int] = Field(description="Prep time in minutes.")

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Give me a recipe for banana bread",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Recipe.model_json_schema()
    },
)

recipe = Recipe.model_validate_json(interaction.output_text)
print(recipe)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const ai = new GoogleGenAI({});

const recipeJsonSchema = {
  type: "object",
  properties: {
    recipe_name: { type: "string", description: "Name of the recipe." },
    ingredients: {
      type: "array",
      items: { type: "string" },
      description: "List of ingredients."
    },
    prep_time_minutes: {
      type: "integer",
      description: "Prep time in minutes."
    }
  },
  required: ["recipe_name", "ingredients"]
};

const recipeSchema = z.fromJSONSchema(recipeJsonSchema);

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "Give me a recipe for banana bread",
  response_format: {
    type: "text",
    mime_type: "application/json",
    schema: recipeJsonSchema
  },
});

const recipe = recipeSchema.parse(JSON.parse(interaction.output_text));
console.log(recipe);
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> recipeNameProp = new HashMap<>();
recipeNameProp.put("type", "string");
recipeNameProp.put("description", "Name of the recipe.");

Map<String, Object> itemsProp = new HashMap<>();
itemsProp.put("type", "string");

Map<String, Object> ingredientsProp = new HashMap<>();
ingredientsProp.put("type", "array");
ingredientsProp.put("items", itemsProp);
ingredientsProp.put("description", "List of ingredients.");

Map<String, Object> prepTimeProp = new HashMap<>();
prepTimeProp.put("type", "integer");
prepTimeProp.put("description", "Prep time in minutes.");

Map<String, Object> properties = new HashMap<>();
properties.put("recipe_name", recipeNameProp);
properties.put("ingredients", ingredientsProp);
properties.put("prep_time_minutes", prepTimeProp);

Map<String, Object> recipeJsonSchema = new HashMap<>();
recipeJsonSchema.put("type", "object");
recipeJsonSchema.put("properties", properties);
recipeJsonSchema.put("required", Arrays.asList("recipe_name", "ingredients"));

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            TextResponseFormat.builder()
                .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
                .schema(recipeJsonSchema)
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Give me a recipe for banana bread"))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Who won the latest Super Bowl and what was the score?"),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.GoogleSearch{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }

    // Optional: Inspect search queries and citations
    for _, step := range res.Interaction.Steps {
        if searchCall := step.GoogleSearchCallStep; searchCall != nil {
            fmt.Printf("Search queries: %v\n", searchCall.Arguments.Queries)
        } else if modelOut := step.ModelOutputStep; modelOut != nil {
            for _, part := range modelOut.Content {
                if textPart := part.TextContent; textPart != nil {
                    for _, annotation := range textPart.Annotations {
                        if citation := annotation.URLCitation; citation != nil {
                            var title, url string
                            if citation.Title != nil {
                                title = *citation.Title
                            }
                            if citation.URL != nil {
                                url = *citation.URL
                            }
                            fmt.Printf("Source: %s (%s)\n", title, url)
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Give me a recipe for banana bread",
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
          "recipe_name": { "type": "string", "description": "Name of the recipe." },
          "ingredients": {
            "type": "array",
            "items": { "type": "string" },
            "description": "List of ingredients."
          },
          "prep_time_minutes": {
            "type": "integer",
            "description": "Prep time in minutes."
          }
        },
        "required": ["recipe_name", "ingredients"]
      }
    }
  }'
```

**Response:**

```json
{
  "id": "v1_Chd...",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "{\n \"recipe_name\": \"Classic Banana Bread\",\n \"ingredients\": [\n \"3 ripe bananas, mashed\",\n \"1/3 cup melted butter\",\n \"3/4 cup sugar\",\n \"1 egg, beaten\",\n \"1 teaspoon vanilla extract\",\n \"1 teaspoon baking soda\",\n \"Pinch of salt\",\n \"1.5 cups all-purpose flour\"\n ],\n \"prep_time_minutes\": 15\n}"
        }
      ]
    }
  ],
  "object": "interaction",
  "model": "gemini-3.8-flash",
}
```
{% /tab %}
{% /tabs %}

The output text block contains a valid JSON string conforming exactly to the
requested schema. To learn how to define more complex structures and recursive
schemas, see the [structured output guide](/docs/structured-output).

## 8. Use tools {% id="8-use-tools" %}

Ground the model's response in real-time information with Google Search. The API
automatically searches, processes results, and returns citations.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Who won the euro 2024?",
    tools=[{"type": "google_search"}]
)

print(interaction.output_text)

# Print citations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text" and content_block.annotations:
                print("\nCitations:")
                for annotation in content_block.annotations:
                    if annotation.type == "url_citation":
                        print(f" [{annotation.title}]({annotation.url})")
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "Who won the euro 2024?",
  tools: [{ type: "google_search" }]
});

console.log(interaction.output_text);

// Print citations
for (const step of interaction.steps) {
  if (step.type === "model_output") {
    for (const contentBlock of step.content || []) {
      if (contentBlock.type === "text" && contentBlock.annotations) {
        console.log("\nCitations:");
        for (const annotation of contentBlock.annotations) {
          if (annotation.type === "url_citation") {
            console.log(` [${annotation.title}](${annotation.url})`);
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.URLCitation;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Who won the euro 2024?"))
        .tools(Arrays.asList(new GoogleSearch()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

// Print citations
for (Step step : interaction.steps().orElse(Collections.emptyList())) {
  if (step instanceof ModelOutputStep outputStep) {
    for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {
      if (contentBlock instanceof TextContent textContent && textContent.annotations().isPresent()) {
        System.out.println("\nCitations:");
        for (Annotation annotation : textContent.annotations().get()) {
          if (annotation instanceof URLCitation citation) {
            System.out.printf("  [%s](%s)%n", citation.title().orElse(""), citation.url().orElse(""));
          }
        }
      }
    }
  }
}
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Calculate the 20th Fibonacci number and verify if it is prime."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.CodeExecution{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if codeCall := step.CodeExecutionCallStep; codeCall != nil {
            fmt.Printf("Generated Code:\n%s\n", codeCall.Arguments.Code)
        } else if codeRes := step.CodeExecutionResultStep; codeRes != nil {
            fmt.Printf("Execution Output:\n%s\n", codeRes.Result)
        }
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Who won the euro 2024?",
    "tools": [{"type": "google_search"}]
  }'
```

**Response:**

```json
{
  "id": "v1_Chd...",
  "status": "completed",
  "steps": [
    {
      "type": "thought",
      "signature": "EvEFCu4F..."
    },
    {
      "type": "google_search_call",
      "arguments": {
        "queries": ["UEFA Euro 2024 winner"]
      }
    },
    {
      "type": "google_search_result",
      "call_id": "search_001",
      "result": [
        {
          "search_suggestions": ""
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Spain won Euro 2024, defeating England 2-1 in the final.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.uefa.com/euro2024",
              "title": "uefa.com",
              "start_index": 0,
              "end_index": 56
            }
          ]
        }
      ]
    }
  ],
  "object": "interaction",
  "model": "gemini-3.8-flash",
}
```
{% /tab %}
{% /tabs %}

The search steps are detailed within the interaction history, and the final
output includes inline citations pointing to web sources.

You can learn how to extract search citations in the [Google Search grounding
guide](/docs/google-search), or see how to combine multiple tools in the [tool
combination guide](/docs/tool-combination).

{% card-grid %}
{% card href="/docs/code-execution" title="Code execution" description="Run Python code in a secure sandboxed Borg environment." icon="code" %}{% /card %}
{% card href="/docs/url-context" title="URL context" description="Pass public web URLs directly to ground responses in webpage content." icon="link" %}{% /card %}
{% card href="/docs/file-search" title="File search" description="Index and search across uploaded documents and media files." icon="search" %}{% /card %}
{% card href="/docs/maps-grounding" title="Google Maps" description="Ground responses in real-world geospatial and location data." icon="map" %}{% /card %}
{% card href="/docs/computer-use" title="Computer use" description="Browser automation and screen interaction." icon="computer" %}{% /card %}
{% /card-grid %}

## 9. Call your own functions {% id="9-call-your-own-functions" %}

Function calling lets you connect the model to your code. You declare a
function's name and parameters, the model decides when to call it and returns
structured arguments, and you execute it locally and send the result back.

{% tabs %}
{% tab title="Stateful (recommended)" %}

{% tabs %}
{% tab label="Python" %}
```python
import json
from google import genai

client = genai.Client()

weather_tool = {
    "type": "function",
    "name": "get_current_temperature",
    "description": "Gets the current temperature for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city name, e.g. San Francisco",
            },
        },
        "required": ["location"],
    },
}

available_functions = {
    "get_current_temperature": lambda location: {
        "location": location, "temperature": "22", "unit": "celsius"
    },
}

user_input = "What is the temperature in London?"
previous_id = None

while True:
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        input=user_input,
        tools=[weather_tool],
        previous_interaction_id=previous_id,
    )

    function_results = []
    for step in interaction.steps:
        if step.type == "function_call":
            result = available_functions[step.name](**step.arguments)
            print(f"Called {step.name}({step.arguments}) → {result}")
            function_results.append({
                "type": "function_result",
                "name": step.name,
                "call_id": step.id,
                "result": [{"type": "text", "text": json.dumps(result)}],
            })

    if not function_results:
        break

    user_input = function_results
    previous_id = interaction.id

print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const weatherTool = {
  type: "function",
  name: "get_current_temperature",
  description: "Gets the current temperature for a given location.",
  parameters: {
    type: "object",
    properties: {
      location: {
        type: "string",
        description: "The city name, e.g. San Francisco",
      },
    },
    required: ["location"],
  },
};

const availableFunctions = {
  get_current_temperature: ({ location }) => ({
    location, temperature: "22", unit: "celsius"
  }),
};

let input = "What is the temperature in London?";
let previousId = null;
let interaction;

while (true) {
  interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input,
    tools: [weatherTool],
    previous_interaction_id: previousId,
  });

  const functionResults = [];
  for (const step of interaction.steps) {
    if (step.type === "function_call") {
      const result = availableFunctions[step.name](step.arguments);
      console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);
      functionResults.push({
        type: "function_result",
        name: step.name,
        call_id: step.id,
        result: [{ type: "text", text: JSON.stringify(result) }],
      });
    }
  }

  if (functionResults.length === 0) break;

  input = functionResults;
  previousId = interaction.id;
}

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.FunctionResultStep;
import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

Client client = new Client();

Map<String, Object> locationProp = new HashMap<>();
locationProp.put("type", "string");
locationProp.put("description", "The city name, e.g. San Francisco");

Map<String, Object> properties = new HashMap<>();
properties.put("location", locationProp);

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");
parameters.put("properties", properties);
parameters.put("required", Arrays.asList("location"));

Function weatherTool =
    Function.builder()
        .name("get_current_temperature")
        .description("Gets the current temperature for a given location.")
        .parameters(parameters)
        .build();

InteractionsInput userInput = InteractionsInput.of("What is the temperature in London?");
String previousId = null;
Interaction interaction = null;

while (true) {
  CreateModelInteraction.Builder paramsBuilder =
      CreateModelInteraction.builder()
          .model(Model.of("gemini-3.8-flash"))
          .input(userInput)
          .tools(Arrays.asList(weatherTool));
  if (previousId != null) {
    paramsBuilder.previousInteractionId(previousId);
  }

  interaction =
      client.interactions.create(CreateInteractionRequestBody.of(paramsBuilder.build())).interaction().get();

  List<Step> functionResults = new ArrayList<>();
  for (Step step : interaction.steps().orElse(Collections.emptyList())) {
    if (step instanceof FunctionCallStep fcStep) {
      String resultJson = "{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}";
      System.out.printf(
          "Called %s(%s) -> %s%n",
          fcStep.name().orElse(""), fcStep.arguments().orElse(Collections.emptyMap()), resultJson);
      functionResults.add(
          FunctionResultStep.builder()
              .name(fcStep.name().orElse(""))
              .callId(fcStep.id().orElse(""))
              .result(
                  FunctionResultStepResultUnion.of(
                      Arrays.asList(TextContent.builder().text(resultJson).build())))
              .build());
    }
  }

  if (functionResults.isEmpty()) {
    break;
  }

  userInput = InteractionsInput.ofStep(functionResults);
  previousId = interaction.id().orElse(null);
}

System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Turn 1: Create a CSV file in the sandbox
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Write a Python script to save a CSV file 'sales.csv' with 5 rows of sample data."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.CodeExecution{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    var env *interactions.CreateModelInteractionEnvironment
    if turn1.Interaction.EnvironmentID != nil {
        env = genai.Ptr(interactions.NewCreateModelInteractionEnvironment(*turn1.Interaction.EnvironmentID))
    }

    // Turn 2: Reuse the sandbox environment to analyze the file created in Turn 1
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            PreviousInteractionID: turn1.Interaction.ID,
            Environment:           env,
            Input:                 interactions.NewInteractionsInput("Now read 'sales.csv' and compute the total revenue."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.CodeExecution{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# Turn 1: Send prompt with function declaration
RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is the temperature in London?",
    "tools": [{
      "type": "function",
      "name": "get_current_temperature",
      "description": "Gets the current temperature for a given location.",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "The city name"}
        },
        "required": ["location"]
      }
    }]
  }')

INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')
FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')
FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')
echo "Function: $FC_NAME, Call ID: $FC_ID"

# Turn 2: Send function result back
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "'$INTERACTION_ID'",
    "input": [{
      "type": "function_result",
      "name": "'$FC_NAME'",
      "call_id": "'$FC_ID'",
      "result": [{"type": "text", "text": "{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}"}]
    }],
    "tools": [{
      "type": "function",
      "name": "get_current_temperature",
      "description": "Gets the current temperature for a given location.",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "The city name"}
        },
        "required": ["location"]
      }
    }]
  }'
```

{% /tab %}
{% /tabs %}

{% /tab %}
{% tab title="Stateless" %}
You can also use function calling in stateless mode by managing the conversation
history on the client side and setting `store=false`. In stateless mode, you
must pass the full history of the conversation in the `input` field of each
subsequent request. This history must include:

1.  The initial `user_input` step.
2.  All model-generated steps returned in Turn 1 (including `thought` and
    `function_call` steps) exactly as received.
3.  The `function_result` step containing the output of your executed function.

{% tabs %}
{% tab label="Python" %}
```python
import json
from google import genai

client = genai.Client()

weather_tool = {
    "type": "function",
    "name": "get_current_temperature",
    "description": "Gets the current temperature for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city name, e.g. San Francisco",
            },
        },
        "required": ["location"],
    },
}

available_functions = {
    "get_current_temperature": lambda location: {
        "location": location, "temperature": "22", "unit": "celsius"
    },
}

history = [
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "What is the temperature in London?"}]
    }
]

while True:
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        store=False,
        input=history,
        tools=[weather_tool],
    )

    function_results = []
    for step in interaction.steps:
        history.append(step.model_dump())
        if step.type == "function_call":
            result = available_functions[step.name](**step.arguments)
            print(f"Called {step.name}({step.arguments}) → {result}")
            fn_result = {
                "type": "function_result",
                "name": step.name,
                "call_id": step.id,
                "result": [{"type": "text", "text": json.dumps(result)}],
            }
            function_results.append(fn_result)
            history.append(fn_result)

    if not function_results:
        break

print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const weatherTool = {
  type: "function",
  name: "get_current_temperature",
  description: "Gets the current temperature for a given location.",
  parameters: {
    type: "object",
    properties: {
      location: {
        type: "string",
        description: "The city name, e.g. San Francisco",
      },
    },
    required: ["location"],
  },
};

const availableFunctions = {
  get_current_temperature: ({ location }) => ({
    location, temperature: "22", unit: "celsius"
  }),
};

const history = [
  {
    type: "user_input",
    content: [{ type: "text", text: "What is the temperature in London?" }]
  }
];

let interaction;

while (true) {
  interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    store: false,
    input: history,
    tools: [weatherTool],
  });

  const functionResults = [];
  for (const step of interaction.steps) {
    history.push(step);
    if (step.type === "function_call") {
      const result = availableFunctions[step.name](step.arguments);
      console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);
      const fnResult = {
        type: "function_result",
        name: step.name,
        call_id: step.id,
        result: [{ type: "text", text: JSON.stringify(result) }],
      };
      functionResults.push(fnResult);
      history.push(fnResult);
    }
  }

  if (functionResults.length === 0) break;
}

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.FunctionResultStep;
import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.UserInputStep;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

Client client = new Client();

Map<String, Object> locationProp = new HashMap<>();
locationProp.put("type", "string");
locationProp.put("description", "The city name, e.g. San Francisco");

Map<String, Object> properties = new HashMap<>();
properties.put("location", locationProp);

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");
parameters.put("properties", properties);
parameters.put("required", Arrays.asList("location"));

Function weatherTool =
    Function.builder()
        .name("get_current_temperature")
        .description("Gets the current temperature for a given location.")
        .parameters(parameters)
        .build();

List<Step> history = new ArrayList<>();
history.add(
    UserInputStep.builder()
        .content(Arrays.asList(TextContent.builder().text("What is the temperature in London?").build()))
        .build());

Interaction interaction = null;

while (true) {
  CreateModelInteraction params =
      CreateModelInteraction.builder()
          .model(Model.of("gemini-3.8-flash"))
          .store(false)
          .input(InteractionsInput.ofStep(history))
          .tools(Arrays.asList(weatherTool))
          .build();

  interaction =
      client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

  List<Step> functionResults = new ArrayList<>();
  for (Step step : interaction.steps().orElse(Collections.emptyList())) {
    history.add(step);
    if (step instanceof FunctionCallStep fcStep) {
      String resultJson = "{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}";
      System.out.printf(
          "Called %s(%s) -> %s%n",
          fcStep.name().orElse(""), fcStep.arguments().orElse(Collections.emptyMap()), resultJson);
      FunctionResultStep fnResult =
          FunctionResultStep.builder()
              .name(fcStep.name().orElse(""))
              .callId(fcStep.id().orElse(""))
              .result(
                  FunctionResultStepResultUnion.of(
                      Arrays.asList(TextContent.builder().text(resultJson).build())))
              .build();
      functionResults.add(fnResult);
      history.add(fnResult);
    }
  }

  if (functionResults.isEmpty()) {
    break;
  }
}

System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    recipeSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "recipe_name":       map[string]any{"type": "string"},
            "prep_time_minutes": map[string]any{"type": "integer"},
            "ingredients": map[string]any{
                "type":  "array",
                "items": map[string]any{"type": "string"},
            },
        },
        "required": []string{"recipe_name", "prep_time_minutes", "ingredients"},
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Give me a quick recipe for chocolate chip cookies."),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(interactions.TextResponseFormat{
                    MimeType: interactions.TextResponseFormatMimeTypeApplicationJSON.ToPointer(),
                    Schema:   recipeSchema,
                }),
            )),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# Turn 1: Send request with tools and store: false
RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "store": false,
    "input": [
      {
        "type": "user_input",
        "content": "What is the temperature in London?"
      }
    ],
    "tools": [{
      "type": "function",
      "name": "get_current_temperature",
      "description": "Gets the current temperature for a given location.",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "The city name"}
        },
        "required": ["location"]
      }
    }]
  }')

# Extract model steps (thought, function_call)
MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')
FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')
FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')
echo "Function: $FC_NAME, Call ID: $FC_ID"

# Assume local execution returns:
RESULT="{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}"

# Reconstruct history for Turn 2
HISTORY=$(jq -n \
  --argjson first_input '[{"type": "user_input", "content": "What is the temperature in London?"}]' \
  --argjson model_steps "$MODEL_STEPS" \
  --arg fc_name "$FC_NAME" \
  --arg fc_id "$FC_ID" \
  --arg result "$RESULT" \
  '$first_input + $model_steps + [{"type": "function_result", "name": $fc_name, "call_id": $fc_id, "result": [{"type": "text", "text": $result}]}]')

# Turn 2: Send the full history
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d "{
    \"model\": \"gemini-3.8-flash\",
    \"store\": false,
    \"input\": $HISTORY,
    \"tools\": [{
      \"type\": \"function\",
      \"name\": \"get_current_temperature\",
      \"description\": \"Gets the current temperature for a given location.\",
      \"parameters\": {
        \"type\": \"object\",
        \"properties\": {
          \"location\": {\"type\": \"string\", \"description\": \"The city name\"}
        },
        \"required\": [\"location\"]
      }
    }]
  }"
```

**Response:**

During Turn 1, the model returns a response with status `requires_action` and
the `function_call` step:

```json
{
  "id": "v1_Chd...",
  "status": "requires_action",
  "steps": [
    {
      "type": "function_call",
      "id": "call_abc123",
      "name": "get_current_temperature",
      "arguments": {
        "location": "London"
      }
    }
  ],
  "object": "interaction",
  "model": "gemini-3.8-flash"
}
```

After you run the function locally and submit the result (Turn 2), the final
completed interaction returns:

```json
{
  "id": "v1_Chd...",
  "status": "completed",
  "steps": [
    {
      "type": "function_call",
      "id": "call_abc123",
      "name": "get_current_temperature",
      "arguments": {
        "location": "London"
      }
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The temperature in London is currently 22°C."
        }
      ]
    }
  ],
  "object": "interaction",
  "model": "gemini-3.8-flash",
}
```
{% /tab %}
{% /tabs %}

{% /tab %}
{% /tabs %}

For advanced features like parallel function calling or function choice modes,
see the [function calling guide](/docs/function-calling).

## 10. Run a managed agent {% id="10-run-a-managed-agent" %}

Managed agents run in a remote sandbox with access to tools like code execution
and file management. Pass an `agent` instead of a `model` and set
`environment="remote"`.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment="remote",
)
print(f"Environment: {interaction.environment_id}")
print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  agent: "antigravity-preview-09-2026",
  input: "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
  environment: "remote",
});
console.log(`Environment: ${interaction.environment_id}`);
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("antigravity-preview-09-2026")
        .input(
            InteractionsInput.of(
                "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents."))
        .environment(CreateAgentInteractionEnvironment.of("remote"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Environment: " + interaction.environmentId().orElse(""));
System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-pro"),
            Input: interactions.NewInteractionsInput("Solve this logic puzzle: Three gods A, B, and C are called True, False, and Random..."),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel:     interactions.ThinkingLevelHigh.ToPointer(),
                ThinkingSummaries: interactions.ThinkingSummariesAuto.ToPointer(),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Print thought summaries if returned
    for _, step := range res.Interaction.Steps {
        if thought := step.ThoughtStep; thought != nil {
            for _, part := range thought.Summary {
                if part.TextContent != nil {
                    fmt.Printf("Thought Summary: %s\n", part.TextContent.Text)
                }
            }
        }
    }

    if res.Interaction.OutputText != nil {
        fmt.Printf("Answer: %s\n", *res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    "environment": "remote"
  }'
```

{% /tab %}
{% /tabs %}

You can also define and save [custom agents](/docs/custom-agents) with your own
instructions, skills, and data sources.

{% card-grid %}
{% card href="/docs/managed-agents-quickstart" title="Quickstart" description="Make your first agent call, stream responses, and build a custom agent." icon="rocket_launch" %}{% /card %}
{% card href="/docs/antigravity-agent" title="Antigravity Agent" description="Capabilities, tools, multimodal input, and pricing for the default agent." icon="smart_toy" %}{% /card %}
{% card href="/docs/aistudio-agents" title="Agents in AI Studio" description="Visual playground for prototyping agents without writing code." icon="experiment" %}{% /card %}
{% /card-grid %}

## 11. Run tasks in the background {% id="11-run-tasks-in-the-background" %}

Set `background=True` to run long tasks asynchronously. Poll for results with
`interactions.get()`.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",
    background=True,
)
print(f"Started background task: {interaction.id}")
print(f"Status: {interaction.status}")

# Poll for completion
while True:
    result = client.interactions.get(interaction.id)
    print(f"Status: {result.status}")
    if result.status == "completed":
        print(f"\nResult:\n{result.output_text}")
        break
    elif result.status == "failed":
        print(f"Failed: {result.error}")
        break
    time.sleep(5)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",
  background: true,
});
console.log(`Started background task: ${interaction.id}`);
console.log(`Status: ${interaction.status}`);

// Poll for completion
while (true) {
  const result = await ai.interactions.get(interaction.id);
  console.log(`Status: ${result.status}`);
  if (result.status === "completed") {
    console.log(`\nResult:\n${result.output_text}`);
    break;
  } else if (result.status === "failed") {
    console.log(`Failed: ${JSON.stringify(result.errors)}`);
    break;
  }
  await new Promise(r => setTimeout(r, 5000));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Write a detailed analysis of the impact of artificial intelligence on modern healthcare."))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
String interactionId = interaction.id().orElse("");
System.out.println("Started background task: " + interactionId);
System.out.println("Status: " + interaction.status().map(InteractionStatus::value).orElse(""));

// Poll for completion
while (true) {
  Interaction result =
      client.interactions.get(new GetInteractionByIdRequest(interactionId)).interaction().get();
  String status = result.status().map(InteractionStatus::value).orElse("");
  System.out.println("Status: " + status);
  if ("completed".equals(status)) {
    System.out.println("\nResult:\n" + result.outputText().orElse(""));
    break;
  } else if ("failed".equals(status)) {
    System.out.println("Failed: " + result.errors().orElse(null));
    break;
  }
  Thread.sleep(5000);
}
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Start a Deep Research agent in the background
    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:      interactions.AgentOption("deep-research-preview-04-2026"),
            Input:      interactions.NewInteractionsInput("Research the competitive landscape of solid-state EV batteries in 2026."),
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    interaction := res.Interaction
    fmt.Printf("Started research job: %s\n", *interaction.ID)

    // Poll until completion
    for interaction.Status != interactions.InteractionStatusCompleted && interaction.Status != interactions.InteractionStatusFailed {
        time.Sleep(10 * time.Second)
        getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        interaction = getRes.Interaction
        fmt.Printf("Current status: %s\n", interaction.Status)
    }

    if interaction.Status == interactions.InteractionStatusCompleted {
        if interaction.OutputText != nil {
            fmt.Println(*interaction.OutputText)
        }
    } else {
        fmt.Printf("Research failed: %v\n", interaction.Errors)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# Start a background task
RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",
    "background": true
  }')

INTERACTION_ID=$(echo "$RESPONSE" | jq -r '.id')
echo "Started background task: $INTERACTION_ID"

# Poll for completion
while true; do
  RESULT=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H "Api-Revision: 2026-05-20")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "completed" ]; then
    echo "$RESULT" | jq -r '.steps[] | select(.type=="model_output") | .content[] | select(.type=="text") | .text'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Failed"
    break
  fi
  sleep 5
done
```

**Response:**

The initial response returns immediately with status `in_progress`:

```json
{
  "id": "v1_abc123",
  "status": "in_progress",
  "object": "interaction",
  "model": "gemini-3.8-flash"
}
```

Once the background task is fully executed, checking the interaction state
returns:

```json
{
  "id": "v1_abc123",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Artificial intelligence has transformed modern healthcare in several..."
        }
      ]
    }
  ],
  "object": "interaction",
  "model": "gemini-3.8-flash",
}
```
{% /tab %}
{% /tabs %}

Read about running models and agents asynchronously in the [background execution
guide](/docs/background-execution).

## What's next {% id="whats-next" %}

-   [Text generation](/docs/text-generation): System instructions, generation
    config, and advanced text patterns.
-   [Image generation](/docs/image-generation): Aspect ratios, image editing,
    and style references.
-   [Image understanding](/docs/image-understanding): Classification, object
    detection, and visual Q&A.
-   [Thinking](/docs/thinking): Use chain-of-thought reasoning for complex
    tasks.
-   [Function calling](/docs/function-calling): Parallel, compositional, and
    constrained function modes.
-   [Google Search](/docs/google-search): Grounding, citations, and search
    suggestions.
-   [Managed Agents](/docs/managed-agents-quickstart): Pre-built agents with
    code execution and file management.
-   [Deep Research](/docs/deep-research): Autonomous multi-step research with
    planning and synthesis.
-   [Structured output](/docs/structured-output): JSON schemas, enums, and
    recursive type definitions.

# Using Gemini API keys
Source: https://aistudio.google.com/docs/api-key
Description: Get your Gemini API key and start building in less than 5 minutes using the Interactions API.

To use the Gemini API, you must authenticate your requests. You can
authenticate using a standard or authorization API key.

{% button href="https://aistudio.google.com/apikey" variant="ais" %}Create or view a Gemini API Key{% /button %}

## API key types: Standard versus Authorization {% id="api-keys" %}

API keys provide access to the Gemini API, but their security characteristics
differ. The Gemini API is transitioning from standard API keys to authorization
keys to improve security:

* **Standard API keys**: Associate requests with a Google Cloud project for
    billing and quota purposes. Standard keys don't identify a caller, which
    limits the granularity of permissions and access control they can support.

* **Authorization (auth) keys**: Bound directly to a Google Cloud service
    account. When you use an authorization key, your requests are processed
    under the identity of that bound service account, enabling granular access
    control. Authorization keys are restricted to the Generative Language API
    (Gemini API) by default and provide fast-acting leaked key enforcement that
    quickly stops the usage of leaked keys detected by our systems.

To ensure secure usage, Gemini API will move from standard keys to auth keys:

* **Auth keys default**: Starting May 28, 2026, all new API keys created in
    Google AI Studio are automatically created as auth keys.

* **Unrestricted keys rejected**: The Gemini API rejects requests
    from **unrestricted standard keys**. Standard API keys that have explicit
    restrictions applied continue to work. This restriction prevents the
    unauthorized use of keys that might be shared publicly or linked to other
    services.

{% callout type="note" %}
Requests authenticated by authorization keys are not recorded in
Google Cloud service account usage metrics.
{% /callout %}

## Managing API keys in Google AI Studio {% id="getting-started" %}

You can manage your projects and keys directly in [Google AI Studio](https://aistudio.google.com/apikey).

### Google Cloud projects {% id="google-cloud-projects" %}

Every Gemini API key is associated with a [Google Cloud project](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
Google Cloud projects manage billing, collaborators, and permissions. Google AI
Studio provides a lightweight interface to access these projects.

* **Default project**: If you are a new user, Google AI Studio automatically
    creates a default Google Cloud project and API key after you accept the
    Terms of Service. You can rename this project by navigating to the
    **Projects** view in your dashboard.

* **Existing projects**: If you already have a Google Cloud account, AI
    Studio does not create a default project. Instead, you must import your
    existing projects.

### Importing projects {% id="import-projects" %}

By default, Google AI Studio does not display all of your Google Cloud
projects. You must import the projects you want to use:

1. Go to [Google AI Studio](https://aistudio.google.com).
2. Open the **Dashboard** from the left panel and select **Projects**.
3. Click the **Import projects** button.
4. Search for and select the Google Cloud project you want to import, then
    click **Import**.

5. Once imported, navigate to the **API Keys** page in the dashboard to
    create a key in that project.

### Troubleshooting key creation permissions {% id="key-permission" %}

If the **Create API key** button is unavailable and displays the message:
*"You do not have permission to create a key in this project"*, you lack the
required IAM permissions.

Ask your Google Cloud project or organization administrator to grant you a role
containing the following permissions (such as Project Editor):

* `resourcemanager.projects.get`: Allows AI Studio to verify the project.
* `apikeys.keys.create`: Allows key generation.
* `serviceusage.services.enable`: Ensures the Generative Language API is
    enabled.

* `iam.serviceAccounts.create`: Required to create the linked service account.
* `iam.serviceAccountApiKeyBindings.create`: Binds the service account to the
    API key.

If you cannot get administrative access, you can create a new Google Cloud
project that is not associated with an organization to generate your keys.

### Unknown keys on the Usage page {% id="unknown-keys" %}

The [Usage page](https://aistudio.google.com/usage) in Google AI Studio groups
requests it can't match to a named API key in the project under
**(unknown keys)**. This includes keys deleted more than 30 days ago, keys
without a display name, and requests made with other credentials, such as OAuth.

## Creating keys in the Google Cloud console {% id="cloud-console" %}

Google AI Studio only displays keys that are unrestricted or restricted to the
Gemini API. If you can't use AI Studio, or you want to manage all of your API
keys in one place, follow the Cloud documentation on [creating an API key](https://cloud.google.com/docs/authentication/api-keys#create).
Creating a Gemini API key requires binding it to a
[service account](https://cloud.google.com/iam/docs/service-account-overview).

## Setting up your environment {% id="setup-environment" %}

Once you have a key, configure your environment to use it securely in your
applications.

### Option 1: Use environment variables (Recommended) {% id="set-api-env-var" %}

Set the environment variable `GEMINI_API_KEY` or `GOOGLE_API_KEY`. The Gemini
API client libraries automatically detect and use these variables. If both are
set, `GOOGLE_API_KEY` takes precedence.

Select your operating system to set the variable:

{% tabs %}
{% tab label="Linux/macOS - Bash" %}
Verify if you have a bash configuration file:

```posix-terminal
~/.bashrc
```

If not, create one and open it:

```posix-terminal
touch ~/.bashrc && open ~/.bashrc
```

Add the export command at the end of the file:

```posix-terminal
export GEMINI_API_KEY=[YOUR_API_KEY_HERE]
```

Save the file, then apply the changes:

```posix-terminal
source ~/.bashrc
```
{% /tab %}
{% tab label="macOS - Zsh" %}
Verify if you have a zsh configuration file:

```posix-terminal
~/.zshrc
```

If not, create one and open it:

```posix-terminal
touch ~/.zshrc && open ~/.zshrc
```

Add the export command:

```posix-terminal
export GEMINI_API_KEY=[YOUR_API_KEY_HERE]
```

Save the file, then apply the changes:

```posix-terminal
source ~/.zshrc
```
{% /tab %}
{% tab label="Windows" %}
1. Search for "Environment Variables" in the Windows search bar.
2. Click **Environment Variables** in the System Properties dialog.
3. Under **User variables** or **System variables**, click **New...**.
4. Set the variable name to `GEMINI_API_KEY` and the value to your API key.
5. Click **OK** to save. Open a new terminal session to load the variable.
{% /tab %}
{% /tabs %}

### Option 2: Provide the API key explicitly in code {% id="provide-api-key-explicitly" %}

You can pass the API key explicitly when initializing the client. Only do this
if you cannot use environment variables.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

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

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = Client.builder().apiKey("YOUR_API_KEY").build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain how AI works in a few sentences."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey: "{{ '<var>YOUR_API_KEY</var>' }}",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Explain how AI works in a few sentences."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain how AI works in a few words"
  }'
```
{% /tab %}
{% /tabs %}

## Security and secret management {% id="security" %}

Treat your Gemini API key like a password. If compromised, others can consume
your project's quota, incur unexpected billing charges, and access private
resources.

### Critical security rules {% id="critical-security-rules" %}

* **Keep keys confidential**: Never check API keys into source control systems
    like Git.

* **Never expose keys client-side in production**: Do not hardcode API keys
    directly in web or mobile apps. Keys compiled in client-side code can be
    extracted by users. To secure client-side apps, run a backend proxy
    server to make the actual API calls.

### Secret management best practices {% id="secret-management" %}

* **Environment variables**: Read keys from environment variables rather than
    configuration files.

* **Secret Manager**: For production, store your keys in a secure secret store
    such as [Google Cloud Secret Manager](https://cloud.google.com/secret-manager).

* **Billing alerts**: Set up billing alerts in the Google Cloud console to
    notify you if usage or costs spike.

### Leak response checklist {% id="leak-response" %}

If you suspect your API key has been leaked:

1. **Generate a new key**: Create a replacement key in Google AI Studio or the
    Cloud console.

2. **Update your application**: Deploy your code using the new key.
3. **Disable or delete the compromised key**: Disable the leaked key in the
    Cloud console once the new key is verified. Do not delete the old key until
    the new key is fully active to avoid application downtime.

4. **Audit usage**: Check billing logs and API usage in the Google Cloud
    console to identify unauthorized activity.

## Restricting and securing your keys {% id="restricting-keys" %}

Adding restrictions to your API keys minimizes the potential damage if a key is
compromised.

### Apply request origin restrictions {% id="request-origin-restrictions" %}

Origin restrictions limit which IP addresses, websites, or applications can use
your key.

1. Go to the [Google Cloud console credentials page](https://console.cloud.google.com/apis/credentials).

2. Select your project, and click the name of the API key you want to restrict.
3. Under **Application restrictions**, select **IP addresses** (or the
    appropriate restriction type for your environment).

4. Specify the allowed IP addresses or ranges, then click **Save**.

### Securing unrestricted standard API keys {% id="secure-unrestricted-keys" %}

To continue using the Gemini API, you must secure any unrestricted keys.

#### Method A: Restrict the key to the Gemini API only (AI Studio) {% id="method-a-restrict-the-key-to-the-gemini-api-only-ai-studio" %}

If you only use the key for the Gemini API, secure it directly in AI Studio:

1. On the **API Keys** page in [Google AI Studio](https://aistudio.google.com/api-keys), locate keys marked with the
    **Unrestricted** label.

2. Hover over the label and click **Add restrictions** in the dialog.
3. Select **Restrict to Gemini API only**.
4. Click **Restrict key** to confirm.

{% callout type="note" %}
To restrict an API key, you must have the `apikeys.keys.update` permission
on the associated Google Cloud project. This permission is included in roles
like **API Keys Admin** or **Editor**.
{% /callout %}

#### Method B: Restrict the key for other services (Google Cloud console) {% id="method-b-restrict-the-key-for-other-services-google-cloud-console" %}

If the key is shared with other Google APIs (not recommended), restrict it in
the Cloud console. **Note: Gemini API requests using this key will fail after
these restrictions are applied.**

1. Visit the [Google Cloud console credentials page](https://console.cloud.google.com/apis/credentials).

2. Select the project and the API key.
3. Under **API restrictions**, select **Restrict key**.
4. From the drop-down, select the APIs you want this key to access. Do not
    select the **Generative Language API**.

5. Click **Save**. Create a separate, restricted key in AI Studio to continue
    using the Gemini API.

### Blocked dormant keys {% id="blocked-keys" %}

Starting May 7, 2026, the Gemini API blocks unrestricted API keys that have
been dormant for an extended period. These keys show a **Blocked** tag in AI
Studio. You must generate a new key or use an existing restricted key to
continue.

## Migrate to an auth key {% id="migrate-to-auth-key" %}

Follow these steps to create a new auth API key and update your applications:

1. Go to the [AI Studio API Keys page](https://aistudio.google.com/api-keys).
2. Check the **Key Type** column to identify any keys listed as **Standard**.
3. Click **Create API key** to generate a new key. All new keys created in
    AI Studio are automatically created as auth keys.

4. Copy the new auth API key.
5. Update your application code, environment variables, and any deployment
    configurations to use the new auth API key.

6. Test your application to confirm it works correctly with the new key.
7. Once verified, delete or revoke your old traffic key to prevent misuse.

{% callout type="note" %}
If you don't see your keys, you may need to import your Cloud projects
      into AI Studio. Refer to the [import projects](/docs/api-key#import-projects) section
      for instructions.
{% /callout %}

## Limitations {% id="limitations" %}

Google AI Studio imposes the following project and key management limitations:

* You can create a maximum of 10 projects at a time from the Google AI Studio
    **Projects** page.

* The **API keys** and **Projects** pages display a maximum of 100 keys and 50
    projects.

* Only API keys that are unrestricted or restricted specifically to the
    Generative Language API (Gemini API) are displayed.

For advanced project management or to modify keys with other restrictions, use
the [Google Cloud console credentials page](https://console.cloud.google.com/apis/credentials).

# Gemini Developer API pricing
Source: https://aistudio.google.com/docs/pricing
Description: Gemini Developer API Pricing

Start building free of charge with generous limits, then scale up with prepaid
and pay-as-you-go pricing for your production-ready applications.

{% card-grid %}

{% card title="Free" %}

For developers and small projects getting started with the Gemini API.

{% hr /%}

{% section class="checkmark-icon-list" %}

* {% icon name="check_circle" /%} Limited access to certain models
* {% icon name="check_circle" /%} Free input & output tokens
* {% icon name="check_circle" /%} Google AI Studio access
* {% icon name="check_circle" /%} Content used to improve our products{% sup
%}[*](/docs/terms){% /sup %}
{% /section %}

{% section class="center-content align-bottom" %}
{% button href="https://aistudio.google.com" %}
Get started for Free
{% /button %}
{% /section %}
{% /card %}

{% card title="Paid" %}

For production applications that require higher volumes and advanced features.

{% hr /%}

{% section class="checkmark-icon-list" %}

* {% icon name="check_circle" /%} Higher rate limits for production deployments
* {% icon name="check_circle" /%} Access to Context caching
* {% icon name="check_circle" /%} Batch API (50% cost reduction)
* {% icon name="check_circle" /%} Access to Google's most advanced models
* {% icon name="check_circle" /%} Content **not** used to improve our products{%
sup %}[*](/docs/terms){% /sup %}
{% /section %}

{% section class="center-content align-bottom" %}
{% button href="https://aistudio.google.com/api-keys" %}
Upgrade to Paid
{% /button %}
{% /section %}
{% /card %}

{% card title="Enterprise" %}

For enterprise deployments, powered by
[Gemini Enterprise Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform).

{% hr /%}

{% section class="checkmark-icon-list" %}

* {% icon name="check_circle" /%} All features in Paid, plus optional access to:
* {% icon name="check_circle" /%} Dedicated support channels
* {% icon name="check_circle" /%} Advanced security & compliance
* {% icon name="check_circle" /%} Provisioned throughput
* {% icon name="check_circle" /%} Volume-based discounts (based on usage)
* {% icon name="check_circle" /%} ML ops, model garden and more
{% /section %}

{% section class="center-content align-bottom" %}
{% button href="https://cloud.google.com/contact" %}
Contact Sales
{% /button %}
{% /section %}
{% /card %}

{% /card-grid %}

## Gemini 4 Argon {% id="gemini-4-argon" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-4-argon`](/docs/models/gemini-4-argon)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-4-argon"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our flagship reasoning model, built for complex software engineering, deep
mathematical and scientific problem solving, autonomous multi-step agents, and
long-decode generation up to 1M tokens.

{% callout type="note" %}
Gemini 4 Argon is not available on the Free tier. Every token the model processes is counted and billed, including thinking tokens and internal tool system instructions and function declarations when using grounding.
{% /callout %}

{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $2.00 through November 30, 2026. \
  $4.00 starting December 1, 2026.
---

*   Output price (including thinking tokens)
*   Not available
*   $10.00 through November 30, 2026. \
  $20.00 starting December 1, 2026.
---

*   Context caching price
*   Not available
*   $0.10 through November 30, 2026. \
  $0.20 starting December 1, 2026. \
  Implicit caching only (explicit caching is not supported).
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   Not available
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $1.00 through November 30, 2026. \
  $2.00 starting December 1, 2026.
---

*   Output price (including thinking tokens)
*   Not available
*   $5.00 through November 30, 2026. \
  $10.00 starting December 1, 2026.
---

*   Context caching price
*   Not available
*   $0.05 through November 30, 2026. \
  $0.10 starting December 1, 2026. \
  Implicit caching only (explicit caching is not supported).
---

*   Used to improve our products
*   Not available
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $1.00 through November 30, 2026. \
  $2.00 starting December 1, 2026.
---

*   Output price (including thinking tokens)
*   Not available
*   $5.00 through November 30, 2026. \
  $10.00 starting December 1, 2026.
---

*   Context caching price
*   Not available
*   $0.05 through November 30, 2026. \
  $0.10 starting December 1, 2026. \
  Implicit caching only (explicit caching is not supported).
---

*   Used to improve our products
*   Not available
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.
{% /tab %}

{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $3.60 through November 30, 2026. \
  $7.20 starting December 1, 2026.
---

*   Output price (including thinking tokens)
*   Not available
*   $18.00 through November 30, 2026. \
  $36.00 starting December 1, 2026.
---

*   Context caching price
*   Not available
*   $0.18 through November 30, 2026. \
  $0.36 starting December 1, 2026. \
  Implicit caching only (explicit caching is not supported).
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   Not available
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.
{% /tab %}
{% tab title="Contributor" %}

{% callout type="note" %}
The Gemini API Contributor Tier is offered as a private preview on an
invite-only basis. Speed and reliability are equivalent to
[Standard Tier inference](/docs/optimization). Eligible users will be invited by
email and see a callout in AI Studio.
{% /callout %}

{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD{% sup %}*{% /sup %}
---

*   Input price
*   Not available
*   $1.00
---

*   Output price (including thinking tokens)
*   Not available
*   $5.00
---

*   Context caching price
*   Not available
*   $0.05 \
  Implicit caching only (explicit caching is not supported).
---

*   Used to improve our products
*   Not available
*   [Yes](/docs/logs-policy#contributor-tier)
{% /table %}

{% sup %}*{% /sup %} Discounts and model availability are subject to change.
{% /tab %}
{% /tabs %}

## Gemini 3.8 Flash {% id="gemini-3.8-flash" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-3.8-flash`](/docs/models/gemini-3.8-flash)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.8-flash"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our most intelligent Flash model, engineered for long-horizon software
engineering, autonomous agents, and complex enterprise workflows.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.75 through December 31, 2026. \
  $1.50 starting January 1, 2027.
---

*   Output price (including thinking tokens)
*   Free of charge
*   $3.75 through December 31, 2026. \
  $7.50 starting January 1, 2027.
---

*   Context caching price
*   Free of charge
*   $0.075 through December 31, 2026. \
  $0.15 starting January 1, 2027. \
  $0.50 / 1,000,000 tokens per hour (storage price) through December 31, 2026. \
  $1.00 / 1,000,000 tokens per hour (storage price) starting January 1, 2027.
---

*   Grounding with Google Search
*   Not available
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.375 through December 31, 2026. \
  $0.75 starting January 1, 2027.
---

*   Output price (including thinking tokens)
*   Not available
*   $1.875 through December 31, 2026. \
  $3.75 starting January 1, 2027.
---

*   Context caching price
*   Not available
*   $0.0375 through December 31, 2026. \
  $0.075 starting January 1, 2027. \
  $0.50 / 1,000,000 tokens per hour (storage price) through December 31, 2026. \
  $1.00 / 1,000,000 tokens per hour (storage price) starting January 1, 2027.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.375 through December 31, 2026. \
  $0.75 starting January 1, 2027.
---

*   Output price (including thinking tokens)
*   Not available
*   $1.875 through December 31, 2026. \
  $3.75 starting January 1, 2027.
---

*   Context caching price
*   Not available
*   $0.0375 through December 31, 2026. \
  $0.075 starting January 1, 2027. \
  $0.50 / 1,000,000 tokens per hour (storage price) through December 31, 2026. \
  $1.00 / 1,000,000 tokens per hour (storage price) starting January 1, 2027.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}

{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $1.35 through December 31, 2026. \
  $2.70 starting January 1, 2027.
---

*   Output price (including thinking tokens)
*   Free of charge
*   $6.75 through December 31, 2026. \
  $13.50 starting January 1, 2027.
---

*   Context caching price
*   Free of charge
*   $0.135 through December 31, 2026. \
  $0.27 starting January 1, 2027. \
  $0.50 / 1,000,000 tokens per hour (storage price) through December 31, 2026. \
  $1.00 / 1,000,000 tokens per hour (storage price) starting January 1, 2027.
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Contributor" %}

{% callout type="note" %}
The Gemini API Contributor Tier is offered as a private preview on an
invite-only basis. Speed and reliability are equivalent to
[Standard Tier inference](/docs/optimization). Eligible users will be invited by
email and see a callout in AI Studio.
{% /callout %}

{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD{% sup %}*{% /sup %}
---

*   Input price
*   Free of charge
*   $0.375
---

*   Output price (including thinking tokens)
*   Free of charge
*   $1.875
---

*   Context caching price
*   Free of charge
*   $0.0375 \
  $0.50 / 1,000,000 tokens per hour (storage price)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [Yes](/docs/logs-policy#contributor-tier)
{% /table %}

{% sup %}*{% /sup %} Discounts and model availability are subject to change.
{% /tab %}
{% /tabs %}

## Gemini 3.6 Flash {% id="gemini-3.6-flash" %}

{% two-column-layout %}
{% left-column %}
*[`gemini-3.6-flash`](/docs/models/gemini-3.6-flash)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.6-flash"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our previous generation Flash model, balancing speed and multimodal capabilities
across general agentic and everyday tasks.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.75 through December 31, 2026. \
  $1.50 starting January 1, 2027.
---

*   Output price (including thinking tokens)
*   Free of charge
*   $3.75 through December 31, 2026. \
  $7.50 starting January 1, 2027.
---

*   Context caching price
*   Free of charge
*   $0.075 through December 31, 2026. \
  $0.15 starting January 1, 2027. \
  $0.50 / 1,000,000 tokens per hour (storage price) through December 31, 2026. \
  $1.00 / 1,000,000 tokens per hour (storage price) starting January 1, 2027.
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.375 through December 31, 2026. \
  $0.75 starting January 1, 2027.
---

*   Output price (including thinking tokens)
*   Not available
*   $1.875 through December 31, 2026. \
  $3.75 starting January 1, 2027.
---

*   Context caching price
*   Not available
*   $0.0375 through December 31, 2026. \
  $0.075 starting January 1, 2027. \
  $0.50 / 1,000,000 tokens per hour (storage price) through December 31, 2026. \
  $1.00 / 1,000,000 tokens per hour (storage price) starting January 1, 2027.
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.375 through December 31, 2026. \
  $0.75 starting January 1, 2027.
---

*   Output price (including thinking tokens)
*   Not available
*   $1.875 through December 31, 2026. \
  $3.75 starting January 1, 2027.
---

*   Context caching price
*   Not available
*   $0.0375 through December 31, 2026. \
  $0.075 starting January 1, 2027. \
  $0.50 / 1,000,000 tokens per hour (storage price) through December 31, 2026. \
  $1.00 / 1,000,000 tokens per hour (storage price) starting January 1, 2027.
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $1.35 through December 31, 2026. \
  $2.70 starting January 1, 2027.
---

*   Output price (including thinking tokens)
*   Free of charge
*   $6.75 through December 31, 2026. \
  $13.50 starting January 1, 2027.
---

*   Context caching price
*   Free of charge
*   $0.135 through December 31, 2026. \
  $0.27 starting January 1, 2027. \
  $0.50 / 1,000,000 tokens per hour (storage price) through December 31, 2026. \
  $1.00 / 1,000,000 tokens per hour (storage price) starting January 1, 2027.
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.

## Gemini 3.5 Transcribe Live {% id="gemini-3.5-transcribe-live" %}

{% two-column-layout %}
{% left-column %}
*[`gemini-3.5-transcribe-live`](/docs/models/gemini-3.5-transcribe)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com?model=gemini-3.5-transcribe-live"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our low-latency, real-time speech-to-text model for bidirectional streaming
audio transcription over WebSockets.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $3.50 or $0.005/min{% sup %}*{% /sup %} (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $21.00 or $0.004/min{% sup %}*{% /sup %} (text)
---

*   Grounding with Google Search
*   Not Supported
*
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Estimated pricing is based on 25 audio tokens per second
for input and 175 text tokens per minute for output, for an effective blended
rate of ~$0.009 per min for Live Transcribe.

## Gemini 3.5 Transcribe {% id="gemini-3.5-transcribe" %}

{% two-column-layout %}
{% left-column %}
*[`gemini-3.5-transcribe`](/docs/models/gemini-3.5-transcribe)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com?model=gemini-3.5-transcribe"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our speech-to-text model with automatic language detection, speaker diarization,
word-level timestamps, and custom vocabulary biasing.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $2.00 or $0.003/min{% sup %}*{% /sup %} (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $12.00 or $0.002/min{% sup %}*{% /sup %} (text)
---

*   Grounding with Google Search
*   Not Supported
*
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Estimated pricing is based on 25 audio tokens per second
for input and 175 text tokens per minute for output, for an effective blended
rate of ~$0.005 per min for Transcribe.

## Gemini 3.5 Flash-Lite {% id="gemini-3.5-flash-lite" %}

{% two-column-layout %}
{% left-column %}
*[`gemini-3.5-flash-lite`](/docs/models/gemini-3.5-flash-lite)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.5-flash-lite"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

A cost-efficient model, optimized for high-volume agentic tasks, translation,
and simple data processing.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.30 (text / image / video / audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $2.50
---

*   Context caching price
*   Not available
*   $0.03  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.15 (text / image / video / audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $1.25
---

*   Context caching price
*   Not available
*   $0.015  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.15 (text / image / video / audio)
---

*   Output price (including thinking tokens)
*   Not available
*   $1.25
---

*   Context caching price
*   Not available
*   $0.02  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.
{% /tab %}
{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.54 (text / image / video / audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $4.50
---

*   Context caching price
*   Not available
*   $0.05  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.
{% /tab %}
{% tab title="Contributor" %}

{% callout type="note" %}
The Gemini API Contributor Tier is offered as a private preview on an
invite-only basis. Speed and reliability are equivalent to
[Standard Tier inference](/docs/optimization). Eligible users will be invited by
email and see a callout in AI Studio.
{% /callout %}

{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD{% sup %}*{% /sup %}
---

*   Input price
*   Free of charge
*   $0.15 (text / image / video / audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $1.25
---

*   Context caching price
*   Not available
*   $0.015  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [Yes](/docs/logs-policy#contributor-tier)
{% /table %}

{% sup %}*{% /sup %} Discounts and model availability are subject to change.
{% /tab %}
{% /tabs %}

## Gemini Omni Flash {% id="gemini-omni-1.1-flash" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-omni-1.1-flash`](/docs/models/gemini-omni-flash)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-omni-1.1-flash"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our next-generation video generation and editing model, now generally available
to developers on the paid tier of the Gemini API.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $1.50 (text / image / video / audio)
---

*   Output price (including thinking tokens)
*   Not available
*   $9.00 (text)  \
  $17.50 (video){% sup %}*{% /sup %}
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Billing is based on total output token consumption,
calculated at a rate of 5,792 tokens per second of 720p video. Under Standard
pricing, this equates to an effective price of approximately $0.10 per second.

## Gemini 3.8 Live, Gemini 3.8 Live Extended Thinking, and Gemini 3.1 Flash Live Preview {% id="gemini-3.8-live" %}

{% two-column-layout %} {% left-column class="center-vertically" %}
*[`gemini-3.8-live`](/docs/models/gemini-3.8-live),
[`gemini-3.8-live-extended-thinking`](/docs/models/gemini-3.8-live-extended-thinking),
[`gemini-3.1-flash-live-preview`](/docs/models/gemini-3.1-flash-live-preview)*
{% /left-column %} {% right-column class="center-vertically right-align" %} {%
button href="https://aistudio.google.com/live?model=gemini-3.8-live"
variant="ais" %} Try it in Google AI Studio {% /button %} {% /right-column %} {%
/two-column-layout %}

{% hr /%}

Our low-latency, audio-to-audio models optimized for real-time dialogue with
acoustic nuance detection, numeric precision, and multimodal awareness.

{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.75 (text)  \
  $3.00 or $0.005/min (audio)  \
  $1.00 or $0.002/min (image/video)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $4.50 (text)  \
  $12.00 or $0.018/min (audio)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Supported
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

## Gemini 3.5 Live Translate {% id="gemini-3.5-live-translate-preview" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-3.5-live-translate-preview`](/docs/models/gemini-3.5-live-translate-preview)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/live?model=gemini-3.5-live-translate-preview"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our low-latency, real-time speech to speech translation model that supports 70+
languages.

{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $3.50 or $0.0053/min{% sup %}*{% /sup %} (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $21.00 or $0.0315/min{% sup %}*{% /sup %} (audio)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Billing is based on total input and output audio token
consumption, calculated at a rate of 25 tokens per second of audio, equating to
an effective price of approximately $0.0368 per minute.

## Gemini 3.1 Flash-Lite {% id="gemini-3.1-flash-lite" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-3.1-flash-lite`](/docs/models/gemini-3.1-flash-lite)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.1-flash-lite"
variant="ais"%}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

A cost-efficient model, optimized for high-volume agentic tasks, translation,
and simple data processing.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.25 (text / image / video)  \
  $0.50 (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $1.50
---

*   Context caching price
*   Not available
*   $0.025 (text / image / video)  \
  $0.05 (audio)  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.125 (text / image / video)  \
  $0.25 (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $0.75
---

*   Context caching price
*   Not available
*   $0.0125 (text / image / video)  \
  $0.025 (audio)  \
  $0.50 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.125 (text / image / video)  \
  $0.25 (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $0.75
---

*   Context caching price
*   Not available
*   $0.0125 (text / image / video)  \
  $0.025 (audio)  \
  $0.50 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.45 (text / image / video)  \
  $0.90 (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $2.70
---

*   Context caching price
*   Not available
*   $0.045 (text / image / video)  \
  $0.09 (audio)  \
  $1.80 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.

## Gemini 3.1 Pro Preview {% id="gemini-3.1-pro-preview" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-3.1-pro-preview`](/docs/models/gemini-3.1-pro-preview) and
[`gemini-3.1-pro-preview-customtools`](/docs/models/gemini-3.1-pro-preview#gemini-31-pro-preview-customtools)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.1-pro-preview"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our 3rd generation Pro model, built for multimodal understanding, agentic
capabilities, and vibe-coding.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $2.00, prompts <= 200k tokens  \
  $4.00, prompts > 200k tokens
---

*   Output price (including thinking tokens)
*   Not available
*   $12.00, prompts <= 200k tokens  \
  $18.00, prompts > 200k
---

*   Context caching price
*   Not available
*   $0.20, prompts <= 200k tokens  \
  $0.40, prompts > 200k  \
  $4.50 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   Not available
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $1.00, prompts <= 200k tokens  \
  $2.00, prompts > 200k tokens
---

*   Output price (including thinking tokens)
*   Not available
*   $6.00, prompts <= 200k tokens  \
  $9.00, prompts > 200k
---

*   Context caching price
*   Not available
*   *Same as Standard*  \
  $0.20, prompts <= 200k tokens  \
  $0.40, prompts > 200k  \
  $4.50 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   Not available
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $1.00, prompts <= 200k tokens  \
  $2.00, prompts > 200k tokens
---

*   Output price (including thinking tokens)
*   Not available
*   $6.00, prompts <= 200k tokens  \
  $9.00, prompts > 200k
---

*   Context caching price
*   Not available
*   *Same as Standard*  \
  $0.20, prompts <= 200k tokens  \
  $0.40, prompts > 200k  \
  $4.50 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   Not available
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.
{% /tab %}
{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $3.60, prompts <= 200k tokens  \
  $7.20, prompts > 200k tokens
---

*   Output price (including thinking tokens)
*   Not available
*   $21.60, prompts <= 200k tokens  \
  $32.40, prompts > 200k
---

*   Context caching price
*   Not available
*   $0.36, prompts <= 200k tokens  \
  $0.72, prompts > 200k  \
  $8.10 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   Not available
*   [No](/docs/terms)
{% /table %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.
{% /tab %}
{% tab title="Contributor" %}

{% callout type="note" %}
The Gemini API Contributor Tier is offered as a private preview on an
invite-only basis. Speed and reliability are equivalent to
[Standard Tier inference](/docs/optimization). Eligible users will be invited by
email and see a callout in AI Studio.
{% /callout %}

{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD{% sup %}*{% /sup %}
---

*   Input price
*   Not available
*   $1.00, prompts <= 200k tokens  \
  $2.00, prompts > 200k tokens
---

*   Output price (including thinking tokens)
*   Not available
*   $6.00, prompts <= 200k tokens  \
  $9.00, prompts > 200k tokens
---

*   Context caching price
*   Not available
*   $0.10, prompts <= 200k tokens  \
  $0.20, prompts > 200k tokens  \
  $4.50 / 1,000,000 tokens per hour (storage price)
---

*   Used to improve our products
*   Not available
*   [Yes](/docs/logs-policy#contributor-tier)
{% /table %}

{% sup %}*{% /sup %} Discounts and model availability are subject to change.
{% /tab %}
{% /tabs %}

## Gemini Nano Banana 2.1 🍌 {% id="gemini-nano-banana-2.1" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-nano-banana-2.1`](/docs/models/gemini-nano-banana-2.1)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-nano-banana-2.1"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

An update to Nano Banana 2 (Gemini 3.1 Flash Image), built for high-efficiency
image generation and conversational editing with improved visual quality,
multi-turn character consistency, accurate text rendering, and search-grounded
generation across 1K, 2K, and 4K resolutions.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $1.50 (text/image/video)
---

*   Output price
*   Not available
*   $7.50 (text and thinking)  \
    $30.00 (images)  \
    Equivalent to $0.0336 per 1K image{% sup %}*{% /sup %},  \
    $0.0504 per 2K image{% sup %}*{% /sup %},  \
    and $0.113 per 4K image{% sup %}*{% /sup %}.
---

*   Grounding with Google Web and Image Search{% sup %}**{% /sup %}
*   Not available
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests for text and image-based grounding (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.75 (text/image/video)
---

*   Output price
*   Not available
*   $3.75 (text and thinking)  \
    $15.00 (images)  \
    Equivalent to $0.0168 per 1K image{% sup %}*{% /sup %},  \
    $0.0252 per 2K image{% sup %}*{% /sup %},  \
    and $0.0567 per 4K image{% sup %}*{% /sup %}.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}
{% sup %}*{% /sup %} Image output is priced at $30 per 1,000,000 tokens
(Standard) and $15 per 1,000,000 tokens (Batch). Output images at 1K
(1024x1024px) consume 1120 tokens and are equivalent to $0.0336 per image.
Output images at 2K (2048x2048px) consume 1680 tokens and are equivalent to
$0.0504 per image. Output images at 4K (4096x4096px) consume 3780 tokens and are
equivalent to $0.113 per image.

{% sup %}**{% /sup %} A customer-submitted request to Gemini may result in one
or more queries to Google Search. You will be charged for each individual search
query performed. Retrieved context (text or images) provided by Grounding with
Google Search is not charged as input tokens.

## Gemini 3.1 Flash Image (Nano Banana 2) 🍌 {% id="gemini-3.1-flash-image" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-3.1-flash-image`](/docs/models/gemini-3.1-flash-image)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.1-flash-image"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Designed for speed and efficiency, the Gemini 3.1 Flash Image generation model
is effective for quick, interactive responses and high throughput.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.50 (text/image)
---

*   Output price
*   Not available
*   $3 (text and thinking)  \
  $60.00 (images)  \
  Equivalent to $0.045 per 0.5K image{% sup %}*{% /sup %}  \
  $0.067 per 1K image{% sup %}*{% /sup %},  \
  $0.101 per 2K image{% sup %}*{% /sup %},  \
  and $0.151 per 4K image{% sup %}*{% /sup %}.
---

*   Grounding with Google Web and Image Search{% sup %}**{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests for text and image-based grounding (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Image output is priced at $60 per 1,000,000 tokens. Output
images at 0.5K (512px) consume 747 tokens and are equivalent to $0.045 per
image. Output images at 1K (1024x1024px) consume 1120 tokens and are equivalent
to $0.067 per image. Output images at 2K (2048x2048px) consume 1680 tokens and
are equivalent to $0.101 per image. Output images at 4K (4096x4096px) consume
2520 tokens and are equivalent to $0.151 per image.

## Gemini 3.1 Flash Lite Image (Nano Banana 2 Lite) 🍌 {% id="gemini-3.1-flash-lite-image" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-3.1-flash-lite-image`](/docs/models/gemini-3.1-flash-lite-image)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.1-flash-lite-image"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Designed as the efficiency specialist of the image generation family, the Gemini
3.1 Flash Lite Image model is designed for ultra-low latency and cost-effective
image generation and editing.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.25 (text/image/video)
---

*   Output price
*   Not available
*   $1.50 (text and thinking)  \
  $30.00 (images)  \
  Equivalent to $0.0336 per 1K resolution image{% sup %}*{% /sup %}
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.125 (text/image/video)
---

*   Output price
*   Not available
*   $0.75 (text and thinking)  \
  $15.00 (images)  \
  Equivalent to $0.0168 per 1K resolution image{% sup %}*{% /sup %}
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Image output is priced at $30 per 1,000,000 tokens. Output
images at 1K (1024x1024px) consume 1120 tokens and are equivalent to $0.0336 per
image.

## Gemini 3.8 Flash TTS {% id="gemini-3.8-flash-tts" %}
{% two-column-layout %}
{% left-column %}
*[`gemini-3.8-flash-tts`](/docs/models/gemini-3.8-flash-tts)*
{% /left-column %}
{% right-column %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.8-flash-tts"
variant="ais"
class="right-align" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our 3.8 Flash Text-to-Speech audio model engineered for studio-grade voice fidelity, expressive acting, and long-form stability.
{% tabs %}
{% tab title="Standard" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Free of charge
* $0.50 (text) through December 31, 2026. \
  $1.00 (text) starting January 1, 2027.
---

* Output price
* Free of charge
* $9.00 (audio) through December 31, 2026. \
  $18.00 (audio) starting January 1, 2027. \
  Equivalent to $0.00225 per 10s audio{% sup %}*{% /sup %} through December 31, 2026. \
  Equivalent to $0.0045 per 10s audio{% sup %}*{% /sup %} starting January 1, 2027.
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Not available
* $0.25 (text) through December 31, 2026. \
  $0.50 (text) starting January 1, 2027.
---

* Output price
* Not available
* $4.50 (audio) through December 31, 2026. \
  $9.00 (audio) starting January 1, 2027. \
  Equivalent to $0.001125 per 10s audio{% sup %}*{% /sup %} through December 31, 2026. \
  Equivalent to $0.00225 per 10s audio{% sup %}*{% /sup %} starting January 1, 2027.
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Flex" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Not available
* $0.25 (text) through December 31, 2026. \
  $0.50 (text) starting January 1, 2027.
---

* Output price
* Not available
* $4.50 (audio) through December 31, 2026. \
  $9.00 (audio) starting January 1, 2027. \
  Equivalent to $0.001125 per 10s audio{% sup %}*{% /sup %} through December 31, 2026. \
  Equivalent to $0.00225 per 10s audio{% sup %}*{% /sup %} starting January 1, 2027.
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Priority" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Free of charge
* $0.90 (text) through December 31, 2026. \
  $1.80 (text) starting January 1, 2027.
---

* Output price
* Free of charge
* $16.20 (audio) through December 31, 2026. \
  $32.40 (audio) starting January 1, 2027. \
  Equivalent to $0.00405 per 10s audio{% sup %}*{% /sup %} through December 31, 2026. \
  Equivalent to $0.0081 per 10s audio{% sup %}*{% /sup %} starting January 1, 2027.
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Audio tokens correspond to 25 tokens per second of audio.

## Gemini 3.8 Flash-Lite TTS {% id="gemini-3.8-flash-lite-tts" %}
{% two-column-layout %}
{% left-column %}
*[`gemini-3.8-flash-lite-tts`](/docs/models/gemini-3.8-flash-lite-tts)*
{% /left-column %}
{% right-column %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.8-flash-lite-tts"
variant="ais"
class="right-align" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our 3.8 Flash-Lite Text-to-Speech audio model optimized for high-throughput, low-latency, and cost-efficient conversational speech.
{% tabs %}
{% tab title="Standard" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Free of charge
* $0.50 (text) through December 31, 2026. \
  $1.00 (text) starting January 1, 2027.
---

* Output price
* Free of charge
* $6.00 (audio) through December 31, 2026. \
  $12.00 (audio) starting January 1, 2027. \
  Equivalent to $0.0015 per 10s audio{% sup %}*{% /sup %} through December 31, 2026. \
  Equivalent to $0.003 per 10s audio{% sup %}*{% /sup %} starting January 1, 2027.
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Not available
* $0.25 (text) through December 31, 2026. \
  $0.50 (text) starting January 1, 2027.
---

* Output price
* Not available
* $3.00 (audio) through December 31, 2026. \
  $6.00 (audio) starting January 1, 2027. \
  Equivalent to $0.00075 per 10s audio{% sup %}*{% /sup %} through December 31, 2026. \
  Equivalent to $0.0015 per 10s audio{% sup %}*{% /sup %} starting January 1, 2027.
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Flex" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Not available
* $0.25 (text) through December 31, 2026. \
  $0.50 (text) starting January 1, 2027.
---

* Output price
* Not available
* $3.00 (audio) through December 31, 2026. \
  $6.00 (audio) starting January 1, 2027. \
  Equivalent to $0.00075 per 10s audio{% sup %}*{% /sup %} through December 31, 2026. \
  Equivalent to $0.0015 per 10s audio{% sup %}*{% /sup %} starting January 1, 2027.
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Priority" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Free of charge
* $0.90 (text) through December 31, 2026. \
  $1.80 (text) starting January 1, 2027.
---

* Output price
* Free of charge
* $10.80 (audio) through December 31, 2026. \
  $21.60 (audio) starting January 1, 2027. \
  Equivalent to $0.0027 per 10s audio{% sup %}*{% /sup %} through December 31, 2026. \
  Equivalent to $0.0054 per 10s audio{% sup %}*{% /sup %} starting January 1, 2027.
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Audio tokens correspond to 25 tokens per second of audio.

## Gemini 3.1 Flash TTS Preview {% id="gemini-3.1-flash-tts-preview" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-3.1-flash-tts-preview`](/docs/models/gemini-3.1-flash-tts-preview)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.1-flash-tts-preview"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our 3.1 Flash Text-to-Speech audio model optimized for price-performant,
low-latency, controllable speech generation.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $1.00 (text)
---

*   Output price
*   Free of charge
*   $20.00 (audio)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.50 (text)
---

*   Output price
*   Not available
*   $10.00 (audio)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Audio tokens correspond to 25 tokens per second of audio.

## Gemini 3 Flash Preview {% id="gemini-3-flash-preview" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-3-flash-preview`](/docs/models/gemini-3-flash-preview)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com?model=gemini-3-flash-preview"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our legacy Flash model, providing baseline speed and intelligence.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.50 (text / image / video)  \
  $1.00 (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $3.00
---

*   Context caching price
*   Free of charge
*   $0.05 (text / image / video)  \
  $0.10 (audio)  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.25 (text / image / video)  \
  $0.50 (audio)
---

*   Output price (including thinking tokens)
*   Not available
*   $1.50
---

*   Context caching price
*   Not available
*   *Same as Standard*  \
  $0.05 (text / image / video)  \
  $0.10 (audio)  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.25 (text / image / video)  \
  $0.50 (audio)
---

*   Output price (including thinking tokens)
*   Not available
*   $1.50
---

*   Context caching price
*   Not available
*   *Same as Standard*  \
  $0.05 (text / image / video)  \
  $0.10 (audio)  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.90 (text / image / video)  \
  $1.80 (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $5.40
---

*   Context caching price
*   Free of charge
*   $0.09 (text / image / video)  \
  $0.18 (audio)  \
  $1.80 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search{% sup %}*{% /sup %}
*   Not available{% sup %}**{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Grounding with Google Maps
*   Not available{% sup %}**{% /sup %}
*   5,000 requests per month (free, shared across all Gemini 3 and newer models), then $14 / 1,000
    search queries.
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} A customer-submitted request to Gemini may result in one or
more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}**{% /sup %} Can be tested in Google AI Studio.

## Gemini 3 Pro Image (Nano Banana Pro) 🍌 {% id="gemini-3-pro-image" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-3-pro-image`](/docs/models/gemini-3-pro-image)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/prompts/new_chat?model=gemini-3-pro-image"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our native image generation model, optimized for speed, flexibility, and
contextual understanding. **Text input and output** is priced the same as
[Gemini 3.1 Pro](/docs/pricing#gemini-3.1-pro-preview).
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $2.00 (text/image),  \
  equivalent to $0.0011 per image{% sup %}*{% /sup %}
---

*   Output price
*   Not available
*   $12.00 (text and thinking)  \
  $120.00 (images)  \
  Equivalent to $0.134 per 1K/2K image{% sup %}**{% /sup %}  \
  and $0.24 per 4K image{% sup %}**{% /sup %}
---

*   Grounding with Google Search{% sup %}***{% /sup %}
*   Not available{% sup %}****{% /sup %}
*   5,000 free search requests per month (shared across all Gemini 3 and newer models),
    then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

*   Used to improve our products
*   N/A
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Image input is set at 560 tokens or $0.0011 per image.

{% sup %}**{% /sup %} Image output is priced at $120 per 1,000,000 tokens.
Output images from 1024x1024px (1K) and up to 2048x2048px (2K) consume 1120
tokens and are equivalent to $0.134 per image. Output images up to 4096x4096px
(4K) consume 2000 tokens and are equivalent to $0.24 per image.

{% sup %}***{% /sup %} A customer-submitted request to Gemini may result in one
or more queries to Google Search. You will be charged for each individual search
query performed.

{% sup %}****{% /sup %} Can be tested in Google AI Studio.

## Gemini 2.5 Pro {% id="gemini-2.5-pro" %}

*[`gemini-2.5-pro`](/docs/models/gemini-2.5-pro)*

{% hr /%}

{% callout type="caution" %}
Gemini 2.5 Pro (`gemini-2.5-pro`) is
[deprecated](/docs/deprecations#gemini-2.5-pro-models) and is no longer
available to select in Google AI Studio. Effective December 1, 2026, all API
requests to `gemini-2.5-pro` will automatically route to
[Gemini 3.8 Flash (`gemini-3.8-flash`)](/docs/models/gemini-3.8-flash) and be
billed at [Gemini 3.8 Flash rates](/docs/pricing#gemini-3.8-flash).
{% /callout %}

A Pro model which excels at coding and complex reasoning tasks.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $1.25, prompts <= 200k tokens  \
  $2.50, prompts > 200k tokens
---

*   Output price (including thinking tokens)
*   Free of charge
*   $10.00, prompts <= 200k tokens  \
  $15.00, prompts > 200k
---

*   Context caching price
*   Not available
*   $0.125, prompts <= 200k tokens  \
  $0.25, prompts > 200k  \
  $4.50 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Not available
*   1,500 RPD (free), then $35 / 1,000 grounded prompts
---

*   Grounding with Google Maps
*   Not available
*   10,000 RPD (free), then $25 / 1,000 grounded prompts
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.625, prompts <= 200k tokens  \
  $1.25, prompts > 200k tokens
---

*   Output price (including thinking tokens)
*   Not available
*   $5.00, prompts <= 200k tokens  \
  $7.50, prompts > 200k
---

*   Context caching price
*   Not available
*   $0.125, prompts <= 200k tokens  \
  $0.25, prompts > 200k  \
  $4.50 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Not available
*   1,500 RPD (free), then $35 / 1,000 grounded prompts
---

*   Grounding with Google Maps
*   Not available
*   Not available
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.625, prompts <= 200k tokens  \
  $1.25, prompts > 200k tokens
---

*   Output price (including thinking tokens)
*   Not available
*   $5.00, prompts <= 200k tokens  \
  $7.50, prompts > 200k
---

*   Context caching price
*   Not available
*   $0.125, prompts <= 200k tokens  \
  $0.25, prompts > 200k  \
  $4.50 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Not available
*   1,500 RPD (free), then $35 / 1,000 grounded prompts
---

*   Grounding with Google Maps
*   Not available
*   Not available
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $2.25, prompts <= 200k tokens  \
  $4.50, prompts > 200k tokens
---

*   Output price (including thinking tokens)
*   Free of charge
*   $18.00, prompts <= 200k tokens  \
  $27.00, prompts > 200k
---

*   Context caching price
*   Not available
*   $0.225, prompts <= 200k tokens  \
  $0.45, prompts > 200k  \
  $8.10 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Not available
*   1,500 RPD (free), then $35 / 1,000 grounded prompts
---

*   Grounding with Google Maps
*   Not available
*   10,000 RPD (free), then $25 / 1,000 grounded prompts
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

## Gemini 2.5 Flash {% id="gemini-2.5-flash" %}

*[`gemini-2.5-flash`](/docs/models/gemini-2.5-flash)*

{% hr /%}

{% callout type="caution" %}
Gemini 2.5 Flash (`gemini-2.5-flash`) is
[deprecated](/docs/deprecations#gemini-2.5-flash-models) and is no longer
available to select in Google AI Studio. Effective December 1, 2026, all API
requests to `gemini-2.5-flash` will automatically route to
[Gemini 3.5 Flash-Lite (`gemini-3.5-flash-lite`)](/docs/models/gemini-3.5-flash-lite)
and be billed at
[Gemini 3.5 Flash-Lite rates](/docs/pricing#gemini-3.5-flash-lite).
{% /callout %}

Our first hybrid reasoning model which supports a 1M token context window and
has thinking budgets.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.30 (text / image / video)  \
  $1.00 (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $2.50
---

*   Context caching price
*   Not available
*   $0.03 (text / image / video)  \
  $0.1 (audio)  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Free of charge, up to 500 RPD (limit shared with Flash-Lite RPD)
*   1,500 RPD (free, limit shared with Flash-Lite RPD), then $35 / 1,000
    grounded prompts
---

*   Grounding with Google Maps
*   500 RPD
*   1,500 RPD (free), then $25 / 1,000 grounded prompts
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.15 (text / image / video)  \
  $0.50 (audio)
---

*   Output price (including thinking tokens)
*   Not available
*   $1.25
---

*   Context caching price
*   Not available
*   $0.03 (text / image / video)  \
  $0.1 (audio)  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Not available
*   1,500 RPD (free, limit shared with Flash-Lite RPD), then $35 / 1,000
    grounded prompts
---

*   Grounding with Google Maps
*   Not available
*   Not available
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.15 (text / image / video)  \
  $0.50 (audio)
---

*   Output price (including thinking tokens)
*   Not available
*   $1.25
---

*   Context caching price
*   Not available
*   $0.03 (text / image / video)  \
  $0.1 (audio)  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Not available
*   1,500 RPD (free, limit shared with Flash-Lite RPD), then $35 / 1,000
    grounded prompts
---

*   Grounding with Google Maps
*   Not available
*   Not available
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.54 (text / image / video)  \
  $1.80 (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $4.50
---

*   Context caching price
*   Not available
*   $0.054 (text / image / video)  \
  $0.18 (audio)  \
  $1.80 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Free of charge, up to 500 RPD (limit shared with Flash-Lite RPD)
*   1,500 RPD (free, limit shared with Flash-Lite RPD), then $35 / 1,000
    grounded prompts
---

*   Grounding with Google Maps
*   500 RPD
*   1,500 RPD (free), then $25 / 1,000 grounded prompts
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

## Gemini 2.5 Flash-Lite {% id="gemini-2.5-flash-lite" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-2.5-flash-lite`](/docs/models/gemini-2.5-flash-lite)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com?model=gemini-2.5-flash-lite"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

A small and cost effective model, built for at scale usage.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price (text, image, video)
*   Free of charge
*   $0.10 (text / image / video)  \
  $0.30 (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $0.40
---

*   Context caching price
*   Not available
*   $0.01 (text / image / video)  \
  $0.03 (audio)  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Free of charge, up to 500 RPD (limit shared with Flash RPD)
*   1,500 RPD (free, limit shared with Flash RPD), then $35 / 1,000 grounded
    prompts
---

*   Grounding with Google Maps
*   500 RPD
*   1,500 RPD (free), then $25 / 1,000 grounded prompts
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price (text, image, video)
*   Not available
*   $0.05 (text / image / video)  \
  $0.15 (audio)
---

*   Output price (including thinking tokens)
*   Not available
*   $0.20
---

*   Context caching price
*   Not available
*   $0.01 (text / image / video)  \
  $0.03 (audio)  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Not available
*   1,500 RPD (free, limit shared with Flash RPD), then $35 / 1,000 grounded
    prompts
---

*   Grounding with Google Maps
*   Not available
*   Not available
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price (text, image, video)
*   Not available
*   $0.05 (text / image / video)  \
  $0.15 (audio)
---

*   Output price (including thinking tokens)
*   Not available
*   $0.20
---

*   Context caching price
*   Not available
*   $0.01 (text / image / video)  \
  $0.03 (audio)  \
  $1.00 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Not available
*   1,500 RPD (free, limit shared with Flash RPD), then $35 / 1,000 grounded
    prompts
---

*   Grounding with Google Maps
*   Not available
*   Not available
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price (text, image, video)
*   Free of charge
*   $0.18 (text / image / video)  \
  $0.54 (audio)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $0.72
---

*   Context caching price
*   Not available
*   $0.018 (text / image / video)  \
  $0.054 (audio)  \
  $1.80 / 1,000,000 tokens per hour (storage price)
---

*   Grounding with Google Search
*   Free of charge, up to 500 RPD (limit shared with Flash RPD)
*   1,500 RPD (free, limit shared with Flash RPD), then $35 / 1,000 grounded
    prompts
---

*   Grounding with Google Maps
*   500 RPD
*   1,500 RPD (free), then $25 / 1,000 grounded prompts
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

## Gemini 2.5 Flash Native Audio (Live API) {% id="gemini-2.5-flash-native-audio" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-2.5-flash-native-audio-preview-12-2025`](/docs/models/gemini-2.5-flash-native-audio-preview-12-2025)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com/app/live#gemini-2.5-flash-native-audio-preview-12-2025"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our [Live API](/docs/live-api) native audio models optimized for higher quality
audio outputs with better pacing, voice naturalness, verbosity, and mood.

{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.50 (text)  \
  $3.00 (audio / video)
---

*   Output price (including thinking tokens)
*   Free of charge
*   $2.00 (text)  \
  $12.00 (audio)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}

## Gemini 2.5 Flash Image (Nano Banana) 🍌 {% id="gemini-2.5-flash-image" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-2.5-flash-image`](/docs/models/gemini-2.5-flash-image)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="https://aistudio.google.com?model=gemini-2.5-flash-image"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

{% callout type="warning" %} **Warning:** Gemini 2.5 Flash Image
(`gemini-2.5-flash-image`) is [deprecated](/docs/deprecations) and will be shut
down on March 15, 2027; migrate to
[Gemini 3.1 Flash Lite Image](/docs/models/gemini-3.1-flash-lite-image) to avoid
service disruption. {% /callout %}

A native image generation model, optimized for speed, flexibility, and
contextual understanding. Text input and output is priced the same as [2.5
Flash](/docs/pricing#gemini-2.5-flash).
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.30 (text / image)
---

*   Output price
*   Not available
*   $0.039 per image{% sup %}*{% /sup %}
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.15 (text / image)
---

*   Output price
*   Not available
*   $0.0195 per image{% sup %}*{% /sup %}
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Flex" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.15 (text / image)
---

*   Output price
*   Not available
*   $0.0195 per image{% sup %}*{% /sup %}
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Priority" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.54 (text / image)
---

*   Output price
*   Not available
*   $0.0702 per image{% sup %}*{% /sup %}
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

{% sup %}*{% /sup %} Image output is priced at $30 per 1,000,000 tokens. Output
images up to 1024x1024px consume 1290 tokens and are equivalent to $0.039 per
image.

## Gemini 2.5 Flash Preview TTS {% id="gemini-2.5-flash-preview-tts" %}

{% two-column-layout %}
{% left-column class="center-vertically right-align" %}
*[`gemini-2.5-flash-preview-tts`](/docs/models/gemini-2.5-flash-preview-tts)*
{% /left-column %}
{% right-column %}
{% button
href="https://aistudio.google.com/generate-speech"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our 2.5 Flash text-to-speech audio model optimized for price-performant,
low-latency, controllable speech generation.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.50 (text)
---

*   Output price
*   Free of charge
*   $10.00 (audio)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.25 (text)
---

*   Output price
*   Not available
*   $5.00 (audio)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

## Gemini 2.5 Pro Preview TTS {% id="gemini-2.5-pro-preview-tts" %}

{% two-column-layout %}
{% left-column class="center-vertically right-align" %}
*[`gemini-2.5-pro-preview-tts`](/docs/models/gemini-2.5-pro-preview-tts)*
{% /left-column %}
{% right-column %}
{% button
href="https://aistudio.google.com/generate-speech"
variant="ais" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

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.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $1.00 (text)
---

*   Output price
*   Not available
*   $20.00 (audio)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.50 (text)
---

*   Output price
*   Not available
*   $10.00 (audio)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

## Lyria 3.5 {% id="lyria-3-5" %}

*[`lyria-3.5`](/docs/models/lyria-3.5)*

{% hr /%}

Google's music generation model.

{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per request in USD
---

*   Lyria 3.5 (Full Song)
*   Not available
*   $0.08 per song
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}

## Lyria 3 {% id="lyria-3" %}

*[`lyria-3-clip-preview`](/docs/models/lyria-3-clip-preview) and
[`lyria-3-pro-preview`](/docs/models/lyria-3-pro-preview)*

{% hr /%}

Google's family of legacy music generation models.

{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per request in USD
---

*   Lyria 3 Clip Preview (30s)
*   Not available
*   $0.04 per song
---

*   Lyria 3 Pro Preview (Full Song)
*   Not available
*   $0.08 per song
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}

## Gemini Embedding 2 {% id="gemini-embedding-2" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-embedding-2`](/docs/models/gemini-embedding-2)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="/docs/embeddings"
variant="ais" %} Try the
API
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our first multimodal embedding model, mapping text, images, video, audio, and
PDFs into a unified embedding space.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Text input price
*   Free of charge
*   $0.20
---

*   Image input price
*   Free of charge
*   $0.45 ($0.00012 per image)
---

*   Audio input price
*   Free of charge
*   $6.50 ($0.00016 per second)
---

*   Video input price
*   Free of charge
*   $12.00 ($0.00079 per frame)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Text input price
*   Not available
*   $0.10
---

*   Image input price
*   Not available
*   $0.225 ($0.00006 per image)
---

*   Audio input price
*   Not available
*   $3.25 ($0.00008 per second)
---

*   Video input price
*   Not available
*   $6.00 ($0.000395 per frame)
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

## Gemini Embedding {% id="gemini-embedding" %}

{% two-column-layout %}
{% left-column class="center-vertically" %}
*[`gemini-embedding-001`](/docs/models/gemini-embedding-001)*
{% /left-column %}
{% right-column class="center-vertically right-align" %}
{% button
href="/docs/embeddings"
variant="ais" %} Try the
API
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Our first Gemini Embeddings model for text-only use cases.
{% tabs %}
{% tab title="Standard" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   $0.15
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Not available
*   $0.075
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

## Gemini Robotics ER 2 Preview {% id="gemini-robotics-er-2" %}
{% two-column-layout %}
{% left-column %}
*[`gemini-robotics-er-2-preview`](/docs/models/gemini-robotics-er-2-preview)*
{% /left-column %}
{% right-column %}
{% button
href="https://aistudio.google.com?model=gemini-robotics-er-2-preview"
variant="ais"
class="right-align" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Gemini Robotics ER 2, short for Gemini Robotics Embodied Reasoning 2, is a
vision-language model endpoint that enables robots to understand their environments
precisely, supporting agentic orchestration of robots, video progress
understanding, multi-robot collaboration, and advanced spatial reasoning.
{% tabs %}
{% tab title="Standard" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Free of charge
* $1.00 (text / image / video / audio) through December 31, 2026. \\
  $2.00 (text / image / video / audio) starting January 1, 2027.
---

* Output price (including thinking tokens)
* Free of charge
* $5.00 through December 31, 2026. \\
  $10.00 starting January 1, 2027.
---

* Context caching price
* Not available
* $0.10 through December 31, 2026. \\
  $0.20 starting January 1, 2027. \\
  $0.50 / 1,000,000 tokens per hour (storage price) through December 31, 2026. \\
  $1.00 / 1,000,000 tokens per hour (storage price) starting January 1, 2027.
---

* Grounding with Google Search
* Not available
* 5,000 free search requests per month (shared across all Gemini 3 and newer models), then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% tab title="Batch" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Not available
* $0.50 (text / image / video / audio) through December 31, 2026. \\
  $1.00 (text / image / video / audio) starting January 1, 2027.
---

* Output price (including thinking tokens)
* Not available
* $2.50 through December 31, 2026. \\
  $5.00 starting January 1, 2027.
---

* Context caching price
* Not available
* $0.05 through December 31, 2026. \\
  $0.10 starting January 1, 2027. \\
  $0.50 / 1,000,000 tokens per hour (storage price) through December 31, 2026. \\
  $1.00 / 1,000,000 tokens per hour (storage price) starting January 1, 2027.
---

* Grounding with Google Search
* Not available
* 5,000 free search requests per month (shared across all Gemini 3 and newer models), then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

## Gemini Robotics ER 2 Streaming Preview {% id="gemini-robotics-er-2-streaming" %}
{% two-column-layout %}
{% left-column %}
*[`gemini-robotics-er-2-streaming-preview`](/docs/models/gemini-robotics-er-2-streaming-preview)*
{% /left-column %}
{% right-column %}
{% button
href="https://aistudio.google.com?model=gemini-robotics-er-2-streaming-preview"
variant="ais"
class="right-align" %}
Try it in Google AI Studio
{% /button %}
{% /right-column %}
{% /two-column-layout %}

{% hr /%}

Gemini Robotics ER 2 Streaming is a vision-language model endpoint for robotics
optimized for real-time text streaming using the Live API. It accepts text,
image, video, and audio input and supports bidirectional streaming with
function calling.
{% tabs %}
{% tab title="Standard" %}
{% table %}

* Feature
* Free Tier
* Paid Tier, per 1M tokens in USD
---

* Input price
* Free of charge
* $1.00 (text / image / video / audio) through December 31, 2026. \\
  $2.00 (text / image / video / audio) starting January 1, 2027.
---

* Output price
* Free of charge
* $5.00 through December 31, 2026. \\
  $10.00 starting January 1, 2027.
---

* Grounding with Google Search
* Not available
* 5,000 free search requests per month (shared across all Gemini 3 and newer models), then $14 per 1,000 requests (subject to a [daily cap](/docs/pricing#pricing-for-tools) of 1,500 requests per day).
---

* Used to improve our products
* [Yes](/docs/terms)
* [No](/docs/terms)
{% /table %}
{% /tab %}
{% /tabs %}

## [Gemma 4](https://ai.google.dev/gemma/docs/core/model_card_4) {% id="gemma-4" %}

{% hr /%}

Our lightweight, state-of the art, open model built from the same technology
that powers our Gemini models.

{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   Input price
*   Free of charge
*   Not available
---

*   Output price
*   Free of charge
*   Not available
---

*   Context caching price
*   Free of charge
*   Not available
---

*   Context caching (storage)
*   Free of charge
*   Not available
---

*   Tuning price
*   Not available
*   Not available
---

*   Grounding with Google Search
*   Not available
*   Not available
---

*   Used to improve our products
*   [Yes](/docs/terms)
*   [No](/docs/terms)
{% /table %}

## Pricing for tools {% id="pricing-for-tools" %}

Tools are priced at their own rates, applied to the model using them. Check the
[Models](/docs/models) page for which tools are available to each model.

{% table %}

*   Feature
*   Free Tier
*   Paid Tier, per 1M tokens in USD
---

*   [Google Search](/docs/google-search#pricing)
*   500 RPD free (limit shared for Flash and Flash-Lite).  \
  Not available for Pro.

*   Gemini 2.5 models:  \
  1,500 RPD free (limit shared for Flash and Flash-Lite).  \
  Then $35 / 1,000 grounded prompts  \
  Gemini 3 and newer models:  \
  5,000 free search requests per month (shared across all Gemini 3 and newer
  models), then $14 per 1,000 requests. (Subject to a default daily cap of
  1,500 requests per day (RPD) per project on the Gemini Developer API.)
---

*   [Google Maps](/docs/maps-grounding#pricing-and-rate-limits)
*   500 RPD  \
  Not available for Pro.

*   Gemini 2.5 models:  \
  1,500 RPD free (limit shared for Flash and Flash-Lite)  \
  10,000 RPD free for Pro.  \
  Then $25 / 1,000 grounded prompts  \
  Gemini 3 and newer models:  \
  5,000 requests per month (free, shared across all Gemini 3 and newer models), then
  $14 / 1,000 search queries.
---

*   [Code execution](/docs/code-execution#billing)
*   Free of charge
*   Code execution is billed at the standard token rates for the selected model.
    \
  Costs are determined solely by tool usage; no charges accrue for session  \
  runtime. Generated code and execution results are billed as **Output  \
  tokens** when created, and as **Input tokens** when used by the model in  \
  its iterative reasoning process.
---

*   [URL context](/docs/url-context#limitations)
*   Free of charge
*   Charged as input tokens per model pricing.
---

*   [Computer use](/docs/computer-use)
*   Not available
*   Charged as regular tokens per model pricing (e.g., standard [Gemini 3.8
    Flash](/docs/pricing#gemini-3.8-flash) pricing).
---

*   [File search](/docs/file-search#pricing)
*   Free of charge
*   Charged for embeddings at [Gemini Embedding](/docs/pricing#gemini-embedding)
    ($0.15 / 1M tokens) or
    [Gemini Embedding 2](/docs/pricing#gemini-embedding-2) rates. \
    Retrieved document tokens charged as regular tokens per model pricing.
---

*   [Custom Tools endpoint (Gemini 3.1 Pro Preview)](/docs/models/gemini-3.1-pro-preview)
*   Not available
*   Same as [Gemini 3.1 Pro Preview](/docs/pricing#gemini-3.1-pro-preview)
    pricing
{% /table %}

## Pricing for agents {% id="pricing-for-agents" %}

Agent usage costs are calculated based on the underlying token consumption and
usage of the tools.

{% table %}

*   Feature
*   Model
*   Tools
---

*   [Gemini Deep Research agent](/docs/deep-research)
*   All model inference is charged at standard Gemini list rates, including
    input,  \
  output, and intermediate input / reasoning tokens generated during agentic  \
  loops.

*   Tool usage fees apply per existing pricing structure, maintaining standard \
    distinctions for Search Grounding (retrieved tokens excluded) versus  \
  Url_context / File Search (retrieved tokens included in all other tools).
---

*   [Managed agents in Gemini API](/docs/agents)
*   All model inference is charged at standard Gemini list rates, including
    input,  \
  output, and intermediate input / reasoning tokens generated during agentic  \
  loops. (See [pricing details](/docs/agents#pricing)).

*   Environment compute (CPU, memory, sandbox execution) is not billed during
    the preview period.
---

*   [Antigravity Agent](/docs/antigravity-agent)
*   All model inference is charged at standard Gemini list rates, including
    input,  \
  output, and intermediate input / reasoning tokens generated during agentic  \
  loops. (See [pricing details](/docs/agents#pricing)).

*   Environment compute (CPU, memory, sandbox execution) is not billed during
    the  \
  preview period.
{% /table %}

## Notes {% id="notes" %}

*   **Agentic video understanding:** When using agentic video understanding,
    token usage is variable based on the content loaded by the model rather than
    full video length. This typically results in up to 88% fewer input tokens
    for long-form video, though token counts depend on query complexity and
    dynamic sampling depth (which may exceed 1 FPS for detailed visual
    segments). See [Agentic video
    understanding](/docs/video-understanding#agentic-video-understanding).

*   **Document token billing:** Tokens for the `DOCUMENT` modality (for example,
    PDFs) are billed at the image token rate. In API responses, these tokens
    appear under the `DOCUMENT` modality within `promptTokensDetails`.

*   Google AI Studio usage is free of charge in all [available
    regions](/docs/available-regions). See [Billing FAQs](/docs/billing) for
    details.

*   Prices may differ from the prices listed here and the prices offered on
    Gemini Enterprise Agent Platform. For Gemini Enterprise Agent Platform
    prices, see the [Gemini Enterprise Agent Platform pricing
    page](https://cloud.google.com/products/gemini-enterprise-agent-platform).

*   If you are using [dynamic retrieval](/docs/google-search) to optimize costs,
    only requests that contain at least one grounding support URL from the web
    in their response are charged for Grounding with Google Search. Costs for
    Gemini always apply. Rate limits are subject to change.

*   **Search Grounding rate limits:** On the Gemini Developer API, Grounding
    with Google Search on Gemini 3 and newer models is subject to a default
    daily rate limit of 1,500 requests per day (RPD) per project across all paid
    tiers, resetting daily at midnight Pacific Time. For high-volume production
    workloads requiring higher daily limits, consider using
    [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-search#considerations),
    which provides a default quota of 1,000,000 search queries per day.

# Coding agent setup & developer resources
Source: https://aistudio.google.com/docs/coding-agents
Description: Use Gemini API skills, MCP tools, plugins, and machine-readable documentation to help your coding agent write accurate Gemini code.

AI coding agents rely on training data that cuts off at a set date. Because of this, agents often suggest deprecated models (`gemini-1.5`), older SDKs (`google-generativeai`), or outdated code patterns.

Connecting your agent to official Gemini developer resources helps it write accurate code using current models, the `google-genai` SDK, and the [Interactions API](/docs/interactions-overview).

You can connect your coding agent to Gemini documentation, rules, and CLI tools in five ways:

## Summary of agent resources {% id="summary" %}

| Resource | What it provides | Availability |
| :--- | :--- | :--- |
| **[Gemini Agent Skills](/docs/coding-agents#available-skills)** | Step-by-step rules, SDK patterns, and helper scripts for specific features (`gemini-api-dev`, `gemini-live-api-dev`, `gemini-omni-flash-api`). | Pre-installed in [AI Studio Build](https://ai.studio/build); install with `skills.sh`, Context7, or Managed Agents. |
| **[Gemini Docs MCP Server](/docs/coding-agents#mcp-setup)** | Live search (`gemini_search_docs`) and full page reads (`gemini_get_doc`) across all documentation. | Supported in Claude Code, Cursor, OpenAI Codex, and VS Code. |
| **[Gemini API Plugin](/docs/coding-agents#gemini-api-plugin)** | Bundled package with official Gemini skills, the Docs MCP server, and API key tools. | Antigravity. |
| **[Machine-Readable Docs](/docs/coding-agents#machine-readable-docs)** | Clean Markdown pages, `llms.txt` indexes, and content negotiation headers. | All documentation pages on `aistudio.google.com/docs`. |
| **[Gemini API CLI](/docs/cli)** | Stateless CLI (`gemini-api`) to generate media, analyze files, and run managed agents from the shell without writing SDK code. | Install on macOS, Linux, or Windows with the install script, Go, or prebuilt binaries. |

## Install Gemini agent skills {% id="available-skills" %}

Agent skills give your coding agent procedural rules, current model names, and SDK code patterns. Instead of adding long instructions to your prompt, your agent loads each skill only when needed. This helps your agent avoid deprecated SDKs and use modern Gemini patterns.

Skills work alongside the Gemini Docs MCP server. If your agent does not have the MCP server installed, the skill falls back to [`llms.txt`](https://aistudio.google.com/llms.txt). To learn more about how skills work, read the [Gemini API Skills guide](https://aistudio.google.com/learn/gemini-api-skills).

{% callout type="note" %}
Skills come pre-installed in [Google AI Studio Build](https://ai.studio/build) and are bundled in the [Gemini API plugin](/docs/coding-agents#gemini-api-plugin) for Antigravity.
{% /callout %}

### Install with the CLI (`skills.sh` or Context7) {% id="install-skills-cli" %}

Install skills using [skills.sh](https://skills.sh) (recommended) or [Context7](https://context7.com):

```bash
# List all available skills in the repository
npx skills add google-gemini/gemini-skills --list

# Install a specific skill globally with skills.sh
npx skills add google-gemini/gemini-skills --skill <skill-name> --global

# Or install with Context7
npx ctx7 skills install /google-gemini/gemini-skills <skill-name>
```

### Available skills {% id="skills-catalog" %}

#### `gemini-api-dev` {% id="gemini-api-dev" %}

Skill for building applications with the [Interactions API](/docs/interactions-overview) and the official Gemini API SDKs (`google-genai` for Python and `@google/genai` for TypeScript). This skill covers:

- Text generation, multi-turn chat, streaming, structured outputs, and function calling
- Image generation, text-to-speech (TTS), and multimodal inputs
- Server-side conversation state management, background execution, Deep Research, and managed agents
- Current model names and migrating legacy `generateContent` or `google-generativeai` code

```bash
npx skills add google-gemini/gemini-skills --skill gemini-api-dev --global
```

#### `gemini-live-api-dev` {% id="gemini-live-api-dev" %}

Skill for building real-time audio and video streaming applications with the [Gemini Live API](/docs/live-api). This skill covers:

- WebSocket session management, ephemeral client tokens, and session resumption
- Streaming audio, video, and text with voice activity detection (VAD) and barge-in support
- Background reasoning (extended thinking), non-blocking asynchronous tool calls, transcription, and live speech translation

```bash
npx skills add google-gemini/gemini-skills --skill gemini-live-api-dev --global
```

#### `gemini-omni-flash-api` {% id="gemini-omni-flash-api" %}

Skill for generating and editing video with Gemini Omni Flash using the Interactions API. Includes helper scripts (`upload_file.py`, `generate_video.py`, `prep_video.py`, `inspect_video.py`) and covers:

- Text-to-video generation and prompt crafting
- First-and-last-frame transitions and reference-guided video generation
- Video extensions and media preprocessing workflows

```bash
npx skills add google-gemini/gemini-skills --skill gemini-omni-flash-api --global
```

### Mount skills in Managed Agents {% id="managed-agents-skills" %}

When you run remote managed agents with the Interactions API, you can mount the `google-gemini/gemini-skills` repository into the agent's workspace. See the [Gemini API Skills guide](https://aistudio.google.com/learn/gemini-api-skills) for details:

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Build a script that generates a 5-second video of a neon cityscape.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/google-gemini/gemini-skills",
                "target": ".agents",
            }
        ],
    },
)
```

## Connect the Gemini Docs MCP server {% id="mcp-setup" %}

The public **Gemini Docs MCP server** (`https://gemini-api-docs-mcp.dev`) gives your agent live access to the entire documentation site. Your agent can search and read documentation pages to check request schemas, model limits, and new features:

- `gemini_search_docs`: Searches Gemini API documentation by topic or query.
- `gemini_get_doc`: Reads the full Markdown content of a specific documentation page.

### Quick setup {% id="mcp-quick-setup" %}

Run this command in your terminal or project root to configure your detected coding agents automatically:

```bash
npx add-mcp "https://gemini-api-docs-mcp.dev"
```

### Configuration by environment {% id="mcp-by-environment" %}

{% tabs %}
{% tab label="Claude Code" %}
Run in your terminal:

```bash
$ claude mcp add --transport http geminiDocs https://gemini-api-docs-mcp.dev
```
{% /tab %}

{% tab label="Cursor" %}
Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

```json
{
  "mcpServers": {
    "geminiDocs": {
      "url": "https://gemini-api-docs-mcp.dev"
    }
  }
}
```
{% /tab %}

{% tab label="OpenAI Codex" %}
Run in your terminal:

```bash
$ codex mcp add geminiDocs --url https://gemini-api-docs-mcp.dev
```

Or add to `~/.codex/config.toml`:

```toml
[mcp_servers.geminiDocs]
url = "https://gemini-api-docs-mcp.dev"
```
{% /tab %}

{% tab label="VS Code (Copilot)" %}
Add to `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "geminiDocs": {
      "type": "http",
      "url": "https://gemini-api-docs-mcp.dev"
    }
  }
}
```
{% /tab %}
{% /tabs %}

## Gemini API plugin {% id="gemini-api-plugin" %}

If you use **Antigravity**, the **Gemini API plugin** is the fastest way to set up your workspace. It bundles the Gemini Docs MCP server, all official Gemini skills (`gemini-api-dev`, `gemini-live-api-dev`, `gemini-omni-flash-api`), and API key tools in one download.

- **Install in Antigravity (UI):** Go to **Settings > Customizations > Build with Google Plugins** and download **Gemini API**.
- **Install with the CLI:**
  ```bash
  agy plugin install https://github.com/google-gemini/gemini-skills
  ```

## Machine-readable documentation {% id="machine-readable-docs" %}

Standard web pages include HTML tags, navigation bars, and scripts that take up context window space. AI Studio serves documentation as clean Markdown to save tokens and help agents read documentation directly.

### How to access Markdown {% id="markdown-access-methods" %}

| Method | How to use | Why use it |
| :--- | :--- | :--- |
| **Accept header (content negotiation)** | Send `Accept: text/markdown` on any `/docs/...` URL | Gets raw Markdown from the same URL you visit in a browser without changing the path. |
| **Direct `.md` URLs** | Add `.md` to any doc URL (such as `/docs/coding-agents.md`) | Gives you a clean Markdown link to share in prompts, `AGENTS.md` files, or scripts. |
| **`llms.txt` index** | [`https://aistudio.google.com/llms.txt`](https://aistudio.google.com/llms.txt) | Lists every documentation page with links to each raw Markdown file. |
| **`llms-full.txt` file** | [`https://aistudio.google.com/llms-full.txt`](https://aistudio.google.com/llms-full.txt) | Combines all Gemini API documentation pages into a single file for full context loading. |
| **Discovery headers** | Included on all `/docs` HTTP responses | Sets `Link` and `X-Llms-Txt` headers, and adds an `AI Agent Context` block to Markdown pages to point agents to the documentation indexes. |

To fetch Markdown from any documentation URL using the `Accept` header:

```bash
curl --header "Accept: text/markdown" https://aistudio.google.com/docs/interactions-overview
```

You can also click **Copy page** at the top of any documentation page to copy the Markdown source to your clipboard.

## Recommended project rules (`AGENTS.md`) {% id="project-rules" %}

A project rules file (`AGENTS.md`, `.cursorrules`, or `CLAUDE.md`) sets baseline rules that load at the start of every agent session. Add these guidelines to your project root so coding agents default to current models and SDKs:

```markdown
# Gemini API Guidelines

- Before writing Gemini API code, consult the `geminiDocs` MCP server (`gemini_search_docs` / `gemini_get_doc`) or `https://aistudio.google.com/llms.txt`.
- Always use the current Google Gen AI SDK (`google-genai` for Python, `@google/genai` for TypeScript/JavaScript). Never use legacy SDKs (`google-generativeai` or `@google/generative-ai`).
- Use the Interactions API (`client.interactions.create`) for new applications unless a specific feature requires `generateContent`.
- Use current recommended models (see https://aistudio.google.com/docs/models) and avoid deprecated models.
```

## Verify and troubleshoot {% id="verification-troubleshooting" %}

### Verify your setup {% id="verify-setup" %}

To test your setup, ask your coding agent:

```none
Look up the request schema for the Gemini Interactions API in the documentation.
```

A configured agent will use `gemini_search_docs` on the `geminiDocs` MCP server and write code using `client.interactions.create` with the `google-genai` or `@google/genai` SDK.

### Status commands {% id="status-commands" %}

| Environment | MCP verification | Skills verification |
| :--- | :--- | :--- |
| **Claude Code** | Run `/mcp` | Run `/skills` |
| **Cursor** | Open **Settings > Features > MCP** | Open **Settings > Rules** |
| **OpenAI Codex** | Run `codex mcp list` | Check `.codex/skills/` or `~/.codex/skills/` |
| **Antigravity** | Open **Customizations > Connections** | Open **Customizations > Rules** or run `/skills list` |
| **VS Code (Copilot)** | Open **Extensions > MCP** or Output panel | Click **Select Tools** in Copilot Chat |

### Troubleshooting {% id="troubleshooting" %}

- **Skill or MCP server not detected:** Restart your editor (Cursor or VS Code) or terminal session (Claude Code or Codex). Most agents load MCP servers and skills only when they start.
- **Global skill conflict:** If your agent ignores a globally installed skill, install the skill in your project root without `--global`:
  ```bash
  npx skills add google-gemini/gemini-skills --skill gemini-api-dev
  ```
- **Rules ignored:** Make sure your `AGENTS.md`, `.cursorrules`, or `CLAUDE.md` file is in the root directory of your project.

## What's next {% id="whats-next" %}

- [Gemini API CLI](/docs/cli)
- [Gemini API Skills guide](https://aistudio.google.com/learn/gemini-api-skills)
- [Gemini API skills on GitHub](https://github.com/google-gemini/gemini-skills)
- [Interactions API](/docs/interactions-overview)
- [Available models](/docs/models)
- [Libraries and SDKs](/docs/libraries)

# Gemini API CLI
Source: https://aistudio.google.com/docs/cli
Description: Give coding agents, shell scripts, and CI pipelines a stateless CLI to generate text and media, analyze files, and run Gemini managed agents.

The Gemini API CLI (`gemini-api`) is a stateless, zero-dependency command-line client built for AI agents with shell access, scripts, and CI pipelines. Your coding agent can use it to generate text and media, analyze files, and delegate tasks to [Gemini managed agents](/docs/agents). It works with Antigravity, Claude Code, Cursor, and any standard shell environment.

Every feature runs as a standard shell command on the [Interactions API](/docs/interactions-overview). Run the same commands from an agent subprocess, your terminal, or a CI pipeline:

```bash
# 1. Install on macOS or Linux
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

# 2. Set your API key
export GEMINI_API_KEY="YOUR_API_KEY"

# 3. Generate media, analyze a file, or launch a background managed agent
gemini-api image "Minimalist isometric icon of a cloud database" --out ./assets/db-icon.jpg
gemini-api analyze -i ./docs/quarterly-report.pdf "Summarize the key findings in three bullets."
gemini-api agent run "Compare WebRTC SFU architectures and cite sources" \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false
```

{% callout type="note" %}
`gemini-api` is an open-source beta release that evolves alongside the [Interactions API](/docs/interactions-overview). Breaking changes can occur between minor versions. Pin a specific [release version](https://github.com/google-gemini/gemini-api-cli/releases) in automated agent environments and CI pipelines.
{% /callout %}

## How it works {% id="how-it-works" %}

Raw REST calls and interactive CLIs often cause issues for coding agents. Base64 media fills the context window, interactive prompts block subprocesses, and stale training data causes hallucinated flags.

Four design choices keep `gemini-api` reliable for agents:

- **Offline schema lookup:** Pass `--usage` to print the command tree (in [KDL](https://kdl.dev)), or `--schema` to print the JSON Schema for `--body` requests.
- **Files on disk, paths on `stdout`:** Media and transcription commands write files to disk and print only the output path, keeping binary data out of context.
- **Dry runs and structured output:** `--dry-run` validates inputs, redacts credentials, and previews the HTTP request offline. Pass `-o json`, `-o toon`, or `--jq` for machine-readable output. Add `--agent-mode` to return structured JSON errors on `stderr`, and check [exit codes](/docs/cli#exit-codes) to handle failures. Commands never prompt unless you pass `--interactive`.
- **Stateless by default:** Commands keep no hidden local state. Chain multi-step work explicitly with `--previous-interaction-id`, an uploaded `files/<id>` URI, or a background interaction ID.

With `-o json`, media commands still write the file to disk and print metadata to `stdout`:

```json
{
  "kind": "image",
  "mime_type": "image/jpeg",
  "path": "/path/to/project/assets/db-icon.jpg",
  "response_id": "v1_...",
  "size_bytes": 2914159,
  "status": "completed"
}
```

## Get started {% id="get-started" %}

Install the CLI, put `gemini-api` on your `PATH`, set `GEMINI_API_KEY`, and add usage rules to your coding agent.

### 1. Install the binary {% id="install" %}

{% tabs %}
{% tab label="macOS and Linux" %}
```bash
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash
```

To install a specific release, set `GEMINI_VERSION` to a release tag:

```bash
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION=<release-tag> bash
```
{% /tab %}

{% tab label="Windows (PowerShell)" %}
```bash
iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex
```
{% /tab %}

{% tab label="Go" %}
```bash
go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest
```
{% /tab %}

{% tab label="Prebuilt binaries" %}
Download versioned archives for macOS, Linux, and Windows from [GitHub Releases](https://github.com/google-gemini/gemini-api-cli/releases) and place `gemini-api` on your `PATH`. Use prebuilt archives to pin exact versions in Docker images and CI.
{% /tab %}
{% /tabs %}

### 2. Configure authentication and verify {% id="authentication" %}

Create an API key in [Google AI Studio](https://aistudio.google.com/apikey) (see [API keys](/docs/api-key)). Set `GEMINI_API_KEY` in your shell and your agent's subprocess environment:

```bash
export GEMINI_API_KEY="YOUR_API_KEY"
```

On a local workstation, you can save the key in your OS keychain (macOS Keychain, Linux Secret Service, or Windows Credential Manager). Pass `--no-keyring` to store the key in `~/.config/gemini-api/config.yaml` instead:

```bash
# Save to your OS keychain (or run gemini-api configure --interactive)
gemini-api configure --api-key "YOUR_API_KEY"

# Check the active credential source, then preview a request offline
gemini-api whoami
gemini-api generate "Confirm CLI setup in one sentence." --dry-run
```

{% callout type="warning" %}
Treat `GEMINI_API_KEY` as a secret. In CI, inject the key from your secret store instead of committing it to a repository or build file.
{% /callout %}

### 3. Give your agent instructions {% id="agent-instructions" %}

Add this snippet to your project's `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, or system prompt so your coding agent knows how to use `gemini-api`:

```markdown
## Gemini API CLI (`gemini-api`)

You have access to `gemini-api` through the shell. Use it to generate text or media (images, speech, music, video), analyze documents and recordings, or run and manage Gemini managed agents.

1. Run `gemini-api --help` or `gemini-api --usage` to choose a command, and `gemini-api <command> --schema` before building a `--body` JSON payload.
2. Preview unfamiliar or complex calls offline with `--dry-run -o json`.
3. For a single JSON result or `--jq` filtering on `generate` or `agent run`, pass `--stream=false -o json`.
4. To chain multi-step workflows, capture the output paths that media and transcription commands print to stdout, and the `id` values returned by `generate` or `agent run`.
```

Then prompt your coding agent as usual:

```none
Build a landing page for our developer tool. Use Gemini to generate a hero
illustration and a 15-second welcome voiceover, and start a background Deep
Research agent to compare competing CLI onboarding flows. Wire the assets and
findings into the page.
```

## Commands {% id="commands" %}

Run `gemini-api --help` to list all commands, or `gemini-api explore` to browse them interactively.

| Group | Command | What it does |
| :--- | :--- | :--- |
| Create | `image` | Generates or edits images (`-i`), writes a JPEG file, and prints its path. |
| Create | `tts` | Synthesizes 24 kHz mono WAV speech (one or two speakers) and prints the output path. |
| Create | `music` | Generates music tracks or loops, writes the audio file, and prints its path. |
| Create | `video` | Generates or edits MP4 clips and waits until done (`--async` returns an ID immediately). |
| Create | `generate` | Generates text and streams it to `stdout` (`--stream=false` returns one complete result). |
| Understand | `analyze` | Answers questions about PDFs, images, audio, video, CSV and text files, or public YouTube URLs. |
| Understand | `transcribe` | Writes speaker-labeled, timestamped transcripts (`md`, `text`, `json`, or `srt`) and prints the output paths. |
| Manage agents | `agent` | Runs managed agents (`run`, `status`, `cancel`, `delete-interaction`) and manages custom agent definitions (`create`, `list`, `get`, `delete`). |
| Manage agents | `environments`, `credentials`, `webhooks`, `triggers` | Configures sandbox environments, stored credentials, webhook delivery, and scheduled runs for managed agents. |
| Setup and files | `configure`, `auth`, `whoami` | Configures credentials and defaults, and shows the active auth state. |
| Setup and files | `files` | Uploads, lists, inspects, and deletes files in the Files API. |
| Setup and files | `models` | Lists available models. |

## Workflows {% id="workflows" %}

Each command defaults to a model suited for its task. Pass `--model` (`-m`) to pick a different model. Run `gemini-api models` to list available options.

### Image generation and editing {% id="image" %}

Agents building web or mobile UIs can generate placeholders, icons, and hero images with [Nano Banana](/docs/image-generation). Pass a generated path back in with `-i` to edit the image:

```bash
# Generate a 16:9 image at 2K resolution (512, 1K, 2K, or 4K) and capture its path
HERO_PATH=$(gemini-api image "Friendly robot mascot in a sunlit workshop, space on left for headline" \
  --aspect-ratio 16:9 \
  --image-size 2K \
  --out ./public/images/hero.jpg)

# Edit the generated image
gemini-api image "Add a winter scarf and soft snowfall outside the window" \
  -i "$HERO_PATH" \
  --out ./public/images/hero-winter.jpg
```

Pass `-i` multiple times to combine reference images, such as a character and a style guide.

### Speech synthesis {% id="tts" %}

`gemini-api tts` synthesizes 24 kHz WAV audio for UI cues, accessibility previews, and narrated walkthroughs. The default voice is `Kore`; choose another with `--voice`. For two-speaker dialogue, label each turn in the prompt and map speakers to voices:

```bash
gemini-api tts "Build succeeded. All integration tests passed." \
  --voice Aoede \
  --out ./public/audio/build-ok.wav

gemini-api tts "Alice: Welcome to the release walkthrough! Bob: Let's look at what shipped today." \
  --multi-speaker "Alice=Kore,Bob=Puck" \
  --out ./public/audio/release-intro.wav
```

### Music and video {% id="music-video" %}

Compose original tracks with [Lyria](/docs/music-generation), and generate MP4 clips with [Gemini Omni](/docs/video):

```bash
gemini-api music "Warm ambient synth and acoustic guitar background loop, 95 BPM" \
  --out ./public/audio/bg-loop.mp3

gemini-api video "A drone shot of a mountain landscape at sunrise." \
  --aspect-ratio 16:9 \
  --resolution 1080p \
  --out ./public/video/mountain-sunrise.mp4
```

By default, the `video` command waits for generation to finish and writes the MP4 file to disk. Pass `--async` to return an interaction ID immediately, then run `gemini-api video --resume <id> --out <path>` later. Pass `-i` to animate an existing image.

### Text generation {% id="generate" %}

`gemini-api generate` streams text to `stdout`:

```bash
gemini-api generate "Write a one-paragraph welcome message for new users of a note-taking app."
```

Add `--stdin` to pipe text into the prompt. Pass `--previous-interaction-id` to continue an earlier interaction.

### Document analysis and transcription {% id="analyze" %}

`analyze` answers questions about PDFs, spreadsheets, screenshots, audio and video files, and public YouTube URLs. `transcribe` writes a formatted transcript (`md`, `text`, `json`, or `srt`) to disk:

```bash
gemini-api analyze -i ./docs/product-brief.pdf "List the open questions and who owns each one." > open-questions.md

gemini-api transcribe -i ./fixtures/customer-call.mp4 --format srt --out ./fixtures/customer-call.srt
```

Pass `-i` multiple times to `analyze` to compare files, such as before-and-after screenshots.

`gemini-api` sends local files inline up to 14 MB (20 MB after base64 encoding). For larger files, upload once with `files upload --wait` and reuse the returned `files/<id>` URI:

```bash
FILE_URI=$(gemini-api files upload ./recordings/all-hands.mp4 --wait)

gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps."
gemini-api transcribe -i "$FILE_URI" --format json --out ./recordings/all-hands.json
```

### Run and manage agents {% id="managed-agents" %}

Your coding agent can delegate multi-step research or sandboxed tasks to [Gemini managed agents](/docs/agents), such as the [Deep Research agent](/docs/deep-research). Pass `--background --stream=false` to get an interaction ID immediately instead of holding a stream open:

```bash
# Launch a Deep Research job in the background and capture its interaction ID
RESEARCH_ID=$(gemini-api agent run "Compare open-source vector index benchmarks and cite primary papers." \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false \
  --jq '.id')

# Check status or fetch the finished result while continuing other work
gemini-api agent status "$RESEARCH_ID" -o json
```

Run `gemini-api agent cancel <id>` to stop a running job. You can also launch the [Antigravity agent](/docs/antigravity-agent) in a remote sandbox with `agent run`, or manage [custom agents](/docs/custom-agents) with `agent create`, `list`, `get`, and `delete`. See [Environments](/docs/agent-environment) to configure agent sandboxes.

## Custom request bodies {% id="custom-bodies" %}

For options without dedicated flags, pass a raw [Interactions API](/docs/interactions-overview) JSON payload with `--body` (inline or as `@file.json`). Pass `--body` to set `response_format` schemas, function-calling tools, `generation_config`, or `"store": false`. Run `gemini-api <command> --schema` first to check valid fields:

```bash
# Inspect the JSON Schema for the request body
gemini-api generate --schema > generate-schema.json

# Return schema-constrained JSON and skip storing the interaction
cat logs.txt | gemini-api generate "Extract every error message from these logs." \
  --stdin \
  --body '{
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {"errors": {"type": "array", "items": {"type": "string"}}},
        "required": ["errors"]
      }
    },
    "store": false
  }'
```

`--body` merges with command flags. If both set the same key, the command fails with exit code `2` so conflicting inputs fail fast.

## Exit codes {% id="exit-codes" %}

Every command returns a typed exit code so scripts and agents can handle failures without parsing error text. For example, `3` signals an authentication problem and `2` signals invalid command syntax:

| Code | Meaning |
| :--- | :--- |
| `0` | The command succeeded. |
| `1` | Runtime or API error, such as a network failure, rate limit, or failed background job. |
| `2` | Usage or validation error, such as an unknown flag, missing input, or duplicate `--body` key. |
| `3` | Authentication or authorization failure, such as a missing or invalid API key or token. |

Run `gemini-api --help-global` to list global flags shared by every command (authentication, output, network, and diagnostics).

## Limitations {% id="limitations" %}

- Streaming commands (`generate` and `agent run`) require `--stream=false` when combined with `-o json` or `--jq` to return a single JSON response object.
- Inline `-i` file inputs cap at 14 MB of raw file data (20 MB request payload including base64 encoding). Upload large files with `gemini-api files upload`. The Files API deletes uploaded files after 48 hours.
- `gemini-api` supports standard HTTP requests, SSE streaming, and async polling, not bidirectional WebSockets. For real-time voice and video streaming, use the [Live API](/docs/live-api) with the [Google GenAI SDKs](/docs/libraries).

## What's next {% id="whats-next" %}

- [Coding agent setup](/docs/coding-agents)
- [Interactions API](/docs/interactions-overview)
- [Gemini managed agents](/docs/agents)
- [gemini-api-cli on GitHub](https://github.com/google-gemini/gemini-api-cli)

# Models
Source: https://aistudio.google.com/docs/models
Description: Learn about all of Google's most advanced AI models

## Gemini 4 {% id="gemini-4" %}

{% card-grid columns="2" %}

{% card title="Gemini 4 Argon" description="Our flagship reasoning model with a shared 1M context window and long decodes up to 1M tokens." variant="model-card" %}

{% section class="model-specs" %}

*   *Model code* **gemini-4-argon**
*   *Context* **1M tokens**
*   *Max output* **65K / 1M tokens**
*   *Modalities* **Text, Image, Audio, Video, PDF**

{% /section %}

{% section class="card-actions" %}

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-4-argon" variant="primary" %}Try in AI Studio{% /button %} {% button href="/docs/models/gemini-4-argon" variant="icon-primary" icon="arrow_forward" tooltip="View models" %}{% /button %}

{% /section %}

{% /card %}

{% /card-grid %}
## All Gemini 4 models {% id="all-gemini-4-models" %}

{% table variant="model" %}

*   Model
*   Endpoint
---

*   [Gemini 4 Argon](/docs/models/gemini-4-argon)
*   `gemini-4-argon`
{% /table %}
## Gemini 3 {% id="gemini-3" %}

{% card-grid %}

{% card href="/docs/models/gemini-3.8-flash" title="Gemini 3.8 Flash" description="Our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows." badge="New" icon="spark" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.8-live" title="Gemini 3.8 Live" description="Default Live API model for most low-latency voice agent experiences without reasoning delays." badge="New" icon="settings_voice" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.8-live-extended-thinking" title="Gemini 3.8 Live Extended Thinking" description="High-reasoning Live API model for voice interactions, recommended when higher background reasoning is required." badge="New" icon="psychology" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.8-flash-tts" title="Gemini 3.8 Flash TTS" description="Flagship creative text-to-speech model for studio-grade voice fidelity, expressive acting, Voice design, and Voice replication." badge="New" icon="graphic_eq" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.8-flash-lite-tts" title="Gemini 3.8 Flash-Lite TTS" description="Fast, cost-efficient text-to-speech model for high-volume production, real-time voice agent cascades, and Voice replication." badge="New" icon="graphic_eq" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.6-flash" title="Gemini 3.6 Flash" description="Our previous-generation Flash model, balancing speed and multimodal capabilities across general agentic and everyday tasks." badge="Stable" icon="spark" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.5-flash-lite" title="Gemini 3.5 Flash-Lite" description="Our fastest, most cost-effective 3.5 model for high-throughput execution." badge="Stable" icon="bolt" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.1-flash-lite" title="Gemini 3.1 Flash-Lite" description="Frontier-class performance rivaling larger models at a fraction of the cost." badge="Stable" icon="bolt" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-nano-banana-2.1" title="Nano Banana 2.1" description="High-efficiency image generation and editing model with improved visual quality, typography, and multi-turn consistency." badge="New" icon="banana_spark" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.1-flash-image" title="Nano Banana 2" description="Powerful, high-efficiency image generation and editing, optimized for speed and high-volume use cases." badge="Stable" icon="banana_spark" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.1-flash-lite-image" title="Nano Banana 2 Lite" description="Ultra-low latency and cost-effective image generation and editing, designed for high-volume interactive use cases." badge="Stable" icon="banana_spark" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3-pro-image" title="Nano Banana Pro" description="State-of-the-art image generation and editing models for highly contextual native image creation." badge="Stable" icon="banana_spark" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.5-transcribe" title="Gemini 3.5 Transcribe" description="Low-latency speech-to-text model with utterance-based language detection, speaker diarization, and word timestamps." badge="Stable" icon="speech_to_text" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-omni-flash" title="Gemini Omni Flash" description="Fast video generation, editing, keyframe interpolation, and extension with native audio." badge="Stable" icon="movie_filter" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3-flash-preview" title="Gemini 3 Flash" description="Frontier-class performance rivaling larger models at a fraction of the cost." badge="Preview" icon="spark" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.5-live-translate-preview" title="Gemini 3.5 Live Translate" description="Low-latency, real-time speech to speech translation model that supports 70+ languages." badge="Preview" icon="translate" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.1-flash-live-preview" title="Gemini 3.1 Flash Live" description="Legacy Live API preview model. We recommend updating to Gemini 3.8 Live." badge="Preview" icon="settings_voice" variant="model" %}
{% /card %}

{% card href="/docs/models/gemini-3.1-flash-tts-preview" title="Gemini 3.1 Flash TTS" description="Legacy TTS preview model. We recommend updating to Gemini 3.8 Flash TTS or Gemini 3.8 Flash-Lite TTS." badge="Preview" icon="graphic_eq" variant="model" %}
{% /card %}

{% /card-grid %}
## All Gemini 3 models {% id="all-gemini-3-models" %}

{% table variant="model" %}

*   Model
*   Endpoint
---

*   [Gemini 3.8 Flash](/docs/models/gemini-3.8-flash)
*   `gemini-3.8-flash`
---

*   [Gemini 3.8 Live](/docs/models/gemini-3.8-live)
*   `gemini-3.8-live`
---

*   [Gemini 3.8 Live Extended Thinking](/docs/models/gemini-3.8-live-extended-thinking)
*   `gemini-3.8-live-extended-thinking`
---

*   [Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts)
*   `gemini-3.8-flash-tts`
---

*   [Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts)
*   `gemini-3.8-flash-lite-tts`
---

*   [Gemini 3.6 Flash](/docs/models/gemini-3.6-flash)
*   `gemini-3.6-flash`
---

*   [Gemini 3.5 Flash-Lite](/docs/models/gemini-3.5-flash-lite)
*   `gemini-3.5-flash-lite`
---

*   [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite)
*   `gemini-3.1-flash-lite`
---

*   [Nano Banana 2.1](/docs/models/gemini-nano-banana-2.1)
*   `gemini-nano-banana-2.1`
---

*   [Nano Banana 2](/docs/models/gemini-3.1-flash-image)
*   `gemini-3.1-flash-image`
---

*   [Nano Banana 2 Lite](/docs/models/gemini-3.1-flash-lite-image)
*   `gemini-3.1-flash-lite-image`
---

*   [Nano Banana Pro](/docs/models/gemini-3-pro-image)
*   `gemini-3-pro-image`
---

*   [Gemini 3.5 Transcribe](/docs/models/gemini-3.5-transcribe)
*   `gemini-3.5-transcribe` \
  `gemini-3.5-transcribe-live`
---

*   [Gemini Omni Flash](/docs/models/gemini-omni-flash)
*   `gemini-omni-1.1-flash`
---

*   [Gemini 3.1 Pro](/docs/models/gemini-3.1-pro-preview)
*   `gemini-3.1-pro-preview`
---

*   [Gemini 3 Flash](/docs/models/gemini-3-flash-preview)
*   `gemini-3-flash-preview`
---

*   [Gemini 3.5 Live Translate](/docs/models/gemini-3.5-live-translate-preview)
*   `gemini-3.5-live-translate-preview`
---

*   [Gemini 3.1 Flash Live](/docs/models/gemini-3.1-flash-live-preview)
*   `gemini-3.1-flash-live-preview`
---

*   [Gemini 3.1 Flash TTS](/docs/models/gemini-3.1-flash-tts-preview)
*   `gemini-3.1-flash-tts-preview`
{% /table %}
## Gemini 2.5 Flash {% id="gemini-25-flash" %}

{% callout type="caution" %}
`gemini-2.5-flash` is [deprecated](/docs/deprecations#gemini-2.5-flash-models)
and is no longer available to select in Google AI Studio (API access to the 2.5
models is limited to existing users). Effective December 1, 2026, all API
requests to `gemini-2.5-flash` will automatically route to
[`gemini-3.5-flash-lite`](/docs/models/gemini-3.5-flash-lite). Update your model
string to `gemini-3.5-flash-lite` and review the
[Gemini 3.5 Flash-Lite migration guide](/docs/whats-new-gemini-3.6#migrate-to-gemini-3-5-flash-lite)
before December 1, 2026.
{% /callout %}

{% table variant="model" %}

*   Model
*   Description
*   Endpoint
---

*   [Gemini 2.5 Flash](/docs/models/gemini-2.5-flash)
*   Our best price-performance model for low-latency, high-volume tasks that
    require reasoning.
*   `gemini-2.5-flash`
---

*   [Nano Banana](/docs/models/gemini-2.5-flash-image)
*   State-of-the-art native image generation and editing designed for fast,
    creative workflows.
*   `gemini-2.5-flash-image`
---

*   [Gemini 2.5 Flash Live](/docs/models/gemini-2.5-flash-native-audio-preview-12-2025)
*   Optimized for real-time conversational agents with sub-second native audio
    streaming.
*   `gemini-2.5-flash-native-audio-preview-12-2025`
---

*   [Gemini 2.5 Flash TTS](/docs/models/gemini-2.5-flash-preview-tts)
*   Controllable text-to-speech audio generation with fine control over style
    and pacing.
*   `gemini-2.5-flash-preview-tts`
{% /table %}

## Gemini 2.5 Flash-Lite {% id="gemini-25-flash-lite" %}

{% callout type="note" %}
To ensure reliable performance for everyone, we are limiting access to the 2.5
models to users who have actively used them in the past. `gemini-2.5-flash-lite`
is not deprecated and will continue to be served until further notice through
the API. For any new projects, use our latest models: 3.5 Flash-Lite or 3.8
Flash. This helps us maintain sufficient capacity for both ongoing legacy
workflows and new applications.
{% /callout %}

{% table variant="model" %}

*   Model
*   Description
*   Endpoint
---

*   [Gemini 2.5 Flash-Lite](/docs/models/gemini-2.5-flash-lite)
*   The fastest and most budget-friendly multimodal model in the 2.5 family.
*   `gemini-2.5-flash-lite`
{% /table %}

## Gemini 2.5 Pro {% id="gemini-25-pro" %}

{% callout type="caution" %}
`gemini-2.5-pro` is [deprecated](/docs/deprecations#gemini-2.5-pro-models) and
is no longer available to select in Google AI Studio (API access to the 2.5
models is limited to existing users). Effective December 1, 2026, all API
requests to `gemini-2.5-pro` will automatically route to
[`gemini-3.8-flash`](/docs/models/gemini-3.8-flash). Update your model string to
`gemini-3.8-flash` and review the
[Gemini 3.8 Flash migration guide](/docs/whats-new-gemini-3.8#migrate-to-gemini-3-8-flash)
before December 1, 2026.
{% /callout %}

{% table variant="model" %}

*   Model
*   Description
*   Endpoint
---

*   [Gemini 2.5 Pro](/docs/models/gemini-2.5-pro)
*   Our most advanced model for complex tasks, featuring deep reasoning and
    coding capabilities in the 2.5 family.
*   `gemini-2.5-pro`
---

*   [Gemini 2.5 Pro TTS](/docs/models/gemini-2.5-pro-preview-tts)
*   High-fidelity speech synthesis optimized for quality in structured workflows
    like podcasts and audiobooks.
*   `gemini-2.5-pro-preview-tts`
{% /table %}

## Audio models {% id="audio-models" %}

*This section contains all audio models, including ones that may already be
listed in other sections*

{% table variant="model" %}

*   Model
*   Description
*   Endpoint
---

*   [Gemini 3.8 Live](/docs/models/gemini-3.8-live)
*   The default option for most low-latency voice agent experiences and real-time
    dialogue without reasoning delays.
*   `gemini-3.8-live`
---

*   [Gemini 3.8 Live Extended Thinking](/docs/models/gemini-3.8-live-extended-thinking)
*   Our high-reasoning audio-to-audio model, recommended when higher background
    reasoning is required during live interactions.
*   `gemini-3.8-live-extended-thinking`
---

*   [Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts)
*   Flagship creative text-to-speech model for studio-grade voice fidelity,
    expressive acting, and regional dialects across 130 languages.
*   `gemini-3.8-flash-tts`
---

*   [Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts)
*   Fast, cost-efficient text-to-speech model built for high-throughput
    production workloads across 101 languages.
*   `gemini-3.8-flash-lite-tts`
---

*   [Gemini 3.1 Flash Live](/docs/models/gemini-3.1-flash-live-preview)
*   Legacy audio-to-audio preview model. We recommend updating to Gemini 3.8 Live.
*   `gemini-3.1-flash-live-preview`
---

*   [Gemini 3.1 Flash TTS](/docs/models/gemini-3.1-flash-tts-preview)
*   Legacy text-to-speech preview model. We recommend updating to Gemini 3.8
    Flash TTS or Gemini 3.8 Flash-Lite TTS.
*   `gemini-3.1-flash-tts-preview`
---

*   [Gemini 2.5 Flash Live](/docs/models/gemini-2.5-flash-native-audio-preview-12-2025)
*   Our flagship Live API model for low-latency, bidirectional voice and video
    agents with native audio reasoning.
*   `gemini-2.5-flash-native-audio-preview-12-2025`
---

*   [Gemini 2.5 Flash TTS](/docs/models/gemini-2.5-flash-preview-tts)
*   Fast and controllable text-to-speech for low-latency, cost-efficient
    applications and real-time assistants.
*   `gemini-2.5-flash-preview-tts`
---

*   [Gemini 2.5 Pro TTS](/docs/models/gemini-2.5-pro-preview-tts)
*   High-fidelity speech synthesis optimized for quality in structured workflows
    like podcasts and audiobooks.
*   `gemini-2.5-pro-preview-tts`
{% /table %}
## Generative media models {% id="generative-media-models" %}

*This section contains all generative media models, including ones that may
already be listed in other sections*

{% table variant="model" %}

*   Model
*   Description
*   Endpoint
---

*   [Nano Banana 2.1](/docs/models/gemini-nano-banana-2.1)
*   High-efficiency image generation and editing model with improved visual
    quality, typography, and multi-turn consistency.
*   `gemini-nano-banana-2.1`
---

*   [Nano Banana 2](/docs/models/gemini-3.1-flash-image)
*   High-efficiency production-scale visual creation, combining the intelligence
    of the Gemini 3 series with lightning-fast generation speeds.
*   `gemini-3.1-flash-image`
---

*   [Nano Banana 2 Lite](/docs/models/gemini-3.1-flash-lite-image)
*   Our fastest and cheapest Gemini image model, engineered for velocity and
    scale where speed and cost are the primary operational constraints. Not
    optimized for multiple reference inputs or multi-turn sequential editing.
*   `gemini-3.1-flash-lite-image`
---

*   [Nano Banana Pro](/docs/models/gemini-3-pro-image)
*   A professional design engine with a reasoning core for studio-quality 4K
    visuals, complex layouts, and precise text rendering.
*   `gemini-3-pro-image`
---

*   [Gemini Omni Flash](/docs/models/gemini-omni-flash)
*   Fast video generation, editing, keyframe interpolation, and extension with
    native audio.
*   `gemini-omni-1.1-flash`
---

*   [Nano Banana](/docs/models/gemini-2.5-flash-image)
*   State-of-the-art native image generation and editing designed for fast,
    creative workflows.
*   `gemini-2.5-flash-image`
---

*   Imagen 4 (Shut down)
*   Text-to-image model featuring fast and ultra-fast generation (shut down).
*   `imagen-4.0-generate`
{% /table %}

## Music generation models {% id="music-models" %}

*This section contains all music generation models, including ones that may
already be listed in other sections*

{% table variant="model" %}

*   Model
*   Description
*   Endpoint
---

*   [Lyria 3.5](/docs/models/lyria-3.5)
*   Our flagship music generation model, optimized for full-length songs with
    complex structural coherence.
*   `lyria-3.5`
---

*   [Lyria 3 Clip](/docs/models/lyria-3-clip-preview)
*   Optimized for generating short musical clips, loops, and previews up to 30
    seconds.
*   `lyria-3-clip-preview`
---

*   [Lyria 3 Pro](/docs/models/lyria-3-pro-preview)
*   Previous generation music generation model for full-length songs.
*   `lyria-3-pro-preview`
---

*   [Lyria RealTime](/docs/models/lyria-realtime-exp)
*   High-fidelity music generation model providing granular creative control and
    real-time streaming capabilities.
*   `lyria-realtime-exp`
{% /table %}

## Tool and agent models {% id="tool-and-agent-models" %}

{% table variant="model" %}

*   Model
*   Description
*   Endpoint
---

*   [Gemini Deep Research](/docs/models/deep-research-preview-04-2026)
*   An agentic model that autonomously plans and executes multi-step research
    across hundreds of sources to produce cited, interactive reports.
*   `deep-research-preview-04-2026`
---

*   [Gemini Deep Research Max](/docs/models/deep-research-max-preview-04-2026)
*   Maximum comprehensiveness for automated context gathering and synthesis
    across hundreds of sources.
*   `deep-research-max-preview-04-2026`
---

*   [Antigravity Agent](/docs/models/antigravity-preview-09-2026)
*   A general-purpose managed agent that autonomously plans, reasons, runs code,
    manages files, and browses the web inside a secure, isolated Linux sandbox.
*   `antigravity-preview-09-2026`
{% /table %}

## Specialized task models {% id="specialized-task-models" %}

{% table variant="model" %}

*   Model
*   Description
*   Endpoint
---

*   [Gemini Embedding 2](/docs/models/gemini-embedding-2)
*   Our first multimodal embedding model, mapping text, images, video, audio,
    and PDFs into a unified embedding space for advanced semantic search and RAG
    systems.
*   `gemini-embedding-2`
---

*   [Gemini Embedding](/docs/models/gemini-embedding-001)
*   High-dimensional vector representations for advanced semantic search, text
    classification, and RAG systems.
*   `gemini-embedding-001`
---

*   [Gemini Robotics ER 2](/docs/robotics-overview)
*   Embodied reasoning model delivering advanced video understanding, spatial
    reasoning, multi-step tool orchestration, and multi-robot collaboration for
    robotics tasks.
*   `gemini-robotics-er-2-preview`
{% /table %}

## Previous models {% id="previous-models" %}

{% callout type="warning" %}
These models are [deprecated](/docs/deprecations) and will be shut down soon;
migrate to newer models to prevent service interruptions.
{% /callout %}

{% table variant="model" %}

*   Model
*   Description
*   Endpoint
---

*   [Gemini Robotics ER 1.6](/docs/models/gemini-robotics-er-1.6-preview) (Shut down)
*   Advanced embodied reasoning model that understands physical spaces and plans
    multi-step tasks for robotic agents with new capabilities like instrument
    reading, improved spatial and physical reasoning.
*   `gemini-robotics-er-1.6-preview`
---

*   [Computer Use](/docs/models/gemini-2.5-computer-use-preview-10-2025) (Shut down)
*   A specialized model that can "see" a digital screen and perform UI actions
    like clicking, typing, and navigating to automate complex browser tasks.
*   `gemini-2.5-computer-use-preview-10-2025`
---

*   [Gemini 2.0 Flash](/docs/models/gemini-2.0-flash) (Shut down)
*   Our second generation workhorse model, with next-gen features and improved
    capabilities, including superior speed, native tool use, and a 1M token
    context window.
*   `gemini-2.0-flash`
---

*   [Gemini 2.0 Flash-Lite](/docs/models/gemini-2.0-flash-lite) (Shut down)
*   Our fastest second generation model, optimized for cost efficiency and low
    latency.
*   `gemini-2.0-flash-lite`
---

*   [Gemini 3.1 Flash-Lite Preview](/docs/models/gemini-3.1-flash-lite-preview)
    (Shut down)
*   Our most cost-efficient multimodal model, offering the fastest performance
    for high-frequency, lightweight tasks.
*   `gemini-3.1-flash-lite-preview`
---

*   [Gemini 3 Pro Preview](/docs/models/gemini-3-pro-preview) (Shut down)
*   Our state-of-the-art reasoning model, with advanced multimodal
    understanding.
*   `gemini-3-pro-preview`
{% /table %}

## Model version name patterns {% id="model-versions" %}

Gemini models are available in either _stable_, _preview_, _latest_, or
_experimental_ versions.

{% callout type="note" %}
Note: The following list refers to the model string naming convention as of
September, 2025. Models released prior to that may have different naming
conventions. Refer to the exact model string if you are using an older model.
{% /callout %}

### Stable {% class="hide-from-toc" id="stable" %}

Points to a specific stable model. Stable models usually don't change. Most
production apps should use a specific stable model.

For example: `gemini-3.6-flash`.

### Preview {% class="hide-from-toc" id="preview" %}

Points to a preview model which may be used for production. Preview models will
typically have billing enabled, might come with more restrictive rate limits and
will be deprecated with at least 2 weeks notice.

For example: `gemini-2.5-flash-preview-09-2025`.

### Latest {% class="hide-from-toc" id="latest" %}

Points to the latest release for a specific model variation. This can be a
stable, preview or experimental release. This alias will get hot-swapped with
every new release of a specific model variation. A **2-week notice** will be
provided through email before the version behind latest is changed.

For example: `gemini-flash-latest`.

### Experimental {% class="hide-from-toc" id="experimental" %}

Points to an experimental model which will typically not be suitable for
production use and come with more restrictive rate limits. We release
experimental models to gather feedback and get our latest updates into the hands
of developers quickly.

Experimental models are not stable and availability of model endpoints is
subject to change.

## Model deprecations {% id="model-deprecations" %}

For information about model deprecations, visit the [Gemini
deprecations](/docs/deprecations) page.

# Gemini 4 Argon
Source: https://aistudio.google.com/docs/models/gemini-4-argon
Description: Explore Gemini 4 Argon (gemini-4-argon), Google's latest Gemini 4 model for coding, reasoning, and agents, featuring a 1M context window and long decode.

Gemini 4 Argon (`gemini-4-argon`) is our flagship reasoning model, built for complex software engineering, deep mathematical and scientific problem solving, autonomous multi-step agents, and long decode up to 1M tokens.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-4-argon" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Latest model](/docs/latest-model) page for full coverage of features, API changes, and migration guidance.

## gemini-4-argon {% id="gemini-4-argon" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-4-argon`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Context window (unified input and output token limit)**
    1,048,576

    **Max output**
    65,536 (default synchronous) / up to 1,048,576 (with [long decode](/docs/long-decode))
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Agentic video understanding**
    {% badge type="supported" label="Supported (defaults to static)" /%}
    {% /section %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" label="Supported (Implicit only)" /%}
    Note: Explicit caching is not supported.
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Computer use**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" label="Supported (low, medium, high)" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-4-argon`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* October 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-4-argon/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-4-argon)
{% /table %}

# Gemini Nano Banana 2.1
Source: https://aistudio.google.com/docs/models/gemini-nano-banana-2.1
Description: Learn about Gemini Nano Banana 2.1 from Google

**Gemini Nano Banana 2.1** (`gemini-nano-banana-2.1`) is the latest
high-efficiency image generation and conversational editing model. An update
to Nano Banana 2
([Gemini 3.1 Flash Image](/docs/models/gemini-3.1-flash-image)), it maintains
Flash-level speed and cost efficiency while delivering significant
improvements in visual quality, prompt adherence, multi-turn character
consistency, and text rendering. It serves as the more efficient counterpart to
[Gemini 3 Pro Image](/docs/models/gemini-3-pro-image) (Nano Banana Pro).

**Key updates:**

* Improved visual quality and realism across `1K`, `2K`, and `4K` output
  resolutions (default `1K`)
* Fixed tiling artifacts on wide and panoramic aspect ratios (`1:4`, `4:1`,
  `1:8`, `8:1`) at `2K` and `4K` resolutions
* Enhanced text rendering and infographic layout accuracy
* Multi-image fusion supporting up to 14 reference images (character consistency
  for up to 4 characters and object fidelity for up to 10 objects)
* Grounding with Google Web and Image Search
* Configurable Thinking levels (`minimal`, `medium` default, and `high`)

{% button href="https://aistudio.google.com?model=gemini-nano-banana-2.1" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Image generation](/docs/image-generation) page for full
coverage of features and capabilities.

## gemini-nano-banana-2.1 {% id="gemini-nano-banana-2-1" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-nano-banana-2.1`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, and PDF

    **Output**
    Image and Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    131,072

    **Output token limit**
    32,768
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more
      details.

    * Stable: `gemini-nano-banana-2.1`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* October 2026
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-nano-banana-2.1)
{% /table %}

# Gemini 3.1 Flash image
Source: https://aistudio.google.com/docs/models/gemini-3.1-flash-image
Description: Learn about Gemini 3.1 Flash Image from Google

**Nano Banana 2** provides high-quality image generation and conversational
editing at a mainstream price point and low latency. It serves as the
high-efficiency counterpart to [Gemini 3 Pro Image](/docs/models/gemini-3-pro-image), optimized for speed and
high-volume developer use cases.

**Key updates:**

* New output resolution options:
  * New support for 0.5K, 2K and 4K, default 1K
* New Image Search Grounding:
  * Integration of both text and image search results to inform generation with
    real-time web data

  * Supported with Thinking on or off
* New 1:4, 4:1, 1:8 and 8:1 aspect ratios
* Improved aspect ratio adherence
* Improved image quality and consistency
* Improved i18n text rendering

{% button href="https://aistudio.google.com?model=gemini-3.1-flash-image" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Image generation](/docs/image-generation) page for full
coverage of features and capabilities.

## gemini-3.1-flash-image {% id="gemini-31-flash-image" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.1-flash-image`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, and PDF

    **Output**
    Image and Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    131,072

    **Output token limit**
    32,768
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-3.1-flash-image`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* February 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-1-flash-image/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.1-flash-image)
{% /table %}

# Gemini 3.1 Pro preview
Source: https://aistudio.google.com/docs/models/gemini-3.1-pro-preview
Description: Learn about Gemini 3.1 Pro Preview from Google

Built to refine the performance and reliability of the Gemini 3 Pro series,
Gemini 3.1 Pro Preview provides better thinking, improved token
efficiency, and a more grounded, factually consistent experience. It's optimized
for software engineering behavior and usability, as well as agentic workflows
requiring precise tool usage and reliable multi-step execution across real-world
domains.

{% button
    href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.1-pro-preview"
    variant="ais" %}
  Try in Google AI Studio
{% /button %}

## Documentation {% id="documentation" %}

Visit the [Gemini 3 Developer Guide](/docs/latest-model) page for full coverage
of features and capabilities.

## gemini-3.1-pro-preview {% id="gemini-31-pro-preview" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.1-pro-preview`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more
  details.

    * Preview: `gemini-3.1-pro-preview`
    * Preview: [`gemini-3.1-pro-preview-customtools`](/docs/models/gemini-3.1-pro-preview#gemini-31-pro-preview-customtools)
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* February 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-1-pro/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.1-pro-preview)
{% /table %}
#### gemini-3.1-pro-preview-customtools {% id="gemini-31-pro-preview-customtools" %}

For those building with a mix of bash and custom tools, Gemini 3.1 Pro
Preview comes with a separate endpoint available via the API called
`gemini-3.1-pro-preview-customtools`. This endpoint is better at prioritizing
your custom tools (for example `view_file` or `search_code`).

Note that while `gemini-3.1-pro-preview-customtools` is optimized for agentic
workflows that use custom tools and bash, you may see quality fluctuations in
some use cases which don't benefit from such tools.

# Gemini 3 Pro preview
Source: https://aistudio.google.com/docs/models/gemini-3-pro-preview
Description: Learn about Gemini 3 Pro Preview from Google

{% callout type="warning" %}
Gemini 3 Pro Preview is [deprecated](/docs/deprecations) and was shut down on
March 9, 2026. Migrate to [Gemini 4 Argon](/docs/models/gemini-4-argon) to avoid
service disruption.
{% /callout %}

## gemini-3-pro-preview {% id="gemini-3-pro-preview" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3-pro-preview`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Computer use**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * *Shut down*: `gemini-3-pro-preview`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* November 2025
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-pro/)
{% /table %}

# Gemini 3 Pro image
Source: https://aistudio.google.com/docs/models/gemini-3-pro-image
Description: Learn about Gemini 3 Pro Image from Google

**Nano Banana Pro** is a sophisticated reasoning-driven engine for
professional-grade image editing and generation, offering studio-quality
precision and advanced creative control. Nano Banana Pro is best for complex
graphic design, high-fidelity product mockups, and factual data visualizations
that require accurate text rendering and real-world grounding via Google Search.

{% button href="https://aistudio.google.com?model=gemini-3-pro-image" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Image generation](/docs/image-generation) page for full
coverage of features and capabilities.

## gemini-3-pro-image {% id="gemini-3-pro-image" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3-pro-image`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Image and Text

    **Output**
    Image and Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    65,536

    **Output token limit**
    32,768
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-3-pro-image`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* November 2025
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-pro-image/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3-pro-image)
{% /table %}

# Gemini 3.8 Flash
Source: https://aistudio.google.com/docs/models/gemini-3.8-flash
Description: Learn about Gemini 3.8 Flash from Google

Gemini 3.8 Flash is our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows—all with the speed and cost efficiency of Flash.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.8-flash" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the
[What's new in Gemini 3.8 Flash](/docs/whats-new-gemini-3.8)
page for full coverage of features and capabilities.

## gemini-3.8-flash {% id="gemini-38-flash" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.8-flash`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Computer use**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" label="Supported (low, medium, high)" /%}
    Note: `minimal` is not supported and returns an error.
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-3.8-flash`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* September 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-8-flash/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.8-flash)
{% /table %}

# Gemini 3.8 Flash TTS
Source: https://aistudio.google.com/docs/models/gemini-3.8-flash-tts
Description: Learn about the Gemini 3.8 Flash TTS model from Google, including when to use it and how to migrate from earlier TTS models.

Gemini 3.8 Flash TTS (`gemini-3.8-flash-tts`) is Google's flagship creative
text-to-speech model, engineered for studio-grade voice fidelity, expressive
acting, authentic regional accents, and rock-solid long-form multi-turn
stability.

{% button href="https://aistudio.google.com?model=gemini-3.8-flash-tts" variant="ais" %}Try in Google AI Studio{% /button %}

## Overview and capabilities {% id="overview-and-capabilities" %}

Gemini 3.8 Flash TTS sets a new benchmark for expressive audio generation:

*   **High acoustic fidelity and acting nuance:** Delivers rich emotional range,
    natural cadence, and precise adherence to turn-level `style` directions and
    inline vocal events (`<laugh>`, `<sigh>`, `<short pause>`).
*   **Long-form multi-turn stability:** Maintains consistent voice identity,
    timbre, volume, and acoustic room tone across extended dialogues and
    multi-minute narrations without voice drift.
*   **Authentic regional accents and pronunciation:** Supports regional accents
    and minority dialects.
*   **Full voice ecosystem support:** Works seamlessly with prebuilt voices, the
    Extended Voice Library (`GET /v1beta/voices`), custom
    [Voice design](/docs/voice-design) personas, and
    [Voice replication](/docs/voice-replication) (persistent stored voices by
    default, plus optional stateless keys). You can also design and replicate
    voices interactively in
    [Google AI Studio](https://aistudio.google.com/generate-speech).

Visit the [Text-to-speech](/docs/speech-generation) guide for full coverage of
features, prompting best practices, and code examples.

## When to use which TTS model {% id="when-to-use-which-tts-model" %}

Both Gemini 3.8 TTS models share the same API schema and prompting structure.
Choose the model that fits your workload:

| Feature / workload | Gemini 3.8 Flash TTS (`gemini-3.8-flash-tts`) | Gemini 3.8 Flash-Lite TTS (`gemini-3.8-flash-lite-tts`) |
| :------------ | :----------------------- | :----------------------------- |
| **Primary strength** | Maximum voice fidelity, acting nuance, and dialect coverage | High throughput, low latency, and cost efficiency |
| **Best use cases** | Audiobooks, studio narration, complex multi-speaker dialogue, heavy vocal-burst acting, difficult pronunciation, regional dialects | High-volume production, real-time voice agent cascades, read-aloud features, voice replication, everyday single-speaker generation |
| **Supported languages** | 130 languages | 101 languages |
| **Recommended replacement for** | New flagship creative tier | `gemini-3.1-flash-tts-preview` |

## Migration guide {% id="migration-guide" %}

If you are migrating from `gemini-3.1-flash-tts-preview` or earlier Gemini TTS
models, update your requests for the Gemini 3.8 TTS schema:

1.  **Move turn-level directions into `speech_metadata`:** Gemini 3.8 TTS treats
    input text strictly as a verbatim transcript. Inline text directions like
    `"Say cheerfully: Hello!"` or `"Speaker 1: Hello!"` may be spoken aloud.
    Move sustained delivery instructions (`style`) and speaker labels
    (`speaker`) into structured metadata:
    *   **Interactions API:** Attach an annotation with `"type":
        "speech_metadata"`, `"speaker"`, and `"style"` to each text content
        block.
    *   **GenerateContent API:** Attach `"speech_metadata": {"speaker": "...",
        "style": "..."}` to each `part`.
2.  **Use angle-bracket inline tags only for point-in-time vocal events:** Keep
    momentary non-speech vocalizations and pauses inline in the transcript using
    angle brackets (such as `<laugh>`, `<sigh>`, `<cough>`, `<breath>`, or
    `<short pause>`). Put delivery styles like whispering in
    `speech_metadata.style`.
3.  **Specify `speaker` on every turn in multi-speaker requests:** Every turn in
    a multi-speaker request must explicitly include `speaker` inside
    `speech_metadata` matching one of the configured speakers.
4.  **Design personas upfront with Voice design:** Replace long legacy Audio
    Profile / Director's Notes blocks with a custom voice created in
    [Voice design](/docs/voice-design), then carry that `voice_...` ID through
    your TTS requests with minimal or empty `style` strings.
5.  **Account for default WAV (`audio/wav`) output on unary requests:** Unlike
    `gemini-3.1-flash-tts-preview` and earlier TTS models (which returned
    headerless raw PCM `audio/l16` by default), Gemini 3.8 TTS returns WAV audio
    (`audio/wav` / `AUDIO_WAV`) with a standard RIFF header by default for unary
    requests.
    *   If your code previously wrapped raw PCM bytes in a WAV header (for
        example, using Python's `wave` module or `ffmpeg`), remove the manual
        header wrapper and write the returned bytes directly to a `.wav` file.
    *   If your pipeline requires headerless raw PCM, mu-law, or A-law audio,
        explicitly set `response_format.mime_type` to `"audio/l16"`,
        `"audio/mulaw"`, or `"audio/alaw"` (for example, `{"response_format":
        {"type": "audio", "mime_type": "audio/l16"}}` in the Interactions API,
        or `AUDIO_L16`, `AUDIO_MULAW`, or `AUDIO_ALAW` in `generateContent`).
        See
        [Audio output formats](/docs/speech-generation#audio-output-formats).

## gemini-3.8-flash-tts {% id="gemini-38-flash-tts" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.8-flash-tts`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text

    **Output**
    Audio
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    8,192

    **Output token limit**
    16,384 (Gemini API serving limit)
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * `gemini-3.8-flash-tts`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* September 2026
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.8-flash-tts)
{% /table %}
## Supported languages {% id="supported-languages" %}

`gemini-3.8-flash-tts` detects the input language automatically and supports
**over 130 languages**:

| Language | Language | Language |
| :--- | :--- | :--- |
| Acehnese (Arab script) | Greek | Nepali (individual language) |
| Afrikaans | Guarani | Nigerian Fulfulde |
| Akan | Gujarati | North Azerbaijani |
| Amharic | Haitian Creole | Northern Sotho |
| Armenian | Halh Mongolian | Northern Uzbek |
| Assamese | Hausa | Norwegian Bokmål |
| Awadhi | Hebrew | Norwegian Nynorsk |
| Balinese | Hindi | Nyanja |
| Bangla | Hungarian | Occitan |
| Banjar (Arab script) | Icelandic | Odia (individual language) |
| Banjar (Latn script) | Igbo | Pangasinan |
| Bashkir | Iloko | Persian (Afghanistan) |
| Basque | Indonesian | Polish |
| Belarusian | Iranian Persian | Portuguese |
| Bemba | Italian | Punjabi |
| Bhojpuri | Japanese | Romanian |
| Bosnian | Javanese | Russian |
| Buginese | Kabyle | Santali |
| Bulgarian | Kamba | Serbian |
| Burmese | Kannada | Sindhi |
| Cantonese | Kashmiri (Arab script) | Sinhala |
| Catalan | Kashmiri (Deva script) | Slovak |
| Cebuano | Kazakh | Slovenian |
| Central Kurdish | Khmer | Somali |
| Chhattisgarhi | Kikuyu | South Azerbaijani |
| Chinese (Hans script) | Kinyarwanda | Southern Pashto |
| Chinese (Hant script) | Kongo | Southern Sotho |
| Crimean Tatar | Korean | Spanish |
| Croatian | Kyrgyz | Standard Arabic (Arab script) |
| Czech | Lao | Standard Arabic (Latn script) |
| Danish | Latgalian | Standard Latvian |
| Dutch | Lingala | Standard Malay |
| Dyula | Lithuanian | Swahili (individual language) |
| Dzongkha | Luxembourgish | Swati |
| Egyptian Arabic | Macedonian | Swedish |
| English | Magahi | Tajik |
| Estonian | Maithili | Tamil |
| Filipino | Malayalam | Telugu |
| Finnish | Maltese | Thai |
| French | Manipuri | Tigrinya |
| Galician | Marathi | Tosk Albanian |
| Ganda | Minangkabau (Arab script) | Turkish |
| Georgian | Minangkabau (Latn script) | Uyghur |
| German | Mizo | Vietnamese |

# Gemini 3.8 Flash-Lite TTS
Source: https://aistudio.google.com/docs/models/gemini-3.8-flash-lite-tts
Description: Learn about the Gemini 3.8 Flash-Lite TTS model from Google, including when to use it and how to migrate from earlier TTS models.

Gemini 3.8 Flash-Lite TTS (`gemini-3.8-flash-lite-tts`) is Google's fast,
cost-efficient workhorse text-to-speech model built to replace
`gemini-3.1-flash-tts-preview` for high-throughput production workloads.

{% button href="https://aistudio.google.com?model=gemini-3.8-flash-lite-tts" variant="ais" %}Try in Google AI Studio{% /button %}

## Overview and capabilities {% id="overview-and-capabilities" %}

Gemini 3.8 Flash-Lite TTS combines low latency with expressive, natural speech:

*   **High-throughput efficiency:** Optimized for bulk production,
    conversational voice agent cascades, read-aloud features, and everyday
    single-speaker speech generation across major languages.
*   **Drop-in schema compatibility:** Shares the exact same API schema and
    structured prompting format as `gemini-3.8-flash-tts`, allowing you to
    switch models with a single parameter change.
*   **Full voice ecosystem support:** Supports prebuilt voices, the Extended
    Voice Library (`GET /v1beta/voices`), custom
    [Voice design](/docs/voice-design) personas, and
    [Voice replication](/docs/voice-replication) (persistent stored voices by
    default, plus optional stateless keys). You can also design and replicate
    voices interactively in
    [Google AI Studio](https://aistudio.google.com/generate-speech).

Visit the [Text-to-speech](/docs/speech-generation) guide for full coverage of
features, prompting best practices, and code examples.

## When to use which TTS model {% id="when-to-use-which-tts-model" %}

Both Gemini 3.8 TTS models share the same API schema and prompting structure.
Choose the model that fits your workload:

| Feature / workload | Gemini 3.8 Flash-Lite TTS (`gemini-3.8-flash-lite-tts`) | Gemini 3.8 Flash TTS (`gemini-3.8-flash-tts`) |
| :------------ | :----------------------------- | :----------------------- |
| **Primary strength** | High throughput, low latency, and cost efficiency | Maximum voice fidelity, acting nuance, and dialect coverage |
| **Best use cases** | High-volume production, real-time voice agent cascades, read-aloud features, voice replication, everyday single-speaker generation | Audiobooks, studio narration, complex multi-speaker dialogue, heavy vocal-burst acting, difficult pronunciation, regional dialects |
| **Supported languages** | 101 languages | 130 languages |
| **Recommended replacement for** | `gemini-3.1-flash-tts-preview` | New flagship creative tier |

## Migration guide {% id="migration-guide" %}

If you are upgrading from `gemini-3.1-flash-tts-preview` to
`gemini-3.8-flash-lite-tts`, update your requests for the Gemini 3.8 TTS schema:

1.  **Move turn-level directions into `speech_metadata`:** Gemini 3.8 TTS treats
    input text strictly as a verbatim transcript. Inline text directions like
    `"Say cheerfully: Hello!"` or `"Speaker 1: Hello!"` may be spoken aloud.
    Move sustained delivery instructions (`style`) and speaker labels
    (`speaker`) into structured metadata:
    *   **Interactions API:** Attach an annotation with `"type":
        "speech_metadata"`, `"speaker"`, and `"style"` to each text content
        block.
    *   **GenerateContent API:** Attach `"speech_metadata": {"speaker": "...",
        "style": "..."}` to each `part`.
2.  **Use angle-bracket inline tags only for point-in-time vocal events:** Keep
    momentary non-speech vocalizations and pauses inline in the transcript using
    angle brackets (such as `<laugh>`, `<sigh>`, `<cough>`, `<breath>`, or
    `<short pause>`). Put delivery styles like whispering in
    `speech_metadata.style`.
3.  **Specify `speaker` on every turn in multi-speaker requests:** Every turn in
    a multi-speaker request must explicitly include `speaker` inside
    `speech_metadata` matching one of the configured speakers.
4.  **Design personas upfront with Voice design:** Replace long legacy Audio
    Profile / Director's Notes blocks with a custom voice created in
    [Voice design](/docs/voice-design), then carry that `voice_...` ID through
    your TTS requests with minimal or empty `style` strings.
5.  **Account for default WAV (`audio/wav`) output on unary requests:** Unlike
    `gemini-3.1-flash-tts-preview` and earlier TTS models (which returned
    headerless raw PCM `audio/l16` by default), Gemini 3.8 TTS returns WAV audio
    (`audio/wav` / `AUDIO_WAV`) with a standard RIFF header by default for unary
    requests.
    *   If your code previously wrapped raw PCM bytes in a WAV header (for
        example, using Python's `wave` module or `ffmpeg`), remove the manual
        header wrapper and write the returned bytes directly to a `.wav` file.
    *   If your pipeline requires headerless raw PCM, mu-law, or A-law audio,
        explicitly set `response_format.mime_type` to `"audio/l16"`,
        `"audio/mulaw"`, or `"audio/alaw"` (for example, `{"response_format":
        {"type": "audio", "mime_type": "audio/l16"}}` in the Interactions API,
        or `AUDIO_L16`, `AUDIO_MULAW`, or `AUDIO_ALAW` in `generateContent`).
        See
        [Audio output formats](/docs/speech-generation#audio-output-formats).

## gemini-3.8-flash-lite-tts {% id="gemini-38-flash-lite-tts" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.8-flash-lite-tts`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text

    **Output**
    Audio
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    8,192

    **Output token limit**
    16,384 (Gemini API serving limit)
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * `gemini-3.8-flash-lite-tts`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* September 2026
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.8-flash-lite-tts)
{% /table %}
## Supported languages {% id="supported-languages" %}

`gemini-3.8-flash-lite-tts` detects the input language automatically and
supports **over 100 languages**:

| Language | Language | Language |
| :--- | :--- | :--- |
| Acehnese (Arab script) | German | Manipuri |
| Afrikaans | Greek | Marathi |
| Akan | Gujarati | Minangkabau (Arab script) |
| Amharic | Haitian Creole | Mizo |
| Armenian | Halh Mongolian | Nepali (individual language) |
| Assamese | Hausa | Nigerian Fulfulde |
| Awadhi | Hebrew | North Azerbaijani |
| Balinese | Hindi | Northern Sotho |
| Bangla | Hungarian | Northern Uzbek |
| Banjar (Latn script) | Icelandic | Norwegian Bokmål |
| Basque | Iloko | Norwegian Nynorsk |
| Belarusian | Indonesian | Nyanja |
| Bhojpuri | Iranian Persian | Odia (individual language) |
| Bosnian | Italian | Persian (Afghanistan) |
| Buginese | Japanese | Polish |
| Bulgarian | Javanese | Portuguese |
| Cantonese | Kamba | Punjabi |
| Catalan | Kannada | Romanian |
| Cebuano | Kashmiri (Arab script) | Russian |
| Central Kurdish | Kashmiri (Deva script) | Santali |
| Chhattisgarhi | Kazakh | Serbian |
| Chinese (Hans script) | Khmer | Sinhala |
| Chinese (Hant script) | Kikuyu | Slovak |
| Croatian | Kinyarwanda | South Azerbaijani |
| Czech | Kongo | Southern Pashto |
| Danish | Korean | Spanish |
| Dutch | Kyrgyz | Standard Arabic (Arab script) |
| Egyptian Arabic | Lao | Standard Arabic (Latn script) |
| English | Lingala | Standard Latvian |
| Estonian | Macedonian | Standard Malay |
| Filipino | Magahi | Tamil |
| French | Maithili | Telugu |
| Galician | Malayalam | Turkish |
| Ganda | Maltese | Vietnamese |
| Georgian | — | — |

# Gemini 3.8 Live
Source: https://aistudio.google.com/docs/models/gemini-3.8-live
Description: Learn about Gemini 3.8 Live, our flagship low-latency audio-to-audio model for real-time multimodal dialogue.

Gemini 3.8 Live (`gemini-3.8-live`) is the default option for low-latency,
audio-to-audio voice agent experiences and real-time dialogue without
reasoning-induced delays. It supports interleaved reasoning, asynchronous and
synchronous function calling, full-session client content updates, and built-in
proactive audio.

For complex agentic tasks requiring multi-step reasoning and configurable
thinking budgets, see
[Gemini 3.8 Live Extended Thinking](/docs/models/gemini-3.8-live-extended-thinking).

{% button href="https://aistudio.google.com/live?model=gemini-3.8-live"
variant="ais" %} Try in Google AI Studio {% /button %}

## Documentation {% id="documentation" %}

Visit the [Live API](/docs/live-api) guide for full coverage of features,
streaming configurations, and tool integrations.

## gemini-3.8-live {% id="gemini-38-live" %}

{% table variant="model" %}

* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.8-live`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, images, audio

    **Output**
    Text and audio
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    131,072

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" label="Supported (interleaved reasoning)" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more
    details.

    *   Stable: `gemini-3.8-live`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* September 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-8-audio/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.8-live)
{% /table %}
## Migrating from Gemini 3.1 Flash Live {% id="migrating" %}

Gemini 3.8 Live delivers ultra-low latency audio-to-audio interactions and
expands support for asynchronous workflows. When migrating from
`gemini-3.1-flash-live-preview`, review the following updates:

*   **Model string**: Update your model string from
    `gemini-3.1-flash-live-preview` to `gemini-3.8-live`.
*   **Thinking configuration**: `thinking_level` is not supported in
    `gemini-3.8-live` because interleaved reasoning is built in. Omit
    `thinking_level` and `thinking_config` from your session setup. If your
    application requires configurable background reasoning (`low`, `medium`, or
    `high`), use
    [`gemini-3.8-live-extended-thinking`](/docs/models/gemini-3.8-live-extended-thinking).
    See [Thinking in the Live API](/docs/live-api/thinking).
*   **Asynchronous function calling**: Asynchronous execution (`behavior:
    NON_BLOCKING`) is the default function calling mode. You can still use
    synchronous blocking mode for backward compatibility by setting `behavior:
    BLOCKING` on your tool declarations. Function scheduling options (`SILENT`,
    `WHEN_IDLE`, and `INTERRUPTED`) are also supported. See
    [Asynchronous function calling](/docs/live-api/tools#async-function-calling).
*   **Client content updates**: `send_client_content` is supported throughout
    the entire session lifecycle (both initial history seeding and mid-turn
    context updates) with explicit roles (`user` or `model`). Setting
    `turn_complete=true` unconditionally interrupts active model generation. If
    you send content without `turn_complete`, the server waits for subsequent
    messages before responding. See
    [Incremental content updates](/docs/live-api/capabilities#incremental-updates).
*   **Proactive audio**: Proactive audio is permanently enabled. Setting
    `proactive_audio: false` returns an error, so omit `proactive_audio` if you
    are migrating code that disables it.
*   **Affective dialogue**: Affective dialogue is removed from the API. Remove
    any `enable_affective_dialog` configurations from your setup.
*   **Turn coverage**: Defaults to
    [`TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`](/api-reference/live#RealtimeInputConfig.TurnCoverage).
    Video frames are sent to the model by default, so send frames only when
    needed to manage context and cost.
*   **Response modalities**: Audio is the only supported response modality
    (`response_modalities=["AUDIO"]`). Enable `output_audio_transcription` if
    your application requires a text transcript. See
    [Audio transcriptions](/docs/live-api/capabilities#audio-transcription).

For a feature comparison across all Live API models, see the
[Model comparison](/docs/live-api/capabilities#model-comparison) table in the
capabilities guide.

# Gemini 3.8 Live Extended Thinking
Source: https://aistudio.google.com/docs/models/gemini-3.8-live-extended-thinking
Description: Learn about Gemini 3.8 Live Extended Thinking, our Live API model engineered for complex reasoning and asynchronous tool orchestration.

Gemini 3.8 Live Extended Thinking (`gemini-3.8-live-extended-thinking`) is our
high-reasoning audio-to-audio Live API model for complex, multi-step problem
solving during real-time voice interactions. It processes configurable
background reasoning (`low`, `medium`, `high`), thought summaries, and
asynchronous tool calls while streaming continuous audio responses.

For low-latency conversational voice experiences without background reasoning
delays, see [Gemini 3.8 Live](/docs/models/gemini-3.8-live).

{% button
href="https://aistudio.google.com/live?model=gemini-3.8-live-extended-thinking"
variant="ais" %} Try in Google AI Studio {% /button %}

## Documentation {% id="documentation" %}

Visit the [Live API](/docs/live-api) and
[Thinking in the Live API](/docs/live-api/thinking) guides for full coverage of
reasoning configurations and asynchronous tool integrations.

## gemini-3.8-live-extended-thinking {% id="gemini-38-live-extended-thinking" %}

{% table variant="model" %}

* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.8-live-extended-thinking`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, images, audio

    **Output**
    Text and audio
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    131,072

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" label="Supported (Async only)" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more
    details.

    *   Stable: `gemini-3.8-live-extended-thinking`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* September 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-8-audio/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.8-live)
{% /table %}
## Upgrading to Gemini 3.8 Live Extended Thinking {% id="upgrading" %}

Gemini 3.8 Live Extended Thinking introduces background reasoning during live
audio sessions. When integrating this model, update your client state management
to handle asynchronous reasoning signals:

*   **Asynchronous reasoning protocol**: When interacting with models that use
    asynchronous reasoning, `turnComplete: true` no longer signals that the
    model is completely idle. The server may continue processing background
    reasoning or tool calls. Keep your client listening for subsequent server
    messages (such as tool calls or audio frames) after `turnComplete: true`
    arrives.
*   **Monitoring `interaction_status`**: Check `server_content.interaction_status`
    on incoming
    [`BidiGenerateContentServerContent`](/api-reference/live#BidiGenerateContentServerContent)
    messages to determine the current server state before closing the session:
    *   `IN_PROGRESS`: The server is actively processing user input, running
        background reasoning, or awaiting responses for asynchronous tool calls.
        Additional model output or tool calls may follow.
    *   `IDLE`: The server has finished all processing, reasoning, and tool
        calls. The session is idle and waiting for user input.
*   **Function calling**: Function calling is exclusively asynchronous
    (`behavior: NON_BLOCKING`). Synchronous blocking mode returns an error, and
    function scheduling options (`SILENT`, `WHEN_IDLE`, and `INTERRUPTED`) are
    not supported. See
    [Asynchronous function calling](/docs/live-api/tools#async-function-calling).
*   **Thinking configuration**: Configure background reasoning using
    `thinking_config` in your session setup with `thinking_level` values `low`,
    `medium`, or `high`. Note that `MINIMAL` is not supported. See
    [Thinking in the Live API](/docs/live-api/thinking).
*   **Client content updates**: `send_client_content` is supported throughout
    the entire session lifecycle (both initial history seeding and mid-turn
    context updates) with explicit roles (`user` or `model`). Setting
    `turn_complete=true` immediately interrupts active generation. See
    [Incremental content updates](/docs/live-api/capabilities#incremental-updates).
*   **Proactive audio**: Permanently enabled. Setting `proactive_audio: false`
    returns an error.
*   **Affective dialogue**: Removed from the API. Remove any
    `enable_affective_dialog` configurations from your setup.

For a feature comparison across all Live API models, see the
[Model comparison](/docs/live-api/capabilities#model-comparison) table in the
capabilities guide.

# Gemini 3.7 Flash
Source: https://aistudio.google.com/docs/models/gemini-3.7-flash
Description: Learn about Gemini 3.7 Flash from Google

{% callout type="caution" %} **Deprecated:** Gemini 3.7 Flash
(`gemini-3.7-flash`) is deprecated and has been replaced by
[Gemini 3.8 Flash (`gemini-3.8-flash`)](/docs/latest-model). It is no longer
available to select in Google AI Studio, and API requests to
`gemini-3.7-flash` are automatically routed to `gemini-3.8-flash`.
{% /callout %}

Gemini 3.7 Flash is a previous-generation model in the Gemini 3 series of
natively multimodal reasoning models, now replaced by
[Gemini 3.8 Flash](/docs/latest-model).

## Documentation {% id="documentation" %}

Visit the [What's new in Gemini 3.7 Flash](/docs/whats-new-gemini-3.7) page for
reference coverage of features and capabilities, or the
[Latest model](/docs/latest-model) page for Gemini 3.8 Flash.

## gemini-3.7-flash {% id="gemini-37-flash" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.7-flash`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Computer use**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" label="Supported (low, medium, high)" /%}
    Note: `minimal` is not supported and returns an error.
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Deprecated: `gemini-3.7-flash` (automatically routed to `gemini-3.8-flash`)
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* August 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-7-flash/)
{% /table %}

# Gemini 3.6 Flash
Source: https://aistudio.google.com/docs/models/gemini-3.6-flash
Description: Learn about Gemini 3.6 Flash from Google

{% callout type="note" %}
Gemini 3.6 Flash (`gemini-3.6-flash`) is a previous-generation Flash model that
remains available for production use. For our newest Flash model, see
[Gemini 3.8 Flash](/docs/models/gemini-3.8-flash).
{% /callout %}

Gemini 3.6 Flash provides sustained frontier-level intelligence optimized for
real-world tasks at a higher speed and lower cost. Designed for the agentic era,
it excels at code generation, agentic execution, and spatial reasoning. This model is particularly effective for rapid agentic loops involving
complex coding cycles and iterations.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.6-flash" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the
[What's new in Gemini 3.6 Flash and 3.5 Flash-Lite](/docs/whats-new-gemini-3.6)
page for full coverage of features and capabilities.

## gemini-3.6-flash {% id="gemini-36-flash" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.6-flash`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Computer use**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-3.6-flash`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* July 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-6-flash/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.6-flash)
{% /table %}

# Gemini 3.5 Flash
Source: https://aistudio.google.com/docs/models/gemini-3.5-flash
Description: Learn about Gemini 3.5 Flash from Google

{% callout type="caution" %} **Deprecated:** Gemini 3.5 Flash
(`gemini-3.5-flash`) is deprecated and has been replaced by
[Gemini 3.6 Flash (`gemini-3.6-flash`)](/docs/models/gemini-3.6-flash). It is no
longer available to select in Google AI Studio, and API requests to
`gemini-3.5-flash` are automatically routed to `gemini-3.6-flash`. Update your
model string to `gemini-3.6-flash` (or
[Gemini 3.8 Flash](/docs/models/gemini-3.8-flash)). {% /callout %}

Gemini 3.5 Flash is a deprecated earlier-generation Flash model that provided
sustained frontier-level intelligence optimized for real-world tasks at a higher
speed and lower cost.

## Documentation {% id="documentation" %}

Visit the
[What's new in Gemini 3.5 Flash](/docs/whats-new-gemini-3.5)
page for full coverage of features and capabilities.

## gemini-3.5-flash {% id="gemini-35-flash" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.5-flash`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Computer use**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Deprecated: `gemini-3.5-flash` (automatically routed to `gemini-3.6-flash`)
    * Preview: `gemini-3-flash-preview`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* May 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-5-flash/)
{% /table %}

# Gemini 3.5 Flash-Lite
Source: https://aistudio.google.com/docs/models/gemini-3.5-flash-lite
Description: Learn about Gemini 3.5 Flash-Lite from Google

Gemini 3.5 Flash-Lite is a low-latency, cost-effective multimodal model
optimized for high-throughput, low-cost execution for subagent tasks and document parsing. The model supports text, image,
video, audio, and PDF inputs, and is designed for high-volume agentic workflows,
simple data extraction, and applications where latency and API cost are the
primary constraints.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.5-flash-lite" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the
[What's new in Gemini 3.6 Flash and 3.5 Flash-Lite](/docs/whats-new-gemini-3.6)
page for full coverage of features and capabilities.

## gemini-3.5-flash-lite {% id="gemini-35-flash-lite" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.5-flash-lite`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Computer use**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-3.5-flash-lite`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* July 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-5-flash-lite/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.5-flash-lite)
{% /table %}

# Gemini Omni Flash
Source: https://aistudio.google.com/docs/models/gemini-omni-flash
Description: Learn about the Gemini Omni Flash video generation and editing model

Gemini Omni Flash is a high-performance model for fast, conversational video
generation and editing. It excels at turning text and images into video,
lets you refine and edit generated videos through natural language
conversations using the Interactions API, and supports video extension,
resolution upscaling, and advanced interpolation.

{% button href="https://aistudio.google.com?model=gemini-omni-1.1-flash" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Gemini Omni Flash](/docs/omni)
page for full coverage of features and capabilities.

## gemini-omni-1.1-flash {% id="gemini-omni-1.1-flash" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* **Gemini API**
    `gemini-omni-1.1-flash`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Input**
    Text, Image, Video (up to 10s for editing and extension)

    **Output**
    Video
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Limits

    {% /section %}
* **Context window**
    1,048,576 tokens

    **Output video**
    3s-10s (360p/720p/1080p/4K, 24 FPS)
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-omni-1.1-flash`
    * Shut down: `gemini-omni-flash-preview`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* August 2026
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-omni-1.1-flash)
{% /table %}

# Gemini 3.5 Transcribe
Source: https://aistudio.google.com/docs/models/gemini-3.5-transcribe
Description: Learn about the Gemini 3.5 Transcribe model from Google

Gemini 3.5 Transcribe is a speech-to-text model based on Gemini's audio understanding capabilities. It provides low-latency, accurate transcription with utterance-based language detection, speaker diarization, word-level timestamps, Smart transcription, and custom vocabulary speech biasing.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.5-transcribe" variant="ais" %}
  Try in Google AI Studio
{% /button %}

## Documentation {% id="documentation" %}

Gemini 3.5 Transcribe converts speech to text from audio files. It automatically detects 85+ languages, handles multi-language code-switching, identifies individual speakers, outputs word-level timestamps, and adapts to domain-specific terms through custom vocabulary biasing.

Visit the [Audio transcription](/docs/transcribe) guide for full coverage of non-streaming features. For real-time, low-latency streaming transcription over WebSockets, visit the [Live transcription](/docs/live-api/live-transcribe) guide using `gemini-3.5-transcribe-live`. For detailed pricing, see the [Pricing page](/docs/pricing#gemini-3.5-transcribe).

## gemini-3.5-transcribe {% id="gemini-35-transcribe" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.5-transcribe`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Audio (up to 1 hour)

    **Output**
    Text, Word annotations
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Audio limits

    {% /section %}
* **Unary audio limit**
    Up to 1 hour per request (up to 30 minutes when speaker diarization or word-level timestamps are enabled)
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **[Audio transcription](/docs/transcribe)**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **[Speaker diarization](/docs/transcribe#speaker-diarization)**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **[Word-level timestamps](/docs/transcribe#word-timestamps)**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **[Custom vocabulary](/docs/transcribe#custom-vocabulary)**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **[Smart transcription](/docs/transcribe#transcription-modes)**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **[Caching](/docs/caching)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Code execution](/docs/code-execution)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[File search](/docs/file-search)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Function calling](/docs/function-calling)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Image generation](/docs/image-generation)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Thinking](/docs/thinking)**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="speed" /%}Consumption options

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **[Batch API](/docs/batch-api)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Flex inference](/docs/flex-inference)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Priority inference](/docs/priority-inference)**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * `gemini-3.5-transcribe` (Unary)
    * `gemini-3.5-transcribe-live` (Live API)
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* August 2026
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Gemini 3.5 Transcribe](/docs/pricing#gemini-3.5-transcribe) \
    [Gemini 3.5 Transcribe Live](/docs/pricing#gemini-3.5-transcribe-live)
{% /table %}
## Feature support and limitations {% id="feature-support-and-limitations" %}

Gemini 3.5 Transcribe supports the following features across its two endpoints:

| Feature | Live Streaming (`gemini-3.5-transcribe-live`) | Audio File Processing (`gemini-3.5-transcribe`) | Notes / Limitations |
| :--- | :--- | :--- | :--- |
| **Language Auto-detection** | Supported (85+ languages) | Supported (85+ languages) | Includes mid-session code-mixing. |
| **Word-level Timestamps** | Not Supported | Supported | Degrades transcription accuracy. Incompatible with custom vocabulary. |
| **Custom Vocabulary Biasing** | Supported (up to 1,000 terms) | Supported (up to 1,000 terms) | Customers typically see best results with up to 100 terms. Incompatible with diarization and timestamps. |
| **Smart Dictation & Formatting** | Supported | Supported | Includes filler word removal and intent-aware alphanumeric formatting. |
| **Speaker Diarization** | Not Supported | Supported (up to 8 speakers) | Attribution for 3+ speakers is experimental. Incompatible with custom vocabulary. |
| **Max Audio Duration** | 10 minutes per session. | Up to 1 hour | File processing is limited to 30 minutes when features like diarization or timestamps are enabled. |

## Supported languages {% id="supported-languages" %}

The following languages and BCP-47 language codes are supported for Gemini 3.5 Transcribe:

| Language | BCP-47 Code | Language | BCP-47 Code |
| :--- | :--- | :--- | :--- |
| Afrikaans | `af-ZA` | Japanese | `ja-JP` |
| Amharic | `am-ET` | Javanese | `jv-ID` |
| Arabic (Egypt) | `ar-EG` | Kabuverdianu | `kea-CV` |
| Armenian | `hy-AM` | Kannada | `kn-IN` |
| Assamese | `as-IN` | Kazakh | `kk-KZ` |
| Azerbaijani | `az-AZ` | Korean | `ko-KR` |
| Belarusian | `be-BY` | Kyrgyz | `ky-KG` |
| Bengali (Bangladesh) | `bn-BD` | Latvian | `lv-LV` |
| Bengali (India) | `bn-IN` | Lingala | `ln-CD` |
| Bosnian | `bs-BA` | Lithuanian | `lt-LT` |
| Bulgarian | `bg-BG` | Macedonian | `mk-MK` |
| Bulgarian (Aromanian) | `rup-BG` | Malay | `ms-MY` |
| Burmese | `my-MM` | Malayalam | `ml-IN` |
| Cantonese (Traditional) | `yue-Hant-HK` | Maltese | `mt-MT` |
| Catalan | `ca-ES` | Mandarin Chinese (Simplified) | `cmn-Hans-CN` |
| Cebuano | `ceb` | Marathi | `mr-IN` |
| Central Khmer | `km-KH` | Mongolian | `mn-MN` |
| Croatian | `hr-HR` | Nepali | `ne-NP` |
| Czech | `cs-CZ` | Norwegian | `nb-NO` |
| Danish | `da-DK` | Oriya | `or-IN` |
| Dutch | `nl-NL` | Polish | `pl-PL` |
| English (Great Britain) | `en-GB` | Portuguese (Brazil) | `pt-BR` |
| English (India) | `en-IN` | Portuguese (Portugal) | `pt-PT` |
| English (United States) | `en-US` | Punjabi | `pa-IN` |
| Estonian | `et-EE` | Punjabi (Gurmukhi script) | `pa-Guru-IN` |
| Farsi | `fa-IR` | Romanian | `ro-RO` |
| Filipino | `fil-PH` | Russian | `ru-RU` |
| Finnish | `fi-FI` | Serbian | `sr-RS` |
| French | `fr-FR` | Sindhi (Arabic script) | `sd-Arab-IN` |
| Galician | `gl-ES` | Slovak | `sk-SK` |
| Georgian | `ka-GE` | Slovenian | `sl-SI` |
| German | `de-DE` | Spanish (Latin America) | `es-419` |
| Greek | `el-GR` | Spanish (United States) | `es-US` |
| Gujarati | `gu-IN` | Swahili (Kenya) | `sw-KE` |
| Hausa | `ha-NG` | Swedish | `sv-SE` |
| Hebrew | `he-IL` | Tajik | `tg-TJ` |
| Hindi | `hi-IN` | Telugu | `te-IN` |
| Hungarian | `hu-HU` | Thai | `th-TH` |
| Icelandic | `is-IS` | Turkish | `tr-TR` |
| Indian English | `en-IN` | Ukrainian | `uk-UA` |
| Indonesian | `id-ID` | Uzbek | `uz-UZ` |
| Italian | `it-IT` | Vietnamese | `vi-VN` |

# Gemini 3.1 Flash Lite image
Source: https://aistudio.google.com/docs/models/gemini-3.1-flash-lite-image
Description: Learn about Gemini 3.1 Flash Lite Image from Google

**Nano Banana 2 Lite** is designed as the efficiency specialist of the image
generation family, offering ultra-low latency and cost-effective image
generation and editing. By targeting a sub-2 second latency and significantly
reduced TPU compute costs, this model enables high-volume interactive developer
use cases and real-time consumer applications.

**Key capabilities:**

*   **Sub-2 second end-to-end latency**
*   **Interleaved generation and editing** with native support for Text -> Text + Image(s) and Image + Text -> Text + Image(s).
*   **Optimized for lower resolutions** of 1K (1024x1024px).
*   Supports a discrete set of **14 aspect ratios** including standard formats.
*   **Fast multi-turn local edits** (swapping colors, sticker creation, background adjustments).
*   Maintains high character alignment matching original Nano Banana standards.
*   New `1:1`, `3:2`, `2:3`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` aspect ratios.
*   Supported `image_size` values: `1024px` (1K). *(Note: 2K and 4K are unsupported).*
*   **SynthID watermarking (Always On) + C2PA**.

{% button href="https://aistudio.google.com?model=gemini-3.1-flash-lite-image" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Image generation](/docs/image-generation) page for full
coverage of features and capabilities.

## gemini-3.1-flash-lite-image {% id="gemini-31-flash-lite-image" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.1-flash-lite-image`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, and PDF

    **Output**
    Image and Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    65,536

    **Output token limit**
    4,096
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" %}Supported (minimal and high){% /badge %}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-3.1-flash-lite-image`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* June 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-1-flash-lite-image/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.1-flash-lite-image)
{% /table %}

# Gemini 3.5 Live translate
Source: https://aistudio.google.com/docs/models/gemini-3.5-live-translate-preview
Description: Learn about the Gemini 3.5 Live Translate model from Google

Gemini 3.5 Live Translate is our low-latency, audio-to-audio model optimized for
real-time translation of spoken conversations. It enables seamless,
bidirectional translation with high accuracy and natural voice output.

{% button
    href="https://aistudio.google.com/live?model=gemini-3.5-live-translate-preview"
    variant="ais" %}
  Try in Google AI Studio
{% /button %}

## Documentation {% id="documentation" %}

Visit the [Live Translation](/docs/live-api/live-translate) guide for full
coverage of features and capabilities.

## gemini-3.5-live-translate-preview {% id="gemini-35-live-translate-preview" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.5-live-translate-preview`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Audio (speech)

    **Output**
    Audio (translated speech) and Text (transcript)
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    131,072

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **[Audio generation](/docs/speech-generation)**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **[Caching](/docs/caching)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Code execution](/docs/code-execution)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[File search](/docs/file-search)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Function calling](/docs/function-calling)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Grounding with Google Maps](/docs/maps-grounding)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Image generation](/docs/image-generation)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Live API](/docs/live-api)**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **[Live translation](/docs/live-api/live-translate)**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **[Search grounding](/docs/google-search)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Structured outputs](/docs/structured-output)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Thinking](/docs/thinking)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[URL context](/docs/url-context)**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="speed" /%}Consumption options

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **[Batch API](/docs/batch-api)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Flex inference](/docs/flex-inference)**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **[Priority inference](/docs/priority-inference)**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more
  details.

    * Preview: `gemini-3.5-live-translate-preview`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* June 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-5-audio/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.5-live-translate-preview)
{% /table %}

# Gemini 3 Flash preview
Source: https://aistudio.google.com/docs/models/gemini-3-flash-preview
Description: Learn about Gemini 3 Flash Preview from Google

The best model in the world for multimodal understanding, and our most powerful
agentic and vibe-coding model yet, delivering richer visuals and deeper
interactivity, all built on a foundation of state-of-the-art reasoning.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-3-flash-preview" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Gemini 3 Developer Guide](/docs/latest-model) page for full coverage
of features and capabilities.

## gemini-3-flash-preview {% id="gemini-3-flash-preview" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3-flash-preview`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Computer use**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * `Preview: gemini-3-flash-preview`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* December 2025
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-flash/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3-flash-preview)
{% /table %}

# Gemini 3.1 Flash TTS (text-to-speech) preview
Source: https://aistudio.google.com/docs/models/gemini-3.1-flash-tts-preview
Description: Learn about Gemini 3.1 Flash TTS Preview model from Google

{% callout type="note" %}
`gemini-3.1-flash-tts-preview` is a legacy preview model. For new and
production workloads, migrate to
[Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts)
(`gemini-3.8-flash-tts`) or
[Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts)
(`gemini-3.8-flash-lite-tts`). See the
[migration guide](/docs/speech-generation#migration).
{% /callout %}

The Gemini 3.1 Flash TTS Preview model provides powerful, low-latency speech
generation with natural outputs, steerable prompts, and expressive audio
tags for precise narration control.

{% button href="https://aistudio.google.com?model=gemini-3.1-flash-tts-preview" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

The Gemini 3.1 Flash TTS Preview model introduces expressive [audio tags](/docs/speech-generation#controllable)
for controlling narration, as well as overall improvements to naturalness,
controllability, and multilinguality.

Visit the [Text-to-Speech](/docs/speech-generation) guide for full
coverage of features and capabilities.

## gemini-3.1-flash-tts-preview {% id="gemini-31-flash-tts-preview" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.1-flash-tts-preview`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text

    **Output**
    Audio
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    8,192

    **Output token limit**
    16,384
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * `gemini-3.1-flash-tts-preview`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* April 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-1-flash-audio/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.1-flash-tts-preview)
{% /table %}

# Veo 3.1 Lite preview
Source: https://aistudio.google.com/docs/models/veo-3.1-lite-generate-preview
Description: Learn about the Veo 3.1 video generation model from Google

{% callout type="warning" %} `veo-3.1-lite-generate-preview` was
[shut down](/docs/deprecations) on **October 22, 2026**; migrate to
[Gemini Omni Flash](/docs/models/gemini-omni-flash) (`gemini-omni-1.1-flash`) or
the GA models available through the
[Gemini Enterprise Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate)
to avoid service interruptions. {% /callout %}

Veo 3.1 Lite Preview is a high-efficiency, developer-first video model providing
high-fidelity video generation, editing, and cinematic control. It leverages the
state-of-the-art Veo 3.1 model to democratize professional-grade video AI by
offering a scalable, programmable interface for creators and enterprises.

## Documentation {% id="documentation" %}

Visit the [Video generation](/docs/video) page for full coverage of
features and capabilities. Note that Veo 3.1 Lite Preview does not support
[4K outputs](/docs/veo#resolution) or
[Extension](/docs/veo#extending-veo-videos).

## veo-3.1-lite-generate-preview {% id="veo-31-lite-generate-preview" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* **Gemini API**
    `veo-3.1-lite-generate-preview`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Input**
    Text, Image

    **Output**
    Video with audio
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Limits

    {% /section %}
* **Text input**
    1,024 tokens

    **Output video**
    1
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* March 2026
{% /table %}

# Gemini 3.1 Flash live preview
Source: https://aistudio.google.com/docs/models/gemini-3.1-flash-live-preview
Description: Learn about the Gemini 3.1 Flash Live Preview model from Google

Gemini 3.1 Flash Live Preview is our legacy preview audio-to-audio model for
real-time dialogue and voice-first AI applications.

{% callout type="note" %} For new applications and production workloads, we
recommend migrating to [Gemini 3.8 Live](/docs/models/gemini-3.8-live)
(`gemini-3.8-live`) or
[Gemini 3.8 Live Extended Thinking](/docs/models/gemini-3.8-live-extended-thinking)
(`gemini-3.8-live-extended-thinking`). {% /callout %}

{% button
    href="https://aistudio.google.com/live?model=gemini-3.1-flash-live-preview"
    variant="ais" %}
  Try in Google AI Studio
{% /button %}

## Documentation {% id="documentation" %}

Visit the [Live API](/docs/live-api) guide for full coverage
of features and capabilities.

## gemini-3.1-flash-live-preview {% id="gemini-31-flash-live-preview" %}
{% table variant="model" %}

* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.1-flash-live-preview`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, images, audio

    **Output**
    Text and audio
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    131,072

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Preview: `gemini-3.1-flash-live-preview`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* March 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-1-flash-audio/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.8-live)
{% /table %}
## Migrating from Gemini 2.5 Flash Live {% id="migrating" %}

Gemini 3.1 Flash Live Preview is optimized for low-latency, real-time dialogue.
When migrating from `gemini-2.5-flash-native-audio-preview-12-2025`, consider
the following:

- **Model string**: Update your model string from
  `gemini-2.5-flash-native-audio-preview-12-2025` to
  `gemini-3.1-flash-live-preview`.

- **Thinking configuration**: Gemini 3.1 uses `thinkingLevel` (with settings
  like `minimal`, `low`, `medium`, and `high`) instead of `thinkingBudget`.
  The default is `minimal` to optimize for lowest latency. See
  [Thinking levels and budgets](/docs/thinking?generate-content=true#levels-budgets).

- **Server events**: A single
  [`BidiGenerateContentServerContent`](https://ai.google.dev/api/live#bidigeneratecontentservercontent)
  event can now contain multiple content parts simultaneously (for example,
  audio chunks and transcript). Update your code to process all parts in each
  event to avoid missing content.

-   **Client content**: `send_client_content` is supported for appending text or
    structured context turns mid-session as well as seeding initial history
    (setting
    [`initial_history_in_client_content`](https://ai.google.dev/api/live#HistoryConfig)
    in
    [`history_config`](https://ai.google.dev/api/live#BidiGenerateContentSetup)).
    You can also use
    [`send_realtime_input`](https://ai.google.dev/api/live#bidigeneratecontentrealtimeinput)
    to stream realtime text, audio, or video chunks. See
    [Incremental content updates](/docs/live-api/capabilities#incremental-updates).

- **Turn coverage**: Defaults to
  [`TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`](https://ai.google.dev/api/live#turncoverage) instead
  of `TURN_INCLUDES_ONLY_ACTIVITY`. The model's turn now includes detected
  audio activity and all video frames. If your application currently sends a
  constant stream of video frames, you may want to update your application to
  only send video frames when there is audio activity to avoid incurring
  additional costs.

- **Async function calling**: Not yet supported. Function calling is
  synchronous only. The model will not start responding until you've sent
  the tool response. See
  [Async function calling](/docs/live-api/tools#async-function-calling).

- **Proactive audio and affective dialogue**: These features are not yet
  supported in Gemini 3.1 Flash Live. Remove any configuration for these
  features from your code. See
  [Proactive audio](/docs/live-api/capabilities#proactive-audio) and
  [Affective dialogue](/docs/live-api/capabilities#affective-dialog).

For a detailed feature comparison, see the
[Model comparison](/docs/live-api/capabilities#model-comparison) table in the capabilities
guide.

# Gemini 3.1 Flash-Lite
Source: https://aistudio.google.com/docs/models/gemini-3.1-flash-lite
Description: Learn about Gemini 3.1 Flash-Lite from Google

Gemini 3.1 Flash-Lite is a low-latency, cost-effective multimodal model
optimized for high-frequency, lightweight tasks. The model supports text, image,
video, audio, and PDF inputs, and is designed for high-volume agentic workflows,
simple data extraction, and applications where latency and API cost are the
primary constraints.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-3.1-flash-lite" variant="ais" %}Try in Google AI Studio{% /button %}

## gemini-3.1-flash-lite {% id="gemini-31-flash-lite" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.1-flash-lite`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Computer use**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * `Stable: gemini-3.1-flash-lite`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* May 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-1-flash-lite/)
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-3.1-flash-lite)
{% /table %}
## Developer guide {% id="developer-guide" %}

Gemini 3.1 Flash-Lite is best at handling straightforward tasks at significant
scale. Here are some use cases best suited for Gemini 3.1 Flash-Lite:

* **Translation**: Fast, cheap, high-volume translation, such as processing
    chat messages, reviews, and support tickets at scale. You can use system
    instructions to constrain output to only the translated text with no extra
    commentary:

    ```python
    from google import genai

    client = genai.Client()
    text = "Hey, are you down to grab some pizza later? I'm starving!"

    response = client.models.generate_content(
        model="gemini-3.1-flash-lite",
        config={
            "system_instruction": "Only output the translated text"
        },
        contents=f"Translate the following text to German: {text}"
    )

    print(response.text)
    ```

* **Transcription**: Process recordings, voice notes, or any audio content
    where you need a text transcript without spinning up a separate
    speech-to-text pipeline. Supports multimodal inputs, so you can pass audio
    files directly for transcription:

    ```python
    from google import genai

    client = genai.Client()

    uploaded_file = client.files.upload(file='sample.mp3')

    prompt = 'Generate a transcript of the audio.'

    response = client.models.generate_content(
      model="gemini-3.1-flash-lite",
      contents=[prompt, uploaded_file]
    )

    print(response.text)
    ```

* **Lightweight agentic tasks and data extraction**: Entity extraction,
    classification, and lightweight data processing pipelines supported with
    structured JSON output. For example, extracting structured data from an
    e-commerce customer review:

    ```python
    from google import genai
    from pydantic import BaseModel, Field

    client = genai.Client()

    prompt = "Analyze the user review and determine the aspect, sentiment score, summary quote, and return risk"
    input_text = "The boots look amazing and the leather is high quality, but they run way too small. I'm sending them back."

    class ReviewAnalysis(BaseModel):
        aspect: str = Field(description="The feature mentioned (e.g., Price, Comfort, Style, Shipping)")
        summary_quote: str = Field(description="The specific phrase from the review about this aspect")
        sentiment_score: int = Field(description="1 to 5 (1=worst, 5=best)")
        is_return_risk: bool = Field(description="True if the user mentions returning the item")

    response = client.models.generate_content(
        model="gemini-3.1-flash-lite",
        contents=[prompt, input_text],
        config={
            "response_mime_type": "application/json",
            "response_json_schema": ReviewAnalysis.model_json_schema(),
        },
    )

    print(response.text)
    ```

* **Document processing and summarization**: Parse PDFs and return concise
    summaries, like for building a document processing pipeline or quickly
    triaging incoming files:

    ```python
    from google import genai
    from google.genai import types
    import httpx

    client = genai.Client()

    doc_url = "https://storage.googleapis.com/generativeai-downloads/data/med_gemini.pdf"
    doc_data = httpx.get(doc_url).content

    prompt = "Summarize this document"
    response = client.models.generate_content(
        model="gemini-3.1-flash-lite",
        contents=[
            types.Part.from_bytes(
                data=doc_data,
                mime_type='application/pdf',
            ),
            prompt
        ]
    )

    print(response.text)
    ```

* **Model routing**: Use a low-latency and low-cost model as a classifier that
    routes queries to the appropriate model based on task complexity. This is a
    real pattern in production - the open-source [Gemini CLI](https://geminicli.com/docs/core/#model-fallback) uses Flash-Lite to
    classify task complexity and route to Flash or Pro accordingly.

    ```python
    from google import genai

    client = genai.Client()

    FLASH_MODEL = 'flash'
    PRO_MODEL = 'pro'

    CLASSIFIER_SYSTEM_PROMPT = f"""
    You are a specialized Task Routing AI. Your sole function is to analyze the user's request and classify its complexity. Choose between `{FLASH_MODEL}` (SIMPLE) or `{PRO_MODEL}` (COMPLEX).

    1. `{FLASH_MODEL}`: A fast, efficient model for simple, well-defined tasks.
    2. `{PRO_MODEL}`: A powerful, advanced model for complex, open-ended, or multi-step tasks.

    A task is COMPLEX if it meets ONE OR MORE of the following criteria:

    1. High Operational Complexity (Est. 4+ Steps/Tool Calls)
    2. Strategic Planning and Conceptual Design
    3. High Ambiguity or Large Scope
    4. Deep Debugging and Root Cause Analysis

    A task is SIMPLE if it is highly specific, bounded, and has Low Operational Complexity (Est. 1-3 tool calls).
    """

    user_input = "I'm getting an error 'Cannot read property 'map' of undefined' when I click the save button. Can you fix it?"

    response_schema = {
      "type": "object",
      "properties": {
        "reasoning": {
          "type": "string",
          "description": "A brief, step-by-step explanation for the model choice, referencing the rubric."
        },
        "model_choice": {
          "type": "string",
          "enum": [FLASH_MODEL, PRO_MODEL]
        }
      },
      "required": ["reasoning", "model_choice"]
    }

    response = client.models.generate_content(
        model="gemini-3.1-flash-lite",
        contents=user_input,
        config={
            "system_instruction": CLASSIFIER_SYSTEM_PROMPT,
            "response_mime_type": "application/json",
            "response_json_schema": response_schema
        },
    )

    print(response.text)
    ```

* **Thinking**: For better accuracy for tasks that benefit from step-by-step
    reasoning, configure thinking so the model spends additional compute on
    internal reasoning before producing the final output:

    ```python
    from google import genai
    from google.genai import types

    client = genai.Client()

    response = client.models.generate_content(
        model="gemini-3.1-flash-lite",
        contents="How does AI work?",
        config=types.GenerateContentConfig(
            thinking_config=types.ThinkingConfig(thinking_level="high")
        ),
    )

    print(response.text)
    ```

# Gemini 3.1 Flash-Lite preview
Source: https://aistudio.google.com/docs/models/gemini-3.1-flash-lite-preview
Description: Learn about Gemini 3.1 Flash-Lite preview from Google

{% callout type="warning" %}
Gemini 3.1 Flash-Lite Preview is [deprecated](/docs/deprecations) and has been
shut down on May 25, 2026. Migrate to
[Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite) to avoid service
disruption.
{% /callout %}

## gemini-3.1-flash-lite-preview {% id="gemini-31-flash-lite-preview" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-3.1-flash-lite-preview`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, Image, Video, Audio, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Computer use**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * *Shut down*: `gemini-3.1-flash-lite-preview`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* March 2026
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model card

    {% /section %}
* [Model card](https://deepmind.google/models/model-cards/gemini-3-1-flash-lite/)
{% /table %}

# Gemini 2.5 Flash
Source: https://aistudio.google.com/docs/models/gemini-2.5-flash
Description: Learn about Gemini 2.5 Flash from Google

{% callout type="caution" %}
Gemini 2.5 Flash (`gemini-2.5-flash`) is
[deprecated](/docs/deprecations#gemini-2.5-flash-models) and is no longer
available to select in Google AI Studio (API access is limited to existing users
until December 1, 2026). Effective December 1, 2026, all API requests to
`gemini-2.5-flash` will automatically route to
[Gemini 3.5 Flash-Lite (`gemini-3.5-flash-lite`)](/docs/models/gemini-3.5-flash-lite)
and be billed at
[Gemini 3.5 Flash-Lite rates](/docs/pricing#gemini-3.5-flash-lite). Before
December 1, 2026, update your model string to `gemini-3.5-flash-lite` and review
the
[Gemini 3.5 Flash-Lite migration guide](/docs/whats-new-gemini-3.6#migrate-to-gemini-3-5-flash-lite).
Breaking API changes include function calling and `thought_signature`
validation, `thinking_level` replacing `thinking_budget`, and removed sampling
parameters and prefilled model turns.
{% /callout %}

Our best model in terms of price-performance, offering well-rounded
capabilities. 2.5 Flash is best for large scale processing, low-latency, high
volume tasks that require thinking, and agentic use cases.

## gemini-2.5-flash {% id="gemini-25-flash" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.5-flash`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, images, video, audio

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Deprecated: `gemini-2.5-flash` (effective December 1, 2026, automatically routed to `gemini-3.5-flash-lite`)
    * Shut down: [gemini-2.5-flash-preview-09-2025](/docs/models/gemini-2.5-flash-preview-09-2025)
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* June 2025
---

* {% section class="model-property" %}

    {% icon name="cognition_2" /%}Knowledge cutoff

    {% /section %}
* January 2025
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-2.5-flash)
{% /table %}

# Gemini 2.5 Flash preview
Source: https://aistudio.google.com/docs/models/gemini-2.5-flash-preview-09-2025
Description: Learn about Gemini 2.5 Flash Preview from Google

{% callout type="warning" %}
    This model is [shut down](/docs/deprecations) as of February 17, 2026; migrate to [Gemini 2.5 Flash](/docs/models/gemini-2.5-flash) for improved performance.
{% /callout %}

## gemini-2.5-flash-preview-09-2025 {% id="gemini-25-flash-preview-09-2025" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.5-flash-preview-09-2025`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, images, video, audio

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL Context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: [gemini-2.5-flash](/docs/models/gemini-2.5-flash)
    * Shut down: `gemini-2.5-flash-preview-09-2025`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* September 2025
---

* {% section class="model-property" %}

    {% icon name="cognition_2" /%}Knowledge cutoff

    {% /section %}
* January 2025
{% /table %}

# Gemini 2.5 Flash image (Nano Banana)
Source: https://aistudio.google.com/docs/models/gemini-2.5-flash-image
Description: Learn about Gemini 2.5 Flash Image from Google

Our best engine for high-velocity visual creation, offering state-of-the-art
speed and efficiency. Gemini 2.5 Flash Image, also known as Nano Banana, is best
for high-volume generation, conversational image editing, and low-latency
creative workflows that require native multimodal understanding.

{% button href="https://aistudio.google.com?model=gemini-2.5-flash-image" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Image generation](/docs/image-generation) guide for full
coverage of features and capabilities.

## gemini-2.5-flash-image {% id="gemini-25-flash-image" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.5-flash-image`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Image and Text

    **Output**
    Image and Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    65,536

    **Output token limit**
    32,768
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-2.5-flash-image`
    * Deprecated: `gemini-2.5-flash-image-preview`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* October 2025
---

* {% section class="model-property" %}

    {% icon name="cognition_2" /%}Knowledge cutoff

    {% /section %}
* June 2025
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-2.5-flash-image)
{% /table %}

# Gemini 2.5 Flash live preview
Source: https://aistudio.google.com/docs/models/gemini-2.5-flash-native-audio-preview-12-2025
Description: Learn about Gemini 2.5 Flash Live from Google

The Live API enables low-latency, real-time voice and video interactions with
Gemini 2.5 Flash. It processes continuous streams of audio, video, or text to
deliver immediate, human-like spoken responses, creating a natural
conversational experience for your users.

{% button href="https://aistudio.google.com?model=gemini-2.5-flash-native-audio-preview-12-2025" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Live API](/docs/live-api) guide for full coverage
of features and capabilities.

## gemini-2.5-flash-native-audio-preview-12-2025 {% id="gemini-25-flash-native-audio-preview-12-2025" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.5-flash-native-audio-preview-12-2025`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Audio, video, text

    **Output**
    Audio and text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    131,072

    **Output token limit**
    8,192
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Preview: `gemini-2.5-flash-native-audio-preview-12-2025`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* September 2025
---

* {% section class="model-property" %}

    {% icon name="cognition_2" /%}Knowledge cutoff

    {% /section %}
* January 2025
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-2.5-flash-native-audio)
{% /table %}

# Gemini 2.5 Flash text-to-speech
Source: https://aistudio.google.com/docs/models/gemini-2.5-flash-preview-tts
Description: Learn about Gemini 2.5 Flash TTS from Google

Our fastest engine for high-fidelity speech synthesis, offering low-latency and
cost-efficient audio generation. Gemini 2.5 Flash TTS is best for real-time
assistants, high-volume narration, and conversational use cases that require
fine-grained control over voice style and pacing.

{% button href="https://aistudio.google.com?model=gemini-2.5-flash-preview-tts" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Text-to-Speech](/docs/speech-generation) guide for full
coverage of features and capabilities.

## gemini-2.5-flash-preview-tts {% id="gemini-25-flash-preview-tts" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.5-flash-preview-tts`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text

    **Output**
    Audio
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    8,192

    **Output token limit**
    16,384
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * `gemini-2.5-flash-preview-tts`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* December 2025
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-2.5-flash-preview-tts)
{% /table %}

# Gemini 2.5 Flash-Lite
Source: https://aistudio.google.com/docs/models/gemini-2.5-flash-lite
Description: Learn about Gemini 2.5 Flash-Lite from Google

{% callout type="note" %}
To ensure reliable performance for everyone, we are limiting access to the 2.5
models to users who have actively used them in the past. `gemini-2.5-flash-lite`
is not deprecated and will continue to be served until further notice through
the API. For any new projects, use our latest models: 3.5 Flash-Lite or 3.8
Flash. This helps us maintain sufficient capacity for both ongoing legacy
workflows and new applications.
{% /callout %}

Our most cost-efficient multimodal model, offering the fastest performance for
high-frequency, lightweight tasks. Gemini 2.5 Flash-Lite is best for high-volume
classification, simple data extraction, and extremely low-latency applications
where budget and speed are the primary constraints.

{% button href="https://aistudio.google.com?model=gemini-2.5-flash-lite" variant="ais" %}Try in Google AI Studio{% /button %}

## gemini-2.5-flash-lite {% id="gemini-25-flash-lite" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.5-flash-lite`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, image, video, audio, PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-2.5-flash-lite`
    * Shut down: [gemini-2.5-flash-lite-preview-09-2025](/docs/models/gemini-2.5-flash-lite-preview-09-2025)
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* July 2025
---

* {% section class="model-property" %}

    {% icon name="cognition_2" /%}Knowledge cutoff

    {% /section %}
* January 2025
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-2.5-flash-lite)
{% /table %}

# Gemini 2.5 Flash-Lite preview
Source: https://aistudio.google.com/docs/models/gemini-2.5-flash-lite-preview-09-2025
Description: Learn about Gemini 2.5 Flash-Lite Preview from Google

{% callout type="warning" %}
  This model is [shut down](/docs/deprecations) as of March 31, 2026. Migrate to [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite) to avoid service disruption.
{% /callout %}

## gemini-2.5-flash-lite-preview-09-2025 {% id="gemini-25-flash-lite-preview-09-2025" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.5-flash-lite-preview-09-2025`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text, image, video, audio, PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: [gemini-2.5-flash-lite](/docs/models/gemini-2.5-flash-lite)
    * Shut down: `gemini-2.5-flash-lite-preview-09-2025`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* September 2025
---

* {% section class="model-property" %}

    {% icon name="cognition_2" /%}Knowledge cutoff

    {% /section %}
* January 2025
{% /table %}

# Gemini 2.5 Pro
Source: https://aistudio.google.com/docs/models/gemini-2.5-pro
Description: Learn about Gemini 2.5 Pro from Google

{% callout type="caution" %}
Gemini 2.5 Pro (`gemini-2.5-pro`) is
[deprecated](/docs/deprecations#gemini-2.5-pro-models) and is no longer
available to select in Google AI Studio (API access is limited to existing users
until December 1, 2026). Effective December 1, 2026, all API requests to
`gemini-2.5-pro` will automatically route to
[Gemini 3.8 Flash (`gemini-3.8-flash`)](/docs/models/gemini-3.8-flash) and be
billed at [Gemini 3.8 Flash rates](/docs/pricing#gemini-3.8-flash). Before
December 1, 2026, update your model string to `gemini-3.8-flash` and review the
[Gemini 3.8 Flash migration guide](/docs/whats-new-gemini-3.8#migrate-to-gemini-3-8-flash).
Breaking API changes include function calling and `thought_signature`
validation, `thinking_level` replacing `thinking_budget`, and removed sampling
parameters and prefilled model turns.
{% /callout %}

Our state-of-the-art thinking model, capable of reasoning over complex problems
in code, math, and STEM, as well as analyzing large datasets, codebases, and
documents using long context.

## gemini-2.5-pro {% id="gemini-25-pro" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.5-pro`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Audio, images, video, text, and PDF

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    65,536
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Deprecated: `gemini-2.5-pro` (effective December 1, 2026, automatically routed to `gemini-3.8-flash`)
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* June 2025
---

* {% section class="model-property" %}

    {% icon name="cognition_2" /%}Knowledge cutoff

    {% /section %}
* January 2025
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-2.5-pro)
{% /table %}

# Gemini 2.5 Pro text-to-speech
Source: https://aistudio.google.com/docs/models/gemini-2.5-pro-preview-tts
Description: Learn about Gemini 2.5 Pro TTS from Google

Our premium engine for studio-quality speech synthesis, offering high-fidelity
and sophisticated audio generation. Gemini 2.5 Pro TTS is best for long-form
content, professional narrations, and complex creative workflows that require
the highest level of vocal clarity and natural prosody.

{% button href="https://aistudio.google.com?model=gemini-2.5-pro-preview-tts" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Text-to-Speech](/docs/speech-generation) guide for full
coverage of features and capabilities.

## gemini-2.5-pro-preview-tts {% id="gemini-25-pro-preview-tts" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.5-pro-preview-tts`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text

    **Output**
    Audio
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    8,192

    **Output token limit**
    16,384
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * `gemini-2.5-pro-preview-tts`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* December 2025
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-2.5-pro-preview-tts)
{% /table %}

# Gemini 2.5 computer use model
Source: https://aistudio.google.com/docs/models/gemini-2.5-computer-use-preview-10-2025
Description: Learn about the Gemini Computer Use model from Google

{% callout type="warning" %}
This model was [shut down](/docs/deprecations) on **July 28, 2026**; migrate to
[Gemini 3.8 Flash](/docs/models/gemini-3.8-flash) or other
[Gemini 3](/docs/models#gemini-3) models with built-in
[computer use](/docs/computer-use) support to avoid service interruptions.
{% /callout %}

An agentic capability model designed for direct interface interaction, allowing
Gemini to perceive and navigate digital environments. Gemini 2.5 Computer Use is
best for browser automation, multi-step software tasks, and UI testing that
requires visual reasoning and precise cursor control.

## Documentation {% id="documentation" %}

Visit the [Computer use](/docs/computer-use) page for full coverage
of features and capabilities.

## gemini-2.5-computer-use-preview-10-2025 {% id="gemini-25-computer-use-preview-10-2025" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_computer-use.md" /%}

# Gemini 2.0 Flash
Source: https://aistudio.google.com/docs/models/gemini-2.0-flash
Description: Learn about Gemini 2.0 Flash from Google

{% callout type="warning" %} Gemini 2.0 Flash is
[deprecated](/docs/deprecations) and has been shut down June 1, 2026. Migrate to
[Gemini 3.8 Flash](/docs/models/gemini-3.8-flash) to avoid service disruption.
{% /callout %}

## gemini-2.0-flash {% id="gemini-20-flash" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.0-flash`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Audio, images, video, and text
    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    8,192
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    Experimental
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * *Shut down*: `gemini-2.0-flash`
    * *Shut down*: `gemini-2.0-flash-001`
    * *Shut down*: `gemini-2.0-flash-exp`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* February 2025
---

* {% section class="model-property" %}

    {% icon name="cognition_2" /%}Knowledge cutoff

    {% /section %}
* August 2024
{% /table %}

# Gemini 2.0 Flash-Lite
Source: https://aistudio.google.com/docs/models/gemini-2.0-flash-lite
Description: Learn about Gemini 2.0 Flash-Lite from Google

{% callout type="warning" %}
Gemini 2.0 Flash-Lite is [deprecated](/docs/deprecations) and has been shut down June 1, 2026. Migrate to [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite) to avoid service disruption.
{% /callout %}

## gemini-2.0-flash-lite {% id="gemini-20-flash-lite" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `gemini-2.0-flash-lite`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Audio, images, video, and text

    **Output**
    Text
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    1,048,576

    **Output token limit**
    8,192
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * *Shut down*: `gemini-2.0-flash-lite`
    * *Shut down*: `gemini-2.0-flash-lite-001`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* February 2025
---

* {% section class="model-property" %}

    {% icon name="cognition_2" /%}Knowledge cutoff

    {% /section %}
* August 2024
{% /table %}

# Imagen 4
Source: https://aistudio.google.com/docs/models/imagen
Description: Learn about Imagen 4 from Google

{% callout type="warning" %}
  The Imagen 4 standard, ultra, and fast endpoints are [deprecated](/docs/deprecations) and will be shut down on **August 17, 2026**; migrate to [Gemini 3.1 Flash Image](/docs/models/gemini-3.1-flash-image) to avoid service interruptions.
{% /callout %}

A high-performance engine for advanced visual synthesis, offering sophisticated
creative control and photorealistic output. Use Imagen 4 for professional
branding, intricate scene composition, and high-fidelity design tasks that
require precise text rendering and complex lighting.

{% button href="https://aistudio.google.com?model=imagen-4.0-generate-001" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Imagen](/docs/image-generation) page for full coverage of
features and capabilities.

## imagen-4.0-generate-001 {% id="imagen-40-generate-001" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* **Gemini API**
    `imagen-4.0-generate-001`

    `imagen-4.0-ultra-generate-001`

    `imagen-4.0-fast-generate-001`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Input**
    Text

    **Output**
    Images
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    480 tokens (text)

    **Output images**
    1 to 4 (Ultra/Standard/Fast)
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* June 2025
{% /table %}

# Veo 3.1
Source: https://aistudio.google.com/docs/models/veo-3.1-generate-preview
Description: Learn about the Veo 3.1 video generation model from Google

{% callout type="warning" %} `veo-3.1-generate-preview` and
`veo-3.1-fast-generate-preview` were [shut down](/docs/deprecations) on
**October 22, 2026**; migrate to
[Gemini Omni Flash](/docs/models/gemini-omni-flash) (`gemini-omni-1.1-flash`) or
the GA models available through the
[Gemini Enterprise Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate)
to avoid service interruptions. {% /callout %}

A state-of-the-art cinematic engine designed for high-end creative storytelling
and experimental video production. Veo 3.1 is best for professional-grade 4K
output, natively synchronized audio generation, and complex camera movements
that require the highest level of temporal consistency and artistic control.

## Documentation {% id="documentation" %}

Visit the [Video generation](/docs/video) page for full coverage of
features and capabilities.

## veo-3.1-generate-preview {% id="veo-31-generate-preview" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* **Gemini API**
    `veo-3.1-generate-preview`
    `veo-3.1-fast-generate-preview`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Input**
    Text, Image

    **Output**
    Video with audio
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Limits

    {% /section %}
* **Text input**
    1,024 tokens

    **Output video**
    1
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* January 2026
{% /table %}

# Veo 2.0
Source: https://aistudio.google.com/docs/models/veo-2.0-generate-001
Description: Learn about the Veo 2.0 video generation model from Google

{% callout type="warning" %}
  This model was [shut down](/docs/deprecations) on **June 30, 2026**; migrate to [Gemini Omni Flash](/docs/models/gemini-omni-flash) (`gemini-omni-1.1-flash`) or the GA models available through the [Gemini Enterprise Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate) to avoid service interruptions.
{% /callout %}

Our robust and reliable stable video generation model, providing consistent
performance for production-ready workflows. Veo 2.0 is best for standard 1080p
content creation, social media assets, and high-volume video tasks that
prioritize reliable character consistency and predictable sub-second generation
speeds.

## Documentation {% id="documentation" %}

Visit the [Video generation](/docs/video) page for full coverage of
features and capabilities.

## veo-2.0-generate-001 {% id="veo-20-generate-001" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* **Gemini API**
    `veo-2.0-generate-001`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Input**
    Text, image

    **Output**
    Video
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Limits

    {% /section %}
* **Text input**
    N/A

    **Image input**
    Any image resolution and aspect ratio up to 20MB file size

    **Output video**
    Up to 2
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* April 2025
{% /table %}

# Gemini Embedding model
Source: https://aistudio.google.com/docs/models/gemini-embedding-001
Description: Learn about the Gemini Embedding model from Google

A specialized engine for high-dimensional vector representation, providing
efficient numerical mapping of text and images. The Gemini Embedding model is
best for semantic search, document retrieval, and recommendation systems that
require fast, scalable similarity calculations across large datasets.

## Documentation {% id="documentation" %}

Visit the [Embeddings](/docs/embeddings) page for full coverage
of features and capabilities.

## gemini-embedding-001 {% id="gemini-embedding-001" %}
  {% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* **Gemini API**
    `gemini-embedding-001`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Input**
    Text

    **Output**
    Text embeddings
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    2,048

    **Output dimension size**
    Flexible, supports: 128 - 3072, Recommended: 768, 1536, 3072
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-embedding-001`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* June 2025
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-embedding)
{% /table %}

# Gemini Embedding 2 model
Source: https://aistudio.google.com/docs/models/gemini-embedding-2
Description: Learn about the Gemini Embedding 2 model from Google

Our first multimodal embedding model, providing efficient numerical mapping of
text, images, video, audio, and PDFs into a single unified embedding space. The
Gemini Embedding 2 model is best for cross-modal semantic search, document
retrieval, and recommendation systems that require fast, scalable similarity
calculations across large multimodal datasets.

## Documentation {% id="documentation" %}

Visit the [Embeddings](/docs/embeddings) page for full coverage
of features and capabilities.

## gemini-embedding-2 {% id="gemini-embedding-2" %}
  {% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* **Gemini API**
    `gemini-embedding-2`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Input**
    Text, image, video, audio, PDF

    **Output**
    Text embeddings
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    8,192

    **Output dimension size**
    Flexible, supports: 128 - 3072, Recommended: 768, 1536, 3072
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `gemini-embedding-2`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* April 2026
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#gemini-embedding-2)
{% /table %}

# Gemini Embedding 2 preview model
Source: https://aistudio.google.com/docs/models/gemini-embedding-2-preview
Description: Learn about the Gemini Embedding 2 model from Google

Our first multimodal embedding model, providing efficient numerical mapping of
text, images, video, audio, and PDFs into a single unified embedding space. The
Gemini Embedding 2 model is best for cross-modal semantic search, document
retrieval, and recommendation systems that require fast, scalable similarity
calculations across large multimodal datasets.

## Documentation {% id="documentation" %}

Visit the [Embeddings](/docs/embeddings) page for full coverage
of features and capabilities.

## gemini-embedding-2-preview {% id="gemini-embedding-2-preview" %}
  {% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* **Gemini API**
    `gemini-embedding-2-preview`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Input**
    Text, image, video, audio, PDF

    **Output**
    Text embeddings
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    8,192

    **Output dimension size**
    Flexible, supports: 128 - 3072, Recommended: 768, 1536, 3072
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Preview: `gemini-embedding-2-preview`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* March 2026
{% /table %}

# Gemini Robotics ER 2
Source: https://aistudio.google.com/docs/models/gemini-robotics-er-2-preview
Description: Learn about Gemini Robotics ER 2 from Google

Gemini Robotics ER 2 is a vision-language model (VLM) for robotics that
accepts text, image, video, and audio input. It supports spatial reasoning,
video understanding, agentic code execution, multi-step tool
orchestration, and multi-robot coordination.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-robotics-er-2-preview" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation

Visit the [Robotics](/docs/robotics-overview) page for full coverage
of features and capabilities.

## gemini-robotics-er-2-preview {% id="gemini-robotics-er-2-preview" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_robotics-er.md" /%}

# Gemini Robotics ER 2 streaming
Source: https://aistudio.google.com/docs/models/gemini-robotics-er-2-streaming-preview
Description: Learn about Gemini Robotics ER 2 Streaming from Google

Gemini Robotics ER 2 Streaming is a vision-language model (VLM) for robotics
optimized for real-time text streaming using the Live API. It accepts text,
image, video, and audio input and supports bidirectional streaming with
function calling.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-robotics-er-2-streaming-preview" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation

Visit the [Live API for robotics](/docs/robotics-streaming) page for
full coverage of features and capabilities.

## gemini-robotics-er-2-streaming-preview {% id="gemini-robotics-er-2-streaming-preview" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_robotics-er.md" /%}

# Gemini Robotics ER 1.5
Source: https://aistudio.google.com/docs/models/gemini-robotics-er-1.5-preview
Description: Learn about Gemini Robotics Preview model from Google

{% callout type="note" %}
Note: This version is planned for [deprecation soon](/docs/deprecations). See
the [models](/docs/models) page for the latest model version.
{% /callout %}

Gemini Robotics ER 1.5 is a vision-language model (VLM) that brings Gemini's
agentic capabilities to robotics. It's designed for advanced reasoning in the
physical world, allowing robots to interpret complex visual data, perform
spatial reasoning, and plan actions from natural language commands.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-robotics-er-1.5-preview" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Robotics](/docs/robotics-overview) page for full coverage
of features and capabilities.

## gemini-robotics-er-1.5-preview {% id="gemini-robotics-er-15-preview" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_1.5-robotics-er.md" /%}

# Gemini Robotics ER 1.6
Source: https://aistudio.google.com/docs/models/gemini-robotics-er-1.6-preview
Description: Learn about Gemini Robotics Preview model from Google

{% callout type="note" %}
This version is deprecated. Migrate to
[Gemini Robotics ER 2](/docs/models/gemini-robotics-er-2-preview)
(`gemini-robotics-er-2-preview`). See the [deprecations](/docs/deprecations)
page for details.
{% /callout %}

Gemini Robotics ER 1.6 is a vision-language model (VLM) that brings Gemini's
agentic capabilities to robotics. It's designed for advanced reasoning in the
physical world, allowing robots to interpret complex visual data, perform
spatial reasoning, and plan actions from natural language commands.

## Documentation {% id="documentation" %}

Visit the [Robotics](/docs/robotics-overview) page for full coverage
of features and capabilities.

## gemini-robotics-er-1.6-preview {% id="gemini-robotics-er-16-preview" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_1.6-robotics-er.md" /%}

# Deep Research Pro preview
Source: https://aistudio.google.com/docs/models/deep-research-pro-preview-12-2025
Description: Learn about Gemini Deep Research Pro preview model from Google

{% callout type="warning" %}
`deep-research-pro-preview-12-2025` is [deprecated](/docs/deprecations#managed-agents) and will be shut down on October 23, 2026. Migrate to [`deep-research-preview-04-2026`](/docs/models/deep-research-preview-04-2026) or [`deep-research-max-preview-04-2026`](/docs/models/deep-research-max-preview-04-2026).
{% /callout %}

A powerful agentic researcher designed for autonomous, multi-step investigations
that synthesize complex information into comprehensive, cited reports. Powered
by Gemini 3.1 Pro, this model is optimized for long-running tasks and
accuracy-critical analysis across hundreds of public web sources and private
workspace data like Gmail and Drive.

## Documentation {% id="documentation" %}

Visit the [Deep Research](/docs/deep-research) page for full coverage
of features and capabilities.

## deep-research-pro-preview-12-2025 {% id="deep-research-pro-preview-12-2025" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_deep-research-pro-preview.md" /%}

# Deep Research preview
Source: https://aistudio.google.com/docs/models/deep-research-preview-04-2026
Description: Learn about Gemini Deep Research preview model from Google

A powerful agentic researcher designed for autonomous, multi-step investigations
that synthesize complex information into comprehensive, cited reports. This
model supports collaborative planning, visualization, MCP servers, and File
Search. It comes in two versions: Deep Research for speed and efficiency, and
Deep Research Max for maximum comprehensiveness.

## Documentation {% id="documentation" %}

Visit the [Deep Research](/docs/deep-research) page for full coverage
of features and capabilities.

## deep-research-preview-04-2026 {% id="deep-research-preview-04-2026" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_deep-research-preview.md" /%}

# Deep Research Max preview
Source: https://aistudio.google.com/docs/models/deep-research-max-preview-04-2026
Description: Learn about Gemini Deep Research Max preview model from Google

Maximum comprehensiveness for automated context gathering and synthesis. Deep
Research Max is optimized for long-running, accuracy-critical investigations
that synthesize complex information from hundreds of public web sources and
private workspace data into comprehensive, cited reports. It supports
collaborative planning, visualization, MCP servers, and File Search.

## Documentation {% id="documentation" %}

Visit the [Deep Research](/docs/deep-research) page for full coverage
of features and capabilities.

## deep-research-max-preview-04-2026 {% id="deep-research-max-preview-04-2026" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_deep-research-max-preview.md" /%}

# Antigravity preview
Source: https://aistudio.google.com/docs/models/antigravity-preview-05-2026
Description: Learn about Antigravity Agent preview model from Google

{% callout type="warning" %}
`antigravity-preview-05-2026` is [deprecated](/docs/deprecations#managed-agents) and will be shut down on October 5, 2026. Migrate to [`antigravity-preview-09-2026`](/docs/models/antigravity-preview-09-2026).
{% /callout %}

A powerful general-purpose managed agent designed for autonomous, multi-step
workflows. This model plans, reasons, runs code, manages files, and searches the
web inside a secure, isolated Linux sandbox hosted by Google.

## Documentation {% id="documentation" %}

Visit the [Antigravity Agent](/docs/antigravity-agent) page for full
coverage of features, capabilities, and code samples.

## antigravity-preview-05-2026 {% id="antigravity-preview-05-2026" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_antigravity-preview.md" /%}

# Antigravity preview
Source: https://aistudio.google.com/docs/models/antigravity-preview-09-2026
Description: Learn about Antigravity Agent preview model from Google

A powerful general-purpose managed agent designed for autonomous, multi-step
workflows. This model plans, reasons, runs code, manages files, and searches the
web inside a secure, isolated Linux sandbox hosted by Google.

The September 2026 release (`antigravity-preview-09-2026`) upgrades the runtime
harness with improved prompt caching, native code search tools, and efficient
line-range file editing.

## Documentation {% id="documentation" %}

Visit the [Antigravity Agent](/docs/antigravity-agent) page for full
coverage of features, capabilities, and code samples.

## antigravity-preview-09-2026 {% id="antigravity-preview-09-2026" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_antigravity-preview-09-2026.md" /%}

# Lyria RealTime experimental
Source: https://aistudio.google.com/docs/models/lyria-realtime-exp
Description: Learn about the Lyria RealTime experimental music generation model from Google

An experimental engine for high-fidelity musical synthesis, offering innovative
capabilities for generating and transforming audio content. Lyria RealTime
is best for AI-assisted songwriting, unique instrumental generation, and
creative audio workflows that require deep control over melody and rhythm, with
no vocals.

{% button href="https://deepmind.google/models/lyria/lyria-realtime/" variant="primary" %}Try Lyria RealTime{% /button %}

## Documentation {% id="documentation" %}

Visit the [Realtime music generation](/docs/realtime-music-generation)
page for full coverage of features and capabilities.

## lyria-realtime-exp {% id="lyria-realtime-exp" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_lyria-exp.md" /%}

# Lyria 3.5
Source: https://aistudio.google.com/docs/models/lyria-3.5
Description: Learn about Lyria 3.5 from Google DeepMind

Lyria 3.5 is Google's flagship music generation model. It is
optimized for generating full-length songs with complex structural coherence,
including multiple verses, choruses, and bridges. It generates high-quality,
44.1 kHz stereo audio from text prompts or image inputs.

{% button href="https://aistudio.google.com/prompts/new_chat?model=lyria-3.5" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Music Generation](/docs/music-generation) guide for full coverage of
features and capabilities.

## lyria-3.5 {% id="lyria-35" %}
{% table variant="model" %}
* Property
* Description
---

* {% section class="model-property" %}

    {% icon name="id_card" /%}Model code

    {% /section %}
* `lyria-3.5`
---

* {% section class="model-property" %}

    {% icon name="save" /%}Supported data types

    {% /section %}
* **Inputs**
    Text and Image

    **Output**
    Audio (MP3), Text (Lyrics)
---

* {% section class="model-property" %}

    {% icon name="token_auto" /%}Token limits{% sup %}[[*]](/docs/tokens){% /sup %}

    {% /section %}
* **Input token limit**
    131,072
---

* {% section class="model-property" %}

    {% icon name="handyman" /%}Capabilities

    {% /section %}
* {% section class="three-column-grid" %}

    {% section %}
    **Audio generation**
    {% badge type="supported" /%}
    {% /section %}

    {% section %}
    **Batch API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Caching**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Code execution**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **File search**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Flex inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Function calling**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Grounding with Google Maps**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Image generation**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Live API**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Priority inference**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Search grounding**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Structured outputs**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **Thinking**
    {% badge type="not-supported" /%}
    {% /section %}

    {% section %}
    **URL context**
    {% badge type="not-supported" /%}
    {% /section %}
    {% /section %}
---

* {% section class="model-property" %}

    {% icon name="123" /%}Versions

    {% /section %}
* Read the [model version patterns](/docs/models#model-versions) for more details.

    * Stable: `lyria-3.5`
---

* {% section class="model-property" %}

    {% icon name="calendar_month" /%}Latest update

    {% /section %}
* September 2026
---

* {% section class="model-property" %}

    {% icon name="paid" /%}Pricing

    {% /section %}
* [Pricing](/docs/pricing#lyria-3-5)
{% /table %}

# Lyria 3 Clip preview
Source: https://aistudio.google.com/docs/models/lyria-3-clip-preview
Description: Learn about Lyria 3 Clip Preview from Google DeepMind

Lyria 3 Clip Preview is Google's model optimized for generating short
musical clips, loops, and previews. It generates 30-second high-quality, 48kHz
stereo audio from text prompts or image inputs.

{% button href="https://aistudio.google.com/prompts/new_chat?model=lyria-3-clip-preview" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Music Generation](/docs/music-generation) guide for full
coverage of features and capabilities.

## lyria-3-clip-preview {% id="lyria-3-clip-preview" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_lyria-3.md" /%}

# Lyria 3 Pro preview
Source: https://aistudio.google.com/docs/models/lyria-3-pro-preview
Description: Learn about Lyria 3 Pro Preview from Google DeepMind

Lyria 3 Pro Preview is Google's flagship music generation model. It is
optimized for generating full-length songs with complex structural coherence,
including multiple verses, choruses, and bridges. It generates high-quality,
48kHz stereo audio from text prompts or image inputs.

{% button href="https://aistudio.google.com/prompts/new_chat?model=lyria-3-pro-preview" variant="ais" %}Try in Google AI Studio{% /button %}

## Documentation {% id="documentation" %}

Visit the [Music Generation](/docs/music-generation) guide for full
coverage of features and capabilities.

## lyria-3-pro-preview {% id="lyria-3-pro-preview" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_lyria-3.md" /%}

# What's new in Gemini 4 Argon
Source: https://aistudio.google.com/docs/latest-model
Description: Learn what's new in Gemini 4 Argon (gemini-4-argon), Google's new Gemini 4 model with a 1M shared context window, long decode, pricing, and API migration guide.

Gemini 4 Argon (`gemini-4-argon`) is our latest, most capable model. It can reason longer on hard problems for better results on complex coding, agentic, math, and science tasks. Gemini 4 Argon is available through the Gemini API and in Google AI Studio.

Gemini 4 Argon supports a unified 1M-token context window, long decode up to 1M tokens, and tunable thinking levels (`low`, `medium`, `high`).

{% card-grid %}
{% card
  href="https://aistudio.google.com/apps?model=gemini-4-argon"
  icon="experiment"
  title="Try it in AI Studio"
  description="Build apps from scratch with Gemini 4 Argon and AI Studio."
/%}
{% card
  href="https://aistudio.google.com/learn/gemini-4-argon-showcase"
  icon="smart_toy"
  title="App Gallery"
  description="Play and remix apps, built with Gemini 4 Argon."
/%}
{% card
  href="https://aistudio.google.com/learn/gemini-4-argon"
  icon="rocket_launch"
  title="Get started"
  description="Get started with Gemini 4 Argon with starter prompts."
/%}
{% /card-grid %}

This guide explains what's new in Gemini 4 Argon, API changes, code examples, and migration guidance.

## New model {% id="new-model" %}

| Model | Model ID | Default thinking level | Pricing | Description |
| :---- | :---- | :---: | :---- | :---- |
| Gemini 4 Argon | `gemini-4-argon` | `medium` | Available through Nov 30, 2026 at an introductory price of $2/1M input tokens and $10/1M output tokens ($4/1M input and $20/1M output thereafter). See [pricing](/docs/pricing) for more details. | Our most capable model, built to solve the hardest problems with depth and precision across real-world software engineering and knowledge work tasks. |

For complete details, see the [Gemini 4 Argon model page](/docs/models/gemini-4-argon). For introductory pricing details, see the [pricing section](/docs/latest-model#pricing) later on this page or the [pricing page](/docs/pricing#gemini-4-argon).

## Quickstart {% id="quickstart" %}

Use the following example to send a request to `gemini-4-argon` with the recommended default `thinking_level` (`medium`) and a 64K output token limit:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Write a three.js script that renders a realistic 3D black hole with gravitational lensing."
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-4-argon",
  input: "Write a three.js script that renders a realistic 3D black hole with gravitational lensing.",
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-4-argon",
    "input": "Write a three.js script that renders a realistic 3D black hole with gravitational lensing."
  }'
```
{% /tab %}
{% /tabs %}

## What's new in Gemini 4 Argon {% id="whats-new-gemini-4-argon" %}

* **Unified 1M input-output token limit:** Input, thinking, and output share one window of 1,048,576 tokens.
* **Long decode:** A single response can now go past 64K tokens, up to 1M tokens minus your input. See [Long decode](/docs/long-decode).
* **Agentic video understanding:** [Agentic video understanding](/docs/video-understanding#agentic-video-understanding) is now generally available.
* **Supported in Managed Agents:** The [Antigravity agent](/docs/antigravity-agent) in Gemini Managed Agents now supports Gemini 4 Argon.

For more details, see the [Gemini 4 Argon model page](/docs/models/gemini-4-argon). For pricing details, see the [pricing page](/docs/pricing#gemini-4-argon).

## Larger output and long decode {% id="long-decode" %}

Gemini 4 Argon can think longer on hard math, science, and coding problems.

* **Use `thinking_level` to control reasoning depth:** The thinking level decides how deeply the model reasons before it answers. `max_output_tokens` is a hard limit: the response stops once thinking and output together reach it, so set it high enough that it doesn't cut the answer short.
* **Generate up to 1M tokens with background execution:** Use background execution with `max_output_tokens` greater than 65,536 to let a single response go past 64K tokens, up to 1M tokens. The model generates long responses in hops of up to 64K tokens, and each hop continues from where the previous one stopped. With background execution, our servers run these continuation hops for you. Because each hop adds a `model_output` step to `interaction.steps`, join the text across all `model_output` steps when the interaction completes.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete, rigorous proof of the prime number theorem.",
    background=True,
    generation_config={
        "max_output_tokens": 262144,
        "thinking_level": "high",
    },
)

while interaction.status in ("in_progress", "queued"):
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

# Each hop adds a model_output step, so join the text of all of them.
text = "".join(
    content.text
    for step in interaction.steps
    if step.type == "model_output"
    for content in step.content
    if content.type == "text"
)
print(text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
  model: "gemini-4-argon",
  input: "Write a complete, rigorous proof of the prime number theorem.",
  background: true,
  generation_config: {
    max_output_tokens: 262144,
    thinking_level: "high",
  },
});

while (interaction.status === "in_progress" || interaction.status === "queued") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await client.interactions.get(interaction.id);
}

// Each hop adds a model_output step, so join the text of all of them.
const text = interaction.steps
  .filter((step) => step.type === "model_output")
  .flatMap((step) => step.content ?? [])
  .filter((content) => content.type === "text")
  .map((content) => content.text)
  .join("");
console.log(text);
console.log("Status:", interaction.status);
console.log("Usage:", interaction.usage);
```
{% /tab %}
{% tab label="REST" %}
```bash
ID=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-argon",
    "input": "Write a complete, rigorous proof of the prime number theorem.",
    "background": true,
    "generation_config": {
      "max_output_tokens": 262144,
      "thinking_level": "high"
    }
  }' | jq -r '.id')

while true; do
  RESP=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$ID" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status')
  if [[ "$STATUS" != "in_progress" && "$STATUS" != "queued" ]]; then
    echo "$RESP" | jq -r '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
    break
  fi
  sleep 5
done
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
If you set `background: true` without defining `max_output_tokens`, the server stops after 64K tokens.
{% /callout %}

Background execution is the recommended way to run long decode. It runs the continuation loop server-side until the model finishes or reaches `max_output_tokens`. If you need finer-grained control over retries, backoff, and error handling (or don't want your interactions stored), you can use client-side continuation in the [Interactions API](/docs/long-decode#client-side-continuation) or the [GenerateContent API](/docs/long-decode?generate-content=true). For streaming, reconnection, token counting, and when to use long decode, see the [long decode guide](/docs/long-decode).

### Setting output token limits {% id="setting-output-token-limits" %}

`max_output_tokens` sets the total thinking and output tokens for a response. Set it high enough that thinking doesn't cut the answer short, and low enough to limit spend when a hard prompt uses all of it.

Use these values as a starting point:

* **Standard tasks:** Keep the default of 65,536 or don't set any value.
* **Existing apps with a limit lower than 32K:** Raise `max_output_tokens` to at least 32,768. Gemini 4 Argon can spend more of the limit on thinking than earlier models. To use fewer tokens, lower the thinking level instead.
* **Complex reasoning and coding:** Set `background: true` and set `max_output_tokens` to 131,072 or 262,144, up to 1,048,576 minus your input tokens.

## Understanding thinking levels {% id="understanding-thinking-levels" %}

The [thinking level](/docs/thinking) is your main control over quality, latency, and token use in Gemini 4 Argon:

| Thinking level | Token use | When to use |
| :---- | :---- | :---- |
| `low` | Fewest tokens, lowest latency | Simpler tasks and cost-sensitive work. Also works for analysis and writing tasks that need light thinking. Quality can drop on hard tasks. |
| `medium` (default) | Balanced | Recommended for most tasks, including complex code and agentic use cases. |
| `high` | Most tokens, slowest first token | Complex reasoning, hard math and science, and the most difficult code or agent tasks. Pairs well with long decode for long outputs. |

Run your evaluations at all three levels, then pick the lowest level that meets your quality bar. To learn more, see the [thinking guide](/docs/thinking).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely.",
    generation_config={
        "thinking_level": "medium"  # Balanced reasoning effort for complex tasks
    }
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-4-argon",
  input: "Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely.",
  generation_config: {
    thinking_level: "medium", // Balanced reasoning effort for complex tasks
  },
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-4-argon",
    "input": "Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely.",
    "generation_config": {
      "thinking_level": "medium"
    }
  }'
```
{% /tab %}
{% /tabs %}

## Gemini 4 Argon in Managed Agents {% id="managed-agents" %}

The [Antigravity agent](/docs/antigravity-agent) in Gemini Managed Agents supports Gemini 4 Argon. To use it, set the model in `agent_config`:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input=(
        "Audit https://web.dev for performance, Core Web Vitals, and SEO. "
        "Query Google's PageSpeed Insights API for both Mobile and Desktop strategies. "
        "Check search indexing with Google Search for site:web.dev. "
        "Format the output as a side-by-side scorecard table with prioritized fixes."
    ),
    environment="remote",
    agent_config={
        "type": "antigravity",
        "model": "gemini-4-argon",
    },
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  agent: "antigravity-preview-09-2026",
  input:
    "Audit https://web.dev for performance, Core Web Vitals, and SEO. " +
    "Query Google's PageSpeed Insights API for both Mobile and Desktop strategies. " +
    "Check search indexing with Google Search for site:web.dev. " +
    "Format the output as a side-by-side scorecard table with prioritized fixes.",
  environment: "remote",
  agent_config: {
    type: "antigravity",
    model: "gemini-4-argon",
  },
}, { timeout: 300000 });

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Audit https://web.dev for performance, Core Web Vitals, and SEO. Query Google'\''s PageSpeed Insights API for both Mobile and Desktop strategies. Check search indexing with Google Search for site:web.dev. Format the output as a side-by-side scorecard table with prioritized fixes.",
    "environment": "remote",
    "agent_config": {
      "type": "antigravity",
      "model": "gemini-4-argon"
    }
  }'
```
{% /tab %}
{% /tabs %}

For more options, see [model selection](/docs/antigravity-agent#model-selection) in the Antigravity agent guide.

## Migration checklist {% id="migration-checklist" %}

{% callout type="note" %}
**Automate this migration with a coding agent.** If you use a coding agent that supports skills (like Antigravity), install the [gemini-api-dev skill](/docs/coding-agents#gemini-api-dev) and run:

```none
/gemini-api-dev migrate my app to Gemini 4 Argon
```
{% /callout %}

### Migrate to gemini-4-argon {% id="migrate-to-gemini-4-argon" %}

* **Update model ID:** Change your target model string to `gemini-4-argon`.
* **Review `max_output_tokens`:** If you set it explicitly today, consider raising it. We recommend at least 32,768, since Gemini 4 Argon can spend more of the limit on thinking.
* **Configure thinking level:** Choose `low`, `medium` (default), or `high`, and test your workload at all three.
* **Move off explicit context caching:** Explicit caching (`cachedContents` / `caches.create`) is not supported on Gemini 4 Argon. Remove calls that create or reference `cached_content` from your requests. [Implicit caching](/docs/caching) is enabled by default for prompts of at least 4,096 tokens and discounts cached input tokens by 95% on cache hits.
* **Remove sampling parameters:** Remove `temperature`, `top_p`, and `top_k` from your requests. If provided, they are ignored.
* **Use background execution for long outputs:** For tasks that need more than 64K tokens, set `background` to true and `max_output_tokens` greater than 65,536.
* **Increase client timeouts:** Hard prompts can take several minutes. Use background execution, or set HTTP client timeouts to at least 15 minutes.
* **Keep conversation state on the server:** Use `previous_interaction_id` for multi-turn and function calling conversations.
* **Review your cost estimates:** Every token the model processes is billed, including internal tool system instructions and function declarations when using grounding (see [Pricing](/docs/latest-model#pricing)).

## Pricing {% id="pricing" %}

Gemini 4 Argon is available at introductory pricing through November 30, 2026:

* **Input tokens:** $2.00 per 1M tokens ($4.00 starting December 1, 2026)
    * **Cached input tokens:** Implicit caching discounts cached input by 95%, to $0.10 per 1M tokens ($0.20 starting December 1, 2026).
* **Output tokens, including thinking tokens:** $10.00 per 1M tokens ($20.00 starting December 1, 2026)

Every token the model processes is counted and billed, including thinking tokens and internal tool system instructions and function declarations when using grounding. Grounding with Google Search also remains billed per query.

Gemini 4 Argon is not available on the Free tier. For complete pricing tiers, see the [pricing page](/docs/pricing#gemini-4-argon).

## Other models {% id="other-models" %}

* [Gemini 3.8 Flash](/docs/whats-new-gemini-3.8)
* [Gemini 3.6 Flash and 3.5 Flash-Lite](/docs/whats-new-gemini-3.6)
* [See all models](/docs/models)

## What's next {% id="whats-next" %}

* Read the [long decode guide](/docs/long-decode) for streaming, reconnection, and token counting.
* Learn how thinking levels and thought summaries work in the [thinking guide](/docs/thinking).
* Learn about long-running jobs in the [background execution guide](/docs/background-execution).
* Test and refine prompts in [Google AI Studio](https://aistudio.google.com/prompts/new_chat?model=gemini-4-argon).

# What's new in Gemini 3.8 Flash
Source: https://aistudio.google.com/docs/whats-new-gemini-3.8
Description: Learn about what's new in Gemini 3.8 Flash, including model capabilities, API changes, and migration guidance.

{% button href="/docs/latest-model" variant="ais" %}Latest model{% /button %} {% button href="/docs/whats-new-gemini-3.8#other-models" variant="ais" %}Other models{% /button %}

Gemini 3.8 Flash (`gemini-3.8-flash`) is our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows.

This guide explains what's new in Gemini 3.8 Flash, API changes, code examples, and migration guidance.

## New model {% id="new-model" %}

| Model | Model ID | Default thinking level | Pricing | Description |
| :---- | :---- | :---: | ----- | :---- |
| Gemini 3.8 Flash | `gemini-3.8-flash` | `medium` | 3.8 Flash is available through the end of year at an introductory price of $0.75/1M input tokens and $3.75/1M output tokens; see [pricing](/docs/pricing) for more details. | Our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows. |

Gemini 3.8 Flash supports a 1M token context window, 64k max output tokens, tunable thinking levels (`low`, `medium`, `high`), and the same suite of built-in tools.

For complete specs, see the [Gemini 3.8 Flash model page](/docs/models/gemini-3.8-flash). For introductory pricing details, see the [pricing section](/docs/whats-new-gemini-3.8#pricing) later on this page or the [pricing page](/docs/pricing#gemini-3.8-flash).

## Quickstart {% id="quickstart" %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Write a three.js script that renders a realistic 3D black hole."
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Write a three.js script that renders a realistic 3D black hole.",
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Write a three.js script that renders a realistic 3D black hole."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Write a three.js script that renders a realistic 3D black hole."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Write a three.js script that renders a realistic 3D black hole."
  }'
```
{% /tab %}
{% /tabs %}

## What's new in Gemini 3.8 Flash {% id="whats-new-gemini-3-8-flash" %}

* **Long-horizon software engineering:** Delivers strong results on real-world coding benchmarks, complex multi-file refactoring, and deterministic tool execution. See the [evaluation methodology](https://deepmind.google/models/evals-methodology/gemini-3-8-flash/) for details.
* **Autonomous agents:** Lets you build resilient multi-step planning and tool orchestration workflows, substantially reducing failed loops and errors.
* **Complex enterprise workflows:** Delivers superior accuracy, deep reasoning, and high factual rigor across demanding domain tasks and large-scale data pipelines.
* **Default model for Managed Agents:** The default agent for managed agents: the [Antigravity agent](/docs/antigravity-agent), now uses Gemini 3.8 Flash. The [Antigravity SDK](https://antigravity.google/docs/sdk/overview/) also uses Gemini 3.8 Flash by default.
* **Introductory pricing:** Gemini 3.8 Flash is available at an introductory rate of $0.75/1M input tokens and $3.75/1M output tokens through December 31, 2026. Standard pricing of $1.50/1M input tokens and $7.50/1M output tokens takes effect January 1, 2027.

Gemini 3.8 Flash can use more tokens on longer running and complex tasks, by design. To deliver higher-quality results on difficult, multi-step goals, the model takes smaller reasoning steps, calls tools iteratively, and verifies its work along the way. Not every workflow needs this level of verification. For everyday tasks, you can lower the [reasoning](/docs/whats-new-gemini-3.8#understanding-reasoning-levels) effort to reduce token consumption. Alternatively, Gemini 3.6 Flash remains supported.

## Understanding reasoning levels {% id="understanding-reasoning-levels" %}

Gemini 3.8 Flash gives you flexible control over latency and intelligence by adjusting the model's thinking level:

* **Low thinking effort**: Reduces time-to-answer for latency-critical tasks like incident response pipelines, real-time chat, writing drafts, and fast data analysis.
* **Medium (default):** Best quality for most tasks. Recommended for complex code and agentic use cases, providing higher first-pass accuracy.
* **High thinking effort**: Maximizes the model's reasoning and tool orchestration capabilities. Best for deep reasoning, mathematics, and difficult multi-step tasks.

Note: `minimal` thinking level is not supported for Gemini 3.8 Flash and will return an error.

The following example sets `thinking_level` to `medium` for a complex code analysis request:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely.",
    generation_config={
        "thinking_level": "medium"  # Balanced reasoning effort for complex tasks
    }
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely.",
  generation_config: {
    thinking_level: "medium"
  }
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ThinkingLevel;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely."))
        .generationConfig(
            GenerationConfig.builder()
                .thinkingLevel(ThinkingLevel.MEDIUM) // Balanced reasoning effort for complex tasks
                .build())
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely."),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel: interactions.ThinkingLevelMedium.ToPointer(), // Balanced reasoning effort for complex tasks
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely.",
    "generation_config": {
      "thinking_level": "medium"
    }
  }'
```
{% /tab %}
{% /tabs %}

## Updated Antigravity agent {% id="updated-antigravity-agent" %}

Due to its improved performance and reasoning, the [Antigravity agent](/docs/antigravity-agent) in Gemini Managed Agents is now built with Gemini 3.8 Flash by default.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input=(
        "Audit https://web.dev for performance, Core Web Vitals, and SEO. "
        "Query Google's PageSpeed Insights API for both Mobile and Desktop strategies. "
        "Check search indexing with Google Search for site:web.dev. "
        "Format the output as a side-by-side scorecard table with prioritized fixes."
    ),
    environment="remote",
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  agent: "antigravity-preview-09-2026",
  input: "Audit https://web.dev for performance, Core Web Vitals, and SEO. Query Google's PageSpeed Insights API for both Mobile and Desktop strategies. Check search indexing with Google Search for site:web.dev. Format the output as a side-by-side scorecard table with prioritized fixes.",
  environment: "remote",
}, { timeout: 300000 });

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent(AgentOption.of("antigravity-preview-09-2026"))
        .input(
            InteractionsInput.of(
                "Audit https://web.dev for performance, Core Web Vitals, and SEO. "
                    + "Query Google's PageSpeed Insights API for both Mobile and Desktop strategies. "
                    + "Check search indexing with Google Search for site:web.dev. "
                    + "Format the output as a side-by-side scorecard table with prioritized fixes."))
        .environment(CreateAgentInteractionEnvironment.of("remote"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("antigravity-preview-09-2026"),
            Input: interactions.NewInteractionsInput(
                "Audit https://web.dev for performance, Core Web Vitals, and SEO. " +
                    "Query Google's PageSpeed Insights API for both Mobile and Desktop strategies. " +
                    "Check search indexing with Google Search for site:web.dev. " +
                    "Format the output as a side-by-side scorecard table with prioritized fixes.",
            ),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Audit https://web.dev for performance, Core Web Vitals, and SEO. Query Google'\''s PageSpeed Insights API for both Mobile and Desktop strategies. Check search indexing with Google Search for site:web.dev. Format the output as a side-by-side scorecard table with prioritized fixes.",
    "environment": "remote"
}'
```
{% /tab %}
{% /tabs %}

The underlying Gemini model [can be configured](/docs/antigravity-agent#model-selection) using `agent_config`.

## Migration checklist {% id="migration-checklist" %}

{% callout type="note" %}
**Automate this migration with a coding agent.** If you use a coding agent that supports skills (like Antigravity),
install the [gemini-api-dev skill](/docs/coding-agents#gemini-api-dev) and run:

`/gemini-api-dev migrate my app to Gemini 3.8 Flash`
{% /callout %}

### Migrate to gemini-3.8-flash {% id="migrate-to-gemini-3-8-flash" %}

* **Update Model ID:** Change your target model string to `gemini-3.8-flash`.
* **Configure thinking level:** Replace `thinking_budget` with the string enum `thinking_level`. Note that `minimal` is not supported on Gemini 3.8 Flash; choose `low`, `medium` (default), or `high`.
* **Apply Gemini 3 API parameter changes:** Remove deprecated sampling parameters (`temperature`, `top_p`, `top_k`), `candidate_count` (unsupported in Gemini 3 and later), and prefilled model turns. See [Gemini 3.6 API changes and parameter updates](/docs/whats-new-gemini-3.6#api-changes-and-parameter-updates).
* **Enforce turn validation rules:** Standardize multi-turn conversations on server-side `previous_interaction_id` and remove prefilled model turns.
* **Audit function calling:**
  * Place multimodal assets inside the response payload.
  * Format inline instructions using `\n\n`.
  * If you see `Malformed_Function_Call` errors tied to pre-tool text, see [Workarounds for pre-tool text requirements](/docs/function-calling#workarounds-for-pre-tool-text-requirements).
  * Only if using generateContent API: Ensure all `FunctionResponse` objects include `call_id` and `name`.
* **Baseline Gemini 3 requirements:** For SDK updates and thought signature preservation, see [Thought signatures](/docs/thinking#signatures).

## Pricing {% id="pricing" %}

Take advantage of introductory pricing across Google AI Studio and Gemini Enterprise Agent Platform through December 31, 2026 for Gemini 3.8 Flash and Gemini 3.6 Flash. Standard pricing takes effect January 1, 2027. For complete pricing tiers, see the [pricing page](/docs/pricing#gemini-3.8-flash).

## Other models {% id="other-models" %}

* [Gemini 4 Argon (Latest)](/docs/latest-model)
* [Gemini 3.6 Flash and 3.5 Flash-Lite](/docs/whats-new-gemini-3.6)
* [See all models](/docs/models)

## What's next {% id="whats-next" %}

* Review API specs on the [Models Overview](/docs/models).
* Explore multi-agent orchestration in the [Interactions API Overview](/docs/interactions-overview).
* Test and refine prompts in [Google AI Studio](https://aistudio.google.com/prompts/new_chat?model=gemini-3.8-flash).

# What's new in Gemini 3.7 Flash
Source: https://aistudio.google.com/docs/whats-new-gemini-3.7
Description: Learn about what's new in Gemini 3.7 Flash, including model capabilities, API changes, and migration guidance.

{% button href="/docs/latest-model" variant="ais" %}Latest model{% /button %}
{% button href="/docs/whats-new-gemini-3.7#other-models" variant="ais" %}Other models{% /button %}
{% callout type="caution" %} **Deprecated:** Gemini 3.7 Flash
(`gemini-3.7-flash`) is deprecated and has been replaced by
[Gemini 3.8 Flash (`gemini-3.8-flash`)](/docs/whats-new-gemini-3.8). It is no longer
available to select in Google AI Studio, and API requests to
`gemini-3.7-flash` are automatically routed to `gemini-3.8-flash`.
Update your model string to `gemini-3.8-flash` and review the
[Gemini 3.8 Flash guide](/docs/whats-new-gemini-3.8). {% /callout %}

Gemini 3.7 Flash (`gemini-3.7-flash`) is a previous-generation Flash model in
the Gemini 3 series, now deprecated and automatically routed to
[Gemini 3.8 Flash](/docs/whats-new-gemini-3.8).

This guide is preserved for reference and documents the capabilities and changes
introduced in Gemini 3.7 Flash.

## Model overview {% id="new-model" %}

| Model | Model ID | Default thinking level | Description |
| :---- | :---- | :---: | :---- |
| Gemini 3.7 Flash (Deprecated) | `gemini-3.7-flash` | `medium` | Previous-generation Flash model built for coding, agentic workflows, and multi-step execution. Replaced by [Gemini 3.8 Flash](/docs/whats-new-gemini-3.8). |
Gemini 3.7 Flash supports a 1M token context window, 64k max output tokens, tunable thinking levels (`low`, `medium`, `high`), and the same suite of built-in tools as 3.6 Flash.

For complete specs, see the
[Gemini 3.7 Flash model page](/docs/models/gemini-3.7-flash).

## Quickstart {% id="quickstart" %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="Write a responsive navigation component in React with smooth animations and dark mode toggle."
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-3.7-flash",
  input: "Write a responsive navigation component in React with smooth animations and dark mode toggle.",
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
    import com.google.genai.gaos.models.interactions.CreateModelInteraction;
    import com.google.genai.gaos.models.interactions.Interaction;
    import com.google.genai.gaos.models.interactions.InteractionsInput;
    import com.google.genai.gaos.models.interactions.Model;
    import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

    Client client = new Client();
    CreateModelInteraction req = CreateModelInteraction.builder()
        .model(Model.of("gemini-3.7-flash"))
        .input(InteractionsInput.of("Write a responsive navigation component in React with smooth animations and dark mode toggle."))
        .build();
    Interaction interaction =
        client.interactions.create(CreateInteractionRequestBody.of(req)).interaction().get();
    System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}

{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-3.7-flash",
    "input": "Write a responsive navigation component in React with smooth animations and dark mode toggle."
  }'
```
{% /tab %}
{% /tabs %}

## What's new in Gemini 3.7 Flash {% id="whats-new-gemini-3-7-flash" %}

* **Coding and agentic tasks:** Significantly higher quality on real-world software engineering and agentic benchmarks, improving issue resolution and reducing failed agent loops.
* **Web development and stronger design parity:** Generates higher-fidelity desktop and web application code directly from design mocks, with strong gains in design adherence and in auditing existing codebases against mocks to verify 1:1 design parity.

## Understanding reasoning levels {% id="understanding-reasoning-levels" %}

Gemini 3.7 Flash gives developers flexible control over latency and intelligence by adjusting the model's thinking level:

* **Low thinking effort**: Reduces time-to-answer for latency-critical tasks like incident response pipelines, real-time chat, writing drafts, and fast data analysis.
* **Medium (default):** Best quality for most tasks. Recommended for complex code and agentic use cases, with higher first-pass accuracy.
* **High thinking effort**: Maximizes the model's ability to think and use tools. Best for complex reasoning, hard math, and difficult coding and agent tasks. Allows extended thoughts and function calls, with higher token consumption and cost.

To configure thinking levels in Gemini 3.7 Flash:

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely.",
    generation_config={
        "thinking_level": "medium"  # Balanced reasoning effort for complex tasks
    }
)

print(interaction.output_text)
```

For multi-language code examples (JavaScript, Java, Go, REST) and in-depth reasoning concepts, see [Understanding reasoning levels in Gemini 3.8 Flash](/docs/whats-new-gemini-3.8#understanding-reasoning-levels).

## Antigravity agent support {% id="updated-antigravity-agent" %}

Gemini 3.7 Flash introduced support for powering the [Antigravity agent](/docs/antigravity-agent) in Gemini Managed Agents and the [Google Antigravity SDK](https://antigravity.google/docs/sdk/overview/).

For current code samples and the latest default agent configuration, see the [Antigravity agent guide](/docs/antigravity-agent) and the [Gemini 3.8 Flash guide](/docs/whats-new-gemini-3.8#updated-antigravity-agent).

## Other models {% id="other-models" %}

*   [Gemini 4 Argon (Latest)](/docs/latest-model)
*   [Gemini 3.8 Flash](/docs/whats-new-gemini-3.8)
*   [Gemini 3.6 Flash and 3.5 Flash-Lite](/docs/whats-new-gemini-3.6)
*   [See all models](/docs/models)

## What's next {% id="whats-next" %}

* Review API specs on the [Models Overview](/docs/models).
* Explore multi-agent orchestration in the [Interactions API Guide](/docs/interactions-overview).
* Test and refine prompts in [Google AI Studio](https://aistudio.google.com/).

# What's new in Gemini 3.6 Flash and 3.5 Flash-Lite
Source: https://aistudio.google.com/docs/whats-new-gemini-3.6
Description: Learn about what's new in Gemini 3.6 Flash and Gemini 3.5 Flash-Lite, including model capabilities, API changes, and migration guidance.

{% button href="/docs/latest-model" variant="ais" %}Latest model{% /button %}
{% button href="/docs/whats-new-gemini-3.6#other-models" variant="ais" %}Other models{% /button %}
Gemini 3.6 Flash (`gemini-3.6-flash`) and Gemini 3.5 Flash-Lite
(`gemini-3.5-flash-lite`) are previous-generation releases in the Gemini 3
series and remain available for production use. For our newest Flash model, see
[Gemini 3.8 Flash](/docs/whats-new-gemini-3.8).

* **Gemini 3.6 Flash**: Stronger performance on complex agentic and multimodal tasks while reducing token usage, at a lower price point than 3.5 Flash.
* **Gemini 3.5 Flash-Lite**: The fastest, lowest-cost model in the 3.5 family. Outperforms prior Flash-Lite generations for high-throughput execution.

This guide explains what was introduced in each model, what API changes affect
your code, and how to migrate.

{% callout type="note" %}
You can automate this migration with a coding agent that supports [skills](/docs/coding-agents#gemini-api-dev) (like Antigravity).
{% /callout %}

{% tabs %}
{% tab title="Gemini 3.6 Flash" %}
1. Install the skill:

   ```bash
   npx skills add google-gemini/gemini-skills --skill gemini-interactions-api --global
   ```

2. Apply the skill:

   ```bash
   /gemini-interactions-api migrate my app to Gemini 3.6 Flash
   ```
{% /tab %}
{% tab title="Gemini 3.5 Flash-Lite" %}
1. Install the skill:

   ```bash
   npx skills add google-gemini/gemini-skills --skill gemini-interactions-api --global
   ```

2. Apply the skill:

   ```bash
   /gemini-interactions-api migrate my app to Gemini 3.5 Flash-Lite
   ```
{% /tab %}
{% /tabs %}

## New models {% id="new-models" %}

| Model | Model ID | Default thinking level | Pricing | Description |
| :---- | :---- | :---: | ----- | :---- |
| Gemini 3.6 Flash | `gemini-3.6-flash` | `medium` | $1.50/1M input tokens and $7.50/1M output tokens | Balances speed with intelligence for agentic and multimodal tasks. |
| Gemini 3.5 Flash-Lite | `gemini-3.5-flash-lite` | `minimal` |  $0.30/1M input tokens and $2.50/1M output tokens | The fastest, lowest-cost 3.5 model for high-throughput execution. |

Both models support the 1M token context window, 64k max output tokens, thinking, and the full suite of built-in tools including [Computer Use](/docs/computer-use).

For complete specs, see the model pages:

* [Gemini 3.6 Flash model page](/docs/models/gemini-3.6-flash)
* [Gemini 3.5 Flash-Lite model page](/docs/models/gemini-3.5-flash-lite)

For detailed pricing, see the [pricing page](/docs/pricing).

## Quickstart {% id="quickstart" %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.6-flash",
    input="Write a three.js script that renders an interactive 3D robot."
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.6-flash",
    input: "Write a three.js script that renders an interactive 3D robot.",
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions"   -H "x-goog-api-key: $GEMINI_API_KEY"   -H 'Content-Type: application/json'   -X POST   -d '{
    "model": "gemini-3.6-flash",
    "input": {
      "parts": [{"text": "Write a three.js script that renders an interactive 3D robot."}]
    }
  }'
```
{% /tab %}
{% /tabs %}

## What's new in Gemini 3.6 Flash {% id="whats-new-gemini-3-6-flash" %}

* **Token and turn reduction:** Completes multi-step workflows with fewer reasoning steps, conversational turns, and tool calls than Gemini 3.5. It also reduces execution loop spiraling.
* **Improved code generation:** Produces higher quality production-ready code with fewer unwanted edits and fewer debugging loops.
* **Better instruction following**: Reduces unwanted file changes during diagnostic tasks.
* **Strong multimodal and spatial reasoning:** Improved performance on chart interpretation, visual blueprint conversion, and multi-element web layout generation.
* **Upfront programmatic inspection:** Prefers running diagnostic code scripts before making changes more frequently than Gemini 3.5 Flash. This improves accuracy on complex tasks, but can add extra exploratory steps on routine frontend work.
* **Computer Use support:** Supported as a built-in tool for agentic UI automation.
* **UI styling preference**: Better at creating functional code, though human evaluators preferred earlier models for visual layout and styling. You can mitigate this by providing explicit design guidelines.
* **Default thinking effort (medium):** Uses the same `medium` default thinking level as Gemini 3.5 Flash.
* **Reduced pricing**: Lower output token costs ($7.50/1M versus $9.00/1M for 3.5 Flash). Input tokens remain at $1.50/1M.

## What's new in Gemini 3.5 Flash-Lite {% id="whats-new-gemini-3-5-flash-lite" %}

* **Reduced task execution latency:** Highest throughput in the 3.5 family for high-volume data parsing and document extraction.
* **Enhanced reasoning and multimodal performance:** Strong migration path from Gemini 2.5 Flash, with higher scores on reasoning tasks like HLE (18.0% versus 11.0%) and multimodal benchmarks like CharXIV (74.5% versus 63.7%).
* **Subagent orchestration and tool reliability:** Improves tool execution reliability for code execution, search, and MCP workflows. Increase the thinking level for autonomous planning and complex subagent tasks.
* **Improved document understanding:** Improves accuracy on document parsing and structured data extraction. Experiment with both minimal and high thinking levels depending on document complexity.
* **Interactive web coding and tabular data processing:** Performs strongly on frontend JavaScript and tabular data processing by planning using lightweight code execution.
* **Chatbot and persona persistence:** Stronger multi-turn instruction following and persona consistency over Gemini 3.1 Flash-Lite.
* **Computer Use support:** Supported as a built-in tool for agentic UI automation.

## Choosing the right Flash or Flash-Lite model {% id="choosing-the-right-flash-model" %}

Use this table to select the right model and migration path for your workloads.

Both models require removing deprecated sampling parameters (`temperature`, `top_p`, `top_k`) and prefilled model turns. See [API changes](/docs/whats-new-gemini-3.6#api-changes-and-parameter-updates) for details.

| Model | Primary use cases | Recommended migration target |
| :---- | :---- | :---- |
| **Gemini 3.6 Flash** (`gemini-3.6-flash`) | Code generation, spatial/multimodal reasoning, multi-step agentic workflows | **Gemini 3.5 Flash**, **Gemini 3 Flash (Preview)**, or **Gemini 3.1 Pro** |
| **Gemini 3.5 Flash-Lite** (`gemini-3.5-flash-lite`) | Autonomous subagent execution, high-volume data analysis and document extraction, structured JSON parsing | **Gemini 3.1 Flash-Lite** or **Gemini 2.5 Flash** |

## Antigravity agent support {% id="updated-antigravity-agent" %}

Gemini 3.6 Flash introduced support for the [Antigravity agent](/docs/antigravity-agent) in Gemini Managed Agents.

For current code samples and the latest default agent configuration, see the [Antigravity agent guide](/docs/antigravity-agent) and the [Gemini 3.8 Flash guide](/docs/whats-new-gemini-3.8#updated-antigravity-agent).

## API changes and parameter updates {% id="api-changes-and-parameter-updates" %}

Starting with Gemini 3.6 Flash and Gemini 3.5 Flash-Lite, the following API changes apply to these models and all future Gemini model releases.

* **Sampling parameter deprecation**: `temperature`, `top_p`, and `top_k` are deprecated. The API ignores these parameters and returns an error in future model generations.
* **Prefilled model turn validation**: Prefilling model turns is no longer supported. If the last non-empty turn in the request is a `model` turn, the API returns a `400` error.

The following sections provide detailed explanations and code samples for each API change.

### 1. Sampling parameter deprecation (temperature, top_p, top_k) {% id="sampling-parameter-deprecation" %}

`temperature`, `top_p`, and `top_k` are deprecated and ignored. In future model generations, supplying these parameters returns an HTTP 400 error. **Remove these parameters from all requests.**

```python
# ⚠️ Remove these parameters (deprecated)
generation_config = {
     "temperature": 0.7,
     "top_p": 0.9,
     "top_k": 40,
}
```

To improve determinism, define a system instruction with explicit rules for your
specific use case.

### 2. Prefilled model turn validation {% id="prefilled-model-turn-validation" %}

API requests ending with a non-empty model role turn are disallowed and return an **HTTP 400 Error**.

#### ⚠️ Avoid {% id="prefill-avoid" %}

In legacy `generateContent` or raw REST payloads, ending with a model role turn
is now disallowed:

```json
/* ❌ DO NOT: End payload contents with a 'model' role turn */
{
  "contents": [
    {"role": "user", "parts": [{"text": "Translate 'Hello world' to Spanish."}]},
    {"role": "model", "parts": [{"text": "Translation:"}]}  /* ❌ Returns error */
  ]
}
```

#### ✅ Recommended Migration (Interactions API) {% id="prefill-recommended-migration" %}

In the Interactions API, model turns are not manually prefilled. If your application previously prefilled a model turn to suppress preambles or force JSON formatting, use system_instruction or [Structured outputs](/docs/structured-output) instead.

```python
# ✅ RECOMMENDED: Use system_instruction in the Interactions API to specify output format
interaction = client.interactions.create(
    model="gemini-3.6-flash",
    input="Translate 'Hello world' to Spanish.",
    system_instruction="Output only the translation without introductory text.",
)
```

## Migration checklist {% id="migration-checklist" %}

{% callout type="note" %}
You can automate this migration with a coding agent that supports [skills](/docs/coding-agents#gemini-api-dev) (like Antigravity).
{% /callout %}

{% tabs %}
{% tab title="Gemini 3.6 Flash" %}
1. Install the skill:

   ```bash
   npx skills add google-gemini/gemini-skills --skill gemini-interactions-api --global
   ```

2. Apply the skill:

   ```bash
   /gemini-interactions-api migrate my app to Gemini 3.6 Flash
   ```
{% /tab %}
{% tab title="Gemini 3.5 Flash-Lite" %}
1. Install the skill:

   ```bash
   npx skills add google-gemini/gemini-skills --skill gemini-interactions-api --global
   ```

2. Apply the skill:

   ```bash
   /gemini-interactions-api migrate my app to Gemini 3.5 Flash-Lite
   ```
{% /tab %}
{% /tabs %}

### Migrate to gemini-3.6-flash {% id="migrate-to-gemini-3-6-flash" %}

* **Update Model ID:** Change your target model string to `gemini-3.6-flash`.
* **Apply parameter updates:** Remove deprecated sampling parameters (`temperature`, `top_p`, `top_k`), `candidate_count` (unsupported in Gemini 3 and later), and prefilled model turns as detailed in [API changes and parameter updates](/docs/whats-new-gemini-3.6#api-changes-and-parameter-updates).
* **Configure thinking level:** Replace `thinking_budget` with `thinking_level` (`"medium"` or `"high"`).
* **Audit function calling:**
  * Place multimodal assets inside the response payload.
  * Format inline instructions using `\n\n`.
  * If you see `Malformed_Function_Call` errors tied to pre-tool text, see [Workarounds for pre-tool text requirements](/docs/function-calling#workarounds-for-pre-tool-text-requirements).
*   **Baseline Gemini 3.x requirements:** For SDK updates and thought signature
    preservation, see [Thought signatures](/docs/thinking#signatures).

### Migrate to gemini-3.5-flash-lite {% id="migrate-to-gemini-3-5-flash-lite" %}

* **Update Model ID:** Change your target model string to `gemini-3.5-flash-lite`.
* **Configure thinking effort level:**
  * For high-volume extraction, routing, or classification: leave `thinking_level` at `"minimal"` (default) for maximum throughput.
  * For autonomous subagents with tool calls, code execution, or multi-step reasoning: set `thinking_level` to `"medium"` or `"high"` to prevent premature tool termination.
* **Remove deprecated parameters and validate function calling:** Apply the [same rules as 3.6 Flash](/docs/whats-new-gemini-3.6#migrate-to-gemini-3-6-flash).
*   **Baseline Gemini 3.x requirements:** Refer to
    [Thought signatures](/docs/thinking#signatures).

## Other models {% id="other-models" %}

*   [Gemini 4 Argon (Latest)](/docs/latest-model)
*   [Gemini 3.8 Flash](/docs/whats-new-gemini-3.8)
*   [See all models](/docs/models)

## What's next {% id="whats-next" %}

* Review API specs on the [Models Overview](/docs/models).
* Explore multi-agent orchestration in the [Interactions API Guide](/docs/interactions-overview).
* Test and refine prompts in [Google AI Studio](https://aistudio.google.com/).

# What's new in Gemini 3.5 Flash
Source: https://aistudio.google.com/docs/whats-new-gemini-3.5
Description: Learn about the new features and migration guidance for Gemini 3.5 Flash.

{% button href="/docs/latest-model" variant="ais" %}Latest model{% /button %}
{% button href="/docs/whats-new-gemini-3.5#other-models" variant="ais" %}Other models{% /button %}
{% callout type="caution" %} **Deprecated:** Gemini 3.5 Flash
(`gemini-3.5-flash`) is deprecated and has been replaced by
[Gemini 3.6 Flash (`gemini-3.6-flash`)](/docs/whats-new-gemini-3.6). It is no
longer available to select in Google AI Studio, and API requests to
`gemini-3.5-flash` are automatically routed to `gemini-3.6-flash`. Update your
model string to `gemini-3.6-flash` (or
[Gemini 3.8 Flash](/docs/latest-model)) and review the
[Gemini 3.6 Flash guide](/docs/whats-new-gemini-3.6). {% /callout %}

Gemini 3.5 Flash (`gemini-3.5-flash`) is an earlier-generation Flash model in
the Gemini 3 series, now deprecated and automatically routed to
[Gemini 3.6 Flash](/docs/whats-new-gemini-3.6).

This guide is preserved for reference and documents the capabilities and
baseline Gemini 3.x parameter updates introduced in Gemini 3.5 Flash.

## Model overview {% id="new-model" %}

| Model | Model ID | Description |
| :---- | :---- | :---- |
| Gemini 3.5 Flash (Deprecated) | `gemini-3.5-flash` | Earlier-generation Flash model for agentic and coding tasks. Replaced by [Gemini 3.6 Flash](/docs/whats-new-gemini-3.6). |
Gemini 3.5 Flash supports the 1M token context window, 65k max output tokens, thinking, and the same set of tools and platform features as Gemini 3 Flash, including [Computer Use](/docs/computer-use).

For complete specs, see the [models overview](/docs/models/gemini-3.5-flash).

## Quickstart {% id="quickstart" %}

All examples in this guide use the Interactions API. The GenerateContent API is
also supported; the same configuration options and recommendations apply.

{% tabs %}
{% tab label="Python" filename="quickstart.py" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.6-flash",
    input="Explain how parallel agentic execution works in three sentences."
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="quickstart.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.6-flash",
    input: "Explain how parallel agentic execution works in three sentences.",
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.6-flash",
    "input": "Explain how parallel agentic execution works in three sentences."
  }'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.5-flash"))
        .input(
            InteractionsInput.of(
                "Explain how parallel agentic execution works in three sentences."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-flash"),
            Input: interactions.NewInteractionsInput("Explain how parallel agentic execution works in three sentences."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

## What's new {% id="whats-new" %}

*   **Sustained frontier performance:** Our most intelligent Flash model, optimized for agentic and coding tasks at scale.
*   **Agentic execution:** Sub-agent deployment, problem solving, and rapid agentic loops at scale.
*   **Coding:** Iterative coding cycles, rapid exploration, and prototyping to test alternate paths and dynamically explore solutions.
*   **Long horizon:** Multi-step workflows and tool use at scale.
*   **Thought preservation:** The model maintains intermediate reasoning across multi-turn conversations automatically. No API changes needed.
*   **New default effort level:** Default thinking effort changed from `high` to `medium`. See [New default effort level](/docs/whats-new-gemini-3.5#default-effort-level) for details.
*   **Improved `low` thinking:** `low` is now significantly improved for code and agentic tasks that require fewer steps, offering strong quality at lower latency and cost.
*   **GA release:** Stable model for scaled production use.

### Choosing the right Flash model {% id="choose-model" %}

Gemini 3.5 Flash is deprecated and automatically routed to
[Gemini 3.6 Flash](/docs/whats-new-gemini-3.6). Depending on your cost, latency,
and capability requirements, we recommend the following models:

*   **Gemini 3.8 Flash**: Our latest and most intelligent Flash model for
    complex coding and agentic workflows. See the
    [Gemini 3.8 Flash guide](/docs/latest-model).
*   **Gemini 3.6 Flash**: Direct replacement for Gemini 3.5 Flash with reduced
    token usage and lower output pricing. See the
    [Gemini 3.6 Flash and 3.5 Flash-Lite guide](/docs/whats-new-gemini-3.6).
*   **Gemini 3.5 Flash-Lite / Gemini 3.1 Flash-Lite**: For low-cost, high-volume
    tasks that don't require full Flash reasoning depth, use
    [Gemini 3.5 Flash-Lite](/docs/models/gemini-3.5-flash-lite) or
    [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite).

## Behavioral changes {% id="behavioral-changes" %}

### New default effort level: `medium` {% id="default-effort-level" %}

The default thinking effort is now **`medium`**, changed from `high` in Gemini 3
Flash Preview. `medium` yields very good results across a wide range of tasks
while being faster and more cost-efficient. For complex problems, `high`
encourages the model to think more deeply.

| Effort level | When to use |
| :---- | :---- |
| `minimal` | Optimized for response speed. Chat-like use cases, quick factual answers, simpler tool calls. |
| `low` | Code and agentic tasks that require lower latency and fewer steps. Also works well for analysis and writing tasks that require some thinking. |
| **`medium` (default)** | **Best quality for most tasks. Recommended for complex code and agentic use cases.** |
| `high` | Maximizes the model's ability to think and use tools. Best for complex reasoning, hard math, and the most difficult code or agent tasks. Allows extended thoughts and function calls. |

To override the default, set `thinking_level` in your config:

{% tabs %}
{% tab label="Python" filename="thinking_level.py" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.6-flash",
    input="Prove that the square root of 2 is irrational.",
    generation_config={"thinking_level": "high"},
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="thinking_level.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.6-flash",
    input: "Prove that the square root of 2 is irrational.",
    generation_config: { thinking_level: "high" },
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.6-flash",
    "input": "Prove that the square root of 2 is irrational.",
    "generation_config": {"thinking_level": "high"}
  }'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ThinkingLevel;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.5-flash"))
        .input(InteractionsInput.of("Prove that the square root of 2 is irrational."))
        .generationConfig(GenerationConfig.builder().thinkingLevel(ThinkingLevel.HIGH).build())
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-flash"),
            Input: interactions.NewInteractionsInput("Prove that the square root of 2 is irrational."),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel: interactions.ThinkingLevelHigh.ToPointer(),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
Start with `medium`, it provides the best quality for the vast majority of
tasks. Try `low` for a faster, cheaper experience with strong quality. Switch to
`high` for complex reasoning, hard math, or difficult coding challenges. Use
`minimal` to optimize for speed in simple queries.
{% /callout %}

The following table shows which thinking levels are supported per model:

{% table %}
* Thinking Level
* Gemini 3.5 Flash
* Gemini 3.1 Pro
* Gemini 3.1 Flash-Lite
* Gemini 3 Flash
* Description
---

* **`minimal`**
* Supported
* Not supported
* Supported (Default)
* Supported
* Matches the "no thinking" setting for most queries. Note, `minimal` does not guarantee that thinking is off, the model may reason very minimally for complex tasks.
---

* **`low`**
* Supported
* Supported
* Supported
* Supported
* Minimizes latency and cost.
---

* **`medium`**
* Supported (Default)
* Supported
* Supported
* Supported
* Balanced thinking for most tasks.
---

* **`high`**
* Supported (Dynamic)
* Supported (Default, Dynamic)
* Supported (Dynamic)
* Supported (Default, Dynamic)
* Maximizes reasoning depth.
{% /table %}

{% callout type="caution" %}
You cannot use both `thinking_level` and the legacy `thinking_budget` parameter
in the same request. Doing so will return a 400 error.
{% /callout %}

### Thought preservation {% id="thought-preservation" %}

The model maintains intermediate reasoning across multi-turn conversations
automatically. When present in the conversation history, reasoning context
carries forward, which improves performance on complex multi-step tasks like
iterative debugging and code refactoring. No API changes needed:

*   **Interactions API**: Thoughts are already preserved automatically. No change in behavior.
*   **GenerateContent API**: Beginning with Gemini 3.5 Flash, the model uses reasoning context from all previous turns when thought signatures are present in the conversation history. To enable this, pass the full, unmodified conversation history (including [thought signatures](/docs/thinking#signatures)) in `contents`. The SDKs handle this automatically.

## Parameter updates and best practices in Gemini 3.x {% id="parameter-updates" %}

The following apply to **all Gemini 3.x models**, including Gemini 3.5 Flash.

*   **`temperature`, `top_p`, `top_k`**: we strongly recommend not changing the default values. Gemini 3's reasoning capabilities are optimized for the default settings.
*   Use `thinking_level` instead of `thinking_budget`.
*   **Function calling response matching**: `id`, `name`, and response count must match the preceding calls.
*   **Multimodal function responses**: include multimodal content inside the function response, not outside it.
*   **Inline instructions in function responses**: append to the function response text, not as separate parts.
*   **Reduce unnecessary tool calls**: Use lower thinking levels or experiment with system instructions to reduce tool calls in agentic workflows.

See the sections below for how to update your code.

### Sampling parameters (no longer recommended) {% id="sampling-parameters" %}

`temperature`, `top_p`, and `top_k` are no longer recommended for all Gemini 3.x
models. Gemini 3's reasoning capabilities are optimized for the default
settings. **Remove these parameters from all requests.**

```python
# ⚠️ Remove these parameters (not recommended)
generation_config = {
    "temperature": 0.7,
    "top_p": 0.9,
    "top_k": 40,
}
```

To ensure determinism, we recommend defining a system instruction with explicit
rules for your specific use case.

### `thinking_budget` (no longer recommended) {% id="thinking-budget" %}

The raw numeric `thinking_budget` parameter is no longer recommended across all
Gemini 3.x models. Use the `thinking_level` string enum instead.

```python
# ⚠️ Before (not recommended)
generation_config = {
    "thinking": {"thinking_budget": 7500},
}

# ✅ After
generation_config = {
    "thinking": {"thinking_level": "medium"},
}
```

Available values: `minimal`, `low`, `medium` (default), and `high`.

### Function calling: strict response matching {% id="function-calling" %}

The Interactions API already errors on mismatched function responses. The
GenerateContent API does not yet error, but mismatched responses cause the model
to return empty responses with `finish_reason: STOP` in most cases. Always
follow these conventions:

| Requirement | Details |
| :---- | :---- |
| Include `id` | Every `FunctionResponse` must include the `id` from the corresponding `FunctionCall` |
| Match `name` | The `name` in the response must match the `name` in the call |
| Match counts | Return exactly one `FunctionResponse` for each `FunctionCall` received |

{% tabs %}
{% tab label="Python" filename="function_calling_match.py" %}
```python
# ✅ Include matching call_id and name in the function_result
final_interaction = client.interactions.create(
    model="gemini-3.6-flash",
    previous_interaction_id=interaction.id,
    tools=[my_tool],
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [{"type": "text", "text": json.dumps(result)}],
    }],
)
```
{% /tab %}
{% tab label="JavaScript" filename="function_calling_match.js" %}
```javascript
// ✅ Include matching call_id and name in the function_result
const finalInteraction = await client.interactions.create({
  model: "gemini-3.6-flash",
  previousInteractionId: interaction.id,
  tools: [myTool],
  input: [{
    type: "function_result",
    name: fcStep.name,
    call_id: fcStep.id,
    result: [{ type: "text", text: JSON.stringify(result) }],
  }],
});
```
{% /tab %}
{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.6-flash",
    "previous_interaction_id": "<INTERACTION_ID>",
    "tools": [...],
    "input": [{
      "type": "function_result",
      "name": "my_function",
      "call_id": "<CALL_ID>",
      "result": [{"type": "text", "text": "..."}]
    }]
  }'
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionResultStep;
import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

// Assumes interactionId, callId, functionName, myTool, and resultJson from previous step
String interactionId = "interaction-id-123";
String callId = "call-id-123";
String functionName = "get_weather";
Function myTool = Function.builder().name(functionName).build();
String resultJson = "{\"temperature\": \"72F\"}";

// ✅ Include matching callId and name in the FunctionResultStep
FunctionResultStep functionResult =
    FunctionResultStep.builder()
        .name(functionName)
        .callId(callId)
        .result(
            FunctionResultStepResultUnion.of(
                Arrays.asList(TextContent.builder().text(resultJson).build())))
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.5-flash"))
        .previousInteractionId(interactionId)
        .tools(Arrays.asList(myTool))
        .input(InteractionsInput.ofStep(Arrays.asList(functionResult)))
        .build();

Interaction finalInteraction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Assumes interactionID, callID, functionName, myTool, and resultJSON from previous step
    interactionID := "interaction-id-123"
    callID := "call-id-123"
    functionName := "get_weather"
    myTool := interactions.NewTool(interactions.Function{Name: genai.Ptr(functionName)})
    resultJSON := `{"temperature": "72F"}`

    // ✅ Include matching CallID and Name in the FunctionResultStep
    functionResult := interactions.NewStep(interactions.FunctionResultStep{
        Name:   genai.Ptr(functionName),
        CallID: callID,
        Result: interactions.NewFunctionResultStepResultUnion([]interactions.FunctionResultSubcontent{
            interactions.NewFunctionResultSubcontent(interactions.TextContent{Text: resultJSON}),
        }),
    })

    finalRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.5-flash"),
            PreviousInteractionID: genai.Ptr(interactionID),
            Tools:                 []interactions.Tool{myTool},
            Input:                 interactions.NewInteractionsInput([]interactions.Step{functionResult}),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = finalRes
}
```
{% /tab %}
{% /tabs %}

### Multimodal function responses {% id="multimodal-function-responses" %}

We often see clients provide images outside function response. This can lead to unexpected model behavior (e.g. thought leakage) and result in lower quality outputs. Follow the recommendation in [Multimodal Function Responses API docs](/docs/function-calling?example=meeting#multimodal) instead and include multimodal content in the function response parts that you send to the model. The model can process this multimodal content in its next turn to produce a more informed response.

{% tabs %}
{% tab label="Python" filename="multimodal_function.py" %}
```python
# ✅ Include multimodal content in the function response
final_interaction = client.interactions.create(
    model="gemini-3.6-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": tool_call.name,
            "call_id": tool_call.id,
            "result": [
                {"type": "text", "text": "instrument.jpg"},
                {
                    "type": "image",
                    "mime_type": "image/jpeg",
                    "data": base64_image_data,
                },
            ],
        }
    ],
)
```
{% /tab %}
{% tab label="JavaScript" filename="multimodal_function.js" %}
```javascript
// ✅ Include multimodal content in the function response
const finalInteraction = await client.interactions.create({
  model: "gemini-3.6-flash",
  previousInteractionId: interaction.id,
  input: [{
    type: "function_result",
    name: toolCall.name,
    call_id: toolCall.id,
    result: [
      { type: "text", text: "instrument.jpg" },
      {
        type: "image",
        mime_type: "image/jpeg",
        data: base64ImageData,
      },
    ],
  }],
});
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FunctionResultStep;
import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

// Assumes interactionId, callId, functionName, and base64ImageData from previous step
String interactionId = "interaction-id-123";
String callId = "call-id-123";
String functionName = "get_instrument_image";
String base64ImageData = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=";

// ✅ Include multimodal content in the function response
FunctionResultStep functionResult =
    FunctionResultStep.builder()
        .name(functionName)
        .callId(callId)
        .result(
            FunctionResultStepResultUnion.of(
                Arrays.asList(
                    TextContent.builder().text("instrument.jpg").build(),
                    ImageContent.builder()
                        .mimeType(ImageContentMimeType.IMAGE_JPEG)
                        .data(base64ImageData)
                        .build())))
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.5-flash"))
        .previousInteractionId(interactionId)
        .input(InteractionsInput.ofStep(Arrays.asList(functionResult)))
        .build();

Interaction finalInteraction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Assumes interactionID, callID, functionName, and base64ImageData from previous step
    interactionID := "interaction-id-123"
    callID := "call-id-123"
    functionName := "get_instrument_image"
    base64ImageData := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="

    // ✅ Include multimodal content in the function response
    functionResult := interactions.NewStep(interactions.FunctionResultStep{
        Name:   genai.Ptr(functionName),
        CallID: callID,
        Result: interactions.NewFunctionResultStepResultUnion([]interactions.FunctionResultSubcontent{
            interactions.NewFunctionResultSubcontent(interactions.TextContent{
                Text: "instrument.jpg",
            }),
            interactions.NewFunctionResultSubcontent(interactions.ImageContent{
                MimeType: interactions.ImageContentMimeType("image/jpeg").ToPointer(),
                Data:     genai.Ptr(base64ImageData),
            }),
        }),
    })

    finalRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.5-flash"),
            PreviousInteractionID: genai.Ptr(interactionID),
            Input:                 interactions.NewInteractionsInput([]interactions.Step{functionResult}),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = finalRes
}
```
{% /tab %}
{% /tabs %}

### Inline instructions in function responses {% id="inline-instructions" %}

We often see clients provide additional instructions along with function
responses as subsequent `Parts`. This can lead to unexpected model behavior
(e.g. thought leakage) and result in lower quality outputs. Instead, append any
extra instructions to the end of the function response text separated by two
newlines.

{% tabs %}
{% tab label="Python" filename="inline_instructions.py" %}
```python
# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_interaction = client.interactions.create(
    model="gemini-3.6-flash",
    previous_interaction_id=interaction.id,
    tools=[my_tool],
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [{"type": "text", "text": result_text}],
    }],
)
```
{% /tab %}
{% tab label="JavaScript" filename="inline_instructions.js" %}
```javascript
// ✅ Append inline instructions to the end of the function response separated by two newlines
const resultText = `${JSON.stringify(result)}\n\n<your inline instructions>`;

const finalInteraction = await client.interactions.create({
  model: "gemini-3.6-flash",
  previousInteractionId: interaction.id,
  tools: [myTool],
  input: [{
    type: "function_result",
    name: fcStep.name,
    call_id: fcStep.id,
    result: [{ type: "text", text: resultText }],
  }],
});
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionResultStep;
import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

// Assumes interactionId, callId, functionName, myTool, and resultJson from previous step
String interactionId = "interaction-id-123";
String callId = "call-id-123";
String functionName = "get_weather";
Function myTool = Function.builder().name(functionName).build();
String resultJson = "{\"temperature\": \"72F\"}";

// ✅ Append inline instructions to the end of the function response separated by two newlines
String resultText = resultJson + "\n\n<your inline instructions>";

FunctionResultStep functionResult =
    FunctionResultStep.builder()
        .name(functionName)
        .callId(callId)
        .result(
            FunctionResultStepResultUnion.of(
                Arrays.asList(TextContent.builder().text(resultText).build())))
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.5-flash"))
        .previousInteractionId(interactionId)
        .tools(Arrays.asList(myTool))
        .input(InteractionsInput.ofStep(Arrays.asList(functionResult)))
        .build();

Interaction finalInteraction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Assumes interactionID, callID, functionName, myTool, and resultJSON from previous step
    interactionID := "interaction-id-123"
    callID := "call-id-123"
    functionName := "get_weather"
    myTool := interactions.NewTool(interactions.Function{Name: genai.Ptr(functionName)})
    resultJSON := `{"temperature": "72F"}`

    // ✅ Append inline instructions to the end of the function response separated by two newlines
    resultText := resultJSON + "\n\n<your inline instructions>"

    functionResult := interactions.NewStep(interactions.FunctionResultStep{
        Name:   genai.Ptr(functionName),
        CallID: callID,
        Result: interactions.NewFunctionResultStepResultUnion([]interactions.FunctionResultSubcontent{
            interactions.NewFunctionResultSubcontent(interactions.TextContent{Text: resultText}),
        }),
    })

    finalRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.5-flash"),
            PreviousInteractionID: genai.Ptr(interactionID),
            Tools:                 []interactions.Tool{myTool},
            Input:                 interactions.NewInteractionsInput([]interactions.Step{functionResult}),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = finalRes
}
```
{% /tab %}
{% /tabs %}

### Reducing unnecessary tool calls {% id="reducing-tool-calls" %}

If you experience an overuse of tool calls, two techniques help minimize them:

1.  **Start by reducing the thinking level** (`medium`, `low`, or `minimal`):
    Higher thinking levels encourage the model to use more tools to explore and
    verify, so lowering the level can reduce tool calls.
2.  **Add a system instruction:** If overuse persists after adjusting the
    thinking level, consider a prompt that restricts tool usage. For example:

    ```text
    You have a limited action budget of <n> tool calls. Use them efficiently.
    ```

{% callout type="caution" %} **We strongly recommend updating to `google-genai`
SDK v2.0.0 or later.** This version introduces breaking changes to the
Interactions API. See the
[breaking changes migration guide](/docs/interactions-breaking-changes-may-2026)
for details. {% /callout %}

## Gemini 3 family features {% id="gemini-3-features" %}

Gemini 3.5 Flash inherits all Gemini 3 family capabilities, including Computer Use.
Features introduced in Gemini 3 that carry forward:

*   [**Thinking**](/docs/thinking)**:** Encrypted reasoning context preserved across API calls. Automatic in the Interactions API; implicit in GenerateContent.
*   [**Structured outputs with tools**](/docs/structured-output)**:** Combine JSON mode with built-in tools (Search, URL context, code execution, function calling).
*   [**Multimodal function responses**](/docs/function-calling#multimodal)**:** Return images, audio, and other media in function call results.
*   [**Code execution with images**](/docs/code-execution#images)**:** Execute code that processes and generates images.
*   [**Combined tool use**](/docs/tool-combination)**:** Use built-in tools and custom function calling in the same request.
*   [**Media resolution**](/docs/media-resolution)**:** Fine-grained control over token allocation for image, video, and PDF inputs. Gemini 3 models support per-content-item resolution settings (`low`, `medium`, `high`, `ultra_high`) for mixed-fidelity prompts.
*   [**Thought signatures**](/docs/thinking#signatures)**:** Encrypted
    representations of the model's internal reasoning. Required for multi-turn
    function calling in stateless mode; managed automatically by the
    Interactions API and the official SDKs.

## Prompting best practices {% id="prompting-best-practices" %}

Gemini 3.x models are reasoning models, which changes how you should prompt.

*   **Precise instructions:** Be concise. Gemini 3.x responds best to direct,
    clear instructions. Verbose or complex prompt engineering techniques
    designed for older models may cause the model to over-analyze.
*   **Output verbosity:** By default, Gemini 3 and 3.1 is less verbose and
    prefers direct, efficient answers. If your use case requires a
    conversational tone, steer the model explicitly in your prompt (for example,
    "Explain this as a friendly, talkative assistant").
*   **Context management:** When working with large datasets (such as entire
    books, codebases, or long videos), place your specific instructions or
    questions at the end of the prompt, after the data context. Anchor the
    model's reasoning by starting your question with a phrase like, "Based on
    the preceding information...".

Learn more about prompt design strategies in the
[prompt engineering guide](/docs/prompting-strategies).

## Limitations {% id="limitations" %}

*   Image segmentation is not supported in Gemini 3.x. For segmentation
    workloads, continue using Gemini 2.5 Flash with thinking off, or
    [Gemini Robotics-ER 1.6](/docs/robotics-overview).

## FAQ {% id="faq" %}

1.  **What is the knowledge cutoff for Gemini 3.5 Flash?** Gemini 3.5 Flash has
    a knowledge cutoff of January 2025. For more recent information, use the
    [Search Grounding](/docs/google-search) tool.
2.  **What are the context window limits?** Gemini 3.5 Flash supports a 1
    million token input context window and up to 65k output tokens.
3.  **Will my old `thinking_budget` code still work?** Yes, `thinking_budget` is
    still supported for backward compatibility, but we recommend migrating to
    `thinking_level` for more predictable performance. Don't use both in the
    same request.
4.  **Does Gemini 3.5 Flash support the Batch API?** Yes. See the
    [Batch API](/docs/batch-api) guide for details.
5.  **Is Context Caching supported?** Yes, [Context Caching](/docs/caching) is
    supported.
6.  **Which tools are supported?** Gemini 3.5 Flash supports
    [Google Search](/docs/google-search),
    [Grounding with Google Maps](/docs/maps-grounding),
    [File Search](/docs/file-search), [Code Execution](/docs/code-execution),
    [URL Context](/docs/url-context), and standard
    [Function Calling](/docs/function-calling), including
    [combined tool use](/docs/tool-combination), and
    [Computer Use](/docs/computer-use).

## Other models {% id="other-models" %}

*   [Gemini 3.8 Flash (Latest)](/docs/latest-model)
*   [Gemini 3.6 Flash and 3.5 Flash-Lite](/docs/whats-new-gemini-3.6)
*   [See all models](/docs/models)

## What's next {% id="whats-next" %}

*   Learn more about prompt design strategies in the
    [prompt engineering guide](/docs/prompting-strategies).
*   Get started with the
    [Gemini 3 Cookbook](https://github.com/google-gemini/cookbook)
*   Learn about [Gemini API optimization and inference](/docs/optimization)

# Nano Banana image generation
Source: https://aistudio.google.com/docs/image-generation
Description: Get started generating images with the Gemini API using Nano Banana and Nano Banana Pro

{% button href="https://aistudio.google.com" variant="ais" %}Try in Google AI Studio{% /button %}

**Nano Banana** is the name for Gemini's native image generation capabilities.
Gemini can generate and process images conversationally
with text, images, video, or a combination. This lets you create, edit, and
iterate on visuals with unprecedented control.

## Model selection {% id="model-selection" %}

Nano Banana refers to the following models available in the Gemini API:

* **Nano Banana 2.1**: The [Gemini Nano Banana 2.1](/docs/models/gemini-nano-banana-2.1)
  model (`gemini-nano-banana-2.1`). An update to Nano Banana 2, serving as the
  primary high-efficiency workhorse model for image generation and
  conversational editing. It maintains Flash-level speed and cost efficiency
  while delivering improved visual quality, text rendering, multi-turn
  consistency, and Google Search grounding across 1K, 2K, and 4K resolutions.

* **Nano Banana 2 Lite**: The [Gemini 3.1 Flash Lite Image](/docs/models/gemini-3.1-flash-lite-image)
  model (`gemini-3.1-flash-lite-image`). The fastest and cheapest Gemini image
  model, engineered for velocity and scale where speed and cost are primary
  constraints. Not optimized for multiple reference inputs or multi-turn
  sequential editing.

* **Nano Banana 2**: The [Gemini 3.1 Flash Image](/docs/models/gemini-3.1-flash-image)
  model (`gemini-3.1-flash-image`). The previous-generation high-efficiency
  workhorse model, optimized for speed, 4K generation, and multiple reference
  image consistency. Recommended for all new projects to use Nano Banana 2.1.

* **Nano Banana Pro**: The [Gemini 3 Pro Image](/docs/models/gemini-3-pro-image) model
  (`gemini-3-pro-image`). The premium choice for complex visual tasks,
  utilizing advanced reasoning ("Thinking") to follow complex instructions,
  maintain brand consistency, and render high-fidelity text.

* **Nano Banana**: The [Gemini 2.5 Flash Image](/docs/models/gemini-2.5-flash-image) model
  (`gemini-2.5-flash-image`). The legacy model of the Nano Banana series. Recommended
  migration path is Nano Banana 2 Lite for higher quality, faster speeds,
  and lower pricing.

All generated images include a [SynthID watermark](https://ai.google.dev/responsible/docs/safeguards/synthid).

## Image generation (text-to-image) {% id="image-generation-text-to-image" %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
)

with open("generated_image.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {

  const ai = new GoogleGenAI({});

  const prompt =
    "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme";

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: prompt,
  });
  const generatedImage = interaction.output_image;
  if (generatedImage) {
    if (generatedImage && generatedImage.data) {
    const buffer = Buffer.from(generatedImage.data, "base64");
    fs.writeFileSync("gemini-native-image.png", buffer);
  }
    console.log("Image saved as gemini-native-image.png");
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputImage().isPresent()
    && interaction.outputImage().get().data().isPresent()) {
  byte[] imageBytes =
      Base64.getDecoder().decode(interaction.outputImage().get().data().get());
  Files.write(Paths.get("generated_image.png"), imageBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput("Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputImage != nil && res.Interaction.OutputImage.Data != nil {
        imageBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputImage.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("generated_image.png", imageBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": [
      {"type": "text", "text": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"}
    ]
  }'
```
{% /tab %}
{% /tabs %}

You can retrieve generated image data by using the `interaction.output_image`
property, which returns the last generated image block.

{% callout type="note" %}
Note: For complex, interleaved text-and-image outputs (such as stories
containing illustrations), convenience properties will not capture all parts.
You must manually iterate over the steps instead-see
[Interleaved text and images](/docs/image-generation#interleaved-output) for an example.
{% /callout %}

## Image editing (text-and-image-to-image) {% id="gemini-image-editing" %}

**Reminder**: Make sure you have the necessary rights to any images you upload.
Don't generate content that infringe on others' rights, including videos or
images that deceive, harass, or harm. Your use of this generative AI service is
subject to our [Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy).

Provide an image and use text prompts to add, remove, or modify elements,
change the style, or adjust the color grading.

The following example demonstrates uploading `base64` encoded images.
For multiple images, larger payloads, and supported MIME types, check the [Image
understanding](/docs/image-understanding) page.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64

client = genai.Client()

with open("/path/to/cat_image.png", "rb") as f:
    image_bytes = f.read()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
          "type": "text",
          "text": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"
        },
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/png"
        }
    ],
)

with open("generated_image.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {

  const ai = new GoogleGenAI({});

  const imagePath = "path/to/cat_image.png";
  const imageData = fs.readFileSync(imagePath);
  const base64Image = imageData.toString("base64");

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: [
      { type: "text", text: "Create a picture of my cat eating a nano-banana in a" +
              "fancy restaurant under the Gemini constellation" },
      {
        type: "image",
        mime_type: "image/png",
        data: base64Image
      },
    ],
  });
  const generatedImage = interaction.output_image;
  if (generatedImage) {
    if (generatedImage && generatedImage.data) {
    const buffer = Buffer.from(generatedImage.data, "base64");
    fs.writeFileSync("gemini-native-image.png", buffer);
  }
    console.log("Image saved as gemini-native-image.png");
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] inputBytes = Files.readAllBytes(Paths.get("/path/to/cat_image.png"));
String base64Image = Base64.getEncoder().encodeToString(inputBytes);

Content textContent =
    TextContent.builder()
        .text("Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme")
        .build();
Content imageContent =
    ImageContent.builder()
        .data(base64Image)
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputImage().isPresent()
    && interaction.outputImage().get().data().isPresent()) {
  byte[] outputBytes =
      Base64.getDecoder().decode(interaction.outputImage().get().data().get());
  Files.write(Paths.get("generated_image.png"), outputBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    inputBytes, err := os.ReadFile("/path/to/cat_image.png")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(inputBytes)

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
                }),
                interactions.NewContent(interactions.ImageContent{
                    Data:     genai.Ptr(base64Image),
                    MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputImage != nil && res.Interaction.OutputImage.Data != nil {
        outputBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputImage.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("generated_image.png", outputBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -d "{
      \"model\": \"gemini-nano-banana-2.1\",
      \"input\": [
        {\"type\": \"text\", \"text\": \"Create a picture of my cat eating a nano-banana in a fancy restaurant under the Gemini constellation\"},
        {
          \"type\": \"image\",
          \"mime_type\": \"image/jpeg\",
          \"data\": \"[BASE64_IMAGE_DATA]\"
        }
      ]
    }"
```
{% /tab %}
{% /tabs %}

### Multi-turn image editing {% id="multi-turn-image-editing" %}

Keep generating and editing images conversationally. Multi-turn
conversation is the recommended way to iterate on images. The following
example shows a prompt to generate an infographic about photosynthesis.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Create a vibrant infographic that explains photosynthesis as if it were a recipe for a plant's favorite food. Show the \"ingredients\" (sunlight, water, CO2) and the \"finished dish\" (sugar/energy). The style should be like a page from a colorful kids' cookbook, suitable for a 4th grader.",
    tools=[{"type": "google_search"}],
)

with open("photosynthesis.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "Create a vibrant infographic that explains photosynthesis as if it were a recipe for a plant's favorite food. Show the \"ingredients\" (sunlight, water, CO2) and the \"finished dish\" (sugar/energy). The style should be like a page from a colorful kids' cookbook, suitable for a 4th grader.",
    tools: [{"type": "google_search"}],
  });

  const generatedImage = interaction.output_image;
  if (generatedImage) {
    if (generatedImage && generatedImage.data) {
    const buffer = Buffer.from(generatedImage.data, "base64");
    fs.writeFileSync("photosynthesis.png", buffer);
  }
    console.log("Image saved as photosynthesis.png");
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "Create a vibrant infographic that explains photosynthesis as if it were a recipe for a plant's favorite food. Show the \"ingredients\" (sunlight, water, CO2) and the \"finished dish\" (sugar/energy). The style should be like a page from a colorful kids' cookbook, suitable for a 4th grader."))
        .tools(Arrays.asList(new GoogleSearch()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputImage().isPresent()
    && interaction.outputImage().get().data().isPresent()) {
  byte[] imageBytes =
      Base64.getDecoder().decode(interaction.outputImage().get().data().get());
  Files.write(Paths.get("photosynthesis.png"), imageBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput(`Create a vibrant infographic that explains photosynthesis as if it were a recipe for a plant's favorite food. Show the "ingredients" (sunlight, water, CO2) and the "finished dish" (sugar/energy). The style should be like a page from a colorful kids' cookbook, suitable for a 4th grader.`),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.GoogleSearch{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputImage != nil && res.Interaction.OutputImage.Data != nil {
        imageBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputImage.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("photosynthesis.png", imageBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": [
      {"type": "text", "text": "Create a vibrant infographic that explains photosynthesis as if it were a recipe for a plants favorite food. Show the \"ingredients\" (sunlight, water, CO2) and the \"finished dish\" (sugar/energy). The style should be like a page from a colorful kids cookbook, suitable for a 4th grader."}
    ],
    "tools": [{"type": "google_search"}]
  }'
```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/infographic-eng.png"
  alt="AI-generated infographic about photosynthesis"
  caption="AI-generated infographic about photosynthesis"
  variant="screenshot"
/%}

You can then use the `previous_interaction_id` to change the language on the
graphic to Spanish.

{% tabs %}
{% tab label="Python" %}
```python
interaction_2 = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Update this infographic to be in Spanish. Do not change any other elements of the image.",
    previous_interaction_id=interaction.id,
    response_format={
        "type": "image",
        "mime_type": "image/jpeg",
        "aspect_ratio": "16:9",
        "image_size": "2K"
    },
)

generated_image = interaction_2.output_image
if generated_image:
    with open("photosynthesis_spanish.png", "wb") as f:
        f.write(base64.b64decode(generated_image.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction2 = await ai.interactions.create({
  model: "gemini-nano-banana-2.1",
  input: "Update this infographic to be in Spanish. Do not change any other elements of the image.",
  previous_interaction_id: interaction.id,
  response_format: {
    type: "image",
    mime_type: "image/png",
    aspect_ratio: "16:9",
    image_size: "2K"
  },
});

const generatedImage = interaction2.output_image;
if (generatedImage) {
  if (generatedImage && generatedImage.data) {
    const buffer = Buffer.from(generatedImage.data, "base64");
    fs.writeFileSync("photosynthesis_spanish.png", buffer);
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormatAspectRatio;
import com.google.genai.gaos.models.interactions.ImageResponseFormatImageSize;
import com.google.genai.gaos.models.interactions.ImageResponseFormatMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction turn1Params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "Create a vibrant infographic that explains photosynthesis as if it were a recipe for a plant's favorite food."))
        .tools(Arrays.asList(new GoogleSearch()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(turn1Params)).interaction().get();

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            ImageResponseFormat.builder()
                .mimeType(ImageResponseFormatMimeType.IMAGE_JPEG)
                .aspectRatio(ImageResponseFormatAspectRatio.of("16:9"))
                .imageSize(ImageResponseFormatImageSize.TWO_K)
                .build()));

CreateModelInteraction turn2Params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "Update this infographic to be in Spanish. Do not change any other elements of the image."))
        .previousInteractionId(interaction.id().orElse(""))
        .responseFormat(format)
        .build();

Interaction interaction2 =
    client.interactions.create(CreateInteractionRequestBody.of(turn2Params)).interaction().get();

if (interaction2.outputImage().isPresent()
    && interaction2.outputImage().get().data().isPresent()) {
  byte[] imageBytes =
      Base64.getDecoder().decode(interaction2.outputImage().get().data().get());
  Files.write(Paths.get("photosynthesis_spanish.png"), imageBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput("Create a vibrant infographic that explains photosynthesis as if it were a recipe for a plant's favorite food."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.GoogleSearch{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.ImageResponseFormat{
            MimeType:    interactions.ImageResponseFormatMimeTypeImageJpeg.ToPointer(),
            AspectRatio: interactions.ImageResponseFormatAspectRatio("16:9").ToPointer(),
            ImageSize:   interactions.ImageResponseFormatImageSizeTwoK.ToPointer(),
        }),
    )

    res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-nano-banana-2.1"),
            Input:                 interactions.NewInteractionsInput("Update this infographic to be in Spanish. Do not change any other elements of the image."),
            PreviousInteractionID: res1.Interaction.ID,
            ResponseFormat:        genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res2.Interaction.OutputImage != nil && res2.Interaction.OutputImage.Data != nil {
        imageBytes, err := base64.StdEncoding.DecodeString(*res2.Interaction.OutputImage.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("photosynthesis_spanish.png", imageBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "Update this infographic to be in Spanish. Do not change any other elements of the image.",
    "previous_interaction_id": "[PREVIOUS_INTERACTION_ID]",
    "response_format": {
      "type": "image",
      "mime_type": "image/jpeg",
      "aspect_ratio": "16:9",
      "image_size": "2K"
    }
  }'
```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/infographic-spanish.png"
  alt="AI-generated infographic of photosynthesis in Spanish"
  caption="AI-generated infographic of photosynthesis in Spanish"
  variant="screenshot"
/%}

## Features of Nano Banana {% id="gemini-3-capabilities" %}

Nano Banana models offer state-of-the-art image generation and editing. Gemini
Nano Banana 2.1 and Gemini 3.1 Flash Image are optimized for speed and
high-volume use-cases, and Gemini 3 Pro Image is optimized for professional
asset production.
Designed to tackle the most challenging workflows through advanced reasoning,
they excel at complex, multi-turn creation and modification tasks.

- **High-resolution output**: Built-in generation capabilities for 1K, 2K, and 4K visuals.
  - **Gemini 3.1 Flash Image** adds the smaller 512px (0.5K) resolution (not supported on Gemini Nano Banana 2.1).
- **Advanced text rendering**: Capable of generating legible, stylized text for
  infographics, menus, diagrams, and marketing assets.

- **Grounding with Google Search**: The model can use Google Search as a tool to
  verify facts and generate imagery based on real-time data (e.g., current
  weather maps, stock charts, recent events).

  - **Gemini Nano Banana 2.1 and Gemini 3.1 Flash Image** add the integration of Google Image Search
  Grounding alongside Web Search.

- **Thinking mode**: The model utilizes a "thinking" process to reason through
  complex prompts. It generates interim "thought images" (visible in the backend
  but not charged) to refine the composition before producing the final
  high-quality output.

- **Up to 14 reference images**: Mix up to 14 reference images to
  produce the final image.

- **New aspect ratios**: Gemini Nano Banana 2.1 and Gemini 3.1 Flash Image add 1:4, 4:1, 1:8, and
  8:1 [aspect ratios](/docs/image-generation#aspect-ratios-and-image-size).

### Use up to 14 reference images {% id="use-14-images" %}

Nano Banana models allow you to mix up to 14 reference images. These 14 images
can include the following:

| Gemini Nano Banana 2.1 & Gemini 3.1 Flash Image | Gemini 3 Pro Image |
| :---- | :---- |
| Up to 10 images of objects with high-fidelity to include in the final image | Up to 6 images of objects with high-fidelity to include in the final image |
| Up to 4 images of characters to maintain character consistency | Up to 5 images of characters to maintain character consistency |
| N/A | Up to 3 images to be used as style references |

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
from PIL import Image
import base64

prompt = "An office group photo of these people, they are making funny faces."

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "text",
            "text": prompt,
        },
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/png"
        },
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/png"
        },
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/png"
        },
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/png"
        },
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/png"
        },
    ],
    response_format={
        "type": "image",
        "aspect_ratio": "5:4",
        "image_size": "2K"
    },
)

with open("office.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))
```

{% /tab %}
{% tab label="JavaScript" %}

  ```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: [
      {
        type: "text",
        text: "An office group photo of these people, they are making funny faces.",
      },
      { type: "image", mime_type: "image/jpeg", data: base64ImageFile1 },
      { type: "image", mime_type: "image/jpeg", data: base64ImageFile2 },
      { type: "image", mime_type: "image/jpeg", data: base64ImageFile3 },
      { type: "image", mime_type: "image/jpeg", data: base64ImageFile4 },
      { type: "image", mime_type: "image/jpeg", data: base64ImageFile5 },
    ],
    response_format: {
      type: "image",
      aspect_ratio: "5:4",
      image_size: "2K",
    },
  });

  if (interaction.output_image && interaction.output_image.data) {
    const buffer = Buffer.from(interaction.output_image.data, 'base64');
    fs.writeFileSync('office.png', buffer);
  }
}

await main();
  ```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormatAspectRatio;
import com.google.genai.gaos.models.interactions.ImageResponseFormatImageSize;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

String prompt = "An office group photo of these people, they are making funny faces.";

byte[] imageBytes = Files.readAllBytes(Paths.get("/path/to/person.png"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);

Content textContent = TextContent.builder().text(prompt).build();
Content imageContent =
    ImageContent.builder()
        .data(base64Image)
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();

List<Content> contents =
    Arrays.asList(
        textContent,
        imageContent,
        imageContent,
        imageContent,
        imageContent,
        imageContent);

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            ImageResponseFormat.builder()
                .aspectRatio(ImageResponseFormatAspectRatio.of("5:4"))
                .imageSize(ImageResponseFormatImageSize.TWO_K)
                .build()));

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputImage().isPresent()
    && interaction.outputImage().get().data().isPresent()) {
  byte[] outBytes =
      Base64.getDecoder().decode(interaction.outputImage().get().data().get());
  Files.write(Paths.get("office.png"), outBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "An office group photo of these people, they are making funny faces."

    imageBytes, err := os.ReadFile("/path/to/person.png")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)

    textContent := interactions.NewContent(interactions.TextContent{
        Text: prompt,
    })
    imageContent := interactions.NewContent(interactions.ImageContent{
        Data:     genai.Ptr(base64Image),
        MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
    })

    contents := []interactions.Content{
        textContent,
        imageContent,
        imageContent,
        imageContent,
        imageContent,
        imageContent,
    }

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.ImageResponseFormat{
            AspectRatio: interactions.ImageResponseFormatAspectRatio("5:4").ToPointer(),
            ImageSize:   interactions.ImageResponseFormatImageSizeTwoK.ToPointer(),
        }),
    )

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:          interactions.Model("gemini-nano-banana-2.1"),
            Input:          interactions.NewInteractionsInput(contents),
            ResponseFormat: genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputImage != nil && res.Interaction.OutputImage.Data != nil {
        outBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputImage.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("office.png", outBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}

  ```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -d "{
      \"model\": \"gemini-nano-banana-2.1\",
      \"input\": [
        {\"type\": \"text\", \"text\": \"An office group photo of these people, they are making funny faces.\"},
        {\"type\": \"image\", \"mime_type\": \"image/png\", \"data\": \"[BASE64_DATA_IMG_1]\"},
        {\"type\": \"image\", \"mime_type\": \"image/png\", \"data\": \"[BASE64_DATA_IMG_2]\"},
        {\"type\": \"image\", \"mime_type\": \"image/png\", \"data\": \"[BASE64_DATA_IMG_3]\"},
        {\"type\": \"image\", \"mime_type\": \"image/png\", \"data\": \"[BASE64_DATA_IMG_4]\"},
        {\"type\": \"image\", \"mime_type\": \"image/png\", \"data\": \"[BASE64_DATA_IMG_5]\"}
      ],
      \"response_format\": {
        \"type\": \"image\",
        \"aspect_ratio\": \"5:4\",
        \"image_size\": \"2K\"
      }
    }"
  ```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/office-group-photo.jpeg"
  alt="AI-generated office group photo"
  caption="AI-generated office group photo"
  variant="screenshot"
/%}

### Grounding with Google Search {% id="use-with-grounding" %}

Use the [Google Search tool](/docs/google-search) to generate images
based on real-time information, such as weather forecasts, stock charts, or
recent events.

Note that when using Grounding with Google Search with image generation,
image-based search results are not passed to the generation model and are
excluded from the response (see [Grounding with Google Image Search](/docs/image-generation#image-search)).

{% callout type="note" %}
Grounding with Google Search is not supported by the
`gemini-3.1-flash-lite-image` model.
{% /callout %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
import base64
prompt = "Visualize the current weather forecast for the next 5 days in San Francisco as a clean, modern weather chart. Add a visual on what I should wear each day"

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=prompt,
    tools=[{"type": "google_search"}],
    response_format={
        "type": "image",
        "mime_type": "image/jpeg",
        "aspect_ratio": "16:9"
    },
)

with open("weather.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "Visualize the current weather forecast for the next 5 days in San Francisco as a clean, modern weather chart. Add a visual on what I should wear each day",
    tools: [{"type": "google_search"}],
    response_format: {
      type: "image",
      mime_type: "image/png",
      aspect_ratio: "16:9",
      image_size: "2K"
    },
  });

  if (interaction.output_image && interaction.output_image.data) {
    const buffer = Buffer.from(interaction.output_image.data, 'base64');
    fs.writeFileSync('weather.png', buffer);
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormatAspectRatio;
import com.google.genai.gaos.models.interactions.ImageResponseFormatMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;

String prompt =
    "Visualize the current weather forecast for the next 5 days in San Francisco as a clean, modern weather chart. Add a visual on what I should wear each day";

Client client = new Client();

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            ImageResponseFormat.builder()
                .mimeType(ImageResponseFormatMimeType.IMAGE_JPEG)
                .aspectRatio(ImageResponseFormatAspectRatio.of("16:9"))
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.of(prompt))
        .tools(Arrays.asList(new GoogleSearch()))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputImage().isPresent()
    && interaction.outputImage().get().data().isPresent()) {
  byte[] imageBytes =
      Base64.getDecoder().decode(interaction.outputImage().get().data().get());
  Files.write(Paths.get("weather.png"), imageBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Visualize the current weather forecast for the next 5 days in San Francisco as a clean, modern weather chart. Add a visual on what I should wear each day"

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.ImageResponseFormat{
            MimeType:    interactions.ImageResponseFormatMimeTypeImageJpeg.ToPointer(),
            AspectRatio: interactions.ImageResponseFormatAspectRatio("16:9").ToPointer(),
        }),
    )

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput(prompt),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.GoogleSearch{}),
            },
            ResponseFormat: genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputImage != nil && res.Interaction.OutputImage.Data != nil {
        imageBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputImage.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("weather.png", imageBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": [
      {"type": "text", "text": "Visualize the current weather forecast for the next 5 days in San Francisco as a clean, modern weather chart. Add a visual on what I should wear each day"}
    ],
    "tools": [{"type": "google_search"}],
    "response_format": {
      "type": "image",
      "mime_type": "image/jpeg",
      "aspect_ratio": "16:9"
    }
  }'
```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/weather-forecast.png"
  alt="AI-generated five day weather chart for San Francisco"
  caption="AI-generated five day weather chart for San Francisco"
  variant="screenshot"
/%}

The response includes `google_search_call` and `google_search_result` steps,
along with inline `url_citation` annotations on the text step:

- **`google_search_result`**: Contains `search_suggestions`, an HTML snippet
  for rendering search suggestions in your UI.

- **`url_citation` annotations**: Inline citations on the text step linking
  parts of the response to their web sources.

### Grounding with Google Search for Images (Nano Banana 2.1 and 3.1 Flash) {% id="image-search" %}

{% callout type="note" %}
Note: This feature is only available for the Gemini Nano Banana 2.1 and Gemini 3.1 Flash Image models.
{% /callout %}

Grounding with Google Image Search allows models to use web images retrieved via
Google Image Search as visual context for image generation. Image Search is a
new search type within the existing Grounding with Google Search tool,
functioning alongside standard [Web Search](/docs/image-generation#use-with-grounding).

To enable Image Search, configure the `google_search` tool in your API request
and specify `image_search` within the `search_types` array. Image Search can be
used independently or together with Web Search.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A detailed painting of a Timareta butterfly resting on a flower",
    tools=[{
      "type": "google_search",
      "search_types": ["web_search", "image_search"]
    }]
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "A detailed painting of a Timareta butterfly resting on a flower",
    tools: [{
      "type": "google_search",
      "search_types": ["web_search", "image_search"]
    }]
  });
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.GoogleSearchSearchType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

GoogleSearch searchTool =
    GoogleSearch.builder()
        .searchTypes(
            Arrays.asList(
                GoogleSearchSearchType.WEB_SEARCH, GoogleSearchSearchType.IMAGE_SEARCH))
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "A detailed painting of a Timareta butterfly resting on a flower"))
        .tools(Arrays.asList(searchTool))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    searchTool := interactions.GoogleSearch{
        SearchTypes: []interactions.GoogleSearchSearchType{
            interactions.GoogleSearchSearchTypeWebSearch,
            interactions.GoogleSearchSearchTypeImageSearch,
        },
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput("A detailed painting of a Timareta butterfly resting on a flower"),
            Tools: []interactions.Tool{
                interactions.NewTool(searchTool),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "A detailed painting of a Timareta butterfly resting on a flower",
    "tools": [{"type": "google_search", "search_types": ["web_search", "image_search"]}]
  }'
```
{% /tab %}
{% /tabs %}

**Display requirements**

When you use Image Search within Grounding with Google Search, you must display
the `search_suggestions` from the `google_search_result` step. Full usage
requirements are detailed in the
[Terms of Service](/docs/terms#grounding-with-google-search).

**Response**

For grounded responses using image search, the API returns inline citations
and attribution metadata as part of the response steps:

* **`url_citation` annotations**: Inline citations on the text content block
    within `model_output`, linking the generated content to its source.

* **`google_search_result`**: Contains `search_suggestions`, an HTML
    snippet for rendering search suggestions in your UI.

### Video-to-image generation (Nano Banana 2.1, 3.1 Flash, and 3.1 Flash Lite) {% id="video-to-image" %}

{% callout type="note" %}
Note: This feature is only available for the Gemini Nano Banana 2.1, Gemini 3.1 Flash Image, and Gemini 3.1 Flash Lite Image models.
{% /callout %}

Video-to-image generation allows you to generate new images using a video's
context as a multimodal reference. This is useful for creating high-quality
video thumbnails, cinematic
posters, summary infographics, or new artwork inspired by a video scene.

During generation, the model analyzes the video frames in context to extract
visual themes and key events, then uses them alongside your text prompt to
synthesize the output image.

You can pass public [YouTube URLs](/docs/video-understanding#youtube)
directly in your API request or upload local video files using the
[Files API](/docs/files).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=UTdfxFyOQTI",
            "mime_type": "video/mp4"
        },
        {"type": "text", "text": "Generate a poster image that captures the key themes of this video."}
    ],
    response_format={"type": "image", "aspect_ratio": "16:9"}
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("video_poster.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
                print("Image saved as video_poster.png")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: [
      {
        type: "video",
        uri: "https://www.youtube.com/watch?v=UTdfxFyOQTI",
        mime_type: "video/mp4"
      },
      { type: "text", text: "Generate a poster image that captures the key themes of this video." }
    ],
    response_format: {
      type: "image",
      aspect_ratio: "16:9"
    }
  });

  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("video_poster.png", buffer);
        }
          console.log("Image saved as video_poster.png");
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormatAspectRatio;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

Content videoContent =
    VideoContent.builder()
        .uri("https://www.youtube.com/watch?v=UTdfxFyOQTI")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();
Content textContent =
    TextContent.builder()
        .text("Generate a poster image that captures the key themes of this video.")
        .build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            ImageResponseFormat.builder()
                .aspectRatio(ImageResponseFormatAspectRatio.of("16:9"))
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content block : outputStep.content().get()) {
          if (block instanceof TextContent) {
            System.out.println(((TextContent) block).text().orElse(""));
          } else if (block instanceof ImageContent) {
            ImageContent img = (ImageContent) block;
            if (img.data().isPresent()) {
              byte[] imgBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("video_poster.png"), imgBytes);
              System.out.println("Image saved as video_poster.png");
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI:      genai.Ptr("https://www.youtube.com/watch?v=UTdfxFyOQTI"),
            MimeType: interactions.VideoContentMimeTypeVideoMp4.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "Generate a poster image that captures the key themes of this video.",
        }),
    }

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.ImageResponseFormat{
            AspectRatio: interactions.ImageResponseFormatAspectRatio("16:9").ToPointer(),
        }),
    )

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:          interactions.Model("gemini-nano-banana-2.1"),
            Input:          interactions.NewInteractionsInput(contents),
            ResponseFormat: genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, block := range step.ModelOutputStep.Content {
                if block.TextContent != nil {
                    fmt.Println(block.TextContent.Text)
                } else if block.ImageContent != nil && block.ImageContent.Data != nil {
                    imgBytes, err := base64.StdEncoding.DecodeString(*block.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("video_poster.png", imgBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                    fmt.Println("Image saved as video_poster.png")
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": [
      {
        "type": "video",
        "uri": "https://www.youtube.com/watch?v=UTdfxFyOQTI",
        "mime_type": "video/mp4"
      },
      {
        "type": "text",
        "text": "Generate a poster image that captures the key themes of this video."
      }
    ],
    "response_format": {
      "type": "image",
      "aspect_ratio": "16:9"
    }
  }'
```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/youtube_infographics.jpg"
  alt="AI-generated infographic from a youtube video"
  caption="AI-generated infographic from a youtube video"
  variant="screenshot"
/%}

### Generate images up to 4K resolution {% id="generate-4k-images" %}

Gemini 3 image models generate 1K images by default but can also output 2K,
4K, and 512px (05.K) (Gemini 3.1 Flash Image only) images. To generate higher
resolution assets, specify the `image_size` in the `response_format`.

You must use an uppercase 'K' (e.g. 512px (05.K), 1K, 2K, 4K). Lowercase
parameters (e.g., 1k) will be rejected.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
import base64

prompt = "Da Vinci style anatomical sketch of a dissected Monarch butterfly. Detailed drawings of the head, wings, and legs on textured parchment with notes in English."

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=prompt,
    response_format={
        "type": "image",
        "mime_type": "image/jpeg",
        "aspect_ratio": "1:1",
        "image_size": "1K"
    },
)

print(interaction.output_text)

with open("butterfly.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "Da Vinci style anatomical sketch of a dissected Monarch butterfly. Detailed drawings of the head, wings, and legs on textured parchment with notes in English.",
    response_format: {
      type: "image",
      mime_type: "image/png",
      aspect_ratio: "1:1",
      image_size: "1K",
    },
  });

  console.log(interaction.output_text);

  if (interaction.output_image && interaction.output_image.data) {
    const buffer = Buffer.from(interaction.output_image.data, 'base64');
    fs.writeFileSync('butterfly.png', buffer);
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormatAspectRatio;
import com.google.genai.gaos.models.interactions.ImageResponseFormatImageSize;
import com.google.genai.gaos.models.interactions.ImageResponseFormatMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

String prompt =
    "Da Vinci style anatomical sketch of a dissected Monarch butterfly. Detailed drawings of the head, wings, and legs on textured parchment with notes in English.";

Client client = new Client();

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            ImageResponseFormat.builder()
                .mimeType(ImageResponseFormatMimeType.IMAGE_JPEG)
                .aspectRatio(ImageResponseFormatAspectRatio.of("1:1"))
                .imageSize(ImageResponseFormatImageSize.ONE_K)
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.of(prompt))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

if (interaction.outputImage().isPresent()
    && interaction.outputImage().get().data().isPresent()) {
  byte[] imageBytes =
      Base64.getDecoder().decode(interaction.outputImage().get().data().get());
  Files.write(Paths.get("butterfly.png"), imageBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Da Vinci style anatomical sketch of a dissected Monarch butterfly. Detailed drawings of the head, wings, and legs on textured parchment with notes in English."

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.ImageResponseFormat{
            MimeType:    interactions.ImageResponseFormatMimeTypeImageJpeg.ToPointer(),
            AspectRatio: interactions.ImageResponseFormatAspectRatio("1:1").ToPointer(),
            ImageSize:   interactions.ImageResponseFormatImageSizeOneK.ToPointer(),
        }),
    )

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:          interactions.Model("gemini-nano-banana-2.1"),
            Input:          interactions.NewInteractionsInput(prompt),
            ResponseFormat: genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }

    if res.Interaction.OutputImage != nil && res.Interaction.OutputImage.Data != nil {
        imageBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputImage.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("butterfly.png", imageBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "Da Vinci style anatomical sketch of a dissected Monarch butterfly. Detailed drawings of the head, wings, and legs on textured parchment with notes in English.",
    "response_format": {
      "type": "image",
      "mime_type": "image/jpeg",
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }'
```
{% /tab %}
{% /tabs %}

The following is an example image generated from this prompt:

{% image
  src="/googledevai/static/gemini-api/docs/images/gemini3-4k-image.png"
  alt="AI-generated Da Vinci style anatomical sketch of a dissected Monarch
butterfly."
  caption="AI-generated Da Vinci style anatomical sketch of a dissected Monarch
butterfly."
  variant="screenshot"
/%}

### Thinking Process {% id="thinking-process" %}

Gemini 3 image models are thinking models that use a reasoning
process ("Thinking") for complex prompts. This feature is enabled by default and
cannot be disabled in the API. To learn more about the thinking process, see
the [Gemini Thinking](/docs/thinking) guide.

The model generates up to two interim images to test composition and logic. The
last image within Thinking is also the final rendered image.

You can check the thoughts that lead to the final image being produced.

{% tabs %}
{% tab label="Python" %}
```python
for step in interaction.steps:
    if step.type == "thought":
        for content_block in step.summary:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                image = Image.open(io.BytesIO(base64.b64decode(content_block.data)))
                image.show()
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
for (const step of interaction.steps) {
  if (step.type === "thought") {
    for (const contentBlock of step.summary) {
      if (contentBlock.type === "text") {
        console.log(contentBlock.text);
      } else if (contentBlock.type === "image") {
        if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("thought_image.png", buffer);
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.ThoughtStep;
import com.google.genai.gaos.models.interactions.ThoughtSummaryContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "A futuristic city built inside a giant glass bottle floating in space"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ThoughtStep) {
      ThoughtStep thoughtStep = (ThoughtStep) step;
      if (thoughtStep.summary().isPresent()) {
        for (ThoughtSummaryContent contentBlock : thoughtStep.summary().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] imgBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("thought_image.png"), imgBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput("A futuristic city built inside a giant glass bottle floating in space"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ThoughtStep != nil {
            for _, contentBlock := range step.ThoughtStep.Summary {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    imgBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("thought_image.png", imgBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% /tabs %}

#### Interleaved text and images {% id="interleaved-output" %}

While standard image generation models only output images, some advanced Gemini
3 models (such as `gemini-3-pro-image`) can generate interleaved
content-like stories or instructional guides containing both text blocks and
illustrations inside the same response.

Because the output is complex and interleaved, convenience properties like
`.output_image` or `.output_text` will not capture the full sequence. To access
and save interleaved content, you must manually iterate over `steps`:

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="gemini-3-pro-image",
    input="Write the story of the lifecycle of a monarch butterfly, interleave illustrations",
)

image_counter = 1
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                filename = f"butterfly_lifecycle_{image_counter}.png"
                with open(filename, "wb") as f:
                    f.write(base64.b64decode(content_block.data))
                print(f"\n[Saved illustration: {filename}]\n")
                image_counter += 1
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await ai.interactions.create({
    model: "gemini-3-pro-image",
    input: "Write the story of the lifecycle of a monarch butterfly, interleave illustrations",
});

let imageCounter = 1;
for (const step of interaction.steps) {
  if (step.type === "model_output") {
    for (const contentBlock of step.content || []) {
      if (contentBlock.type === "text") {
        console.log(contentBlock.text);
      } else if (contentBlock.type === "image") {
        const buffer = Buffer.from(contentBlock.data, "base64");
        const filename = `butterfly_lifecycle_${imageCounter}.png`;
        fs.writeFileSync(filename, buffer);
        console.log(`\n[Saved illustration: ${filename}]\n`);
        imageCounter++;
      }
    }
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3-pro-image"))
        .input(
            InteractionsInput.of(
                "Write the story of the lifecycle of a monarch butterfly, interleave illustrations"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

int imageCounter = 1;
if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              String filename = String.format("butterfly_lifecycle_%d.png", imageCounter);
              byte[] imgBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get(filename), imgBytes);
              System.out.printf("%n[Saved illustration: %s]%n", filename);
              imageCounter++;
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3-pro-image"),
            Input: interactions.NewInteractionsInput("Write the story of the lifecycle of a monarch butterfly, interleave illustrations"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    imageCounter := 1
    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    filename := fmt.Sprintf("butterfly_lifecycle_%d.png", imageCounter)
                    imgBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile(filename, imgBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                    fmt.Printf("\n[Saved illustration: %s]\n", filename)
                    imageCounter++
                }
            }
        }
    }
}
```
{% /tab %}

{% /tabs %}

#### Controlling thinking levels {% id="thinking-levels" %}

With Gemini Nano Banana 2.1, Gemini 3.1 Flash Image, and Gemini 3.1 Flash Lite
Image, you can control the amount of thinking the model uses to balance quality
and latency:

| Model | Supported thinking levels | Default |
| :---- | :---- | :---- |
| **Gemini Nano Banana 2.1** | `minimal`, `medium`, `high` | `medium` |
| **Gemini 3.1 Flash Image** | `minimal`, `high` | `minimal` |
| **Gemini 3.1 Flash Lite Image** | `minimal`, `high` | `minimal` |

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64
import io

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A futuristic city built inside a giant glass bottle floating in space",
    generation_config={"thinking_level": "high"},
)

print(interaction.output_text)

image = Image.open(io.BytesIO(base64.b64decode(interaction.output_image.data)))

image.show()

```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "A futuristic city built inside a giant glass bottle floating in space",
    generation_config: { thinking_level: "high" },
  });

  console.log(interaction.output_text);

  if (interaction.output_image && interaction.output_image.data) {
    const buffer = Buffer.from(interaction.output_image.data, 'base64');
    fs.writeFileSync('image.png', buffer);
  }
}
await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ThinkingLevel;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "A futuristic city built inside a giant glass bottle floating in space"))
        .generationConfig(GenerationConfig.builder().thinkingLevel(ThinkingLevel.HIGH).build())
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

if (interaction.outputImage().isPresent()
    && interaction.outputImage().get().data().isPresent()) {
  byte[] imageBytes =
      Base64.getDecoder().decode(interaction.outputImage().get().data().get());
  Files.write(Paths.get("futuristic_city.png"), imageBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput("A futuristic city built inside a giant glass bottle floating in space"),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel: interactions.ThinkingLevelHigh.ToPointer(),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }

    if res.Interaction.OutputImage != nil && res.Interaction.OutputImage.Data != nil {
        imageBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputImage.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("futuristic_city.png", imageBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "A futuristic city built inside a giant glass bottle floating in space",
    "generation_config": {
      "thinking_level": "high"
    }
  }'
```
{% /tab %}
{% /tabs %}

Note that thinking tokens are billed by default for thinking models, as the
[thinking process](/docs/image-generation#thinking-process) always happens by default whether you view
the process or not.

## Other image generation modes {% id="other-modes" %}

Although Nano Banana image generation models are recommended for most use cases,
you can also explore dedicated image generation models:

* **Imagen**: Google's legacy text-to-image models (shut down).

* **[Veo](/docs/video)**: Google's video generation model.

## Generate images in batch {% id="batch-api" %}

All of the image generation capabilities described on this page can also be
run as batch jobs using the [Batch API](/docs/batch-api).

## Prompting guide and strategies {% id="prompt-guide" %}

This section provides prompt examples and templates for common image generation
and editing workflows. Each example includes a re-usable template and a
sample prompt for the Interactions API.

### Prompts for generating images {% id="image-generation-prompts" %}

The following examples show how to use text prompts to generate various types of
images.

#### 1. Photorealistic scenes {% id="1-photorealistic-scenes" %}

Describe a scene in rich detail. The more specific you are, the more control you
have over the results.

{% tabs %}
{% tab label="Template" %}
```none
A photorealistic [type of shot] of a [subject description] in a [setting
description]. [Description of the light]. Shot from a [camera angle]
with a [lens type].
```
{% /tab %}
{% tab label="Prompt" %}
```none
A photorealistic wide-angle shot of a vibrant coral reef teeming with tropical fish. Crystal-clear turquoise water with sunbeams filtering down from the surface, illuminating a sea turtle gliding gracefully over the coral. Shot from a low perspective with a wide-angle lens. Aspect ratio 16:9.
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A photorealistic wide-angle shot of a vibrant coral reef teeming with tropical fish. Crystal-clear turquoise water with sunbeams filtering down from the surface, illuminating a sea turtle gliding gracefully over the coral. Shot from a low perspective with a wide-angle lens. Aspect ratio 16:9.",
    response_format=[
        {
            "type": "image",
            "mime_type": "image/jpeg",
            "aspect_ratio": "16:9",
        }
    ],
)

print(interaction.output_text)

with open("coral_reef.png", "wb") as f:

    f.write(base64.b64decode(interaction.output_image.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "A photorealistic wide-angle shot of a vibrant coral reef teeming with tropical fish. Crystal-clear turquoise water with sunbeams filtering down from the surface, illuminating a sea turtle gliding gracefully over the coral. Shot from a low perspective with a wide-angle lens. Aspect ratio 16:9.",
    response_format: [
      {
        type: "image",
        mime_type: "image/jpeg",
        aspect_ratio: "16:9",
      }
    ],
  });
  console.log(interaction.output_text);

  if (interaction.output_image && interaction.output_image.data) {
    const buffer = Buffer.from(interaction.output_image.data, 'base64');
    fs.writeFileSync('coral_reef.png', buffer);
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormatAspectRatio;
import com.google.genai.gaos.models.interactions.ImageResponseFormatMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;

Client client = new Client();

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        Arrays.asList(
            ResponseFormat.of(
                ImageResponseFormat.builder()
                    .mimeType(ImageResponseFormatMimeType.IMAGE_JPEG)
                    .aspectRatio(ImageResponseFormatAspectRatio.of("16:9"))
                    .build())));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "A photorealistic wide-angle shot of a vibrant coral reef teeming with tropical fish. Crystal-clear turquoise water with sunbeams filtering down from the surface, illuminating a sea turtle gliding gracefully over the coral. Shot from a low perspective with a wide-angle lens. Aspect ratio 16:9."))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

if (interaction.outputImage().isPresent()
    && interaction.outputImage().get().data().isPresent()) {
  byte[] imageBytes =
      Base64.getDecoder().decode(interaction.outputImage().get().data().get());
  Files.write(Paths.get("coral_reef.png"), imageBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    format := interactions.NewCreateModelInteractionResponseFormat([]interactions.ResponseFormat{
        interactions.NewResponseFormat(interactions.ImageResponseFormat{
            MimeType:    interactions.ImageResponseFormatMimeTypeImageJpeg.ToPointer(),
            AspectRatio: interactions.ImageResponseFormatAspectRatio("16:9").ToPointer(),
        }),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:          interactions.Model("gemini-nano-banana-2.1"),
            Input:          interactions.NewInteractionsInput("A photorealistic wide-angle shot of a vibrant coral reef teeming with tropical fish. Crystal-clear turquoise water with sunbeams filtering down from the surface, illuminating a sea turtle gliding gracefully over the coral. Shot from a low perspective with a wide-angle lens. Aspect ratio 16:9."),
            ResponseFormat: genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }

    if res.Interaction.OutputImage != nil && res.Interaction.OutputImage.Data != nil {
        imageBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputImage.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("coral_reef.png", imageBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "A photorealistic wide-angle shot of a vibrant coral reef teeming with tropical fish. Crystal-clear turquoise water with sunbeams filtering down from the surface, illuminating a sea turtle gliding gracefully over the coral. Shot from a low perspective with a wide-angle lens. Aspect ratio 16:9.",
    "response_format": {
      "type": "image",
      "mime_type": "image/png",
      "aspect_ratio": "16:9"
    }
  }'
```
{% /tab %}
{% /tabs %}

#### 2. Stylized illustrations & stickers {% id="2-stylized-illustrations-stickers" %}

Describe the artistic style, subject, and medium. Be specific about the visual
detail (bold lines, colors, etc.) for consistent results.

{% tabs %}
{% tab label="Template" %}
```none
A [style] of a [subject, with details about accessories or actions]
doing [activity]. The design features [visual qualities, e.g., bold outlines,
cel-shading, etc.] and [color/background preference].
```
{% /tab %}
{% tab label="Prompt" %}
```none
A kawaii-style sticker of a happy red panda wearing a tiny bamboo hat. It's munching on a green bamboo leaf. The design features bold, clean outlines, simple cel-shading, and a vibrant color palette. The background must be white.
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A kawaii-style sticker of a happy red panda wearing a tiny bamboo hat. It's munching on a green bamboo leaf. The design features bold, clean outlines, simple cel-shading, and a vibrant color palette. The background must be white.",
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("red_panda_sticker.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "A kawaii-style sticker of a happy red panda wearing a tiny bamboo hat. It's munching on a green bamboo leaf. The design features bold, clean outlines, simple cel-shading, and a vibrant color palette. The background must be white.",
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("red_panda_sticker.png", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "A kawaii-style sticker of a happy red panda wearing a tiny bamboo hat. It's munching on a green bamboo leaf. The design features bold, clean outlines, simple cel-shading, and a vibrant color palette. The background must be white."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] imgBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("red_panda_sticker.png"), imgBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput("A kawaii-style sticker of a happy red panda wearing a tiny bamboo hat. It's munching on a green bamboo leaf. The design features bold, clean outlines, simple cel-shading, and a vibrant color palette. The background must be white."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    imgBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("red_panda_sticker.png", imgBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "A kawaii-style sticker of a happy red panda wearing a tiny bamboo hat. It is munching on a green bamboo leaf. The design features bold, clean outlines, simple cel-shading, and a vibrant color palette. The background must be white."
  }'
```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/red_panda_sticker.png"
  alt="A kawaii-style sticker of a happy red..."
  caption="A kawaii-style sticker of a happy red panda..."
  variant="screenshot"
/%}

#### 3. Accurate text in images {% id="3-accurate-text-in-images" %}

Gemini excels at rendering text. Be clear about the text, the font style
(descriptively), and the overall design. Use Gemini 3 Pro Image for
professional asset production.

{% tabs %}
{% tab label="Template" %}
```none
Create a [image type] for [brand/concept] with the text "[text to render]"
in a [font style]. The design should be [style description], with a
[color scheme].
```
{% /tab %}
{% tab label="Prompt" %}
```none
Create a modern, minimalist logo for a coffee shop called 'The Daily Grind'. The text should be in a clean, bold, sans-serif font. The color scheme is black and white. Put the logo in a circle. Use a coffee bean in a clever way.
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Create a modern, minimalist logo for a coffee shop called 'The Daily Grind'. The text should be in a clean, bold, sans-serif font. The color scheme is black and white. Put the logo in a circle. Use a coffee bean in a clever way.",
    response_format={"type": "image", "aspect_ratio": "1:1"},
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("logo_example.jpg", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "Create a modern, minimalist logo for a coffee shop called 'The Daily Grind'. The text should be in a clean, bold, sans-serif font. The color scheme is black and white. Put the logo in a circle. Use a coffee bean in a clever way.",
    response_format: { type: "image", aspect_ratio: "1:1" },
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("logo_example.jpg", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormatAspectRatio;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            ImageResponseFormat.builder()
                .aspectRatio(ImageResponseFormatAspectRatio.of("1:1"))
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "Create a modern, minimalist logo for a coffee shop called 'The Daily Grind'. The text should be in a clean, bold, sans-serif font. The color scheme is black and white. Put the logo in a circle. Use a coffee bean in a clever way."))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] imgBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("logo_example.jpg"), imgBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.ImageResponseFormat{
            AspectRatio: interactions.ImageResponseFormatAspectRatio("1:1").ToPointer(),
        }),
    )

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:          interactions.Model("gemini-nano-banana-2.1"),
            Input:          interactions.NewInteractionsInput("Create a modern, minimalist logo for a coffee shop called 'The Daily Grind'. The text should be in a clean, bold, sans-serif font. The color scheme is black and white. Put the logo in a circle. Use a coffee bean in a clever way."),
            ResponseFormat: genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    imgBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("logo_example.jpg", imgBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "Create a modern, minimalist logo for a coffee shop called The Daily Grind. The text should be in a clean, bold, sans-serif font. The color scheme is black and white. Put the logo in a circle. Use a coffee bean in a clever way.",
    "response_format": {
      "type": "image",
      "aspect_ratio": "1:1"
    }
  }'
```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/logo_example.jpg"
  alt="Create a modern, minimalist logo for a coffee shop called
'The Daily Grind'..."
  caption="Create a modern, minimalist logo for a coffee shop called
'The Daily Grind'..."
  variant="screenshot"
/%}

#### 4. Product mockups & commercial photography {% id="4-product-mockups-commercial-photography" %}

Perfect for creating clean, professional product shots for ecommerce,
advertising, or branding.

{% tabs %}
{% tab label="Template" %}
```none
A high-resolution, studio-lit product photograph of a [product description]
on a [background surface/description]. The lighting is a [lighting setup,
e.g., three-point softbox setup] to [lighting purpose]. The camera angle is
a [angle type] to showcase [specific feature]. Ultra-realistic, with sharp
focus on [key detail]. [Aspect ratio].
```
{% /tab %}
{% tab label="Prompt" %}
```none
A high-resolution, studio-lit product photograph of a minimalist ceramic
coffee mug in matte black, presented on a polished concrete surface. The
lighting is a three-point softbox setup designed to create soft, diffused
highlights and eliminate harsh shadows. The camera angle is a slightly
elevated 45-degree shot to showcase its clean lines. Ultra-realistic, with
sharp focus on the steam rising from the coffee. Square image.
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A high-resolution, studio-lit product photograph of a minimalist ceramic coffee mug in matte black, presented on a polished concrete surface. The lighting is a three-point softbox setup designed to create soft, diffused highlights and eliminate harsh shadows. The camera angle is a slightly elevated 45-degree shot to showcase its clean lines. Ultra-realistic, with sharp focus on the steam rising from the coffee. Square image.",
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("product_mockup.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "A high-resolution, studio-lit product photograph of a minimalist ceramic coffee mug in matte black, presented on a polished concrete surface. The lighting is a three-point softbox setup designed to create soft, diffused highlights and eliminate harsh shadows. The camera angle is a slightly elevated 45-degree shot to showcase its clean lines. Ultra-realistic, with sharp focus on the steam rising from the coffee. Square image.",
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("product_mockup.png", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "A high-resolution, studio-lit product photograph of a minimalist ceramic coffee mug in matte black, presented on a polished concrete surface. The lighting is a three-point softbox setup designed to create soft, diffused highlights and eliminate harsh shadows. The camera angle is a slightly elevated 45-degree shot to showcase its clean lines. Ultra-realistic, with sharp focus on the steam rising from the coffee. Square image."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] imgBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("product_mockup.png"), imgBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput("A high-resolution, studio-lit product photograph of a minimalist ceramic coffee mug in matte black, presented on a polished concrete surface. The lighting is a three-point softbox setup designed to create soft, diffused highlights and eliminate harsh shadows. The camera angle is a slightly elevated 45-degree shot to showcase its clean lines. Ultra-realistic, with sharp focus on the steam rising from the coffee. Square image."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    imgBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("product_mockup.png", imgBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "A high-resolution, studio-lit product photograph of a minimalist ceramic coffee mug in matte black, presented on a polished concrete surface. The lighting is a three-point softbox setup designed to create soft, diffused highlights and eliminate harsh shadows. The camera angle is a slightly elevated 45-degree shot to showcase its clean lines. Ultra-realistic, with sharp focus on the steam rising from the coffee. Square image."
  }'
```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/product_mockup.png"
  alt="A high-resolution, studio-lit product photograph of a minimalist
ceramic coffee mug..."
  caption="A high-resolution, studio-lit product photograph of a minimalist
ceramic coffee mug..."
  variant="screenshot"
/%}

#### 5. Minimalist & negative space design {% id="5-minimalist-negative-space-design" %}

Excellent for creating backgrounds for websites, presentations, or marketing
materials where text will be overlaid.

{% tabs %}
{% tab label="Template" %}
```none
A minimalist composition featuring a single [subject] positioned in the
[bottom-right/top-left/etc.] of the frame. The background is a vast, empty
[color] canvas, creating significant negative space. Soft, subtle lighting.
[Aspect ratio].
```
{% /tab %}
{% tab label="Prompt" %}
```none
A minimalist composition featuring a single, delicate red maple leaf
positioned in the bottom-right of the frame. The background is a vast, empty
off-white canvas, creating significant negative space for text. Soft,
diffused lighting from the top left. Square image.
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A minimalist composition featuring a single, delicate red maple leaf positioned in the bottom-right of the frame. The background is a vast, empty off-white canvas, creating significant negative space for text. Soft, diffused lighting from the top left. Square image.",
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("minimalist_design.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "A minimalist composition featuring a single, delicate red maple leaf positioned in the bottom-right of the frame. The background is a vast, empty off-white canvas, creating significant negative space for text. Soft, diffused lighting from the top left. Square image.",
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("minimalist_design.png", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "A minimalist composition featuring a single, delicate red maple leaf positioned in the bottom-right of the frame. The background is a vast, empty off-white canvas, creating significant negative space for text. Soft, diffused lighting from the top left. Square image."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] imgBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("minimalist_design.png"), imgBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput("A minimalist composition featuring a single, delicate red maple leaf positioned in the bottom-right of the frame. The background is a vast, empty off-white canvas, creating significant negative space for text. Soft, diffused lighting from the top left. Square image."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    imgBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("minimalist_design.png", imgBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "A minimalist composition featuring a single, delicate red maple leaf positioned in the bottom-right of the frame. The background is a vast, empty off-white canvas, creating significant negative space for text. Soft, diffused lighting from the top left. Square image."
  }'
```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/minimalist_design.png"
  alt="A minimalist composition featuring a single, delicate red maple leaf..."
  caption="A minimalist composition featuring a single, delicate red maple
leaf..."
  variant="screenshot"
/%}

#### 6. Sequential art (Comic panel / Storyboard) {% id="6-sequential-art-comic-panel-storyboard" %}

Builds on character consistency and scene description to create panels for
visual storytelling. For accuracy with text and storytelling ability, these
prompts work best with Gemini 3 Pro and Gemini 3.1 Flash Image.

{% tabs %}
{% tab label="Template" %}
```none
Make a 3 panel comic in a [style]. Put the character in a [type of scene].
```
{% /tab %}
{% tab label="Prompt" %}
```none
Make a 3 panel comic in a gritty, noir art style with high-contrast black and white inks. Put the character in a humurous scene.
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64

client = genai.Client()

with open('/path/to/your/man_in_white_glasses.jpg', 'rb') as f:
    image_bytes = f.read()
text_input = "Make a 3 panel comic in a gritty, noir art style with high-contrast black and white inks. Put the character in a humurous scene."

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {"type": "text", "text": text_input},
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/jpeg"
        }
    ],
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("comic_panel.jpg", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const imagePath = "/path/to/your/man_in_white_glasses.jpg";
  const imageData = fs.readFileSync(imagePath);
  const base64Image = imageData.toString("base64");

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: [
      { type: "text", text: "Make a 3 panel comic in a gritty, noir art style with high-contrast black and white inks. Put the character in a humurous scene." },
      {
        type: "image",
        mime_type: "image/jpeg",
        data: base64Image
      },
    ],
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("comic_panel.jpg", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("/path/to/your/man_in_white_glasses.jpg"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);
String textInput =
    "Make a 3 panel comic in a gritty, noir art style with high-contrast black and white inks. Put the character in a humurous scene.";

Content textContent = TextContent.builder().text(textInput).build();
Content imageContent =
    ImageContent.builder()
        .data(base64Image)
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] outBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("comic_panel.jpg"), outBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("/path/to/your/man_in_white_glasses.jpg")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)
    textInput := "Make a 3 panel comic in a gritty, noir art style with high-contrast black and white inks. Put the character in a humurous scene."

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: textInput,
        }),
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64Image),
            MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    outBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("comic_panel.jpg", outBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": [
      {"type": "text", "text": "Make a 3 panel comic in a gritty, noir art style with high-contrast black and white inks. Put the character in a humurous scene."},
      {"type": "image", "data": "[BASE64_IMAGE_DATA]", "mime_type": "image/jpeg"}
    ]
  }'
```
{% /tab %}
{% /tabs %}

{% table %}
* Input
* Output
---

* ![Man in white glasses](/googledevai/static/gemini-api/docs/images/man_in_white_glasses.jpg){% class="screenshot" width="50%" %}
    Input image

* ![Make a 3 panel comic in a gritty, noir art style...](/googledevai/static/gemini-api/docs/images/comic_panel.jpg){% class="screenshot" width="50%" %}
    Make a 3 panel comic in a gritty, noir art style...
{% /table %}

#### 7. Grounding with Google Search {% id="grounding-with-search" %}

Use Google Search to generate images based on recent or real-time information.
This is useful for news, weather, and other time-sensitive topics.

{% tabs %}
{% tab label="Prompt" %}
```none
Make a simple but stylish graphic of last night's Arsenal game in the Champion's League
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Make a simple but stylish graphic of last night's Arsenal game in the Champion's League",
    tools=[{"type": "google_search"}],
    response_format={"type": "image", "aspect_ratio": "16:9"},
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("football-score.jpg", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: "Make a simple but stylish graphic of last night's Arsenal game in the Champion's League",
    tools: [{ type: "google_search" }],
    response_format: { type: "image", aspect_ratio: "16:9", image_size: "2K" },
  });

  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("football-score.jpg", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormatAspectRatio;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;

Client client = new Client();

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            ImageResponseFormat.builder()
                .aspectRatio(ImageResponseFormatAspectRatio.of("16:9"))
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "Make a simple but stylish graphic of last night's Arsenal game in the Champion's League"))
        .tools(Arrays.asList(new GoogleSearch()))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] imgBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("football-score.jpg"), imgBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.ImageResponseFormat{
            AspectRatio: interactions.ImageResponseFormatAspectRatio("16:9").ToPointer(),
        }),
    )

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput("Make a simple but stylish graphic of last night's Arsenal game in the Champion's League"),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.GoogleSearch{}),
            },
            ResponseFormat: genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    imgBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("football-score.jpg", imgBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "Make a simple but stylish graphic of last nights Arsenal game in the Champions League",
    "tools": [{"type": "google_search"}],
    "response_format": {
      "type": "image",
      "aspect_ratio": "16:9"
    }
  }'
```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/football-score.jpg"
  alt="AI-generated graphic of an Arsenal football score"
  caption="AI-generated graphic of an Arsenal football score"
  variant="screenshot"
/%}

### Prompts for editing images {% id="image-editing-prompts" %}

These examples show how to provide images alongside your text prompts for
editing, composition, and style transfer.

#### 1. Adding and removing elements {% id="1-adding-and-removing-elements" %}

Provide an image and describe your change. The model will match the original
image's style, lighting, and perspective.

{% tabs %}
{% tab label="Template" %}
```none
Using the provided image of [subject], please [add/remove/modify] [element]
to/from the scene. Ensure the change is [description of how the change should
integrate].
```
{% /tab %}
{% tab label="Prompt" %}
```none
"Using the provided image of my cat, please add a small, knitted wizard hat
on its head. Make it look like it's sitting comfortably and matches the soft
lighting of the photo."
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64

client = genai.Client()

with open('/path/to/your/cat_photo.png', 'rb') as f:
    image_bytes = f.read()
text_input = """Using the provided image of my cat, please add a small, knitted wizard hat on its head. Make it look like it's sitting comfortably and not falling off."""

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {"type": "text", "text": text_input},
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/png"
        }
    ],
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("cat_with_hat.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const imagePath = "/path/to/your/cat_photo.png";
  const imageData = fs.readFileSync(imagePath);
  const base64Image = imageData.toString("base64");

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: [
      { type: "text", text: "Using the provided image of my cat, please add a small, knitted wizard hat on its head. Make it look like it's sitting comfortably and not falling off." },
      {
        type: "image",
        mime_type: "image/png",
        data: base64Image
      },
    ],
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("cat_with_hat.png", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("/path/to/your/cat_photo.png"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);
String textInput =
    "Using the provided image of my cat, please add a small, knitted wizard hat on its head. Make it look like it's sitting comfortably and not falling off.";

Content textContent = TextContent.builder().text(textInput).build();
Content imageContent =
    ImageContent.builder()
        .data(base64Image)
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] outBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("cat_with_hat.png"), outBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("/path/to/your/cat_photo.png")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)
    textInput := "Using the provided image of my cat, please add a small, knitted wizard hat on its head. Make it look like it's sitting comfortably and not falling off."

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: textInput,
        }),
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64Image),
            MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    outBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("cat_with_hat.png", outBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d "{
      \"model\": \"gemini-nano-banana-2.1\",
      \"input\": [
            {\"type\": \"text\", \"text\": \"Using the provided image of my cat, please add a small, knitted wizard hat on its head. Make it look like it's sitting comfortably and not falling off.\"},
            {\"type\": \"image\", \"mime_type\":\"image/png\", \"data\": \"[BASE64_IMAGE_DATA]\"}
        ]
    }"
```
{% /tab %}
{% /tabs %}

{% table %}
* Input
* Output
---

* ![A photorealistic picture of a fluffy ginger cat..](/googledevai/static/gemini-api/docs/images/cat.png){% class="screenshot" width="50%" %}
    A photorealistic picture of a fluffy ginger cat...

* ![Using the provided image of my cat, please add a small, knitted wizard hat...](/googledevai/static/gemini-api/docs/images/cat_with_hat.png){% class="screenshot" width="50%" %}
    Using the provided image of my cat, please add a small, knitted wizard
    hat...
{% /table %}

#### 2. Inpainting (Semantic masking) {% id="2-inpainting-semantic-masking" %}

Conversationally define a "mask" to edit a specific part of an image while
leaving the rest untouched.

{% tabs %}
{% tab label="Template" %}
```none
Using the provided image, change only the [specific element] to [new
element/description]. Keep everything else in the image exactly the same,
preserving the original style, lighting, and composition.
```
{% /tab %}
{% tab label="Prompt" %}
```none
"Using the provided image of a living room, change only the blue sofa to be
a vintage, brown leather chesterfield sofa. Keep the rest of the room,
including the pillows on the sofa and the lighting, unchanged."
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64

client = genai.Client()

with open('/path/to/your/living_room.png', 'rb') as f:
    image_bytes = f.read()
text_input = """Using the provided image of a living room, change only the blue sofa to be a vintage, brown leather chesterfield sofa. Keep the rest of the room, including the pillows on the sofa and the lighting, unchanged."""

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/png"
        },
        {"type": "text", "text": text_input}
    ],
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("living_room_edited.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const imagePath = "/path/to/your/living_room.png";
  const imageData = fs.readFileSync(imagePath);
  const base64Image = imageData.toString("base64");

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: [
      {
        type: "image",
        mime_type: "image/png",
        data: base64Image
      },
      { type: "text", text: "Using the provided image of a living room, change only the blue sofa to be a vintage, brown leather chesterfield sofa. Keep the rest of the room, including the pillows on the sofa and the lighting, unchanged." },
    ],
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("living_room_edited.png", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("/path/to/your/living_room.png"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);
String textInput =
    "Using the provided image of a living room, change only the blue sofa to be a vintage, brown leather chesterfield sofa. Keep the rest of the room, including the pillows on the sofa and the lighting, unchanged.";

Content imageContent =
    ImageContent.builder()
        .data(base64Image)
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();
Content textContent = TextContent.builder().text(textInput).build();

List<Content> contents = Arrays.asList(imageContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] outBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("living_room_edited.png"), outBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("/path/to/your/living_room.png")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)
    textInput := "Using the provided image of a living room, change only the blue sofa to be a vintage, brown leather chesterfield sofa. Keep the rest of the room, including the pillows on the sofa and the lighting, unchanged."

    contents := []interactions.Content{
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64Image),
            MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: textInput,
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    outBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("living_room_edited.png", outBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d "{
      \"model\": \"gemini-nano-banana-2.1\",
      \"input\": [
        {\"type\": \"image\", \"mime_type\":\"image/png\", \"data\": \"[BASE64_IMAGE_DATA]\"},
        {\"type\": \"text\", \"text\": \"Using the provided image of a living room, change only the blue sofa to be a vintage, brown leather chesterfield sofa. Keep the rest of the room, including the pillows on the sofa and the lighting, unchanged.\"}
      ]
    }"
```
{% /tab %}
{% /tabs %}

{% table %}
* Input
* Output
---

* ![A wide shot of a modern, well-lit living room...](/googledevai/static/gemini-api/docs/images/living_room.png){% class="screenshot" width="50%" %}
    A wide shot of a modern, well-lit living room...

* ![Using the provided image of a living room, change only the blue sofa to be a vintage, brown leather chesterfield sofa...](/googledevai/static/gemini-api/docs/images/living_room_edited.png){% class="screenshot" width="50%" %}
    Using the provided image of a living room, change only the blue sofa to be a
    vintage, brown leather chesterfield sofa...
{% /table %}

#### 3. Style transfer {% id="3-style-transfer" %}

Provide an image and ask the model to recreate its content in a different
artistic style.

{% tabs %}
{% tab label="Template" %}
```none
Transform the provided photograph of [subject] into the artistic style of [artist/art style]. Preserve the original composition but render it with [description of stylistic elements].
```
{% /tab %}
{% tab label="Prompt" %}
```none
"Transform the provided photograph of a modern city street at night into the artistic style of Vincent van Gogh's 'Starry Night'. Preserve the original composition of buildings and cars, but render all elements with swirling, impasto brushstrokes and a dramatic palette of deep blues and bright yellows."
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64

client = genai.Client()

with open('/path/to/your/city.png', 'rb') as f:
    image_bytes = f.read()
text_input = """Transform the provided photograph of a modern city street at night into the artistic style of Vincent van Gogh's 'Starry Night'. Preserve the original composition of buildings and cars, but render all elements with swirling, impasto brushstrokes and a dramatic palette of deep blues and bright yellows."""

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/png"
        },
        {"type": "text", "text": text_input}
    ],
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("city_style_transfer.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});
  const imageData = fs.readFileSync("/path/to/your/city.png");
  const base64Image = imageData.toString("base64");

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: [
      {
        type: "image",
        mime_type: "image/png",
        data: base64Image
      },
      { type: "text", text: "Transform the provided photograph of a modern city street at night into the artistic style of Vincent van Gogh's 'Starry Night'. Preserve the original composition of buildings and cars, but render all elements with swirling, impasto brushstrokes and a dramatic palette of deep blues and bright yellows." },
    ],
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("city_style_transfer.png", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("/path/to/your/city.png"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);
String textInput =
    "Transform the provided photograph of a modern city street at night into the artistic style of Vincent van Gogh's 'Starry Night'. Preserve the original composition of buildings and cars, but render all elements with swirling, impasto brushstrokes and a dramatic palette of deep blues and bright yellows.";

Content imageContent =
    ImageContent.builder()
        .data(base64Image)
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();
Content textContent = TextContent.builder().text(textInput).build();

List<Content> contents = Arrays.asList(imageContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] outBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("city_style_transfer.png"), outBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("/path/to/your/city.png")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)
    textInput := "Transform the provided photograph of a modern city street at night into the artistic style of Vincent van Gogh's 'Starry Night'. Preserve the original composition of buildings and cars, but render all elements with swirling, impasto brushstrokes and a dramatic palette of deep blues and bright yellows."

    contents := []interactions.Content{
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64Image),
            MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: textInput,
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    outBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("city_style_transfer.png", outBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d "{
      \"model\": \"gemini-nano-banana-2.1\",
      \"input\": [
        {\"type\": \"image\", \"mime_type\":\"image/png\", \"data\": \"[BASE64_IMAGE_DATA]\"},
        {\"type\": \"text\", \"text\": \"Transform the provided photograph of a modern city street at night into the artistic style of Vincent van Gogh's 'Starry Night'. Preserve the original composition of buildings and cars, but render all elements with swirling, impasto brushstrokes and a dramatic palette of deep blues and bright yellows.\"}
      ]
    }"
```
{% /tab %}
{% /tabs %}

{% table %}
* Input
* Output
---

* ![A photorealistic, high-resolution photograph of a busy city street...](/googledevai/static/gemini-api/docs/images/city.png){% class="screenshot" width="50%" %}
    A photorealistic, high-resolution photograph of a busy city street...

* ![Transform the provided photograph of a modern city street at night...](/googledevai/static/gemini-api/docs/images/city_style_transfer.png){% class="screenshot" width="50%" %}
    Transform the provided photograph of a modern city street at night...
{% /table %}

#### 4. Advanced composition: Combining multiple images {% id="4-advanced-composition-combining-multiple-images" %}

Provide multiple images as context to create a new, composite scene. This is
perfect for product mockups or creative collages.

{% tabs %}
{% tab label="Template" %}
```none
Create a new image by combining the elements from the provided images. Take
the [element from image 1] and place it with/on the [element from image 2].
The final image should be a [description of the final scene].
```
{% /tab %}
{% tab label="Prompt" %}
```none
"Create a professional e-commerce fashion photo. Take the blue floral dress
from the first image and let the woman from the second image wear it.
Generate a realistic, full-body shot of the woman wearing the dress, with
the lighting and shadows adjusted to match the outdoor environment."
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64

client = genai.Client()

with open('/path/to/your/dress.png', 'rb') as f:
    dress_bytes = f.read()
with open('/path/to/your/model.png', 'rb') as f:
    model_bytes = f.read()
text_input = """Create a professional e-commerce fashion photo. Take the blue floral dress from the first image and let the woman from the second image wear it. Generate a realistic, full-body shot of the woman wearing the dress, with the lighting and shadows adjusted to match the outdoor environment."""

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "image",
            "data": base64.b64encode(dress_bytes).decode('utf-8'),
            "mime_type": "image/png"
        },
        {
            "type": "image",
            "data": base64.b64encode(model_bytes).decode('utf-8'),
            "mime_type": "image/png"
        },
        {"type": "text", "text": text_input}
    ],
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("fashion_ecommerce_shot.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const imagePath1 = "/path/to/your/dress.png";
  const imageData1 = fs.readFileSync(imagePath1);
  const base64Image1 = imageData1.toString("base64");
  const imagePath2 = "/path/to/your/model.png";
  const imageData2 = fs.readFileSync(imagePath2);
  const base64Image2 = imageData2.toString("base64");

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: [
      {
        type: "image",
        mime_type: "image/png",
        data: base64Image1
      },
      {
        type: "image",
        mime_type: "image/png",
        data: base64Image2
      },
      { type: "text", text: "Create a professional e-commerce fashion photo. Take the blue floral dress from the first image and let the woman from the second image wear it. Generate a realistic, full-body shot of the woman wearing the dress, with the lighting and shadows adjusted to match the outdoor environment." },
    ],
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("fashion_ecommerce_shot.png", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] dressBytes = Files.readAllBytes(Paths.get("/path/to/your/dress.png"));
byte[] modelBytes = Files.readAllBytes(Paths.get("/path/to/your/model.png"));
String textInput =
    "Create a professional e-commerce fashion photo. Take the blue floral dress from the first image and let the woman from the second image wear it. Generate a realistic, full-body shot of the woman wearing the dress, with the lighting and shadows adjusted to match the outdoor environment.";

Content dressContent =
    ImageContent.builder()
        .data(Base64.getEncoder().encodeToString(dressBytes))
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();
Content modelContent =
    ImageContent.builder()
        .data(Base64.getEncoder().encodeToString(modelBytes))
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();
Content textContent = TextContent.builder().text(textInput).build();

List<Content> contents = Arrays.asList(dressContent, modelContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] outBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("fashion_ecommerce_shot.png"), outBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    dressBytes, err := os.ReadFile("/path/to/your/dress.png")
    if err != nil {
        log.Fatal(err)
    }
    modelBytes, err := os.ReadFile("/path/to/your/model.png")
    if err != nil {
        log.Fatal(err)
    }
    textInput := "Create a professional e-commerce fashion photo. Take the blue floral dress from the first image and let the woman from the second image wear it. Generate a realistic, full-body shot of the woman wearing the dress, with the lighting and shadows adjusted to match the outdoor environment."

    contents := []interactions.Content{
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64.StdEncoding.EncodeToString(dressBytes)),
            MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64.StdEncoding.EncodeToString(modelBytes)),
            MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: textInput,
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    outBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("fashion_ecommerce_shot.png", outBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d "{
      \"model\": \"gemini-nano-banana-2.1\",
      \"input\": [
            {\"type\": \"image\", \"mime_type\":\"image/png\", \"data\": \"[BASE64_IMAGE_DATA_1]\"},
            {\"type\": \"image\", \"mime_type\":\"image/png\", \"data\": \"[BASE64_IMAGE_DATA_2]\"},
            {\"type\": \"text\", \"text\": \"Create a professional e-commerce fashion photo. Take the blue floral dress from the first image and let the woman from the second image wear it. Generate a realistic, full-body shot of the woman wearing the dress, with the lighting and shadows adjusted to match the outdoor environment.\"}
      }]
    }"
```
{% /tab %}
{% /tabs %}

{% table %}
* Input 1
* Input 2
* Output
---

* ![A blue floral summer dress on a neutral background](/googledevai/static/gemini-api/docs/images/dress.png){% class="screenshot" width="50%" %}
    A blue floral summer dress on a neutral background

* ![Full-body shot of a woman with her hair in a bun...](/googledevai/static/gemini-api/docs/images/model.png){% class="screenshot" width="50%" %}
    Full-body shot of a woman with her hair in a bun...

* ![A woman wearing a blue floral summer dress in an outdoor setting](/googledevai/static/gemini-api/docs/images/fashion_ecommerce_shot.png){% class="screenshot" width="50%" %}
    A woman wearing a blue floral summer dress in an outdoor setting
{% /table %}

#### 5. High-fidelity detail preservation {% id="5-high-fidelity-detail-preservation" %}

To ensure critical details (like a face or logo) are preserved during an edit,
describe them in great detail along with your edit request.

{% tabs %}
{% tab label="Template" %}
```none
Using the provided images, place [element from image 2] onto [element from
image 1]. Ensure that the features of [element from image 1] remain
completely unchanged. The added element should [description of how the
element should integrate].
```
{% /tab %}
{% tab label="Prompt" %}
```none
"Take the first image of the woman with brown hair, blue eyes, and a neutral
expression. Add the logo from the second image onto her black t-shirt.
Ensure the woman's face and features remain completely unchanged. The logo
should look like it's naturally printed on the fabric, following the folds
of the shirt."
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64

client = genai.Client()

with open('/path/to/your/woman.png', 'rb') as f:
    woman_bytes = f.read()
with open('/path/to/your/logo.png', 'rb') as f:
    logo_bytes = f.read()
text_input = """Take the first image of the woman with brown hair, blue eyes, and a neutral expression. Add the logo from the second image onto her black t-shirt. Ensure the woman's face and features remain completely unchanged. The logo should look like it's naturally printed on the fabric, following the folds of the shirt."""

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
      {"type": "image", "mime_type":"image/png", "data": base64.b64encode(woman_bytes).decode('utf-8')},
      {"type": "image", "mime_type":"image/png", "data": base64.b64encode(logo_bytes).decode('utf-8')},
      {"type": "text", "text": text_input}
    ],
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("woman_with_logo.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const imagePath1 = "/path/to/your/woman.png";
  const imageData1 = fs.readFileSync(imagePath1);
  const base64Image1 = imageData1.toString("base64");
  const imagePath2 = "/path/to/your/logo.png";
  const imageData2 = fs.readFileSync(imagePath2);
  const base64Image2 = imageData2.toString("base64");

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: [
      {"type": "image", "mime_type":"image/png", "data": base64Image1},
      {"type": "image", "mime_type":"image/png", "data": base64Image2},
      {"type": "text", "text": "Take the first image of the woman with brown hair, blue eyes, and a neutral expression. Add the logo from the second image onto her black t-shirt. Ensure the woman's face and features remain completely unchanged. The logo should look like it's naturally printed on the fabric, following the folds of the shirt."},
    ],
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("woman_with_logo.png", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] womanBytes = Files.readAllBytes(Paths.get("/path/to/your/woman.png"));
byte[] logoBytes = Files.readAllBytes(Paths.get("/path/to/your/logo.png"));
String textInput =
    "Take the first image of the woman with brown hair, blue eyes, and a neutral expression. Add the logo from the second image onto her black t-shirt. Ensure the woman's face and features remain completely unchanged. The logo should look like it's naturally printed on the fabric, following the folds of the shirt.";

Content womanContent =
    ImageContent.builder()
        .data(Base64.getEncoder().encodeToString(womanBytes))
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();
Content logoContent =
    ImageContent.builder()
        .data(Base64.getEncoder().encodeToString(logoBytes))
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();
Content textContent = TextContent.builder().text(textInput).build();

List<Content> contents = Arrays.asList(womanContent, logoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] outBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("woman_with_logo.png"), outBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    womanBytes, err := os.ReadFile("/path/to/your/woman.png")
    if err != nil {
        log.Fatal(err)
    }
    logoBytes, err := os.ReadFile("/path/to/your/logo.png")
    if err != nil {
        log.Fatal(err)
    }
    textInput := "Take the first image of the woman with brown hair, blue eyes, and a neutral expression. Add the logo from the second image onto her black t-shirt. Ensure the woman's face and features remain completely unchanged. The logo should look like it's naturally printed on the fabric, following the folds of the shirt."

    contents := []interactions.Content{
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64.StdEncoding.EncodeToString(womanBytes)),
            MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64.StdEncoding.EncodeToString(logoBytes)),
            MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: textInput,
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    outBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("woman_with_logo.png", outBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d "{
      \"model\": \"gemini-nano-banana-2.1\",
      \"input\": [
        {\"type\": \"image\", \"mime_type\":\"image/png\", \"data\": \"[BASE64_IMAGE_DATA_1]\"},
        {\"type\": \"image\", \"mime_type\":\"image/png\", \"data\": \"[BASE64_IMAGE_DATA_2]\"},
        {\"type\": \"text\", \"text\": \"Take the first image of the woman with brown hair, blue eyes, and a neutral expression. Add the logo from the second image onto her black t-shirt. Ensure the woman's face and features remain completely unchanged. The logo should look like it's naturally printed on the fabric, following the folds of the shirt.\"}
      ]
    }"
```
{% /tab %}
{% /tabs %}

{% table %}
* Input 1
* Input 2
* Output
---

* ![A professional headshot of a woman with brown hair and blue eyes...](/googledevai/static/gemini-api/docs/images/woman.png){% class="screenshot" width="50%" %}
    A professional headshot of a woman with brown hair and blue eyes...

* ![Modern brand identifier with letters G and A](/googledevai/static/gemini-api/docs/images/logo.png){% class="screenshot" width="50%" %}
    Modern brand identifier with letters G and A

* ![Take the first image of the woman with brown hair, blue eyes, and a neutral expression...](/googledevai/static/gemini-api/docs/images/woman_with_logo.png){% class="screenshot" width="50%" %}
    Take the first image of the woman with brown hair, blue eyes, and a neutral
    expression...
{% /table %}

#### 6. Bring something to life {% id="6-bring-something-to-life" %}

Upload a rough sketch or drawing and ask the model to refine it into a
finished image.

{% tabs %}
{% tab label="Template" %}
```none
Turn this rough [medium] sketch of a [subject] into a [style description]
photo. Keep the [specific features] from the sketch but add [new details/materials].
```
{% /tab %}
{% tab label="Prompt" %}
```none
"Turn this rough pencil sketch of a futuristic car into a polished photo of the finished concept car in a showroom. Keep the sleek lines and low profile from the sketch but add metallic blue paint and neon rim lighting."
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64

client = genai.Client()

with open('/path/to/your/car_sketch.png', 'rb') as f:
    sketch_bytes = f.read()
text_input = """Turn this rough pencil sketch of a futuristic car into a polished photo of the finished concept car in a showroom. Keep the sleek lines and low profile from the sketch but add metallic blue paint and neon rim lighting."""

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
      {"type": "image", "mime_type":"image/png", "data": base64.b64encode(sketch_bytes).decode('utf-8')},
      {"type": "text", "text": text_input}
    ],
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("car_photo.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
  const ai = new GoogleGenAI({});

  const imagePath = "/path/to/your/car_sketch.png";
  const imageData = fs.readFileSync(imagePath);
  const base64Image = imageData.toString("base64");

  const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: [
      {"type": "image", "mime_type":"image/png", "data": base64Image},
      {"type": "text", "text": "Turn this rough pencil sketch of a futuristic car into a polished photo of the finished concept car in a showroom. Keep the sleek lines and low profile from the sketch but add metallic blue paint and neon rim lighting."},
    ],
  });
  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log(contentBlock.text);
        } else if (contentBlock.type === "image") {
          if (contentBlock.data) {
          const buffer = Buffer.from(contentBlock.data, "base64");
          fs.writeFileSync("car_photo.png", buffer);
        }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] sketchBytes = Files.readAllBytes(Paths.get("/path/to/your/car_sketch.png"));
String textInput =
    "Turn this rough pencil sketch of a futuristic car into a polished photo of the finished concept car in a showroom. Keep the sleek lines and low profile from the sketch but add metallic blue paint and neon rim lighting.";

Content sketchContent =
    ImageContent.builder()
        .data(Base64.getEncoder().encodeToString(sketchBytes))
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();
Content textContent = TextContent.builder().text(textInput).build();

List<Content> contents = Arrays.asList(sketchContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] outBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("car_photo.png"), outBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    sketchBytes, err := os.ReadFile("/path/to/your/car_sketch.png")
    if err != nil {
        log.Fatal(err)
    }
    textInput := "Turn this rough pencil sketch of a futuristic car into a polished photo of the finished concept car in a showroom. Keep the sleek lines and low profile from the sketch but add metallic blue paint and neon rim lighting."

    contents := []interactions.Content{
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64.StdEncoding.EncodeToString(sketchBytes)),
            MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: textInput,
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-nano-banana-2.1"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                } else if contentBlock.ImageContent != nil && contentBlock.ImageContent.Data != nil {
                    outBytes, err := base64.StdEncoding.DecodeString(*contentBlock.ImageContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    if err := os.WriteFile("car_photo.png", outBytes, 0644); err != nil {
                        log.Fatal(err)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d "{
      \"model\": \"gemini-nano-banana-2.1\",
      \"input\": [
        {\"type\": \"image\", \"mime_type\":\"image/png\", \"data\": \"[BASE64_IMAGE_DATA]\"},
        {\"type\": \"text\", \"text\": \"Turn this rough pencil sketch of a futuristic car into a polished photo of the finished concept car in a showroom. Keep the sleek lines and low profile from the sketch but add metallic blue paint and neon rim lighting.\"}
      ]
    }"
```
{% /tab %}
{% /tabs %}

{% table %}
* Input
* Output
---

* ![Sketch of a car](/googledevai/static/gemini-api/docs/images/car-sketch.jpg){% class="screenshot" width="50%" %}
    Rough sketch of a car

* ![Output showing the final concept car](/googledevai/static/gemini-api/docs/images/car-photo.jpg){% class="screenshot" width="50%" %}
    Polished photo of a car
{% /table %}

#### 7. Character consistency: 360 view {% id="7-character-consistency-360-view" %}

You can generate 360-degree views of a character by iteratively prompting for
different angles. For best results, include previously generated images in
subsequent prompts to maintain consistency. For complex poses, include a
reference image of the selected pose.

{% tabs %}
{% tab label="Template" %}
```none
A studio portrait of [person] against [background], [looking forward/in profile looking right/etc.]
```
{% /tab %}
{% tab label="Prompt" %}
```none
A studio portrait of this man against white, in profile looking right
```
{% /tab %}
{% tab label="Python" %}
```python
from google import genai
from PIL import Image
import base64

client = genai.Client()

with open('/path/to/your/man_in_white_glasses.jpg', 'rb') as f:
    image_bytes = f.read()
text_input = """A studio portrait of this man against white, in profile looking right"""

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input={
      {"type": "text", "text": text_input},
      {"type": "image", "mime_type":"image/png", "data": base64.b64encode(image_bytes).decode('utf-8')}
    },
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                with open("man_right_profile.png", "wb") as f:
                    f.write(base64.b64decode(content_block.data))
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("/path/to/your/man_in_white_glasses.jpg"));
String textInput = "A studio portrait of this man against white, in profile looking right";

Content textContent = TextContent.builder().text(textInput).build();
Content imageContent =
    ImageContent.builder()
        .data(Base64.getEncoder().encodeToString(imageBytes))
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            System.out.println(((TextContent) contentBlock).text().orElse(""));
          } else if (contentBlock instanceof ImageContent) {
            ImageContent img = (ImageContent) contentBlock;
            if (img.data().isPresent()) {
              byte[] outBytes = Base64.getDecoder().decode(img.data().get());
              Files.write(Paths.get("man_right_profile.png"), outBytes);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}

{% /tabs %}

{% table %}
* Input
* Output 1
* Output 2
---

* ![Original input of a man in white glasses](/googledevai/static/gemini-api/docs/images/man_in_white_glasses.jpg){% class="screenshot" width="50%" %}
    Original image

* ![Output of a man in white glasses looking right](/googledevai/static/gemini-api/docs/images/man_in_white_glasses_looking_right.jpg){% class="screenshot" width="50%" %}
    Man in white glasses looking right

* ![Output of a man in white glasses looking forward](/googledevai/static/gemini-api/docs/images/man_in_white_glasses_looking_forward.jpg){% class="screenshot" width="50%" %}
    Man in white glasses looking forward
{% /table %}

### Best Practices {% id="best-practices" %}

To elevate your results from good to great, incorporate these professional
strategies into your workflow.

* **Be Hyper-Specific:** The more detail you provide, the more control you
have. Instead of "fantasy armor," describe it: "ornate elven plate armor, etched
with silver leaf patterns, with a high collar and pauldrons shaped like falcon
wings."

* **Provide Context and Intent:** Explain the *purpose* of the image. The
model's understanding of context will influence the final output. For example,
"Create a logo for a high-end, minimalist skincare brand" will yield better
results than just "Create a logo."

* **Iterate and Refine:** Don't expect a perfect image on the first try. Use
the conversational nature of the model to make small changes. Follow up with
prompts like, "That's great, but can you make the lighting a bit warmer?" or
"Keep everything the same, but change the character's expression to be more
serious."

* **Use Step-by-Step Instructions:** For complex scenes with many elements,
break your prompt into steps. "First, create a background of a serene, misty
forest at dawn. Then, in the foreground, add a moss-covered ancient stone altar.
Finally, place a single, glowing sword on top of the altar."

* **Use "Semantic Negative Prompts":** Instead of saying "no cars," describe
    the intended scene positively: "an empty, deserted street with no signs of
    traffic."

* **Control the Camera:** Use photographic and cinematic language to control
the composition. Terms like `wide-angle shot`, `macro shot`, `low-angle
perspective`.

## Limitations {% id="limitations" %}

* For best performance, use the following languages: EN, ar-EG, de-DE, es-MX,
    fr-FR, hi-IN, id-ID, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, ua-UA, vi-VN, zh-CN.

* Image generation does not support audio inputs. Video inputs are only supported for Gemini Nano Banana 2.1, Gemini 3.1 Flash Image, and Gemini 3.1 Flash Lite Image.
* The model won't always follow the exact number of image outputs that the
    user explicitly asks for.

* `gemini-2.5-flash-image` works best with up to 3 images as input, while
    `gemini-3-pro-image` supports 5 images with high fidelity, and up to
    14 images in total. `gemini-nano-banana-2.1` and `gemini-3.1-flash-image` support character
    resemblance of up to 4 characters and the fidelity of up to 10 objects in a
    single workflow.

* When generating text for an image, Gemini works best if you first generate
    the text and then ask for an image with the text.

* `gemini-nano-banana-2.1` and `gemini-3.1-flash-image` Grounding with Google Search do not support using real-world images of people from web search at this time.
* All generated images include a [SynthID watermark](https://ai.google.dev/responsible/docs/safeguards/synthid).

## Optional configurations {% id="optional-configurations" %}

You can optionally configure the output format, aspect ratio, and image size
using the `response_format` parameter.

### Output format {% id="output-format" %}

The model defaults to returning both text and image responses. You can configure
the response to return only the generated images (omitting the conversational
text) by specifying an image format in the `response_format` parameter.

To request multiple modalities (for example, both text and the generated image),
pass an array of format entries to `response_format` instead.

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Write a short poem about a starry night and generate an image of it.",
    response_format=[
        {"type": "text"},
        {"type": "image"},
    ],
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await ai.interactions.create({
  model: "gemini-nano-banana-2.1",
  input: "Write a short poem about a starry night and generate an image of it.",
  response_format: [
    { type: "text" },
    { type: "image" },
  ],
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        Arrays.asList(
            ResponseFormat.of(TextResponseFormat.builder().build()),
            ResponseFormat.of(ImageResponseFormat.builder().build())));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(
            InteractionsInput.of(
                "Write a short poem about a starry night and generate an image of it."))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    format := interactions.NewCreateModelInteractionResponseFormat([]interactions.ResponseFormat{
        interactions.NewResponseFormat(interactions.TextResponseFormat{}),
        interactions.NewResponseFormat(interactions.ImageResponseFormat{}),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:          interactions.Model("gemini-nano-banana-2.1"),
            Input:          interactions.NewInteractionsInput("Write a short poem about a starry night and generate an image of it."),
            ResponseFormat: genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "Write a short poem about a starry night and generate an image of it.",
    "response_format": [
      { "type": "text" },
      { "type": "image" }
    ]
  }'
```
{% /tab %}
{% /tabs %}

### Aspect ratios and image size {% id="aspect-ratios-and-image-size" %}

By default, the model matches the output image size to that of your input image,
or otherwise generates 1:1 squares. You can control the aspect ratio and the
size of the output image using the `aspect_ratio` and `image_size` fields under
`response_format` when `type` is set to `"image"`.

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=prompt,
    response_format={
        "type": "image",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await ai.interactions.create({
    model: "gemini-nano-banana-2.1",
    input: prompt,
    response_format: {
      type: "image",
      aspect_ratio: "16:9",
      image_size: "2K",
    },
  });
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.ImageResponseFormatAspectRatio;
import com.google.genai.gaos.models.interactions.ImageResponseFormatImageSize;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();
String prompt = "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme";

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            ImageResponseFormat.builder()
                .aspectRatio(ImageResponseFormatAspectRatio.of("16:9"))
                .imageSize(ImageResponseFormatImageSize.TWO_K)
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-nano-banana-2.1"))
        .input(InteractionsInput.of(prompt))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.ImageResponseFormat{
            AspectRatio: interactions.ImageResponseFormatAspectRatio("16:9").ToPointer(),
            ImageSize:   interactions.ImageResponseFormatImageSizeTwoK.ToPointer(),
        }),
    )

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:          interactions.Model("gemini-nano-banana-2.1"),
            Input:          interactions.NewInteractionsInput(prompt),
            ResponseFormat: genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
    "response_format": {
      "type": "image",
      "aspect_ratio": "16:9",
      "image_size": "2K"
    }
  }'
```
{% /tab %}
{% /tabs %}

The different ratios available and the size of the image generated are listed in
the following tables:

{% tabs %}
{% tab label="Nano Banana 2.1" %}
| Aspect ratio | 1K resolution | 1K tokens | 2K resolution | 2K tokens | 4K resolution | 4K tokens |
  | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
  | **1:1** | 1024x1024 | 1120 | 2048x2048 | 1680 | 4096x4096 | 2520 |
  | **1:4** | 512x2048 | 1120 | 1024x4096 | 1680 | 2048x8192 | 2520 |
  | **1:8** | 384x3072 | 1120 | 768x6144 | 1680 | 1536x12288 | 2520 |
  | **2:3** | 848x1264 | 1120 | 1696x2528 | 1680 | 3392x5056 | 2520 |
  | **3:2** | 1264x848 | 1120 | 2528x1696 | 1680 | 5056x3392 | 2520 |
  | **3:4** | 896x1200 | 1120 | 1792x2400 | 1680 | 3584x4800 | 2520 |
  | **4:1** | 2048x512 | 1120 | 4096x1024 | 1680 | 8192x2048 | 2520 |
  | **4:3** | 1200x896 | 1120 | 2400x1792 | 1680 | 4800x3584 | 2520 |
  | **4:5** | 928x1152 | 1120 | 1856x2304 | 1680 | 3712x4608 | 2520 |
  | **5:4** | 1152x928 | 1120 | 2304x1856 | 1680 | 4608x3712 | 2520 |
  | **8:1** | 3072x384 | 1120 | 6144x768 | 1680 | 12288x1536 | 2520 |
  | **9:16** | 768x1376 | 1120 | 1536x2752 | 1680 | 3072x5504 | 2520 |
  | **16:9** | 1376x768 | 1120 | 2752x1536 | 1680 | 5504x3072 | 2520 |
  | **21:9** | 1584x672 | 1120 | 3168x1344 | 1680 | 6336x2688 | 2520 |
{% /tab %}
{% tab label="3.1 Flash Image" %}
| Aspect ratio | 512px resolution | 0.5K tokens | 1K resolution | 1K tokens | 2K resolution | 2K tokens | 4K resolution | 4K tokens |
  | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
  | **1:1** | 512x512 | 747 | 1024x1024 | 1120 | 2048x2048 | 1680 | 4096x4096 | 2520 |
  | **1:4** | 256x1024 | 747 | 512x2048 | 1120 | 1024x4096 | 1680 | 2048x8192 | 2520 |
  | **1:8** | 192x1536 | 747 | 384x3072 | 1120 | 768x6144 | 1680 | 1536x12288 | 2520 |
  | **2:3** | 424x632 | 747 | 848x1264 | 1120 | 1696x2528 | 1680 | 3392x5056 | 2520 |
  | **3:2** | 632x424 | 747 | 1264x848 | 1120 | 2528x1696 | 1680 | 5056x3392 | 2520 |
  | **3:4** | 448x600 | 747 | 896x1200 | 1120 | 1792x2400 | 1680 | 3584x4800 | 2520 |
  | **4:1** | 1024x256 | 747 | 2048x512 | 1120 | 4096x1024 | 1680 | 8192x2048 | 2520 |
  | **4:3** | 600x448 | 747 | 1200x896 | 1120 | 2400x1792 | 1680 | 4800x3584 | 2520 |
  | **4:5** | 464x576 | 747 | 928x1152 | 1120 | 1856x2304 | 1680 | 3712x4608 | 2520 |
  | **5:4** | 576x464 | 747 | 1152x928 | 1120 | 2304x1856 | 1680 | 4608x3712 | 2520 |
  | **8:1** | 1536x192 | 747 | 3072x384 | 1120 | 6144x768 | 1680 | 12288x1536 | 2520 |
  | **9:16** | 384x688 | 747 | 768x1376 | 1120 | 1536x2752 | 1680 | 3072x5504 | 2520 |
  | **16:9** | 688x384 | 747 | 1376x768 | 1120 | 2752x1536 | 1680 | 5504x3072 | 2520 |
  | **21:9** | 792x168 | 747 | 1584x672 | 1120 | 3168x1344 | 1680 | 6336x2688 | 2520 |
{% /tab %}
{% tab label="3 Pro Image" %}
| Aspect ratio | 1K resolution | 1K tokens | 2K resolution | 2K tokens | 4K resolution | 4K tokens |
  | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
  | **1:1** | 1024x1024 | 1120 | 2048x2048 | 1120 | 4096x4096 | 2000 |
  | **2:3** | 848x1264 | 1120 | 1696x2528 | 1120 | 3392x5056 | 2000 |
  | **3:2** | 1264x848 | 1120 | 2528x1696 | 1120 | 5056x3392 | 2000 |
  | **3:4** | 896x1200 | 1120 | 1792x2400 | 1120 | 3584x4800 | 2000 |
  | **4:3** | 1200x896 | 1120 | 2400x1792 | 1120 | 4800x3584 | 2000 |
  | **4:5** | 928x1152 | 1120 | 1856x2304 | 1120 | 3712x4608 | 2000 |
  | **5:4** | 1152x928 | 1120 | 2304x1856 | 1120 | 4608x3712 | 2000 |
  | **9:16** | 768x1376 | 1120 | 1536x2752 | 1120 | 3072x5504 | 2000 |
  | **16:9** | 1376x768 | 1120 | 2752x1536 | 1120 | 5504x3072 | 2000 |
  | **21:9** | 1584x672 | 1120 | 3168x1344 | 1120 | 6336x2688 | 2000 |
{% /tab %}
{% tab label="Gemini 2.5 Flash Image" %}
| Aspect ratio | Resolution | Tokens |
  | --- | --- | --- |
  | 1:1 | 1024x1024 | 1290 |
  | 2:3 | 832x1248 | 1290 |
  | 3:2 | 1248x832 | 1290 |
  | 3:4 | 864x1184 | 1290 |
  | 4:3 | 1184x864 | 1290 |
  | 4:5 | 896x1152 | 1290 |
  | 5:4 | 1152x896 | 1290 |
  | 9:16 | 768x1344 | 1290 |
  | 16:9 | 1344x768 | 1290 |
  | 21:9 | 1536x672 | 1290 |
{% /tab %}

{% /tabs %}

## When to use Imagen {% id="choose-a-model" %}

{% callout type="warning" %}
  Imagen models are shut down. Use Nano Banana models for all image generation tasks.
{% /callout %}

Imagen is shut down and no longer available through the Gemini API. Use Nano Banana for image generation and editing.

## What's next {% id="what-is-next" %}

* Check out the [Veo guide](/docs/video) to learn how to generate
  videos with the Gemini API.

* To learn more about Gemini models, see [Gemini models](/docs/models).

# Generate videos with Veo 3.1 in Gemini API
Source: https://aistudio.google.com/docs/veo
Description: Generate high-fidelity videos with native audio using Google's Veo 3.1 API.

{% callout type="warning" %} Veo 3.1 Preview (`veo-3.1-generate-preview`,
`veo-3.1-fast-generate-preview`, and `veo-3.1-lite-generate-preview`) in the
Gemini API was [shut down](/docs/deprecations) on **October 22, 2026**. Migrate
to [Gemini Omni Flash](/docs/models/gemini-omni-flash) (`gemini-omni-1.1-flash`)
or the GA models available through the
[Gemini Enterprise Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate)
to avoid service interruptions. {% /callout %}

> To learn about video understanding, see the [Video understanding](/docs/video-understanding) guide.

[Veo 3.1](https://deepmind.google/models/veo/) is a model for generating 8-second videos (720p, 1080p, or 4k) with natively generated audio. You can access
this model programmatically using the Gemini API. To learn more about the
available Veo model variants, see the [Model Versions](/docs/veo#model-versions) section.

Veo 3.1 excels at a wide range of visual and cinematic styles and introduces
several new capabilities:

* **Portrait videos**: Choose between landscape (`16:9`) and portrait (`9:16`)
    videos.
* **Video extension**: Extend videos that were previously
    generated using Veo.
* **Frame-specific generation**: Generate a video by
    specifying the first and last frames.
* **Image-based direction**: Use up to three reference images to guide
    the content of your generated video.

For more information about writing effective text prompts for video generation,
see the [Veo prompt guide](/docs/veo#prompt-guide)

## Text to video generation {% id="generate-from-text" %}

The following examples show how you can generate a video with [dialogue](/docs/veo#dialogue), [cinematic realism](/docs/veo#realism), or [creative animation](/docs/veo#style):

### Dialogue & sound effects {% id="dialogue" %}

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai
from google.genai import types

client = genai.Client()

prompt = """A close up of two people staring at a cryptic drawing on a wall, torchlight flickering.
A man murmurs, 'This must be it. That's the secret code.' The woman looks at him and whispering excitedly, 'What did you find?'"""

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt=prompt,
)

# Poll the operation status until the video is ready.
while not operation.done:
    print("Waiting for video generation to complete...")
    time.sleep(10)
    operation = client.operations.get(operation)

# Download the generated video.
generated_video = operation.response.generated_videos[0]
client.files.download(file=generated_video.video, destination="dialogue_example.mp4")
print("Generated video saved to dialogue_example.mp4")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const ai = new GoogleGenAI({});

const prompt = `A close up of two people staring at a cryptic drawing on a wall, torchlight flickering.
A man murmurs, 'This must be it. That's the secret code.' The woman looks at him and whispering excitedly, 'What did you find?'`;

let operation = await ai.models.generateVideos({
    model: "veo-3.1-generate-preview",
    prompt: prompt,
});

// Poll the operation status until the video is ready.
while (!operation.done) {
    console.log("Waiting for video generation to complete...")
    await new Promise((resolve) => setTimeout(resolve, 10000));
    operation = await ai.operations.getVideosOperation({
        operation: operation,
    });
}

// Download the generated video.
const video = operation.response?.generatedVideos?.[0]?.video;
if (video) {
    await ai.files.download({
        file: video,
        downloadPath: "dialogue_example.mp4",
    });
    console.log(`Generated video saved to dialogue_example.mp4`);
}
```

{% /tab %}
{% tab label="Go" filename="sample.go" %}

```go
package main

import (
    "context"
    "log"
    "os"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := `A close up of two people staring at a cryptic drawing on a wall, torchlight flickering.
    A man murmurs, 'This must be it. That's the secret code.' The woman looks at him and whispering excitedly, 'What did you find?'`

    operation, _ := client.Models.GenerateVideos(
        ctx,
        "veo-3.1-generate-preview",
        prompt,
        nil,
        nil,
    )

    // Poll the operation status until the video is ready.
    for !operation.Done {
    log.Println("Waiting for video generation to complete...")
        time.Sleep(10 * time.Second)
        operation, _ = client.Operations.GetVideosOperation(ctx, operation, nil)
    }

    // Download the generated video.
    video := operation.Response.GeneratedVideos[0]
    client.Files.Download(ctx, video.Video, nil)
    fname := "dialogue_example.mp4"
    _ = os.WriteFile(fname, video.Video.VideoBytes, 0644)
    log.Printf("Generated video saved to %s\n", fname)
}
```

{% /tab %}
{% tab label="Java" filename="sample.java" %}

```java
import com.google.genai.Client;
import com.google.genai.types.GenerateVideosOperation;
import com.google.genai.types.GeneratedVideo;

Client client = new Client();

String prompt =
    "A close up of two people staring at a cryptic drawing on a wall, torchlight flickering.\n"
        + "A man murmurs, 'This must be it. That's the secret code.' The woman looks at him and whispering excitedly, 'What did you find?'";

GenerateVideosOperation operation =
    client.models.generateVideos("veo-3.1-generate-preview", prompt, null, null);

// Poll the operation status until the video is ready.
while (!operation.done().orElse(false)) {
  System.out.println("Waiting for video generation to complete...");
  Thread.sleep(10000);
  operation = client.operations.getVideosOperation(operation, null);
}

// Download the generated video.
GeneratedVideo generatedVideo = operation.response().get().generatedVideos().get().get(0);
client.files.download(generatedVideo, "dialogue_example.mp4", null);
System.out.println("Generated video saved to dialogue_example.mp4");
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Note: This script uses jq to parse the JSON response.
# GEMINI API Base URL
BASE_URL="https://generativelanguage.googleapis.com/v1beta"

# Send request to generate video and capture the operation name into a variable.
operation_name=$(curl -s "${BASE_URL}/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "instances": [{
        "prompt": "A close up of two people staring at a cryptic drawing on a wall, torchlight flickering. A man murmurs, \"This must be it. That'\''s the secret code.\" The woman looks at him and whispering excitedly, \"What did you find?\""
      }
    ]
  }' | jq -r .name)

# Poll the operation status until the video is ready
while true; do
  # Get the full JSON status and store it in a variable.
  status_response=$(curl -s -H "x-goog-api-key: $GEMINI_API_KEY" "${BASE_URL}/${operation_name}")

  # Check the "done" field from the JSON stored in the variable.
  is_done=$(echo "${status_response}" | jq .done)

  if [ "${is_done}" = "true" ]; then
    # Extract the download URI from the final response.
    video_uri=$(echo "${status_response}" | jq -r '.response.generateVideoResponse.generatedSamples[0].video.uri')
    echo "Downloading video from: ${video_uri}"

    # Download the video using the URI and API key and follow redirects.
    curl -L -o dialogue_example.mp4 -H "x-goog-api-key: $GEMINI_API_KEY" "${video_uri}"
    break
  fi
  # Wait for 5 seconds before checking again.
  sleep 10
done
```

<devsite-video video-id="rYj2zM5s95s" title="Dialogue & Sound Effects"></devsite-video>

{% /tab %}
{% /tabs %}
### Cinematic realism {% id="realism" %}

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai
from google.genai import types

client = genai.Client()

prompt = """Drone shot following a classic red convertible driven by a man along a winding coastal road at sunset, waves crashing against the rocks below.
The convertible accelerates fast and the engine roars loudly."""

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt=prompt,
)

# Poll the operation status until the video is ready.
while not operation.done:
    print("Waiting for video generation to complete...")
    time.sleep(10)
    operation = client.operations.get(operation)

# Download the generated video.
generated_video = operation.response.generated_videos[0]
client.files.download(file=generated_video.video, destination="realism_example.mp4")
print("Generated video saved to realism_example.mp4")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const ai = new GoogleGenAI({});

const prompt = `Drone shot following a classic red convertible driven by a man along a winding coastal road at sunset, waves crashing against the rocks below.
The convertible accelerates fast and the engine roars loudly.`;

let operation = await ai.models.generateVideos({
    model: "veo-3.1-generate-preview",
    prompt: prompt,
});

// Poll the operation status until the video is ready.
while (!operation.done) {
    console.log("Waiting for video generation to complete...")
    await new Promise((resolve) => setTimeout(resolve, 10000));
    operation = await ai.operations.getVideosOperation({
        operation: operation,
    });
}

// Download the generated video.
const video = operation.response?.generatedVideos?.[0]?.video;
if (video) {
    await ai.files.download({
        file: video,
        downloadPath: "realism_example.mp4",
    });
    console.log(`Generated video saved to realism_example.mp4`);
}
```

{% /tab %}
{% tab label="Go" filename="sample.go" %}

```go
package main

import (
    "context"
    "log"
    "os"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := `Drone shot following a classic red convertible driven by a man along a winding coastal road at sunset, waves crashing against the rocks below.
  The convertible accelerates fast and the engine roars loudly.`

    operation, _ := client.Models.GenerateVideos(
        ctx,
        "veo-3.1-generate-preview",
        prompt,
        nil,
        nil,
    )

    // Poll the operation status until the video is ready.
    for !operation.Done {
    log.Println("Waiting for video generation to complete...")
        time.Sleep(10 * time.Second)
        operation, _ = client.Operations.GetVideosOperation(ctx, operation, nil)
    }

    // Download the generated video.
    video := operation.Response.GeneratedVideos[0]
    client.Files.Download(ctx, video.Video, nil)
    fname := "realism_example.mp4"
    _ = os.WriteFile(fname, video.Video.VideoBytes, 0644)
    log.Printf("Generated video saved to %s\n", fname)
}
```

{% /tab %}
{% tab label="Java" filename="sample.java" %}

```java
import com.google.genai.Client;
import com.google.genai.types.GenerateVideosOperation;
import com.google.genai.types.GeneratedVideo;

Client client = new Client();

String prompt =
    "Drone shot following a classic red convertible driven by a man along a winding coastal road at sunset, waves crashing against the rocks below.\n"
        + "The convertible accelerates fast and the engine roars loudly.";

GenerateVideosOperation operation =
    client.models.generateVideos("veo-3.1-generate-preview", prompt, null, null);

// Poll the operation status until the video is ready.
while (!operation.done().orElse(false)) {
  System.out.println("Waiting for video generation to complete...");
  Thread.sleep(10000);
  operation = client.operations.getVideosOperation(operation, null);
}

// Download the generated video.
GeneratedVideo generatedVideo = operation.response().get().generatedVideos().get().get(0);
client.files.download(generatedVideo, "realism_example.mp4", null);
System.out.println("Generated video saved to realism_example.mp4");
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Note: This script uses jq to parse the JSON response.
# GEMINI API Base URL
BASE_URL="https://generativelanguage.googleapis.com/v1beta"

# Send request to generate video and capture the operation name into a variable.
operation_name=$(curl -s "${BASE_URL}/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "instances": [{
        "prompt": "Drone shot following a classic red convertible driven by a man along a winding coastal road at sunset, waves crashing against the rocks below. The convertible accelerates fast and the engine roars loudly."
      }
    ]
  }' | jq -r .name)

# Poll the operation status until the video is ready
while true; do
  # Get the full JSON status and store it in a variable.
  status_response=$(curl -s -H "x-goog-api-key: $GEMINI_API_KEY" "${BASE_URL}/${operation_name}")

  # Check the "done" field from the JSON stored in the variable.
  is_done=$(echo "${status_response}" | jq .done)

  if [ "${is_done}" = "true" ]; then
    # Extract the download URI from the final response.
    video_uri=$(echo "${status_response}" | jq -r '.response.generateVideoResponse.generatedSamples[0].video.uri')
    echo "Downloading video from: ${video_uri}"

    # Download the video using the URI and API key and follow redirects.
    curl -L -o realism_example.mp4 -H "x-goog-api-key: $GEMINI_API_KEY" "${video_uri}"
    break
  fi
  # Wait for 5 seconds before checking again.
  sleep 10
done
```

<devsite-video video-id="_U-hiHGscak" title="Realism"></devsite-video>

{% /tab %}
{% /tabs %}
### Creative animation {% id="style" %}

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai

client = genai.Client()
prompt = "A whimsical stop-motion animation of a tiny robot tending to a garden of glowing mushrooms on a miniature planet."

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt=prompt,
)

# Poll the operation status until the video is ready.
while not operation.done:
    print("Waiting for video generation to complete...")
    time.sleep(10)
    operation = client.operations.get(operation)

# Download the generated video.
generated_video = operation.response.generated_videos[0]
client.files.download(file=generated_video.video, destination="style_example.mp4")
print("Generated video saved to style_example.mp4")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const ai = new GoogleGenAI({});

const prompt = "A whimsical stop-motion animation of a tiny robot tending to a garden of glowing mushrooms on a miniature planet.";

let operation = await ai.models.generateVideos({
    model: "veo-3.1-generate-preview",
    prompt: prompt,
});

// Poll the operation status until the video is ready.
while (!operation.done) {
    console.log("Waiting for video generation to complete...")
    await new Promise((resolve) => setTimeout(resolve, 10000));
    operation = await ai.operations.getVideosOperation({
        operation: operation,
    });
}

// Download the generated video.
const video = operation.response?.generatedVideos?.[0]?.video;
if (video) {
    await ai.files.download({
        file: video,
        downloadPath: "style_example.mp4",
    });
    console.log(`Generated video saved to style_example.mp4`);
}
```

{% /tab %}
{% tab label="Go" filename="sample.go" %}

```go
package main

import (
    "context"
    "log"
    "os"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := `A whimsical stop-motion animation of a tiny robot tending to a garden of glowing mushrooms on a miniature planet.`

    operation, _ := client.Models.GenerateVideos(
        ctx,
        "veo-3.1-generate-preview",
        prompt,
        nil,
        nil,
    )

    // Poll the operation status until the video is ready.
    for !operation.Done {
    log.Println("Waiting for video generation to complete...")
        time.Sleep(10 * time.Second)
        operation, _ = client.Operations.GetVideosOperation(ctx, operation, nil)
    }

    // Download the generated video.
    video := operation.Response.GeneratedVideos[0]
    client.Files.Download(ctx, video.Video, nil)
    fname := "style_example.mp4"
    _ = os.WriteFile(fname, video.Video.VideoBytes, 0644)
    log.Printf("Generated video saved to %s\n", fname)
}
```

{% /tab %}
{% tab label="Java" filename="sample.java" %}

```java
import com.google.genai.Client;
import com.google.genai.types.GenerateVideosOperation;
import com.google.genai.types.GeneratedVideo;

Client client = new Client();

String prompt =
    "A whimsical stop-motion animation of a tiny robot tending to a garden of glowing mushrooms on a miniature planet.";

GenerateVideosOperation operation =
    client.models.generateVideos("veo-3.1-generate-preview", prompt, null, null);

// Poll the operation status until the video is ready.
while (!operation.done().orElse(false)) {
  System.out.println("Waiting for video generation to complete...");
  Thread.sleep(10000);
  operation = client.operations.getVideosOperation(operation, null);
}

// Download the generated video.
GeneratedVideo generatedVideo = operation.response().get().generatedVideos().get().get(0);
client.files.download(generatedVideo, "style_example.mp4", null);
System.out.println("Generated video saved to style_example.mp4");
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Note: This script uses jq to parse the JSON response.
# GEMINI API Base URL
BASE_URL="https://generativelanguage.googleapis.com/v1beta"

# Send request to generate video and capture the operation name into a variable.
operation_name=$(curl -s "${BASE_URL}/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "instances": [{
        "prompt": "A whimsical stop-motion animation of a tiny robot tending to a garden of glowing mushrooms on a miniature planet."
      }
    ]
  }' | jq -r .name)

# Poll the operation status until the video is ready
while true; do
  # Get the full JSON status and store it in a variable.
  status_response=$(curl -s -H "x-goog-api-key: $GEMINI_API_KEY" "${BASE_URL}/${operation_name}")

  # Check the "done" field from the JSON stored in the variable.
  is_done=$(echo "${status_response}" | jq .done)

  if [ "${is_done}" = "true" ]; then
    # Extract the download URI from the final response.
    video_uri=$(echo "${status_response}" | jq -r '.response.generateVideoResponse.generatedSamples[0].video.uri')
    echo "Downloading video from: ${video_uri}"

    # Download the video using the URI and API key and follow redirects.
    curl -L -o style_example.mp4 -H "x-goog-api-key: $GEMINI_API_KEY" "${video_uri}"
    break
  fi
  # Wait for 5 seconds before checking again.
  sleep 10
done
```

<devsite-video video-id="cbIDB6nXMMg" title="Style"></devsite-video>

{% /tab %}
{% /tabs %}
## Control the aspect ratio {% id="aspect-ratio" %}

Veo 3.1 lets you create landscape (`16:9`, the default setting) or portrait
(`9:16`) videos. You can tell the model which one you want using the
`aspect_ratio` parameter:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai
from google.genai import types

client = genai.Client()

prompt = """A montage of pizza making: a chef tossing and flattening the floury dough, ladling rich red tomato sauce in a spiral, sprinkling mozzarella cheese and pepperoni, and a final shot of the bubbling golden-brown pizza, upbeat electronic music with a rhythmical beat is playing, high energy professional video."""

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt=prompt,
    config=types.GenerateVideosConfig(
      aspect_ratio="9:16",
    ),
)

# Poll the operation status until the video is ready.
while not operation.done:
    print("Waiting for video generation to complete...")
    time.sleep(10)
    operation = client.operations.get(operation)

# Download the generated video.
generated_video = operation.response.generated_videos[0]
client.files.download(file=generated_video.video, destination="pizza_making.mp4")
print("Generated video saved to pizza_making.mp4")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const ai = new GoogleGenAI({});

const prompt = `A montage of pizza making: a chef tossing and flattening the floury dough, ladling rich red tomato sauce in a spiral, sprinkling mozzarella cheese and pepperoni, and a final shot of the bubbling golden-brown pizza, upbeat electronic music with a rhythmical beat is playing, high energy professional video.`;

let operation = await ai.models.generateVideos({
    model: "veo-3.1-generate-preview",
    prompt: prompt,
    config: {
      aspectRatio: "9:16",
    },
});

// Poll the operation status until the video is ready.
while (!operation.done) {
    console.log("Waiting for video generation to complete...")
    await new Promise((resolve) => setTimeout(resolve, 10000));
    operation = await ai.operations.getVideosOperation({
        operation: operation,
    });
}

// Download the generated video.
const video = operation.response?.generatedVideos?.[0]?.video;
if (video) {
    await ai.files.download({
        file: video,
        downloadPath: "pizza_making.mp4",
    });
    console.log(`Generated video saved to pizza_making.mp4`);
}
```

{% /tab %}
{% tab label="Go" filename="sample.go" %}

```go
package main

import (
    "context"
    "log"
    "os"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := `A montage of pizza making: a chef tossing and flattening the floury dough, ladling rich red tomato sauce in a spiral, sprinkling mozzarella cheese and pepperoni, and a final shot of the bubbling golden-brown pizza, upbeat electronic music with a rhythmical beat is playing, high energy professional video.`

  videoConfig := &genai.GenerateVideosConfig{
      AspectRatio: "9:16",
  }

    operation, _ := client.Models.GenerateVideos(
        ctx,
        "veo-3.1-generate-preview",
        prompt,
        nil,
        videoConfig,
    )

    // Poll the operation status until the video is ready.
    for !operation.Done {
    log.Println("Waiting for video generation to complete...")
        time.Sleep(10 * time.Second)
        operation, _ = client.Operations.GetVideosOperation(ctx, operation, nil)
    }

    // Download the generated video.
    video := operation.Response.GeneratedVideos[0]
    client.Files.Download(ctx, video.Video, nil)
    fname := "pizza_making.mp4"
    _ = os.WriteFile(fname, video.Video.VideoBytes, 0644)
    log.Printf("Generated video saved to %s\n", fname)
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Note: This script uses jq to parse the JSON response.
# GEMINI API Base URL
BASE_URL="https://generativelanguage.googleapis.com/v1beta"

# Send request to generate video and capture the operation name into a variable.
operation_name=$(curl -s "${BASE_URL}/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "instances": [{
        "prompt": "A montage of pizza making: a chef tossing and flattening the floury dough, ladling rich red tomato sauce in a spiral, sprinkling mozzarella cheese and pepperoni, and a final shot of the bubbling golden-brown pizza, upbeat electronic music with a rhythmical beat is playing, high energy professional video."
      }
    ],
    "parameters": {
      "aspectRatio": "9:16"
    }
  }' | jq -r .name)

# Poll the operation status until the video is ready
while true; do
  # Get the full JSON status and store it in a variable.
  status_response=$(curl -s -H "x-goog-api-key: $GEMINI_API_KEY" "${BASE_URL}/${operation_name}")

  # Check the "done" field from the JSON stored in the variable.
  is_done=$(echo "${status_response}" | jq .done)

  if [ "${is_done}" = "true" ]; then
    # Extract the download URI from the final response.
    video_uri=$(echo "${status_response}" | jq -r '.response.generateVideoResponse.generatedSamples[0].video.uri')
    echo "Downloading video from: ${video_uri}"

    # Download the video using the URI and API key and follow redirects.
    curl -L -o pizza_making.mp4 -H "x-goog-api-key: $GEMINI_API_KEY" "${video_uri}"
    break
  fi
  # Wait for 5 seconds before checking again.
  sleep 10
done
```

<devsite-video video-id="4-kXyNJt_yg" title="4K drone view of the Grand Canyon"></devsite-video>

{% /tab %}
{% /tabs %}
## Control the resolution {% id="resolution" %}

Veo 3.1 can also directly generate 720p, 1080p or 4k videos (4k not available
for Veo 3.1 Lite).

Note that the higher the resolution, the higher the latency will be. 4k videos
are also more expensive (see [pricing](/docs/pricing)).

[Video extension](/docs/veo#extending-veo-videos) is also limited to 720p videos.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai
from google.genai import types

client = genai.Client()

prompt = """A stunning drone view of the Grand Canyon during a flamboyant sunset that highlights the canyon's colors. The drone slowly flies towards the sun then accelerates, dives and flies inside the canyon."""

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt=prompt,
    config=types.GenerateVideosConfig(
      resolution="4k",
    ),
)

# Poll the operation status until the video is ready.
while not operation.done:
    print("Waiting for video generation to complete...")
    time.sleep(10)
    operation = client.operations.get(operation)

# Download the generated video.
generated_video = operation.response.generated_videos[0]
client.files.download(file=generated_video.video, destination="4k_grand_canyon.mp4")
print("Generated video saved to 4k_grand_canyon.mp4")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const ai = new GoogleGenAI({});

const prompt = `A stunning drone view of the Grand Canyon during a flamboyant sunset that highlights the canyon's colors. The drone slowly flies towards the sun then accelerates, dives and flies inside the canyon.`;

let operation = await ai.models.generateVideos({
    model: "veo-3.1-generate-preview",
    prompt: prompt,
    config: {
      resolution: "4k",
    },
});

// Poll the operation status until the video is ready.
while (!operation.done) {
    console.log("Waiting for video generation to complete...")
    await new Promise((resolve) => setTimeout(resolve, 10000));
    operation = await ai.operations.getVideosOperation({
        operation: operation,
    });
}

// Download the generated video.
const video = operation.response?.generatedVideos?.[0]?.video;
if (video) {
    await ai.files.download({
        file: video,
        downloadPath: "4k_grand_canyon.mp4",
    });
    console.log(`Generated video saved to 4k_grand_canyon.mp4`);
}
```

{% /tab %}
{% tab label="Go" filename="sample.go" %}

```go
package main

import (
    "context"
    "log"
    "os"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := `A stunning drone view of the Grand Canyon during a flamboyant sunset that highlights the canyon's colors. The drone slowly flies towards the sun then accelerates, dives and flies inside the canyon.`

  videoConfig := &genai.GenerateVideosConfig{
      Resolution: "4k",
  }

    operation, _ := client.Models.GenerateVideos(
        ctx,
        "veo-3.1-generate-preview",
        prompt,
        nil,
        videoConfig,
    )

    // Poll the operation status until the video is ready.
    for !operation.Done {
    log.Println("Waiting for video generation to complete...")
        time.Sleep(10 * time.Second)
        operation, _ = client.Operations.GetVideosOperation(ctx, operation, nil)
    }

    // Download the generated video.
    video := operation.Response.GeneratedVideos[0]
    client.Files.Download(ctx, video.Video, nil)
    fname := "4k_grand_canyon.mp4"
    _ = os.WriteFile(fname, video.Video.VideoBytes, 0644)
    log.Printf("Generated video saved to %s\n", fname)
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Note: This script uses jq to parse the JSON response.
# GEMINI API Base URL
BASE_URL="https://generativelanguage.googleapis.com/v1beta"

# Send request to generate video and capture the operation name into a variable.
operation_name=$(curl -s "${BASE_URL}/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "instances": [{
        "prompt": "A stunning drone view of the Grand Canyon during a flamboyant sunset that highlights the canyon'\''s colors. The drone slowly flies towards the sun then accelerates, dives and flies inside the canyon."
      }
    ],
    "parameters": {
      "resolution": "4k"
    }
  }' | jq -r .name)

# Poll the operation status until the video is ready
while true; do
  # Get the full JSON status and store it in a variable.
  status_response=$(curl -s -H "x-goog-api-key: $GEMINI_API_KEY" "${BASE_URL}/${operation_name}")

  # Check the "done" field from the JSON stored in the variable.
  is_done=$(echo "${status_response}" | jq .done)

  if [ "${is_done}" = "true" ]; then
    # Extract the download URI from the final response.
    video_uri=$(echo "${status_response}" | jq -r '.response.generateVideoResponse.generatedSamples[0].video.uri')
    echo "Downloading video from: ${video_uri}"

    # Download the video using the URI and API key and follow redirects.
    curl -L -o 4k_grand_canyon.mp4 -H "x-goog-api-key: $GEMINI_API_KEY" "${video_uri}"
    break
  fi
  # Wait for 5 seconds before checking again.
  sleep 10
done
```

<devsite-video video-id="SDqEif-qtyk" title="4K drone view of the Grand Canyon"></devsite-video>

{% /tab %}
{% /tabs %}
## Image to video generation {% id="generate-from-images" %}

The following code demonstrates generating an image using
[Gemini 3.1 Flash Image aka Nano Banana 2](/docs/image-generation),
then using that image as the
starting frame for generating a video with Veo 3.1.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai

client = genai.Client()

prompt = "Panning wide shot of a calico kitten sleeping in the sunshine"

# Step 1: Generate an image with Nano Banana 2.
image = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=prompt,
    config={"response_modalities":['IMAGE']}
)

# Step 2: Generate video with Veo 3.1 using the image.
operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt=prompt,
    image=image.parts[0].as_image(),
)

# Poll the operation status until the video is ready.
while not operation.done:
    print("Waiting for video generation to complete...")
    time.sleep(10)
    operation = client.operations.get(operation)

# Download the video.
video = operation.response.generated_videos[0]
client.files.download(file=video.video, destination="veo3_with_image_input.mp4")
print("Generated video saved to veo3_with_image_input.mp4")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const ai = new GoogleGenAI({});

const prompt = "Panning wide shot of a calico kitten sleeping in the sunshine";

// Step 1: Generate an image with Nano Banana 2.
const imageResponse = await ai.models.generateContent({
  model: "gemini-3.1-flash-image-preview",
  contents: prompt,
  config: { responseModalities: ["IMAGE"] },
});

const inlineData = imageResponse.candidates?.[0]?.content?.parts?.[0]?.inlineData;

// Step 2: Generate video with Veo 3.1 using the image.
let operation = await ai.models.generateVideos({
  model: "veo-3.1-generate-preview",
  prompt: prompt,
  image: {
    imageBytes: inlineData?.data || '',
    mimeType: inlineData?.mimeType || "image/png",
  },
});

// Poll the operation status until the video is ready.
while (!operation.done) {
  console.log("Waiting for video generation to complete...")
  await new Promise((resolve) => setTimeout(resolve, 10000));
  operation = await ai.operations.getVideosOperation({
    operation: operation,
  });
}

// Download the video.
const video = operation.response?.generatedVideos?.[0]?.video;
if (video) {
    await ai.files.download({
        file: video,
        downloadPath: "veo3_with_image_input.mp4",
    });
    console.log(`Generated video saved to veo3_with_image_input.mp4`);
}
```

{% /tab %}
{% tab label="Go" filename="sample.go" %}

```go
package main

import (
    "context"
    "log"
    "os"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Panning wide shot of a calico kitten sleeping in the sunshine"

    // Step 1: Generate an image with Nano Banana 2.
    imageResponse, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.1-flash-image-preview",
        prompt,
        nil, // GenerateImagesConfig
    )
    if err != nil {
        log.Fatal(err)
    }

    // Step 2: Generate video with Veo 3.1 using the image.
    operation, err := client.Models.GenerateVideos(
        ctx,
        "veo-3.1-generate-preview",
        prompt,
        imageResponse.GeneratedImages[0].Image,
        nil, // GenerateVideosConfig
    )
    if err != nil {
        log.Fatal(err)
    }

    // Poll the operation status until the video is ready.
    for !operation.Done {
        log.Println("Waiting for video generation to complete...")
        time.Sleep(10 * time.Second)
        operation, _ = client.Operations.GetVideosOperation(ctx, operation, nil)
    }

    // Download the video.
    video := operation.Response.GeneratedVideos[0]
    client.Files.Download(ctx, video.Video, nil)
    fname := "veo3_with_image_input.mp4"
    _ = os.WriteFile(fname, video.Video.VideoBytes, 0644)
    log.Printf("Generated video saved to %s\n", fname)
}
```

{% /tab %}
{% tab label="Java" filename="sample.java" %}

```java
import com.google.genai.Client;
import com.google.genai.types.Blob;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.GenerateVideosOperation;
import com.google.genai.types.GeneratedVideo;
import com.google.genai.types.Image;

Client client = new Client();

String prompt = "Panning wide shot of a calico kitten sleeping in the sunshine";

// Step 1: Generate an image with Nano Banana 2.
GenerateContentResponse imageResponse =
    client.models.generateContent(
        "gemini-3.1-flash-image-preview",
        prompt,
        GenerateContentConfig.builder().responseModalities("IMAGE").build());

Blob inlineData = imageResponse.parts().get(0).inlineData().get();
Image image =
    Image.builder()
        .imageBytes(inlineData.data().get())
        .mimeType(inlineData.mimeType().orElse("image/png"))
        .build();

// Step 2: Generate video with Veo 3.1 using the image.
GenerateVideosOperation operation =
    client.models.generateVideos("veo-3.1-generate-preview", prompt, image, null);

// Poll the operation status until the video is ready.
while (!operation.done().orElse(false)) {
  System.out.println("Waiting for video generation to complete...");
  Thread.sleep(10000);
  operation = client.operations.getVideosOperation(operation, null);
}

// Download the video.
GeneratedVideo video = operation.response().get().generatedVideos().get().get(0);
client.files.download(video, "veo3_with_image_input.mp4", null);
System.out.println("Generated video saved to veo3_with_image_input.mp4");
```

{% /tab %}
{% /tabs %}
### Using reference images {% id="reference-images" %}

{% callout type="note" %}
This feature is available for Veo 3.1 models only.
{% /callout %}

Veo 3.1 now accepts up to 3 reference images to guide your generated video's
content. Provide images of a person, character, or product to
preserve the subject's appearance in the output video.

For example, using these three images generated with
[Nano Banana](/docs/image-generation) as references with a
[well-written prompt](/docs/veo#use-reference-images) creates the following video:

| `dress_image` | `woman_image` | `glasses_image` |
| :--- | :--- | :--- |
|  |  |  |

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai

client = genai.Client()

prompt = "The video opens with a medium, eye-level shot of a beautiful woman with dark hair and warm brown eyes. She wears a magnificent, high-fashion flamingo dress with layers of pink and fuchsia feathers, complemented by whimsical pink, heart-shaped sunglasses. She walks with serene confidence through the crystal-clear, shallow turquoise water of a sun-drenched lagoon. The camera slowly pulls back to a medium-wide shot, revealing the breathtaking scene as the dress's long train glides and floats gracefully on the water's surface behind her. The cinematic, dreamlike atmosphere is enhanced by the vibrant colors of the dress against the serene, minimalist landscape, capturing a moment of pure elegance and high-fashion fantasy."

dress_reference = types.VideoGenerationReferenceImage(
  image=dress_image, # Generated separately with Nano Banana
  reference_type="asset"
)

sunglasses_reference = types.VideoGenerationReferenceImage(
  image=glasses_image, # Generated separately with Nano Banana
  reference_type="asset"
)

woman_reference = types.VideoGenerationReferenceImage(
  image=woman_image, # Generated separately with Nano Banana
  reference_type="asset"
)

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt=prompt,
    config=types.GenerateVideosConfig(
      reference_images=[dress_reference, glasses_reference, woman_reference],
    ),
)

# Poll the operation status until the video is ready.
while not operation.done:
    print("Waiting for video generation to complete...")
    time.sleep(10)
    operation = client.operations.get(operation)

# Download the video.
video = operation.response.generated_videos[0]
client.files.download(file=video.video, destination="veo3.1_with_reference_images.mp4")
print("Generated video saved to veo3.1_with_reference_images.mp4")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI, VideoGenerationReferenceType } from "@google/genai";

const ai = new GoogleGenAI({});

const prompt = "The video opens with a medium, eye-level shot of a beautiful woman with dark hair and warm brown eyes. She wears a magnificent, high-fashion flamingo dress with layers of pink and fuchsia feathers, complemented by whimsical pink, heart-shaped sunglasses. She walks with serene confidence through the crystal-clear, shallow turquoise water of a sun-drenched lagoon. The camera slowly pulls back to a medium-wide shot, revealing the breathtaking scene as the dress's long train glides and floats gracefully on the water's surface behind her. The cinematic, dreamlike atmosphere is enhanced by the vibrant colors of the dress against the serene, minimalist landscape, capturing a moment of pure elegance and high-fashion fantasy.";

// dressImage, glassesImage, womanImage generated separately with Nano Banana
// and available as objects like { imageBytes: "...", mimeType: "image/png" }

let operation = await ai.models.generateVideos({
  model: "veo-3.1-generate-preview",
  prompt: prompt,
  config: {
    referenceImages: [
      { image: dressImage, referenceType: VideoGenerationReferenceType.ASSET },
      { image: glassesImage, referenceType: VideoGenerationReferenceType.ASSET },
      { image: womanImage, referenceType: VideoGenerationReferenceType.ASSET },
    ],
  },
});

// Poll the operation status until the video is ready.
while (!operation.done) {
  console.log("Waiting for video generation to complete...");
  await new Promise((resolve) => setTimeout(resolve, 10000));
  operation = await ai.operations.getVideosOperation({
    operation: operation,
  });
}

// Download the video.
const video = operation.response?.generatedVideos?.[0]?.video;
if (video) {
    await ai.files.download({
        file: video,
        downloadPath: "veo3.1_with_reference_images.mp4",
    });
    console.log(`Generated video saved to veo3.1_with_reference_images.mp4`);
}
```

{% /tab %}
{% tab label="Go" filename="sample.go" %}

```go
package main

import (
    "context"
    "log"
    "os"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

  prompt := `The video opens with a medium, eye-level shot of a beautiful woman with dark hair and warm brown eyes. She wears a magnificent, high-fashion flamingo dress with layers of pink and fuchsia feathers, complemented by whimsical pink, heart-shaped sunglasses. She walks with serene confidence through the crystal-clear, shallow turquoise water of a sun-drenched lagoon. The camera slowly pulls back to a medium-wide shot, revealing the breathtaking scene as the dress's long train glides and floats gracefully on the water's surface behind her. The cinematic, dreamlike atmosphere is enhanced by the vibrant colors of the dress against the serene, minimalist landscape, capturing a moment of pure elegance and high-fashion fantasy.`

  // dressImage, glassesImage, womanImage generated separately with Nano Banana
  // and available as *genai.Image objects.
  var dressImage, glassesImage, womanImage *genai.Image

  dressReference := &genai.VideoGenerationReferenceImage{
    Image: dressImage,
    ReferenceType: "asset",
  }
  sunglassesReference := &genai.VideoGenerationReferenceImage{
    Image: glassesImage,
    ReferenceType: "asset",
  }
  womanReference := &genai.VideoGenerationReferenceImage{
    Image: womanImage,
    ReferenceType: "asset",
  }

    operation, _ := client.Models.GenerateVideos(
        ctx,
        "veo-3.1-generate-preview",
        prompt,
    nil, // image
        &genai.GenerateVideosConfig{
      ReferenceImages: []*genai.VideoGenerationReferenceImage{
        dressReference,
        sunglassesReference,
        womanReference,
      },
    },
    )

    // Poll the operation status until the video is ready.
    for !operation.Done {
        log.Println("Waiting for video generation to complete...")
        time.Sleep(10 * time.Second)
        operation, _ = client.Operations.GetVideosOperation(ctx, operation, nil)
    }

    // Download the video.
    video := operation.Response.GeneratedVideos[0]
    client.Files.Download(ctx, video.Video, nil)
    fname := "veo3.1_with_reference_images.mp4"
    _ = os.WriteFile(fname, video.Video.VideoBytes, 0644)
    log.Printf("Generated video saved to %s\n", fname)
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Note: This script uses jq to parse the JSON response.
# It assumes dress_image_base64, glasses_image_base64, and woman_image_base64
# contain base64-encoded image data.

# GEMINI API Base URL
BASE_URL="https://generativelanguage.googleapis.com/v1beta"

# Send request to generate video and capture the operation name into a variable.
operation_name=$(curl -s "${BASE_URL}/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "instances": [{
      "prompt": "The video opens with a medium, eye-level shot of a beautiful woman with dark hair and warm brown eyes. She wears a magnificent, high-fashion flamingo dress with layers of pink and fuchsia feathers, complemented by whimsical pink, heart-shaped sunglasses. She walks with serene confidence through the crystal-clear, shallow turquoise water of a sun-drenched lagoon. The camera slowly pulls back to a medium-wide shot, revealing the breathtaking scene as the dress'\''s long train glides and floats gracefully on the water'\''s surface behind her. The cinematic, dreamlike atmosphere is enhanced by the vibrant colors of the dress against the serene, minimalist landscape, capturing a moment of pure elegance and high-fashion fantasy.",
      "referenceImages": [
        {
          "image": {"inlineData": {"mimeType": "image/png", "data": "'"$dress_image_base64"'"}},
          "referenceType": "asset"
        },
        {
          "image": {"inlineData": {"mimeType": "image/png", "data": "'"$glasses_image_base64"'"}},
          "referenceType": "asset"
        },
        {
          "image": {"inlineData": {"mimeType": "image/png", "data": "'"$woman_image_base64"'"}},
          "referenceType": "asset"
        }
      ]
    }],
  }' | jq -r .name)

# Poll the operation status until the video is ready
while true; do
  # Get the full JSON status and store it in a variable.
  status_response=$(curl -s -H "x-goog-api-key: $GEMINI_API_KEY" "${BASE_URL}/${operation_name}")

  # Check the "done" field from the JSON stored in the variable.
  is_done=$(echo "${status_response}" | jq .done)

  if [ "${is_done}" = "true" ]; then
    # Extract the download URI from the final response.
    video_uri=$(echo "${status_response}" | jq -r '.response.generateVideoResponse.generatedSamples[0].video.uri')
    echo "Downloading video from: ${video_uri}"

    # Download the video using the URI and API key and follow redirects.
    curl -L -o veo3.1_with_reference_images.mp4 -H "x-goog-api-key: $GEMINI_API_KEY" "${video_uri}"
    break
  fi
  # Wait for 10 seconds before checking again.
  sleep 10
done
```

<devsite-video video-id="Hvo89S-lgAo" title="Reference"></devsite-video>

{% /tab %}
{% /tabs %}
### Using first and last frames {% id="using-first-and-last-video-frames" %}

{% callout type="note" %}
This feature is available for Veo 3.1 models only
{% /callout %}

Veo 3.1 lets you create videos using interpolation, or specifying the first and
last frames of the video. For information about writing effective text prompts
for video generation, see the [Veo prompt guide](/docs/veo#use-reference-images).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai

client = genai.Client()

prompt = "A cinematic, haunting video. A ghostly woman with long white hair and a flowing dress swings gently on a rope swing beneath a massive, gnarled tree in a foggy, moonlit clearing. The fog thickens and swirls around her, and she slowly fades away, vanishing completely. The empty swing is left swaying rhythmically on its own in the eerie silence."

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt=prompt,
    image=first_image, # The starting frame is passed as a primary input
    config=types.GenerateVideosConfig(
      last_frame=last_image # The ending frame is passed as a generation constraint in the config
    ),
)

# Poll the operation status until the video is ready.
while not operation.done:
    print("Waiting for video generation to complete...")
    time.sleep(10)
    operation = client.operations.get(operation)

# Download the video.
video = operation.response.generated_videos[0]
client.files.download(file=video.video, destination="veo3.1_with_interpolation.mp4")
print("Generated video saved to veo3.1_with_interpolation.mp4")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const ai = new GoogleGenAI({});

const prompt = "A cinematic, haunting video. A ghostly woman with long white hair and a flowing dress swings gently on a rope swing beneath a massive, gnarled tree in a foggy, moonlit clearing. The fog thickens and swirls around her, and she slowly fades away, vanishing completely. The empty swing is left swaying rhythmically on its own in the eerie silence.";

// firstImage and lastImage generated separately with Nano Banana
// and available as objects like { imageBytes: "...", mimeType: "image/png" }
let operation = await ai.models.generateVideos({
    model: "veo-3.1-generate-preview",
    prompt: prompt,
    image: firstImage, // The starting frame is passed as a primary input
    config: {
      lastFrame: lastImage, // The ending frame is passed as a generation constraint in the config
    },
});

// Poll the operation status until the video is ready.
while (!operation.done) {
    console.log("Waiting for video generation to complete...")
    await new Promise((resolve) => setTimeout(resolve, 10000));
    operation = await ai.operations.getVideosOperation({
        operation: operation,
    });
}

// Download the video.
const video = operation.response?.generatedVideos?.[0]?.video;
if (video) {
    await ai.files.download({
        file: video,
        downloadPath: "veo3.1_with_interpolation.mp4",
    });
    console.log(`Generated video saved to veo3.1_with_interpolation.mp4`);
}
```

{% /tab %}
{% tab label="Go" filename="sample.go" %}

```go
package main

import (
    "context"
    "log"
    "os"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

  prompt := `A cinematic, haunting video. A ghostly woman with long white hair and a flowing dress swings gently on a rope swing beneath a massive, gnarled tree in a foggy, moonlit clearing. The fog thickens and swirls around her, and she slowly fades away, vanishing completely. The empty swing is left swaying rhythmically on its own in the eerie silence.`

  // firstImage and lastImage generated separately with Nano Banana
  // and available as *genai.Image objects.
  var firstImage, lastImage *genai.Image

    operation, _ := client.Models.GenerateVideos(
        ctx,
        "veo-3.1-generate-preview",
        prompt,
    firstImage, // The starting frame is passed as a primary input
        &genai.GenerateVideosConfig{
      LastFrame: lastImage, // The ending frame is passed as a generation constraint in the config
    },
    )

    // Poll the operation status until the video is ready.
    for !operation.Done {
        log.Println("Waiting for video generation to complete...")
        time.Sleep(10 * time.Second)
        operation, _ = client.Operations.GetVideosOperation(ctx, operation, nil)
    }

    // Download the video.
    video := operation.Response.GeneratedVideos[0]
    client.Files.Download(ctx, video.Video, nil)
    fname := "veo3.1_with_interpolation.mp4"
    _ = os.WriteFile(fname, video.Video.VideoBytes, 0644)
    log.Printf("Generated video saved to %s\n", fname)
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Note: This script uses jq to parse the JSON response.
# It assumes first_image_base64 and last_image_base64
# contain base64-encoded image data.

# GEMINI API Base URL
BASE_URL="https://generativelanguage.googleapis.com/v1beta"

# Send request to generate video and capture the operation name into a variable.
# The starting frame is passed as a primary input
# The ending frame is passed as a generation constraint in the config
operation_name=$(curl -s "${BASE_URL}/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "instances": [{
      "prompt": "A cinematic, haunting video. A ghostly woman with long white hair and a flowing dress swings gently on a rope swing beneath a massive, gnarled tree in a foggy, moonlit clearing. The fog thickens and swirls around her, and she slowly fades away, vanishing completely. The empty swing is left swaying rhythmically on its own in the eerie silence.",
      "image": {"inlineData": {"mimeType": "image/png", "data": "'"$first_image_base64"'"}},
      "lastFrame": {"inlineData": {"mimeType": "image/png", "data": "'"$last_image_base64"'"}}
    }],
  }' | jq -r .name)

# Poll the operation status until the video is ready
while true; do
  # Get the full JSON status and store it in a variable.
  status_response=$(curl -s -H "x-goog-api-key: $GEMINI_API_KEY" "${BASE_URL}/${operation_name}")

  # Check the "done" field from the JSON stored in the variable.
  is_done=$(echo "${status_response}" | jq .done)

  if [ "${is_done}" = "true" ]; then
    # Extract the download URI from the final response.
    video_uri=$(echo "${status_response}" | jq -r '.response.generateVideoResponse.generatedSamples[0].video.uri')
    echo "Downloading video from: ${video_uri}"

    # Download the video using the URI and API key and follow redirects.
    curl -L -o veo3.1_with_interpolation.mp4 -H "x-goog-api-key: $GEMINI_API_KEY" "${video_uri}"
    break
  fi
  # Wait for 10 seconds before checking again.
  sleep 10
done
```

| `first_image` | `last_image` | veo3.1_with_interpolation.mp4 |
| :--- | :--- | :--- |
|  |  |  |

{% /tab %}
{% /tabs %}
## Extending Veo videos {% id="extending-veo-videos" %}

{% callout type="note" %}
This feature is available for Veo 3.1 & Veo 3.1 Fast models only, not
{% /callout %}
Veo 3.1 Lite.

Use Veo 3.1 to extend videos that you previously generated with Veo by 7 seconds
and up to 20 times.

Input video limitations:

* Veo-generated videos only up to 141 seconds long.
* Gemini API only supports video extensions for Veo-generated videos.
* The video should come from a previous generation, like
  `operation.response.generated_videos[0].video`
* Videos are stored for 2 days, but if a video is referenced for extension,
  its 2-day storage timer resets. You can only extend videos that were generated
  or referenced in the last two days.
* Input videos are expected to have a certain length, aspect ratio, and dimensions:
    * Aspect ratio: 9:16 or 16:9
    * Resolution: 720p
    * Video length: 141 seconds or less

The output of the extension is a single video combining the user input video and
the generated extended video for up to 148 seconds of video.

This example takes the a Veo-generated video, shown here with
its original prompt, and extends it using the `video` parameter and a new
prompt:

| Prompt | Output: butterfly_video |
| :--- | :--- |
| An origami butterfly flaps its wings and flies out of the french doors into the garden. |  |

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai

client = genai.Client()

prompt = "Track the butterfly into the garden as it lands on an orange origami flower. A fluffy white puppy runs up and gently pats the flower."

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    video=operation.response.generated_videos[0].video, # This must be a video from a previous generation
    prompt=prompt,
    config=types.GenerateVideosConfig(
        number_of_videos=1,
        resolution="720p"
    ),
)

# Poll the operation status until the video is ready.
while not operation.done:
    print("Waiting for video generation to complete...")
    time.sleep(10)
    operation = client.operations.get(operation)

# Download the video.
video = operation.response.generated_videos[0]
client.files.download(file=video.video, destination="veo3.1_extension.mp4")
print("Generated video saved to veo3.1_extension.mp4")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const ai = new GoogleGenAI({});

const prompt = "Track the butterfly into the garden as it lands on an orange origami flower. A fluffy white puppy runs up and gently pats the flower.";

// butterflyVideo must be a video from a previous generation
// available as an object like { videoBytes: "...", mimeType: "video/mp4" }
let operation = await ai.models.generateVideos({
    model: "veo-3.1-generate-preview",
    video: butterflyVideo,
    prompt: prompt,
    config: {
        numberOfVideos: 1,
        resolution: "720p",
    },
});

// Poll the operation status until the video is ready.
while (!operation.done) {
    console.log("Waiting for video generation to complete...")
    await new Promise((resolve) => setTimeout(resolve, 10000));
    operation = await ai.operations.getVideosOperation({
        operation: operation,
    });
}

// Download the video.
const video = operation.response?.generatedVideos?.[0]?.video;
if (video) {
    await ai.files.download({
        file: video,
        downloadPath: "veo3.1_extension.mp4",
    });
    console.log(`Generated video saved to veo3.1_extension.mp4`);
}
```

{% /tab %}
{% tab label="Go" filename="sample.go" %}

```go
package main

import (
    "context"
    "log"
    "os"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

  prompt := `Track the butterfly into the garden as it lands on an orange origami flower. A fluffy white puppy runs up and gently pats the flower.`

  // butterflyVideo must be a video from a previous generation
  // available as a *genai.Video object.
  var butterflyVideo *genai.Video

    operation, _ := client.Models.GenerateVideos(
        ctx,
        "veo-3.1-generate-preview",
        prompt,
    nil, // image
    butterflyVideo,
        &genai.GenerateVideosConfig{
      NumberOfVideos: 1,
      Resolution: "720p",
    },
    )

    // Poll the operation status until the video is ready.
    for !operation.Done {
        log.Println("Waiting for video generation to complete...")
        time.Sleep(10 * time.Second)
        operation, _ = client.Operations.GetVideosOperation(ctx, operation, nil)
    }

    // Download the video.
    video := operation.Response.GeneratedVideos[0]
    client.Files.Download(ctx, video.Video, nil)
    fname := "veo3.1_extension.mp4"
    _ = os.WriteFile(fname, video.Video.VideoBytes, 0644)
    log.Printf("Generated video saved to %s\n", fname)
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Note: This script uses jq to parse the JSON response.
# It assumes butterfly_video_base64 contains base64-encoded
# video data from a previous generation.

# GEMINI API Base URL
BASE_URL="https://generativelanguage.googleapis.com/v1beta"

# Send request to generate video and capture the operation name into a variable.
operation_name=$(curl -s "${BASE_URL}/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "instances": [{
      "prompt": "Track the butterfly into the garden as it lands on an orange origami flower. A fluffy white puppy runs up and gently pats the flower.",
      "video": {"inlineData": {"mimeType": "video/mp4", "data": "'"$butterfly_video_base64"'"}}
    }],
    "parameters": {
      "numberOfVideos": 1,
      "resolution": "720p"
    }
  }' | jq -r .name)

# Poll the operation status until the video is ready
while true; do
  # Get the full JSON status and store it in a variable.
  status_response=$(curl -s -H "x-goog-api-key: $GEMINI_API_KEY" "${BASE_URL}/${operation_name}")

  # Check the "done" field from the JSON stored in the variable.
  is_done=$(echo "${status_response}" | jq .done)

  if [ "${is_done}" = "true" ]; then
    # Extract the download URI from the final response.
    video_uri=$(echo "${status_response}" | jq -r '.response.generateVideoResponse.generatedSamples[0].video.uri')
    echo "Downloading video from: ${video_uri}"

    # Download the video using the URI and API key and follow redirects.
    curl -L -o veo3.1_extension.mp4 -H "x-goog-api-key: $GEMINI_API_KEY" "${video_uri}"
    break
  fi
  # Wait for 10 seconds before checking again.
  sleep 10
done
```

<devsite-video video-id="eSF7-_B4ciA" title="Reference"></devsite-video>

For information about writing effective text prompts for video generation, see
the [Veo prompt guide](/docs/veo#extend-prompt).

{% /tab %}
{% /tabs %}
## Handling asynchronous operations {% id="handling-asynchronous-operations" %}

Video generation is a computationally intensive task. When you send a request
to the API, it starts a long-running job and immediately returns an `operation`
object. You must then poll until the video is ready, which is indicated by the
`done` status being true.

The core of this process is a polling loop, which periodically checks the job's
status.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai
from google.genai import types

client = genai.Client()

# After starting the job, you get an operation object.
operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt="A cinematic shot of a majestic lion in the savannah.",
)

# Alternatively, you can use operation.name to get the operation.
operation = types.GenerateVideosOperation(name=operation.name)

# This loop checks the job status every 10 seconds.
while not operation.done:
    time.sleep(10)
    # Refresh the operation object to get the latest status.
    operation = client.operations.get(operation)

# Once done, the result is in operation.response.
# ... process and download your video ...
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const ai = new GoogleGenAI({});

// After starting the job, you get an operation object.
let operation = await ai.models.generateVideos({
  model: "veo-3.1-generate-preview",
  prompt: "A cinematic shot of a majestic lion in the savannah.",
});

// Alternatively, you can use operation.name to get the operation.
// operation = types.GenerateVideosOperation(name=operation.name)

// This loop checks the job status every 10 seconds.
while (!operation.done) {
    await new Promise((resolve) => setTimeout(resolve, 1000));
    // Refresh the operation object to get the latest status.
    operation = await ai.operations.getVideosOperation({ operation });
}

// Once done, the result is in operation.response.
// ... process and download your video ...
```

{% /tab %}
{% tab label="Go" filename="sample.go" %}

```go
package main

import (
    "context"
    "log"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // After starting the job, you get an operation object.
    operation, _ := client.Models.GenerateVideos(
        ctx,
        "veo-3.1-generate-preview",
        "A cinematic shot of a majestic lion in the savannah.",
        nil,
        nil,
    )

    // This loop checks the job status every 10 seconds.
    for !operation.Done {
        time.Sleep(10 * time.Second)
        // Refresh the operation object to get the latest status.
        operation, _ = client.Operations.GetVideosOperation(ctx, operation, nil)
    }

    // Once done, the result is in operation.Response.
    // ... process and download your video ...
}
```

{% /tab %}
{% tab label="Java" filename="sample.java" %}

```java
import com.google.genai.Client;
import com.google.genai.types.GenerateVideosOperation;

Client client = new Client();

// After starting the job, you get an operation object.
GenerateVideosOperation operation =
    client.models.generateVideos(
        "veo-3.1-generate-preview",
        "A cinematic shot of a majestic lion in the savannah.",
        null,
        null);

// Alternatively, you can use operation.name to construct the operation.
operation = GenerateVideosOperation.builder().name(operation.name().get()).build();

// This loop checks the job status every 10 seconds.
while (!operation.done().orElse(false)) {
  Thread.sleep(10000);
  // Refresh the operation object to get the latest status.
  operation = client.operations.getVideosOperation(operation, null);
}

// Once done, the result is in operation.response().
// ... process and download your video ...
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Note: This script uses jq to parse the JSON response.
# GEMINI API Base URL
BASE_URL="https://generativelanguage.googleapis.com/v1beta"

# Send request to generate video and capture the operation name into a variable.
operation_name=$(curl -s "${BASE_URL}/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "instances": [{
        "prompt": "A cinematic shot of a majestic lion in the savannah."
      }
    ]
  }' | jq -r .name)

# This loop checks the job status every 10 seconds.
while true; do
  # Get the full JSON status and store it in a variable.
  status_response=$(curl -s -H "x-goog-api-key: $GEMINI_API_KEY" "${BASE_URL}/${operation_name}")

  # Check the "done" field from the JSON stored in the variable.
  is_done=$(echo "${status_response}" | jq .done)

  if [ "${is_done}" = "true" ]; then
    # Once done, the result is in status_response.
    # ... process and download your video ...
    echo "Video generation complete."
    break
  fi
  # Wait for 10 seconds before checking again.
  echo "Waiting for video generation to complete..."
  sleep 10
done
```

{% /tab %}
{% /tabs %}
## Veo API parameters and specifications {% id="veo-model-parameters" %}

These are the parameters you can set in your API request to control the video
generation process.

| Parameter | Veo 3.1 & Veo 3.1 Fast | Veo 3.1 Lite | Veo 3 & Veo 3 Fast |
| :--- | :--- | :--- | :--- |
| Instances |  |  |  |
| `prompt`: The text description for the video. Supports audio cues. | `string` | `string` | `string` |
| `image`: An initial image to animate. | `Image` object | `Image` object | `Image` object |
| `lastFrame`: The final image for an interpolation video to transition. Must be used in combination with the `image` parameter. | `Image` object | `Image` object | `Image` object |
| `referenceImages`: Up to three images to be used as style and content references. | `VideoGenerationReferenceImage` object | `n/a` object | n/a |
| `video`: Video to be used for video extension. | `Video` object from a previous generation | n/a | n/a |
| Parameters |  |  |  |
| `aspectRatio`: The video's aspect ratio. | `"16:9"` (default), `"9:16"` | `"16:9"` (default), `"9:16"` | `"16:9"` (default), `"9:16"` |
| `durationSeconds`: Length of the generated video. | `"4"`, `"6"`, `"8"`. Must be "8" when using extension, reference images or with 1080p and 4k resolutions | `"4"`, `"6"`, `"8"`. Must be "8" when using reference images or with 1080p | `"4"`, `"6"`, `"8"`. Must be "8" when using extension, reference images or with 1080p and 4k resolutions |
| `personGeneration`: Controls the generation of people. (See [Limitations](/docs/veo#limitations) for region restrictions) | Text-to-video &amp; Extension: `"allow_all"` only Image-to-video, Interpolation, &amp; Reference images: `"allow_adult"` only | Text-to-video: `"allow_all"` only Image-to-video, Interpolation, &amp; Reference images: `"allow_adult"` only | Text-to-video: `"allow_all"` only Image-to-video: `"allow_adult"` only |
| `resolution`: The video's resolution. | `"720p"` (default), `"1080p"` (only supports 8s duration), `"4k"` (only supports 8s duration) `"720p"` only for extension | `"720p"` (default), `"1080p"` (only supports 8s duration) | `"720p"` (default), `"1080p"` (only supports 8s duration), `"4k"` (only supports 8s duration) `"720p"` only for extension |

Note that the `seed` parameter is also available for Veo 3 models.
It doesn't guarantee determinism, but slightly improves it.

## Model features {% id="model-features" %}

| Feature | Veo 3.1 & Veo 3.1 Fast | Veo 3.1 Lite | Veo 3 & Veo 3 Fast |
| :--- | :--- | :--- | :--- |
| **Audio:** Natively generates audio with video. | ✔️ Always on | ✔️ Always on | ✔️ Always on |
| **Input modalities:** The type of input used for generation. | Text-to-Video, Image-to-Video, Video-to-Video | Text-to-Video, Image-to-Video | Text-to-Video, Image-to-Video |
| **Resolution:** The output resolution of the video. | 720p, 1080p (8s length only), 4k (8s length only) 720p only when using video extension. | 720p, 1080p (8s length only) | 720p &amp; 1080p (16:9 only) |
| **Frame rate:** The output frame rate of the video. | 24fps | 24fps | 24fps |
| **Video duration:** Length of the generated video. | 8 seconds, 6 seconds, 4 seconds 8 seconds only if 1080p or 4k or using reference images | 8 seconds, 6 seconds, 4 seconds 8 seconds only if 1080p or using reference images | 8 seconds |
| **Videos per request:** Number of videos generated per request. | 1 | 1 | 1 |
| **Status:** Model availability | [Preview](/docs/models#preview) | [Preview](/docs/models#preview) | [Stable](/docs/models#stable) |

## Limitations {% id="limitations" %}

* **Multi-video prompting:** Referencing or reasoning across multiple videos is not currently supported. Attempting multi-video prompting may result in degraded model performance or unexpected outputs.
* **Language support:** English (EN) is fully supported, but other languages have not been evaluated, so they may work but results can vary.
* **Request latency:** Min: 11 seconds; Max: 6 minutes (during peak hours).
* **Regional limitations:** In EU, UK, CH, MENA locations, `allow_adult` is
    the only allowed value for `personGeneration`.
* **Video retention:** Generated videos are stored on the server for 2 days,
    after which they are removed. To save a local copy, you must download your
    video within 2 days of generation. Extended videos are treated as newly
    generated videos.
* **Watermarking:** Videos created by Veo are watermarked using [SynthID](https://deepmind.google/technologies/synthid/), our tool for watermarking
    and identifying AI-generated content. Videos can be verified using the
    [SynthID](https://deepmind.google/science/synthid/) verification platform.
* **Safety:** Generated videos are passed through safety filters and
    memorization checking processes that help mitigate privacy, copyright and
    bias risks.
* **Audio error:** Veo 3.1 will sometimes block a video from generating
    because of safety filters or other processing issues with the audio. You
    will not be charged if your video is blocked from generating.

## Veo prompt guide {% id="prompt-guide" %}

This section contains examples of videos you can create using Veo, and shows you
how to modify prompts to produce distinct results.

### Safety filters {% id="safety-filters" %}

Veo applies safety filters across Gemini to help ensure that
generated videos and uploaded photos don't contain offensive content.
Prompts that violate our [terms and guidelines](/docs/usage-policies#abuse-monitoring) are blocked.

### Prompt writing basics {% id="basics" %}

Good prompts are descriptive and clear. To get the most out of Veo, start with
identifying your core idea, refine your idea by adding keywords and modifiers,
and incorporate video-specific terminology into your prompts.

The following elements should be included in your prompt:

* **Subject**: The object, person, animal, or scenery that you want in your
   video, such as *cityscape*, *nature*, *vehicles*, or *puppies*.
* **Action**: What the subject is doing (for example, *walking*, *running*, or
   *turning their head*).
* **Style**: Specify creative direction using specific film
   style keywords, such as *sci-fi*, *horror film*, *film noir*, or animated
   styles like *cartoon*.
* **Camera positioning and motion**: \[Optional\] Control the camera's location
  and movement using terms like *aerial view*, *eye-level*, *top-down shot*,
  *dolly shot*, or *worms eye*.
* **Composition**: \[Optional\] How the shot is framed, such as *wide shot*,
   *close-up*, *single-shot* or *two-shot*.
* **Focus and lens effects**: \[Optional\] Use terms like *shallow focus*,
  *deep focus*, *soft focus*, *macro lens*, and *wide-angle lens* to achieve
  specific visual effects.
* **Ambiance**: \[Optional\] How the color and light contribute to the scene,
   such as *blue tones*, *night*, or *warm tones*.

#### More tips for writing prompts {% id="more-tips" %}

* **Use descriptive language**: Use adjectives and adverbs to paint a clear
  picture for Veo.
* **Enhance the facial details**: Specify
  facial details as a focus of the photo like using the word *portrait* in
  the prompt.

*For more comprehensive prompting strategies, visit [Introduction to
prompt design](/docs/prompting-strategies).*

### Prompting for audio {% id="audio" %}

You can provide Veo with cues for sound effects, ambient noise, and dialogue.
The model captures the nuance of these cues to generate a synchronized
soundtrack.

* **Dialogue:** Use quotes for specific speech. (Example: "This must be the
    key," he murmured.)
* **Sound Effects (SFX):** Explicitly describe sounds. (Example: tires
    screeching loudly, engine roaring.)
* **Ambient Noise:** Describe the environment's soundscape. (Example: A faint,
    eerie hum resonates in the background.)

These videos demonstrate prompting Veo 3's audio generation with increasing
levels of detail.

| Prompt | Generated output |
| :--- | :--- |
| **More detail (Dialogue and ambience)** A wide shot of a misty Pacific Northwest forest. Two exhausted hikers, a man and a woman, push through ferns when the man stops abruptly, staring at a tree. Close-up: Fresh, deep claw marks are gouged into the tree's bark. Man: (Hand on his hunting knife) "That's no ordinary bear." Woman: (Voice tight with fear, scanning the woods) "Then what is it?" A rough bark, snapping twigs, footsteps on the damp earth. A lone bird chirps. |  |
| **Less detail (Dialogue)** Paper Cut-Out Animation. New Librarian: "Where do you keep the forbidden books?" Old Curator: "We don't. They keep us." |  |

<p style="text-align: center;">Try out these prompts yourself to hear the audio!

{% button href="https://deepmind.google/models/veo/" variant="primary" %}Try Veo{% /button %}</p>

### Prompting with reference images {% id="use-reference-images" %}

You can use one or more images as inputs to guide your generated videos, using
Veo's [image-to-video](/docs/veo#generate-from-images)
capabilities. Veo uses the input image as the initial frame. Select an image
closest to what you envision as the first scene of your video to animate
everyday objects, bring drawings and paintings to life, and add movement and
sound to nature scenes.

| Prompt | Generated output |
| :--- | :--- |
| **Input image (Generated by Nano Banana)** A hyperrealistic macro photo of tiny, miniature surfers riding ocean waves inside a rustic stone bathroom sink. A vintage brass faucet is running, creating the perpetual surf. Surreal, whimsical, bright natural lighting. |  |
| **Output Video (Generated by Veo 3.1)** A surreal, cinematic macro video. Tiny surfers ride perpetual, rolling waves inside a stone bathroom sink. A running vintage brass faucet generates the endless surf. The camera slowly pans across the whimsical, sunlit scene as the miniature figures expertly carve the turquoise water. |  |

Veo 3.1 lets you [reference images](/docs/veo#reference-images) or
ingredients to direct your generated
video's content. Provide up to three asset images of a single person, character,
or product. Veo preserves the subject's appearance in the output video.

| Prompt | Generated output |
| :--- | :--- |
| **Reference image (Generated by Nano Banana)** A deep sea angler fish lurks in the deep dark water, teeth bared and bait glowing. |  |
| **Reference image (Generated by Nano Banana)** A pink child's princess costume complete with a wand and tiara, on a plain product background. |  |
| **Output Video (Generated by Veo 3.1)** Create a silly cartoon version of the fish wearing the costume, swimming and waving the wand around. |  |

Using Veo 3.1, you can also generate videos by specifying the [first and last
frames](/docs/veo#using-first-and-last-video-frames) of the video.

| Prompt | Generated output |
| :--- | :--- |
| **First image (Generated by Nano Banana)** A high quality photorealistic front image of a ginger cat driving a red convertible racing car on the French riviera coast. |  |
| **Last image (Generated by Nano Banana)** Show what happens when the car takes off from a cliff. |  |
| **Output Video (Generated by Veo 3.1)** Optional |  |

This feature gives you precise control over your shot's composition by letting
you define the starting and ending frame. Upload an image or use a frame from a
previous video generation to make sure your scene begins and concludes exactly
as you envision it.

### Prompting for extension {% id="extend-prompt" %}

To [extend](/docs/veo#extending-veo-videos) your Veo-generated
video with Veo 3.1 (not available for Veo 3.1 Lite), use the video as an input
along with an optional text prompt. Extend finalizes the final second or 24
frames of your video and continues the action.

Note that voice is not able to be effectively extended if it's not present in
the last 1 second of video.

| Prompt | Generated output |
| :--- | :--- |
| **Input video (Generated by Veo 3.1)** The paraglider takes off from the top of the mountain and starts gliding down the mountains overlooking the flower covered valleys below. |  |
| **Output Video (Generated by Veo 3.1)** Extend this video with the paraglider slowly descending. |  |

### Example prompts and output {% id="examples" %}

This section presents several prompts, highlighting how descriptive details can
elevate the outcome of each video.

#### Icicles {% id="icicles" %}

This video demonstrates how you can use the elements of
[prompt writing basics](/docs/veo#basics) in your prompt.

| Prompt | Generated output |
| :--- | :--- |
| Close up shot (composition) of melting icicles (subject) on a frozen rock wall (context) with cool blue tones (ambiance), zoomed in (camera motion) maintaining close-up detail of water drips (action). |  |

#### Man on the phone {% id="man-on-the-phone" %}

These videos demonstrate how you can revise your prompt with increasingly
specific details to get Veo to refine the output to your liking.

| Prompt | Generated output |
| :--- | :--- |
| **Less detail** The camera dollies to show a close up of a desperate man in a green trench coat. He's making a call on a rotary-style wall phone with a green neon light. It looks like a movie scene. |  |
| **More detail** A close-up cinematic shot follows a desperate man in a weathered green trench coat as he dials a rotary phone mounted on a gritty brick wall, bathed in the eerie glow of a green neon sign. The camera dollies in, revealing the tension in his jaw and the desperation etched on his face as he struggles to make the call. The shallow depth of field focuses on his furrowed brow and the black rotary phone, blurring the background into a sea of neon colors and indistinct shadows, creating a sense of urgency and isolation. |  |

#### Snow leopard {% id="snow-leopard" %}

| Prompt | Generated output |
| :--- | :--- |
| **Simple prompt:** A cute creature with snow leopard-like fur is walking in winter forest, 3D cartoon style render. |  |
| **Detailed prompt:** Create a short 3D animated scene in a joyful cartoon style. A cute creature with snow leopard-like fur, large expressive eyes, and a friendly, rounded form happily prances through a whimsical winter forest. The scene should feature rounded, snow-covered trees, gentle falling snowflakes, and warm sunlight filtering through the branches. The creature's bouncy movements and wide smile should convey pure delight. Aim for an upbeat, heartwarming tone with bright, cheerful colors and playful animation. |  |

### Examples by writing elements {% id="element-examples" %}

These examples show you how to refine your prompts by each basic element.

#### Subject and context {% id="subject" %}

Specify the main focus (subject) and the background or environment (context).

| Prompt | Generated output |
| :--- | :--- |
| An architectural rendering of a white concrete apartment building with flowing organic shapes, seamlessly blending with lush greenery and futuristic elements |  |
| A satellite floating through outer space with the moon and some stars in the background. |  |

#### Action {% id="action" %}

Specify what the subject is doing (e.g., walking, running, or turning their
head).

| Prompt | Generated output |
| :--- | :--- |
| A wide shot of a woman walking along the beach, looking content and relaxed towards the horizon at sunset. |  |

#### Style {% id="style" %}

Add keywords to steer the generation toward a specific aesthetic (e.g., surreal,
vintage, futuristic, film noir).

| Prompt | Generated output |
| :--- | :--- |
| Film noir style, man and woman walk on the street, mystery, cinematic, black and white. |  |

#### Camera motion and composition {% id="camera-motion" %}

Specify how the camera moves (POV shot, aerial view, tracking drone view) and
how the shot is framed (wide shot, close-up, low angle).

| Prompt | Generated output |
| :--- | :--- |
| A POV shot from a vintage car driving in the rain, Canada at night, cinematic. |  |
| Extreme close-up of a an eye with city reflected in it. |  |

#### Ambiance {% id="ambiance" %}

Color palettes and lighting influence the mood. Try terms like "muted orange
warm tones," "natural light," "sunrise," or "cool blue tones."

| Prompt | Generated output |
| :--- | :--- |
| A close-up of a girl holding adorable golden retriever puppy in the park, sunlight. |  |
| Cinematic close-up shot of a sad woman riding a bus in the rain, cool blue tones, sad mood. |  |

### Aspect ratios {% id="aspect-ratios" %}

Veo lets you specify the aspect ratio for your video.

| Prompt | Generated output |
| :--- | :--- |
| **Widescreen (16:9)** Create a video with a tracking drone view of a man driving a red convertible car in Palm Springs, 1970s, warm sunlight, long shadows. |  |
| **Portrait (9:16)** Create a video highlighting the smooth motion of a majestic Hawaiian waterfall within a lush rainforest. Focus on realistic water flow, detailed foliage, and natural lighting to convey tranquility. Capture the rushing water, misty atmosphere, and dappled sunlight filtering through the dense canopy. Use smooth, cinematic camera movements to showcase the waterfall and its surroundings. Aim for a peaceful, realistic tone, transporting the viewer to the serene beauty of the Hawaiian rainforest. |  |

## Model versions {% id="model-versions" %}

Check out the [Pricing](/docs/pricing) page and
[Rate limits](https://aistudio.google.com/rate-limit) for more Veo
model-specific usage details.

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_veo.md" /%}

Veo Fast versions allow developers to create videos with sound while maintaining
high quality and optimizing for speed and business use cases. They're ideal for
backend services that programmatically generate ads, tools for rapid A/B testing
of creative concepts, or apps that need to quickly produce social media content.

## What's next {% id="whats-next" %}

* Get started with the Veo 3.1 API by experimenting in the [Veo Quickstart Colab](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_Veo.ipynb)
and the [Veo 3.1 applet](https://aistudio.google.com/apps/bundled/veo_studio).

* Learn how to write even better prompts with our [Introduction to prompt design](/docs/prompting-strategies).

# Generate and edit videos with Gemini Omni Flash
Source: https://aistudio.google.com/docs/omni
Description: Get started with Gemini Omni Flash for fast, conversational video generation and editing using the Interactions API.

Gemini Omni Flash (`gemini-omni-1.1-flash`) is a high-performance multimodal
model designed for high-speed video generation, editing, and cinematic control.
Gemini Omni is built on the following core capabilities that distinguish it from
previous video models:

*   **Native multimodality:** it processes text, image, audio, and video
    simultaneously, giving you more cohesive, consistent, and controllable
    output.
*   **Conversational editing:** enabled by the [Interactions
    API](/docs/interactions-overview), it lets you iteratively refine
    and edit your videos through natural language conversation. Describe what
    you want to change, and the model applies the edit while preserving the
    parts of the video you want to keep.
*   **World knowledge:** Gemini Omni combines an understanding of
    physics with Gemini's knowledge of history, science, and cultural context,
    bridging the gap from photorealism to meaningful storytelling.

## Text to video generation {% id="text-to-video-generation" %}

Generate a video from a text prompt. The model generates a video with audio
based on your text description. Write prompts with details like scene description,
camera movement, lighting and mood for best results.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A marble rolling fast on a chain reaction style track, continuous smooth shot."
)
with open("marble.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: 'A marble rolling fast on a chain reaction style track, continuous smooth shot.',
});

if (interaction.output_video?.data) {
  fs.writeFileSync('marble.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(
            InteractionsInput.of(
                "A marble rolling fast on a chain reaction style track, continuous smooth shot."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputVideo().isPresent() && interaction.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(interaction.outputVideo().get().data().get());
  Files.write(Paths.get("marble.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput(
                "A marble rolling fast on a chain reaction style track, continuous smooth shot.",
            ),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputVideo != nil && res.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("marble.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$API_KEY" \
-H "Content-Type: application/json" \
-d '{
 "model": "gemini-omni-1.1-flash",
 "input": "A marble rolling fast on a chain reaction style track, continuous smooth shot."
}'
```
{% /tab %}
{% /tabs %}

{% video id="6DRkXO9nM7g" title="Watch video (Reference)" /%}

### REST response schema {% id="rest-response-schema" %}

The convenience field `interaction.output_video` is **SDK-only**.
Get the video output from the `steps` array when using the REST API directly.

**Raw REST JSON structure:**

```json
{
  "steps": [
    { "type": "user_input", "content": [{"type": "text", "text": "..."}] },
    { "type": "thought", "content": [{"text": "...", "type": "thought"}] },
    {
      "type": "model_output",
      "content": [
        {
          "type": "video",
          "mime_type": "video/mp4",
          "data": "AAAAIGZ0eXBpc29t..." // Base64 encoded video data
        }
      ]
    }
  ],
  "id": "v1_...",
  "status": "completed",
  "model": "gemini-omni-1.1-flash",
  "object": "interaction"
}
```

### Control aspect ratio {% id="control-aspect-ratio" %}

Set the `aspect_ratio` to `"9:16"` to create portrait videos. Landscape (16:9)
is the default.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A futuristic city with neon lights and flying cars, cyberpunk style",
    response_format={
        "type": "video",  # optional
        "aspect_ratio": "9:16"  # Supported values: "9:16", "16:9"
    }
)
with open("example.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: 'A futuristic city with neon lights and flying cars, cyberpunk style',
  response_format: {
    type: 'video', // optional
    aspect_ratio: '9:16' // Supported values: '9:16', '16:9'
  },
});

if (interaction.output_video?.data) {
  fs.writeFileSync('example.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.VideoResponseFormat;
import com.google.genai.gaos.models.interactions.VideoResponseFormatAspectRatio;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

VideoResponseFormat videoFormat =
    VideoResponseFormat.builder()
        .aspectRatio(VideoResponseFormatAspectRatio.of("9:16"))
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(
            InteractionsInput.of(
                "A futuristic city with neon lights and flying cars, cyberpunk style"))
        .responseFormat(CreateModelInteractionResponseFormat.of(ResponseFormat.of(videoFormat)))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputVideo().isPresent() && interaction.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(interaction.outputVideo().get().data().get());
  Files.write(Paths.get("example.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    videoFormat := interactions.VideoResponseFormat{
        AspectRatio: interactions.VideoResponseFormatAspectRatioNineHundredAndSixteen.ToPointer(),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput(
                "A futuristic city with neon lights and flying cars, cyberpunk style",
            ),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(videoFormat),
            )),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputVideo != nil && res.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("example.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$API_KEY" \
-H "Content-Type: application/json" \
-d '{
 "model": "gemini-omni-1.1-flash",
 "input": "A futuristic city with neon lights and flying cars, cyberpunk style",
 "response_format": {
   "type": "video",
   "aspect_ratio": "9:16"
 }
}'
```
{% /tab %}
{% /tabs %}

### Output resolution {% id="output-resolution" %}

Control the output resolution of your generated video using the `resolution`
parameter in `response_format`. The default resolution is 720p.

| Value | Description |
| :---- | :---------- |
| `360p` | 360p output resolution |
| `720p` | 720p output resolution (default) |
| `1080p` | 1080p output (upscaled) |
| `4k` | 4K output (upscaled) |

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A drone shot of a mountain landscape at sunrise.",
    response_format={
        "type": "video",
        "resolution": "1080p",
    },
)
with open("hires.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: 'A drone shot of a mountain landscape at sunrise.',
  response_format: {
    type: 'video',
    resolution: '1080p',
  },
});

if (interaction.output_video?.data) {
  fs.writeFileSync('hires.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Resolution;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.VideoResponseFormat;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

VideoResponseFormat videoFormat =
    VideoResponseFormat.builder()
        .resolution(Resolution.of("1080p"))
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(InteractionsInput.of("A drone shot of a mountain landscape at sunrise."))
        .responseFormat(CreateModelInteractionResponseFormat.of(ResponseFormat.of(videoFormat)))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputVideo().isPresent() && interaction.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(interaction.outputVideo().get().data().get());
  Files.write(Paths.get("hires.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    videoFormat := interactions.VideoResponseFormat{
        Resolution: interactions.ResolutionOneThousandAndEightyp.ToPointer(),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput("A drone shot of a mountain landscape at sunrise."),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(videoFormat),
            )),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputVideo != nil && res.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("hires.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$API_KEY" \
-H "Content-Type: application/json" \
-d '{
 "model": "gemini-omni-1.1-flash",
 "input": "A drone shot of a mountain landscape at sunrise.",
 "response_format": {
   "type": "video",
   "resolution": "1080p"
 }
}'
```
{% /tab %}
{% /tabs %}

{% video src="https://storage.googleapis.com/generativeai-downloads/videos/omni_misty_mountains_1080p.mp4" type="video/mp4" /%}

## Image to video generation {% id="image-to-video-generation" %}

You can provide a reference image with your text prompt. Depending on your
prompt, the model will decide
how to use the image. This is useful for bringing product shots, illustrations,
or photographs to life.

The following example shows how to use the reference image of a drawing of a
fish jumping out of water:

![Drawing of a fish jumping out of water](/googledevai/static/gemini-api/docs/images/fish-jumping-inputimage.png)

With the following prompt:

```none
turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video
```

To generate a realistic video of the drawing.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "image", "data": base64_image, "mime_type": "image/jpeg"},
        {"type": "text", "text": "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video"}
    ],
)
with open("clownfish.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: [
    { type: 'image', data: base64Image, mime_type: 'image/jpeg' },
    { type: 'text', text: 'turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video' }
  ]
});

if (interaction.output_video?.data) {
  fs.writeFileSync('clownfish.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("drawing.jpg"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);

Content imageContent =
    ImageContent.builder()
        .data(base64Image)
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

Content textContent =
    TextContent.builder()
        .text(
            "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video")
        .build();

List<Content> contents = Arrays.asList(imageContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputVideo().isPresent() && interaction.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(interaction.outputVideo().get().data().get());
  Files.write(Paths.get("clownfish.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("drawing.jpg")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64Image),
            MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputVideo != nil && res.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("clownfish.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$API_KEY" \
-H "Content-Type: application/json" \
-d '{
 "model": "gemini-omni-1.1-flash",
 "input": [
   {"type": "image", "data": "'"$BASE64_IMAGE"'", "mime_type": "image/jpeg"},
   {"type": "text", "text": "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video"}
 ]
}'
```
{% /tab %}
{% /tabs %}

{% video id="zTNIIZ0X7mA" title="Watch video (Reference)" /%}

{% callout type="note" %}
For best results with image-to-video, use high-resolution images and
provide specific motion descriptions. Vague prompts like "make it move" produce
less compelling results than detailed descriptions of the camera movement,
subject motion, and environmental effects.
{% /callout %}

### First and last frame interpolation {% id="first-and-last-frame-interpolation" %}

Gemini Omni Flash supports video interpolation, allowing you to generate a
video that transitions smoothly between a starting image (first frame) and an
ending image (last frame).

Provide two images in the `input` list and describe the desired transition in
your prompt. The model will animate the scene from the first frame to the
ending frame.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "image", "data": first_frame_b64, "mime_type": "image/jpeg"},
        {"type": "image", "data": last_frame_b64, "mime_type": "image/jpeg"},
        {"type": "text", "text": "A smooth cinematic transition from a lush green forest at sunrise to a snowy forest under a starry night sky."}
    ],
)
with open("interpolation.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({});

const firstFrameB64 = '...';
const lastFrameB64 = '...';

const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: [
    { type: 'image', data: firstFrameB64, mime_type: 'image/jpeg' },
    { type: 'image', data: lastFrameB64, mime_type: 'image/jpeg' },
    { type: 'text', text: 'A smooth cinematic transition from a lush green forest at sunrise to a snowy forest under a starry night sky.' }
  ]
});

if (interaction.output_video?.data) {
  fs.writeFileSync('interpolation.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

String firstFrameB64 =
    Base64.getEncoder().encodeToString(Files.readAllBytes(Paths.get("first_frame.jpg")));
String lastFrameB64 =
    Base64.getEncoder().encodeToString(Files.readAllBytes(Paths.get("last_frame.jpg")));

Content firstFrame =
    ImageContent.builder()
        .data(firstFrameB64)
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

Content lastFrame =
    ImageContent.builder()
        .data(lastFrameB64)
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

Content prompt =
    TextContent.builder()
        .text(
            "A smooth cinematic transition from a lush green forest at sunrise to a snowy forest under a starry night sky.")
        .build();

List<Content> contents = Arrays.asList(firstFrame, lastFrame, prompt);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputVideo().isPresent() && interaction.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(interaction.outputVideo().get().data().get());
  Files.write(Paths.get("interpolation.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    firstBytes, err := os.ReadFile("first_frame.jpg")
    if err != nil {
        log.Fatal(err)
    }
    lastBytes, err := os.ReadFile("last_frame.jpg")
    if err != nil {
        log.Fatal(err)
    }

    firstFrameB64 := base64.StdEncoding.EncodeToString(firstBytes)
    lastFrameB64 := base64.StdEncoding.EncodeToString(lastBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(firstFrameB64),
            MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
        }),
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(lastFrameB64),
            MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "A smooth cinematic transition from a lush green forest at sunrise to a snowy forest under a starry night sky.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputVideo != nil && res.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("interpolation.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$API_KEY" \
-H "Content-Type: application/json" \
-d '{
 "model": "gemini-omni-1.1-flash",
 "input": [
   {"type": "image", "data": "'"$FIRST_FRAME_B64"'", "mime_type": "image/jpeg"},
   {"type": "image", "data": "'"$LAST_FRAME_B64"'", "mime_type": "image/jpeg"},
   {"type": "text", "text": "A smooth cinematic transition from a lush green forest at sunrise to a snowy forest under a starry night sky."}
 ]
}'
```
{% /tab %}
{% /tabs %}

{% video src="https://storage.googleapis.com/generativeai-downloads/videos/omni_keyframe_interpolation.mp4" type="video/mp4" /%}

### Subject reference {% id="subject-reference" %}

You can generate a video incorporating specific subjects provided as reference images.
For example, the following code shows how to provide 2 images of a cat and yarn
to generate a video of the cat playing with the yarn.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "image", "data": cat_b64, "mime_type": "image/png"},
        {"type": "image", "data": yarn_b64, "mime_type": "image/png"},
        {"type": "text", "text": "A cat playfully batting at a ball of yarn."}
    ],
)
with open("cat.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: [
    { type: 'image', data: catData, mime_type: 'image/png' },
    { type: 'image', data: yarnData, mime_type: 'image/png' },
    { type: 'text', text: 'A cat playfully batting at a ball of yarn.' }
  ]
});

if (interaction.output_video?.data) {
  fs.writeFileSync('cat.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

String catB64 = Base64.getEncoder().encodeToString(Files.readAllBytes(Paths.get("cat.png")));
String yarnB64 = Base64.getEncoder().encodeToString(Files.readAllBytes(Paths.get("yarn.png")));

Content catImage =
    ImageContent.builder()
        .data(catB64)
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();

Content yarnImage =
    ImageContent.builder()
        .data(yarnB64)
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();

Content textContent =
    TextContent.builder()
        .text("A cat playfully batting at a ball of yarn.")
        .build();

List<Content> contents = Arrays.asList(catImage, yarnImage, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputVideo().isPresent() && interaction.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(interaction.outputVideo().get().data().get());
  Files.write(Paths.get("cat.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    catBytes, err := os.ReadFile("cat.png")
    if err != nil {
        log.Fatal(err)
    }
    yarnBytes, err := os.ReadFile("yarn.png")
    if err != nil {
        log.Fatal(err)
    }

    catB64 := base64.StdEncoding.EncodeToString(catBytes)
    yarnB64 := base64.StdEncoding.EncodeToString(yarnBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(catB64),
            MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(yarnB64),
            MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "A cat playfully batting at a ball of yarn.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputVideo != nil && res.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("cat.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$API_KEY" \
-H "Content-Type: application/json" \
-d '{
 "model": "gemini-omni-1.1-flash",
 "input": [
   {"type": "image", "data": "'"$CAT_B64"'", "mime_type": "image/png"},
   {"type": "image", "data": "'"$YARN_B64"'", "mime_type": "image/png"},
   {"type": "text", "text": "A cat playfully batting at a ball of yarn."}
 ]
}'
```
{% /tab %}
{% /tabs %}

### Tasks parameter {% id="tasks-parameter" %}

Use the `task` parameter in the `video_config` to explicitly specify the intended
behavior, for example if you want the model to generate a video from an image,
you can set the parameter to `image_to_video`. If this is not set, the
model will infer what you want from the prompt.

{% callout type="tip" %}
We recommend relying primarily on prompting and using the `task` parameter only when prompting doesn't work and you need to help the model understand which mode it should use, as using the `task` field adds some constraints.
{% /callout %}

The following are allowed values:

*   `text_to_video`
*   `image_to_video`
*   `reference_to_video`
*   `edit`
*   `extend`

The following example shows how to set this for the previously shown image
to video example.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "image", "data": base64_image, "mime_type": "image/jpeg"},
        {"type": "text", "text": "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video"}
    ],
    generation_config={
      "video_config": {
        "task": "image_to_video",
      }
    },
)
with open("example.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from 'fs';
const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: [
    { type: 'image', data: base64Image, mime_type: 'image/jpeg' },
    { type: 'text', text: 'turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video' }
  ],
  generation_config: {
    video_config: {
      task: 'image_to_video',
    }
  }
});

if (interaction.output_video?.data) {
  fs.writeFileSync('example.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Task;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoConfig;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("drawing.jpg"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);

Content imageContent =
    ImageContent.builder()
        .data(base64Image)
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

Content textContent =
    TextContent.builder()
        .text(
            "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video")
        .build();

List<Content> contents = Arrays.asList(imageContent, textContent);

GenerationConfig generationConfig =
    GenerationConfig.builder()
        .videoConfig(VideoConfig.builder().task(Task.IMAGE_TO_VIDEO).build())
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(InteractionsInput.ofContent(contents))
        .generationConfig(generationConfig)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputVideo().isPresent() && interaction.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(interaction.outputVideo().get().data().get());
  Files.write(Paths.get("example.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("drawing.jpg")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.ImageContent{
            Data:     genai.Ptr(base64Image),
            MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video",
        }),
    }

    generationConfig := &interactions.GenerationConfig{
        VideoConfig: &interactions.VideoConfig{
            Task: interactions.TaskImageToVideo.ToPointer(),
        },
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:            interactions.Model("gemini-omni-1.1-flash"),
            Input:            interactions.NewInteractionsInput(contents),
            GenerationConfig: generationConfig,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputVideo != nil && res.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("example.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
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-omni-1.1-flash",
    "input": [
      {
        "type": "image",
        "data": "'"$BASE64_IMAGE"'",
        "mime_type": "image/jpeg"
      },
      {
        "type": "text",
        "text": "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video"
      }
    ],
    "generation_config": {
      "video_config": {
        "task": "image_to_video"
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## Stateful video editing {% id="stateful-video-editing" %}

Generate a video and edit it iteratively using follow-up prompts. Each turn
builds on the previous result. The model remembers the video context, applying
your changes while preserving elements you did not mention. Use the
`previous_interaction_id` to track the conversation history and the generated
video state without re-uploading the previous video.

{% callout type="note" %}
See [Limitations](/docs/omni#limitations) for detailed list of restrictions for
      video editing.
{% /callout %}

The following example demonstrates how to generate a first video then edit it:

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

# Turn 1: Generate initial video
res1 = client.interactions.create(model="gemini-omni-1.1-flash", input="A woman playing violin outdoors.")

# Turn 2: Edit the previous video
res2 = client.interactions.create(
    model="gemini-omni-1.1-flash",
    previous_interaction_id=res1.id,
    input="Make the violin invisible."
)
with open("example.mp4", "wb") as f:
    f.write(base64.b64decode(res2.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({});

// Turn 1: Generate initial video
const res1 = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: 'A woman playing violin outdoors.',
});

// Turn 2: Edit the previous video
const res2 = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  previous_interaction_id: res1.id,
  input: 'Make the violin invisible.',
});

if (res2.output_video?.data) {
  if (interaction.output_video?.data) {
    fs.writeFileSync('example.mp4', Buffer.from(interaction.output_video.data, 'base64'));
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

// Turn 1: Generate initial video
CreateModelInteraction turn1Params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(InteractionsInput.of("A woman playing violin outdoors."))
        .build();

Interaction res1 =
    client.interactions.create(CreateInteractionRequestBody.of(turn1Params)).interaction().get();

// Turn 2: Edit the previous video
CreateModelInteraction turn2Params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .previousInteractionId(res1.id().get())
        .input(InteractionsInput.of("Make the violin invisible."))
        .build();

Interaction res2 =
    client.interactions.create(CreateInteractionRequestBody.of(turn2Params)).interaction().get();

if (res2.outputVideo().isPresent() && res2.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(res2.outputVideo().get().data().get());
  Files.write(Paths.get("example.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Turn 1: Generate initial video
    res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput("A woman playing violin outdoors."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Turn 2: Edit the previous video
    res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-omni-1.1-flash"),
            PreviousInteractionID: res1.Interaction.ID,
            Input:                 interactions.NewInteractionsInput("Make the violin invisible."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res2.Interaction.OutputVideo != nil && res2.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res2.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("example.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$API_KEY" \
-H "Content-Type: application/json" \
-d '{
 "model": "gemini-omni-1.1-flash",
 "previous_interaction_id": "'"$PREVIOUS_ID"'",
 "input": "Make the violin invisible."
}'
```
{% /tab %}
{% /tabs %}

Example of an initial video:

{% video id="9yk4HuZmF0g" title="Watch video (Reference)" /%}

Example of an edited video:

{% video id="U5GXcvq6GZY" title="Watch video (Reference)" /%}

Each turn in the conversation produces a new video. The model understands
context from prior turns, letting you make incremental changes like adjusting
lighting, and swapping backgrounds, without re-describing the entire scene.

### Edit your own videos {% id="edit-your-own-videos" %}

Upload your videos using the [Files API](/docs/files) to edit them
with Gemini Omni Flash.

{% callout type="note" %}
Editing uploaded videos is not available in all regions. See [Limitations](/docs/omni#limitations)
      section for details.
{% /callout %}

The following example shows how to edit the following original video:

{% video id="lw9MJDx9Zas" title="Watch video (Reference)" /%}

{% tabs %}
{% tab label="Python" %}
```python
import time
import base64
from google import genai

client = genai.Client()

# Upload video using the file API
video_file = client.files.upload(file="Video.mp4")

while video_file.state == "PROCESSING":
    print('Waiting for video to be processed.')
    time.sleep(10)
    video_file = client.files.get(name=video_file.name)

if video_file.state == "FAILED":
  raise ValueError(video_file.state)
print(f'Video processing complete: ' + video_file.uri)

# Edit your video
interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "video", "uri": video_file.uri},
        {"type": "text", "text": "When the person touches the mirror, make the mirror ripple beautifully like liquid, and the person's arm turns into reflective mirror material"}
    ],
)
with open("example.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({});

// Upload video using the file API
let videoFile = await ai.files.upload({
  file: 'Video.mp4',
});

while (videoFile.state === 'PROCESSING') {
  console.log('Waiting for video to be processed.');
  await new Promise(r => setTimeout(r, 10000));
  videoFile = await ai.files.get({ name: videoFile.name || '' });
}

if (videoFile.state === 'FAILED') {
  throw new Error(videoFile.state);
}
console.log('Video processing complete: ' + videoFile.uri);

// Edit your video
const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: [
    { type: 'video', uri: videoFile.uri },
    { type: 'text', text: "When the person touches the mirror, make the mirror ripple beautifully like liquid, and the person's arm turns into reflective mirror material" }
  ],
});

if (interaction.output_video?.data) {
  fs.writeFileSync('example.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.FileState;
import com.google.genai.types.UploadFileConfig;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

// Upload video using the file API
File videoFile =
    client.files.upload("Video.mp4", UploadFileConfig.builder().mimeType("video/mp4").build());

while (videoFile.state().isPresent()
    && videoFile.state().get().knownEnum() == FileState.Known.PROCESSING) {
  System.out.println("Waiting for video to be processed.");
  Thread.sleep(10000);
  videoFile = client.files.get(videoFile.name().get(), null);
}

if (videoFile.state().isPresent()
    && videoFile.state().get().knownEnum() == FileState.Known.FAILED) {
  throw new IllegalStateException("Video processing failed: " + videoFile.state().get());
}
System.out.println("Video processing complete: " + videoFile.uri().orElse(""));

// Edit your video
Content videoContent = VideoContent.builder().uri(videoFile.uri().get()).build();
Content textContent =
    TextContent.builder()
        .text(
            "When the person touches the mirror, make the mirror ripple beautifully like liquid, and the person's arm turns into reflective mirror material")
        .build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputVideo().isPresent() && interaction.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(interaction.outputVideo().get().data().get());
  Files.write(Paths.get("example.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Upload video using the file API
    videoFile, err := client.Files.UploadFromPath(ctx, "Video.mp4", &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    })
    if err != nil {
        log.Fatal(err)
    }

    for videoFile.State == genai.FileStateProcessing {
        fmt.Println("Waiting for video to be processed.")
        time.Sleep(10 * time.Second)
        videoFile, err = client.Files.Get(ctx, videoFile.Name, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    if videoFile.State == genai.FileStateFailed {
        log.Fatalf("Video processing failed: %s", videoFile.State)
    }
    fmt.Printf("Video processing complete: %s\n", videoFile.URI)

    // Edit your video
    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI: genai.Ptr(videoFile.URI),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "When the person touches the mirror, make the mirror ripple beautifully like liquid, and the person's arm turns into reflective mirror material",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputVideo != nil && res.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("example.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
#!/bin/bash
VIDEO_B64=$(encode_file "$VIDEO_FILE")

curl -sS -w "\n[HTTP %{http_code}]\n" "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d @- <<EOF > video_editing_response.json
{
  "model": "gemini-omni-1.1-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "mime_type": "video/mp4",
          "data": "$VIDEO_B64"
        },
        {
          "type": "text",
          "text": "When the person touches the mirror, make the mirror ripple beautifully like liquid, and the person's arm turns into reflective mirror material"
        }
      ]
    }
  ],
  "response_format": { "type": "video" }
}
EOF
```
{% /tab %}
{% /tabs %}

Example of an edited video:

{% video id="Bn-6vCl1wgQ" title="Watch video (Reference)" /%}

{% callout type="note" %}
You can also pass the data directly in base64, but since videos can be
quite big we recommend using the File API.
{% /callout %}

## Retrieving videos with an URI {% id="retrieving-videos-with-an-uri" %}

Use the `delivery="uri"` parameter in
`response_format` to retrieve generated videos that are larger than 4MB.
This returns a Google-hosted URI that you can poll until the
video is `ACTIVE` before downloading.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

# 1. Request video via URI delivery
interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A beautiful sunset.",
    response_format={"type": "video", "delivery": "uri"}
)

# 2. Extract file name and poll for ACTIVE state
video_output = interaction.output_video
file_name = video_output.uri.split("/")[-1] # Extract ID

print("Waiting for video processing...")
while True:
    f_info = client.files.get(name=f"files/{file_name}")
    if f_info.state.name == "ACTIVE":
        break
    elif f_info.state.name == "FAILED":
        raise RuntimeError("Generation failed.")
    time.sleep(5)

# 3. Download the final video
client.files.download(file=video_output.uri, destination="output.mp4")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});

// 1. Request video using URI delivery
const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: 'A beautiful sunset.',
  response_format: { type: 'video', delivery: 'uri' },
});

// 2. Extract filename and poll for ACTIVE state
const videoOutput = interaction.output_video;
const fileId = videoOutput?.uri?.match(/files\/([a-zA-Z0-9]+)/)?.[1] || '';
const name = `files/${fileId}`;

console.log("Waiting for video processing...");
while (true) {
  const fInfo = await ai.files.get({ name });
  if (fInfo.state === 'ACTIVE') break;
  if (fInfo.state === 'FAILED') throw new Error("Generation failed.");
  await new Promise(r => setTimeout(r, 5000));
}

// 3. Download the final video
await ai.files.download({
  file: name,
  downloadPath: 'output.mp4',
});
console.log("💾 Saved video to output.mp4");
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoResponseFormat;
import com.google.genai.gaos.models.interactions.VideoResponseFormatDelivery;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.FileState;

Client client = new Client();

// 1. Request video using URI delivery
VideoResponseFormat videoFormat =
    VideoResponseFormat.builder()
        .delivery(VideoResponseFormatDelivery.URI)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(InteractionsInput.of("A beautiful sunset."))
        .responseFormat(CreateModelInteractionResponseFormat.of(ResponseFormat.of(videoFormat)))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

// 2. Extract filename and poll for ACTIVE state
VideoContent videoOutput = interaction.outputVideo().get();
String uri = videoOutput.uri().get();
String[] parts = uri.split("/");
String fileName = parts[parts.length - 1];

System.out.println("Waiting for video processing...");
while (true) {
  File fileInfo = client.files.get("files/" + fileName, null);
  if (fileInfo.state().isPresent()
      && fileInfo.state().get().knownEnum() == FileState.Known.ACTIVE) {
    break;
  } else if (fileInfo.state().isPresent()
      && fileInfo.state().get().knownEnum() == FileState.Known.FAILED) {
    throw new RuntimeException("Generation failed.");
  }
  Thread.sleep(5000);
}

// 3. Download the final video
client.files.download(uri, "output.mp4", null);
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "strings"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. Request video using URI delivery
    videoFormat := interactions.VideoResponseFormat{
        Delivery: interactions.VideoResponseFormatDeliveryURI.ToPointer(),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput("A beautiful sunset."),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(videoFormat),
            )),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Extract filename and poll for ACTIVE state
    uri := *res.Interaction.OutputVideo.URI
    parts := strings.Split(uri, "/")
    fileName := parts[len(parts)-1]

    fmt.Println("Waiting for video processing...")
    var fileInfo *genai.File
    for {
        fileInfo, err = client.Files.Get(ctx, "files/"+fileName, nil)
        if err != nil {
            log.Fatal(err)
        }
        if fileInfo.State == genai.FileStateActive {
            break
        } else if fileInfo.State == genai.FileStateFailed {
            log.Fatal("Generation failed.")
        }
        time.Sleep(5 * time.Second)
    }

    // 3. Download the final video
    videoBytes, err := client.Files.Download(ctx, genai.NewDownloadURIFromFile(fileInfo), nil)
    if err != nil {
        log.Fatal(err)
    }
    if err := os.WriteFile("output.mp4", videoBytes, 0644); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
#!/bin/bash

# 1. Initial request to generate the video
RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$API_KEY" \
-H "Content-Type: application/json" \
-d '{
 "model": "gemini-omni-1.1-flash",
 "input": "A beautiful sunset over a calm ocean.",
 "response_format": {"type": "video", "delivery": "uri"}
}')

# Extract FILE_ID from the URI (e.g., "files/abc-123" -> "abc-123")
FILE_URI=$(echo $RESPONSE | jq -r '.output_video.uri')
FILE_ID=$(echo $FILE_URI | cut -d'/' -f2)

echo "Video requested (ID: $FILE_ID). Waiting for processing..."

# 2. Polling loop
while true; do
 # Get current file status
 STATUS_JSON=$(curl -s -X GET "https://generativelanguage.googleapis.com/v1beta/files/$FILE_ID?key=$API_KEY")
 STATE=$(echo $STATUS_JSON | jq -r '.state')

 if [ "$STATE" == "ACTIVE" ]; then
   echo "Processing complete! Downloading..."
   break
 elif [ "$STATE" == "FAILED" ]; then
   echo "Error: Generation failed."
   exit 1
 else
   echo "Current state: $STATE... (waiting 5s)"
   sleep 5
 fi
done

# 3. Final download
curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/files/$FILE_ID:download?alt=media&key=$API_KEY" \
--output "output.mp4"

echo "Done! Video saved to output.mp4"
```
{% /tab %}
{% /tabs %}

**Raw REST JSON structure (URI):**

```json
{
  "steps": [
    { "type": "user_input", "content": [{"type": "text", "text": "..."}] },
    { "type": "thought", "content": [{"text": "...", "type": "thought"}] },
    {
      "type": "model_output",
      "content": [
        {
          "type": "video",
          "mime_type": "video/mp4",
          "uri": "https://generativelanguage.googleapis.com/v1beta/files/...:download?alt=media"
        }
      ]
    }
  ],
  "id": "v1_...",
  "status": "completed",
  "model": "gemini-omni-1.1-flash",
  "object": "interaction"
}
```

{% callout type="note" %}
Currently, calling `GET /v1beta/interactions/{id}` returns the video as
inline base64 data in the `data` field, even if the interaction was originally
created with `delivery: "uri"`. The `uri` field is only guaranteed to be present
in the initial creation response or Server-Sent Events (SSE) stream.
{% /callout %}

## Video extension {% id="video-extension" %}

Extend an existing video by generating a seamless continuation at the tail end
of the clip. Describe how you want the video to continue in your prompt, for example
`"Extend this video"` or `"Continue the scene: the camera pans across the mountains"`.
The model analyzes the input video to generate a 3–10 second continuation.

You can extend:

*   **Videos generated by the model (multi-turn)**: Extend a previously generated
    video by referencing its `previous_interaction_id`.
*   **Uploaded videos**: Provide an uploaded video file (via the Files API) along
    with your extension prompt.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

# Upload your video using the Files API
video_file = client.files.upload(file="my_video.mp4")

# Extend the video using prompt-based extension
interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "video", "uri": video_file.uri},
        {"type": "text", "text": "Continue the scene."}
    ],
)
with open("extended.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({});

// Upload your video using the Files API
let videoFile = await ai.files.upload({
  file: 'my_video.mp4',
});

while (videoFile.state === 'PROCESSING') {
  await new Promise(r => setTimeout(r, 10000));
  videoFile = await ai.files.get({ name: videoFile.name || '' });
}

// Extend the video using prompt-based extension
const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: [
    { type: 'video', uri: videoFile.uri },
    { type: 'text', text: 'Continue the scene.' }
  ],
});

if (interaction.output_video?.data) {
  fs.writeFileSync('extended.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

// Upload your video using the Files API
File videoFile =
    client.files.upload(
        "my_video.mp4", UploadFileConfig.builder().mimeType("video/mp4").build());

// Extend the video using prompt-based extension
Content videoContent = VideoContent.builder().uri(videoFile.uri().get()).build();
Content textContent = TextContent.builder().text("Continue the scene.").build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputVideo().isPresent() && interaction.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(interaction.outputVideo().get().data().get());
  Files.write(Paths.get("extended.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Upload your video using the Files API
    videoFile, err := client.Files.UploadFromPath(ctx, "my_video.mp4", &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Extend the video using prompt-based extension
    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI: genai.Ptr(videoFile.URI),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "Continue the scene.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputVideo != nil && res.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("extended.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$API_KEY" -H "Content-Type: application/json" -d '{
 "model": "gemini-omni-1.1-flash",
 "input": [
   {"type": "video", "uri": "'"$VIDEO_URI"'"},
   {"type": "text", "text": "Continue the scene."}
 ]
}'
```
{% /tab %}
{% /tabs %}

{% video src="https://storage.googleapis.com/generativeai-downloads/videos/omni_scene_extension_base.mp4" type="video/mp4" /%}

{% video src="https://storage.googleapis.com/generativeai-downloads/videos/omni_scene_extension_extended.mp4" type="video/mp4" /%}

### Extending with reference media {% id="extending-with-reference-media" %}

You can provide reference images in the `input` array along with your prompt to
introduce new characters or elements into the extended video:

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

# Upload base video and reference image using the Files API
video_file = client.files.upload(file="my_video.mp4")
character_img = client.files.upload(file="character.png")

# Extend the video while introducing the reference character
interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "video", "uri": video_file.uri},
        {"type": "image", "uri": character_img.uri},
        {"type": "text", "text": "Extend this video: have the character shown in <IMAGE_REF_0> enter the scene and wave."}
    ],
)
with open("extended_with_character.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({});

// Upload base video and reference image using the Files API
let videoFile = await ai.files.upload({ file: 'my_video.mp4' });
let characterImg = await ai.files.upload({ file: 'character.png' });

while (videoFile.state === 'PROCESSING' || characterImg.state === 'PROCESSING') {
  await new Promise(r => setTimeout(r, 10000));
  videoFile = await ai.files.get({ name: videoFile.name || '' });
  characterImg = await ai.files.get({ name: characterImg.name || '' });
}

// Extend the video while introducing the reference character
const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: [
    { type: 'video', uri: videoFile.uri },
    { type: 'image', uri: characterImg.uri },
    { type: 'text', text: 'Extend this video: have the character shown in <IMAGE_REF_0> enter the scene and wave.' }
  ],
});

if (interaction.output_video?.data) {
  fs.writeFileSync('extended_with_character.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

// Upload base video and reference image using the Files API
File videoFile =
    client.files.upload(
        "my_video.mp4", UploadFileConfig.builder().mimeType("video/mp4").build());
File characterImg =
    client.files.upload(
        "character.png", UploadFileConfig.builder().mimeType("image/png").build());

// Extend the video while introducing the reference character
Content videoContent = VideoContent.builder().uri(videoFile.uri().get()).build();
Content imageContent = ImageContent.builder().uri(characterImg.uri().get()).build();
Content textContent =
    TextContent.builder()
        .text(
            "Extend this video: have the character shown in <IMAGE_REF_0> enter the scene and wave.")
        .build();

List<Content> contents = Arrays.asList(videoContent, imageContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-omni-1.1-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputVideo().isPresent() && interaction.outputVideo().get().data().isPresent()) {
  byte[] videoBytes = Base64.getDecoder().decode(interaction.outputVideo().get().data().get());
  Files.write(Paths.get("extended_with_character.mp4"), videoBytes);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Upload base video and reference image using the Files API
    videoFile, err := client.Files.UploadFromPath(ctx, "my_video.mp4", &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    })
    if err != nil {
        log.Fatal(err)
    }
    characterImg, err := client.Files.UploadFromPath(ctx, "character.png", &genai.UploadFileConfig{
        MIMEType: "image/png",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Extend the video while introducing the reference character
    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI: genai.Ptr(videoFile.URI),
        }),
        interactions.NewContent(interactions.ImageContent{
            URI: genai.Ptr(characterImg.URI),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "Extend this video: have the character shown in <IMAGE_REF_0> enter the scene and wave.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-omni-1.1-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputVideo != nil && res.Interaction.OutputVideo.Data != nil {
        videoBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputVideo.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("extended_with_character.mp4", videoBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$API_KEY" -H "Content-Type: application/json" -d '{
 "model": "gemini-omni-1.1-flash",
 "input": [
   {"type": "video", "uri": "'$VIDEO_URI'"},
   {"type": "image", "uri": "'$CHARACTER_IMG_URI'"},
   {"type": "text", "text": "Extend this video: have the character shown in <IMAGE_REF_0> enter the scene and wave."}
 ]
}'
```
{% /tab %}
{% /tabs %}

{% video src="https://storage.googleapis.com/generativeai-downloads/videos/omni_traveler_extension.mp4" type="video/mp4" /%}

{% callout type="tip" %}
Optionally, you can set `"task": "extend"` in `video_config` under `generation_config` if prompting alone does not produce the expected extension mode. However, we recommend relying primarily on prompting first, as using the `task` field adds strict constraints to the model.
{% /callout %}

### Extension constraints and guidelines {% id="extension-constraints" %}

Keep the following rules and constraints in mind when extending videos:

*   **Spoken dialogue on uploaded videos**: Currently, you cannot extend an
    uploaded video where someone is talking to add additional dialogue (it is
    supported if the character remains silent or if the prompt does not add dialogue).
*   **Multi-turn voice extension**: Generating spoken dialogue or speech is supported
    when extending previously generated videos via multi-turn (`previous_interaction_id`).
*   **End-of-clip only**: Extension is limited to appending to the end of the video.
    You cannot prepend content or extend the middle of a clip.
*   **Duration limit**: Input videos for extension must be 10 seconds or less in length
    when uploading (unless using multi-turn).
*   **Regional availability**: Extending uploaded videos is not currently available
    for users in the European Economic Area (EEA), Switzerland, and the United
    Kingdom (extending videos generated by the model is supported in all available regions).

## Best practices {% id="best-practices" %}

*   **Use URI delivery for large videos:** For videos larger than 4MB (>720p
    when available), use `delivery="uri"` in `response_format` to avoid payload
    size limits.
*   **Optimized performance:** Set `background=false`, `store=false`, and
    `stream=false` for faster, synchronous unary generation. Note that setting
    `store=false` means the generated video won't be editable in subsequent
    turns using the `previous_interaction_id`.
*   **Prompt precision:** See [prompt guidance](/docs/omni#prompt-guide) section for
    details.

## Limitations {% id="limitations" %}

*   Uploading and editing images containing minors is not supported in European Economic Area, Switzerland, and the United Kingdom.
*   Uploading and editing images containing certain recognizable people is not supported.
*   Editing or extending uploaded videos is not currently available for users in the European Economic Area (EEA), Switzerland, and the United Kingdom (editing or extending videos generated by the model is supported).
*   Input videos for editing and extension must be 10 seconds or less when uploading (unless extending videos generated by the model in multi-turn).
*   Video extension is limited to appending to the end of a video; prepending or extending the middle of a clip is not supported.
*   You cannot extend an uploaded video where someone is talking to add additional dialogue (characters can remain silent, or multi-turn extension with `previous_interaction_id` can be used).
*   Voice editing is not supported.
*   Uploading audio references is unsupported in the current version of the API.
*   Video references work best with likenesses; any audio in a video reference is ignored. Video references support a maximum of 3 clips, up to 3 seconds each.
*   Referencing or reasoning across multiple videos is not supported. Attempting multi-video prompting may result in degraded model performance or unexpected outputs.
*   Provisioned throughput is not supported.
*   System instructions, temperature, `top_p`, stop sequences, and negative prompts are not supported (you can put your negatives in the regular prompt: e.g., "Do not do X").
*   Using YouTube videos as a media source is not supported.

## Technical details {% id="tech-details" %}

*   All generated videos include SynthID watermarking, which is invisible to viewers but can be detected programmatically for provenance verification.
*   Video generation times vary based on duration, resolution, and current API load. Longer and higher-resolution videos take more time to generate.
*   Omni applies content safety filters to both input prompts and generated video (which vary by region). Prompts that violate usage policies are blocked.
*   English (EN) is fully supported, but other languages have not been evaluated, so they may work but results can vary.

## Gemini Omni Flash prompt guide {% id="prompt-guide" %}

This section contains tips and examples on how to prompt Gemini Omni Flash effectively.

### Single scene {% id="single-scene" %}

By default Omni Flash will try to create a video with a few different shots.
It'll attempt to craft an interesting narrative based on the prompt.

If you need the output video to contain a single scene, you must prompt for that:

*   In a single unbroken scene
*   In a single continuous shot
*   No scene cuts

For example:

```none
Continuous, unbroken handheld shot of a fluffy tabby cat sitting on a sunny windowsill, looking out into a leafy garden. The cat's tail twitches slowly, and its ears rotate slightly toward ambient noises. Sunbeams illuminate dust motes in the air. Sound design: Gentle breeze, distant bird chirps. No dialogue.
```

### Removing unwanted elements {% id="remove-unwanted-elements" %}

If the generated video contains things you don't want, include simple negative prompts to avoid them:

*   No dialogue
*   No embellishments
*   No extra sound effects

### Prompts for editing {% id="prompts-for-editing" %}

Simple prompts work best for video editing. Overly descriptive prompts can lead to unintended changes.

The following are more examples of simple editing prompts:

*   Make this video anime
*   Put a fashionable hat on this person
*   Change the lighting to be more dramatic
*   Change the text on the sign to say "Omni Flash"

When editing a specific aspect of the video, include `"Keep everything else the same"` to maintain visual consistency.

The following are some examples to show how to apply this technique:

*   **Avoid:** `In the video of the man sitting on the sofa, please add a small
    black cat that runs from the right side of the screen, jumps onto his lap,
    and then he starts to stroke its head while looking down.`
    *   **Simplify:** `Add a cat that jumps onto his lap, he begins to pet it.
        Keep everything else the same.`
*   **Avoid:** `Please remove the cell phone that the person is holding in
    their hand and fill in the background so it looks like they are just holding
    their hand empty.`
    *   **Simplify:** `Make the phone invisible. Keep everything else the
        same.`

### Prompting the audio {% id="prompting-audio" %}

By default the model will try to generate an appropriate audio track for a
video. This might not always be what you want. You can use your prompt to
describe the type of audio you want. This is especially important if you want
music in your video:

*   Include calm background music
*   The video has a high energy techno beat
*   The audio is a low tinny radio broadcast in the background, playing a song

### Timing events {% id="timing-events" %}

You can prompt for things to happen at specific times in the video, there is no
precise syntax needed and you can use natural language. This is especially
useful in creating your own scene cuts, rhythm or rapid fire sequences.
See the following for examples:

*   After 3 seconds, a woman enters the scene.
*   At 5s the chorus starts in the background audio.
*   Every 2s cut to a new frame.
*   In a rapid fire sequence, every half a second (12 frames at 24fps) change the scene to a new location.

You can also use a timecode syntax:

```none
[0-3s] A person is walking
[3-6s] They stop and turn around
[6-10s] They start running
```

### Meta prompting {% id="meta-prompting" %}

You can ask Gemini Omni Flash to pay attention to general qualities or
principles of video generation:

*   Consider micro-detail, expression and timing to create a very rich, detailed
    but entirely natural scene.
*   Be extremely detailed in your descriptions of characters and environments.
    Apply costume design principles to characters. Be very specific about the
    people, items and objects in the scene.
*   Include plenty of appropriate detail in the background elements to make the
    scene feel realistic and natural.
*   Make a rapid fire video that shows a different rare `[thing]` every 1s, upbeat
    music, include text to label the thing.

### Text in videos {% id="text-in-videos" %}

You can prompt to include text in your video and Gemini Omni will render in a
way that is correct and readable. If there will be naturally occurring text in
your video, even in background elements, it can help to define what it should
say.

*   One word on the screen at a time: "did, you, know, that, Omni, can, do,
    awesome, text?" Each word appears for 1s with a different animated style. No
    dialogue.
*   There is a street sign that says: "This is an AI generation by Omni", there
    is a storefront that says: "All you need AI", there's a car with the number
    plate: "OMNI1.1"

### Prompts for extending a video {% id="prompts-extending-video" %}

With Gemini Omni 1.1 Flash you can extend videos with prompts like, `"Extend this video"` or `"The scene continues"`. You can extend videos by 10s, up to a total length of 40s.

Omni creates an extension that keeps video, motion, characters and audio coherent by using the last 10s of your original video as context. Some of the final frames in your input video will be edited to make the transition seamless.

When extending, all of this guide's Omni prompting tips still apply:

*   Describe the audio in your extended scene, especially if you need it to change: `"The music continues into the chorus"`
*   Describe if the scene continues, or if there is a shot cut to a new scene (perhaps with the same characters): `"Show the same characters in the next scene"`
*   Include images and videos as references when extending to help keep your outputs accurate, or to introduce new characters: `"The person shown in the reference image enters the scene"`, `"The dog in the reference video <VIDEO_REF_0> jumps onto the sofa"`
*   If using timestamps or a timecode syntax, 0s refers to the beginning of the extended part of the video. If extending a 10s video, the scene cut in this prompt will happen after 12s: `"After 2s cut to a new scene with the same characters"`

### Using tags in prompts to set image and video roles {% id="set-image-roles" %}

You can use tags to bind uploaded media to specific generation roles. This lets
you specify whether each image or video is a starting frame, a final frame, or a
reference.

#### 1. Simple tags (recommended) {% id="simple-tags" %}

For simple cases where media roles are clear from the prompt, you can bind
images and videos to roles directly:

*   **`<FIRST_FRAME>`**: use the image as the starting frame of the video, for
    example: `<FIRST_FRAME> a woman is walking`
*   **`<LAST_FRAME>`**: use the image as the final frame of the video to transition to. Must be used with `<FIRST_FRAME>`, for example: `<FIRST_FRAME> <LAST_FRAME> a woman is walking`
*   **`<IMAGE_REF_N>`**: use the image as a reference, for example: `in the
    style of <IMAGE_REF_0> a woman <IMAGE_REF_1> is walking` (combines style
    reference from the first image and subject reference from the second image).
    Image references start from 0.
*   **`<VIDEO_REF_N>`**: use the video as a character or object reference, for example:
    `the person in <VIDEO_REF_0> is playing the violin`. Video references also start from 0.

The following is an example with 6 reference images:

```none
[0-3s] A studio fashion sequence. Starting with woman <IMAGE_REF_0>, she is holding <IMAGE_REF_1>
[3-6s] Then we see the man <IMAGE_REF_2> holding <IMAGE_REF_3>
[6-10s] And finally another woman <IMAGE_REF_4> who is holding <IMAGE_REF_5> while walking.
```

#### 2. Declaring sources and references {% id="explicit-declarations" %}

For more complex cases with multiple media inputs and multiple roles, you can use
explicit prefix tags paired with natural language instructions. You should
declare these sources and references at the start of your prompt.

*   `[# Sources <FIRST_FRAME>@Image1]` will use the first image as the starting frame.
*   `[# Sources <FIRST_FRAME>@Image1 <LAST_FRAME>@Image2]` will use the first image as the starting frame and the second image as the final frame.
*   `[# Sources <FIRST_FRAME>@Image1 <LAST_FRAME>@Image1]` will use the first image as both the first frame and the last frame, creating a video that loops.
*   `[# Sources <FIRST_FRAME>@Image1] [# References <IMAGE_REF_0>@Image2]` will use the first image as the starting frame and the second image as a reference.
*   `[# Sources <VIDEO_0>@Video1]` will use the video as the primary source video to edit or modify.
*   `[# Sources <PREVIOUS_VIDEO>@Video1]` will use the video from the previous turn to extend.
*   `[# References <IMAGE_REF_0>@Image1]` will use the first image as a reference.
*   `[# References <IMAGE_REF_1>@Image2]` will use the second image as a reference.
*   `[# References <IMAGE_REF_0>@Image1 <IMAGE_REF_1>@Image2]` will use both images as references.
*   `[# References <VIDEO_REF_0>@Video1]` will use the first video as a reference.
*   `[# References <IMAGE_REF_0>@Image1 <VIDEO_REF_0>@Video1]` will use both an image and a video as a reference.

Add guiding instructions at the end of your prompt:

*   For a starting frame: `"Use this image as the starting frame."`
*   For a looping video via start and end frames: `"Use this image as the first frame and the last frame."`
*   For reference images: `"Use the given image(s) as references for video generation. The images should not be used as literal initial frames."`
*   For reference videos: `"Use the given video(s) as references. Do not use them as a source for video editing."`

Some examples of prompts with source and reference declarations:

**Starting frame combined with a reference image:**

```none
[# Sources <FIRST_FRAME>@Image1] [# References <IMAGE_REF_0>@Image2] a woman <IMAGE_REF_0> is walking. Use Image1 as the starting frame. Use Image2 as a reference for the video generation.
```

**Character reference video combined with an object reference image:**

```none
[# References <IMAGE_REF_0>@Image1 <VIDEO_REF_0>@Video1] The woman in <VIDEO_REF_0> is playing the violin shown in <IMAGE_REF_0>. Use Video1 as a character reference and Image1 as an object reference.
```

## What's next {% id="what-s-next" %}

*   Get started with the Gemini Omni Flash by experimenting in the [Omni Quickstart Colab](https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_Omni.ipynb).
*   Learn how to write even better prompts with our [Introduction to prompt design](/docs/prompting-strategies).

# Generate music with Lyria 3.5
Source: https://aistudio.google.com/docs/music-generation
Description: Generate music with the Gemini API using Lyria 3 Clip and Lyria 3.5.

Lyria 3.5 is Google's family of music generation models, available through the
Gemini API. With Lyria 3.5, you can generate high-quality, 44.1 kHz stereo audio
from text prompts or from images. These models deliver structural coherence,
including vocals, timed lyrics, and full instrumental arrangements.

The Lyria family includes models:

| Model | Model ID | Best for | Duration | Output |
|---|---|---|---|---|
| **Lyria 3 Clip** | `lyria-3-clip-preview` | Short clips, loops, previews | 30 seconds | MP3 |
| **Lyria 3.5** | `lyria-3.5` | Full-length songs with verses, choruses, bridges | A couple of minutes (controllable using prompt) | MP3 |

Both models can be used using the new [Interactions
API](/docs/interactions-overview), supporting multimodal inputs (text and
images), and produce **44.1 kHz high-fidelity stereo** audio.

{% callout type="note" %}
Looking for real-time, streaming music generation? See [Real-time music
generation with Lyria RealTime](/docs/realtime-music-generation).
{% /callout %}

## Generate a music clip {% id="generate-music" %}

The Lyria 3 Clip model always generates a **30-second** clip. To generate a
clip, call the `interactions.create` method with a text prompt. The response
always includes the generated lyrics and song structure alongside the audio in
the `steps` schema.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="lyria-3-clip-preview",
    input="A short instrumental acoustic guitar piece.",
)

generated_audio = interaction.output_audio
if generated_audio:
    with open("music.mp3", "wb") as f:
        f.write(base64.b64decode(generated_audio.data))

lyrics = interaction.output_text
if lyrics:
    print(f"Lyrics:\n{lyrics}")
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: 'lyria-3-clip-preview',
    input: 'A short instrumental acoustic guitar piece.',
});

const generatedAudio = interaction.output_audio;
if (generatedAudio) {
  if (generatedAudio?.data) {
    fs.writeFileSync('music.mp3', Buffer.from(generatedAudio.data, 'base64'));
  }
}

const lyrics = interaction.output_text;
if (lyrics) {
  console.log(`Lyrics:\n${lyrics}`);
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("lyria-3-clip-preview"))
        .input(InteractionsInput.of("A short instrumental acoustic guitar piece."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputAudio().isPresent() && interaction.outputAudio().get().data().isPresent()) {
  byte[] audioBytes = Base64.getDecoder().decode(interaction.outputAudio().get().data().get());
  Files.write(Paths.get("music.mp3"), audioBytes);
}

interaction.outputText().ifPresent(lyrics -> System.out.println("Lyrics:\n" + lyrics));
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("lyria-3-clip-preview"),
            Input: interactions.NewInteractionsInput("A short instrumental acoustic guitar piece."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputAudio != nil && res.Interaction.OutputAudio.Data != nil {
        audioBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputAudio.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("music.mp3", audioBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }

    if res.Interaction.OutputText != nil {
        fmt.Printf("Lyrics:\n%s\n", *res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "Api-Revision: 2026-05-20" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "lyria-3-clip-preview",
    "input": "A short instrumental acoustic guitar piece."
}'
```

{% /tab %}
{% /tabs %}

You can retrieve generated music data by using the `interaction.output_audio`
property, which returns the last generated audio block. You can also retrieve
the song's lyrics and structure by using the `interaction.output_text` property.

{% callout type="note" %}
For complex, interleaved multimodal responses (such as music containing both raw
structural breakdowns and audio blocks), convenience properties may not capture
all parts. You must manually iterate over the steps instead-see [Interleaved
lyrics and music](/docs/music-generation#interleaved-output) for an example.
{% /callout %}

## Generate a full-length song {% id="full-song" %}

Use the `lyria-3.5` model to generate full-length songs that last a
couple of minutes. The Pro model understands musical structure and can create
compositions with distinct verses, choruses, and bridges. You can influence the
duration by specifying it in your prompt (e.g., "create a 2-minute song") or by
using [timestamps](/docs/music-generation#timing) to define the structure.

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="lyria-3.5",
    input="An epic cinematic orchestral piece about a journey home. Starts with a solo piano intro, builds through sweeping strings, and climaxes with a massive wall of sound.",
)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    model: 'lyria-3.5',
    input: 'A beautiful piano melody.',
});
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("lyria-3.5"))
        .input(
            InteractionsInput.of(
                "An epic cinematic orchestral piece about a journey home. Starts with a solo piano intro, builds through sweeping strings, and climaxes with a massive wall of sound."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("lyria-3.5"),
            Input: interactions.NewInteractionsInput(
                "An epic cinematic orchestral piece about a journey home. Starts with a solo piano intro, builds through sweeping strings, and climaxes with a massive wall of sound.",
            ),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "Api-Revision: 2026-05-20" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "lyria-3.5",
    "input": "A beautiful piano melody."
}'
```

{% /tab %}
{% /tabs %}

## Select output format {% id="output-format" %}

By default, the Lyria 3.5 models generate audio in **MP3** format. For Lyria
3.5, you can also request the output in **WAV** format by setting the
`response_format`.

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="lyria-3.5",
    input="A beautiful piano melody.",
    response_format={"type": "audio"},
)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    model: 'lyria-3.5',
    input: 'A beautiful piano melody.',
    response_format: {
        type: 'audio',
    },
});
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AudioResponseFormat;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("lyria-3.5"))
        .input(InteractionsInput.of("A beautiful piano melody."))
        .responseFormat(
            CreateModelInteractionResponseFormat.of(
                ResponseFormat.of(AudioResponseFormat.builder().build())))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("lyria-3.5"),
            Input: interactions.NewInteractionsInput("A beautiful piano melody."),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(interactions.AudioResponseFormat{}),
            )),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3.5",
    "input": "A beautiful piano melody.",
    "response_format": {
        "type": "audio"
    }
  }'
```

{% /tab %}
{% /tabs %}

## Parse the response {% id="parse-response" %}

The response from Lyria 3.5 contains multiple content blocks within the `steps`
schema. Interactions return a sequence of steps, where `model_output` steps
contain the generated content. Text content blocks contain the generated lyrics
or a JSON description of the song structure. Content blocks with `audio` type
contain the base64 encoded audio data.

{% tabs %}
{% tab label="Python" %}
```python
lyrics = []
audio_data = None

generated_audio = interaction.output_audio
if generated_audio:
    with open("output.mp3", "wb") as f:
        f.write(base64.b64decode(generated_audio.data))

lyrics = interaction.output_text
if lyrics:
    print(f"Lyrics:\n{lyrics}")
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
const lyrics = [];
let audioData = null;

const generatedAudio = interaction.output_audio;
if (generatedAudio) {
    fs.writeFileSync("output.mp3", Buffer.from(generatedAudio.data, 'base64'));
}

const lyrics = interaction.output_text;
if (lyrics) {
    console.log("Lyrics:\n" + lyrics);
}
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("lyria-3.5"))
        .input(InteractionsInput.of("A song about a starry night."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.outputAudio().isPresent() && interaction.outputAudio().get().data().isPresent()) {
  byte[] audioBytes = Base64.getDecoder().decode(interaction.outputAudio().get().data().get());
  Files.write(Paths.get("output.mp3"), audioBytes);
}

if (interaction.outputText().isPresent()) {
  System.out.println("Lyrics:\n" + interaction.outputText().get());
}
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("lyria-3.5"),
            Input: interactions.NewInteractionsInput("A song about a starry night."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputAudio != nil && res.Interaction.OutputAudio.Data != nil {
        audioBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputAudio.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := os.WriteFile("output.mp3", audioBytes, 0644); err != nil {
            log.Fatal(err)
        }
    }

    if res.Interaction.OutputText != nil {
        fmt.Printf("Lyrics:\n%s\n", *res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl ... | jq -r '.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio") | .data' | base64 -d > output.mp3
```

{% /tab %}
{% /tabs %}

#### Interleaved lyrics and music {% id="interleaved-output" %}

Because the output from Lyria 3.5 is complex-containing separate steps and
blocks for generated lyrics (text) and the song itself (audio)-convenience
properties offer a fast and recommended shortcut.

However, if you want full, programmatic control over the raw timeline of steps
returned by the server (such as logging individual content blocks as they are
received), you can manually iterate over `steps` instead:

{% tabs %}
{% tab label="Python" %}
```python
lyrics = []
audio_data = None

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "audio":
                audio_data = base64.b64decode(content_block.data)
            elif content_block.type == "text":
                lyrics.append(content_block.text)

if lyrics:
    print("Lyrics:\n" + "\n".join(lyrics))

if audio_data:
    with open("output.mp3", "wb") as f:
        f.write(audio_data)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
const lyrics = [];
let audioData = null;

for (const step of interaction.steps) {
    if (step.type === 'model_output') {
        for (const contentBlock of step.content || []) {
            if (contentBlock.type === 'audio') {
                audioData = Buffer.from(contentBlock.data, 'base64');
            } else if (contentBlock.type === 'text') {
                lyrics.push(contentBlock.text);
            }
        }
    }
}

if (lyrics.length) {
    console.log("Lyrics:\n" + lyrics.join("\n"));
}

if (audioData) {
    fs.writeFileSync("output.mp3", audioData);
}
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AudioContent;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.Base64;
import java.util.List;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("lyria-3.5"))
        .input(InteractionsInput.of("A song about a starry night."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

List<String> lyrics = new ArrayList<>();
byte[] audioData = null;

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof AudioContent) {
            AudioContent audioBlock = (AudioContent) contentBlock;
            if (audioBlock.data().isPresent()) {
              audioData = Base64.getDecoder().decode(audioBlock.data().get());
            }
          } else if (contentBlock instanceof TextContent) {
            TextContent textBlock = (TextContent) contentBlock;
            textBlock.text().ifPresent(lyrics::add);
          }
        }
      }
    }
  }
}

if (!lyrics.isEmpty()) {
  System.out.println("Lyrics:\n" + String.join("\n", lyrics));
}

if (audioData != null) {
  Files.write(Paths.get("output.mp3"), audioData);
}
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"
    "strings"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("lyria-3.5"),
            Input: interactions.NewInteractionsInput("A song about a starry night."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    var lyrics []string
    var audioData []byte

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.AudioContent != nil && contentBlock.AudioContent.Data != nil {
                    decoded, err := base64.StdEncoding.DecodeString(*contentBlock.AudioContent.Data)
                    if err != nil {
                        log.Fatal(err)
                    }
                    audioData = decoded
                } else if contentBlock.TextContent != nil {
                    lyrics = append(lyrics, contentBlock.TextContent.Text)
                }
            }
        }
    }

    if len(lyrics) > 0 {
        fmt.Printf("Lyrics:\n%s\n", strings.Join(lyrics, "\n"))
    }

    if audioData != nil {
        if err := os.WriteFile("output.mp3", audioData, 0644); err != nil {
            log.Fatal(err)
        }
    }
}
```
{% /tab %}

{% /tabs %}

## Generate music from images {% id="image-to-music" %}

Lyria 3.5 supports multimodal inputs - you can provide up to **10 images**
alongside your text prompt in the `input` list and the model will compose music
inspired by the visual content.

{% tabs %}
{% tab label="Python" %}
```python
import base64

with open("desert_sunset.jpg", "rb") as f:
    image_bytes = f.read()
    image_b64 = base64.b64encode(image_bytes).decode("utf-8")

response = client.interactions.create(
    model="lyria-3.5",
    input=[
        {
            "type": "text",
            "text": "An atmospheric ambient track inspired by the mood and colors in this image.",
        },
        {
            "type": "image",
            "mime_type": "image/jpeg",
            "data": image_b64,
        },
    ],
)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
import * as fs from "fs";

const imageBytes = fs.readFileSync("desert_sunset.jpg").toString("base64");

const interaction = await client.interactions.create({
    model: "lyria-3.5",
    input: [
        {
            type: "text",
            text: "An atmospheric ambient track inspired by the mood and colors in this image.",
        },
        {
            type: "image",
            mime_type: "image/jpeg",
            data: imageBytes,
        },
    ],
});
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("desert_sunset.jpg"));
String imageB64 = Base64.getEncoder().encodeToString(imageBytes);

Content textContent =
    TextContent.builder()
        .text("An atmospheric ambient track inspired by the mood and colors in this image.")
        .build();
Content imageContent =
    ImageContent.builder()
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .data(imageB64)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("lyria-3.5"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction response =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("desert_sunset.jpg")
    if err != nil {
        log.Fatal(err)
    }
    imageB64 := base64.StdEncoding.EncodeToString(imageBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "An atmospheric ambient track inspired by the mood and colors in this image.",
        }),
        interactions.NewContent(interactions.ImageContent{
            MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
            Data:     genai.Ptr(imageB64),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("lyria-3.5"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "lyria-3.5",
    "input": [
      {"type": "text", "text": "An atmospheric ambient track inspired by the mood and colors in this image."},
      {"type": "image", "mime_type": "image/jpeg", "data": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAP//////////////////////////////////////////////////////////////////////////////////////wgALCAABAAEBAREA/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPxA="}
    ]
  }'
```

{% /tab %}
{% /tabs %}

## Provide custom lyrics {% id="custom-lyrics" %}

You can write your own lyrics and include them in the prompt. Use section tags
like `[Verse]`, `[Chorus]`, and `[Bridge]` to help the model understand the song
structure:

{% tabs %}
{% tab label="Python" %}
```python
prompt = """
Create a dreamy indie pop song with the following lyrics:

[Verse 1]
Walking through the neon glow,
city lights reflect below,
every shadow tells a story,
every corner, fading glory.

[Chorus]
We are the echoes in the night,
burning brighter than the light,
hold on tight, don't let me go,
we are the echoes down below.

[Verse 2]
Footsteps lost on empty streets,
rhythms sync to heartbeats,
whispers carried by the breeze,
dancing through the autumn leaves.
"""

interaction = client.interactions.create(
    model="lyria-3.5",
    input=prompt,
)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
const prompt = `
Create a dreamy indie pop song with the following lyrics:

[Verse 1]
Walking through the neon glow,
city lights reflect below,
every shadow tells a story,
every corner, fading glory.

[Chorus]
We are the echoes in the night,
burning brighter than the light,
hold on tight, don't let me go,
we are the echoes down below.

[Verse 2]
Footsteps lost on empty streets,
rhythms sync to heartbeats,
whispers carried by the breeze,
dancing through the autumn leaves.
`;

const interaction = await client.interactions.create({
    model: 'lyria-3.5',
    input: prompt,
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

String prompt =
    "Create a dreamy indie pop song with the following lyrics:\n\n"
        + "[Verse 1]\n"
        + "Walking through the neon glow,\n"
        + "city lights reflect below,\n"
        + "every shadow tells a story,\n"
        + "every corner, fading glory.\n\n"
        + "[Chorus]\n"
        + "We are the echoes in the night,\n"
        + "burning brighter than the light,\n"
        + "hold on tight, don't let me go,\n"
        + "we are the echoes down below.\n\n"
        + "[Verse 2]\n"
        + "Footsteps lost on empty streets,\n"
        + "rhythms sync to heartbeats,\n"
        + "whispers carried by the breeze,\n"
        + "dancing through the autumn leaves.";

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("lyria-3.5"))
        .input(InteractionsInput.of(prompt))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Create a dreamy indie pop song with the following lyrics:\n\n" +
        "[Verse 1]\n" +
        "Walking through the neon glow,\n" +
        "city lights reflect below,\n" +
        "every shadow tells a story,\n" +
        "every corner, fading glory.\n\n" +
        "[Chorus]\n" +
        "We are the echoes in the night,\n" +
        "burning brighter than the light,\n" +
        "hold on tight, don't let me go,\n" +
        "we are the echoes down below.\n\n" +
        "[Verse 2]\n" +
        "Footsteps lost on empty streets,\n" +
        "rhythms sync to heartbeats,\n" +
        "whispers carried by the breeze,\n" +
        "dancing through the autumn leaves."

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("lyria-3.5"),
            Input: interactions.NewInteractionsInput(prompt),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3.5",
    "input": "Create a dreamy indie pop song with the following lyrics: ..."
  }'
```

{% /tab %}
{% /tabs %}

## Control timing and structure {% id="timing" %}

You can specify exactly what happens at specific moments in the song using
timestamps. This is useful for controlling when instruments enter, when lyrics
are delivered, and how the song progresses:

{% tabs %}
{% tab label="Python" %}
```python
prompt = """
[0:00 - 0:10] Intro: Begin with a soft lo-fi beat and muffled
              vinyl crackle.
[0:10 - 0:30] Verse 1: Add a warm Fender Rhodes piano melody
              and gentle vocals singing about a rainy morning.
[0:30 - 0:50] Chorus: Full band with upbeat drums and soaring
              synth leads. The lyrics are hopeful and uplifting.
[0:50 - 1:00] Outro: Fade out with the piano melody alone.
"""

interaction = client.interactions.create(
    model="lyria-3.5",
    input=prompt,
)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
const prompt = `
[0:00 - 0:10] Intro: Begin with a soft lo-fi beat and muffled
              vinyl crackle.
[0:10 - 0:30] Verse 1: Add a warm Fender Rhodes piano melody
              and gentle vocals singing about a rainy morning.
[0:30 - 0:50] Chorus: Full band with upbeat drums and soaring
              synth leads. The lyrics are hopeful and uplifting.
[0:50 - 1:00] Outro: Fade out with the piano melody alone.
`;

const interaction = await client.interactions.create({
    model: 'lyria-3.5',
    input: prompt,
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

String prompt =
    "[0:00 - 0:10] Intro: Begin with a soft lo-fi beat and muffled vinyl crackle.\n"
        + "[0:10 - 0:30] Verse 1: Add a warm Fender Rhodes piano melody and gentle vocals singing about a rainy morning.\n"
        + "[0:30 - 0:50] Chorus: Full band with upbeat drums and soaring synth leads. The lyrics are hopeful and uplifting.\n"
        + "[0:50 - 1:00] Outro: Fade out with the piano melody alone.";

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("lyria-3.5"))
        .input(InteractionsInput.of(prompt))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "[0:00 - 0:10] Intro: Begin with a soft lo-fi beat and muffled vinyl crackle.\n" +
        "[0:10 - 0:30] Verse 1: Add a warm Fender Rhodes piano melody and gentle vocals singing about a rainy morning.\n" +
        "[0:30 - 0:50] Chorus: Full band with upbeat drums and soaring synth leads. The lyrics are hopeful and uplifting.\n" +
        "[0:50 - 1:00] Outro: Fade out with the piano melody alone."

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("lyria-3.5"),
            Input: interactions.NewInteractionsInput(prompt),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3.5",
    "input": "[0:00 - 0:10] Intro: ..."
  }'
```

{% /tab %}
{% /tabs %}

## Generate instrumental tracks {% id="instrumental" %}

For background music, game soundtracks, or any use case where vocals are not
required, you can prompt the model to produce instrumental-only tracks:

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="lyria-3-clip-preview",
    input="A bright chiptune melody in C Major, retro 8-bit video game style. Instrumental only, no vocals.",
)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    model: 'lyria-3-clip-preview',
    input: 'A bright chiptune melody in C Major, retro 8-bit video game style. Instrumental only, no vocals.',
});
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("lyria-3-clip-preview"))
        .input(
            InteractionsInput.of(
                "A bright chiptune melody in C Major, retro 8-bit video game style. Instrumental only, no vocals."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("lyria-3-clip-preview"),
            Input: interactions.NewInteractionsInput(
                "A bright chiptune melody in C Major, retro 8-bit video game style. Instrumental only, no vocals.",
            ),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3-clip-preview",
    "input": "A bright chiptune melody in C Major, retro 8-bit video game style. Instrumental only, no vocals."
  }'
```

{% /tab %}
{% /tabs %}

## Generate music in different languages {% id="languages" %}

Lyria 3.5 generates lyrics in the language of your prompt. To generate a song
with French lyrics, write your prompt in French. The model adapts its vocal
style and pronunciation to match the language.

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="lyria-3.5",
    input="Crée une chanson pop romantique en français sur un coucher de soleil à Paris. Utilise du piano et de la guitare acoustique.",
)
```

{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    model: 'lyria-3.5',
    input: 'Crée une chanson pop romantique en français sur un coucher de soleil à Paris. Utilise du piano et de la guitare acoustique.',
});
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("lyria-3.5"))
        .input(
            InteractionsInput.of(
                "Crée une chanson pop romantique en français sur un coucher de soleil à Paris. Utilise du piano et de la guitare acoustique."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```

{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("lyria-3.5"),
            Input: interactions.NewInteractionsInput(
                "Crée une chanson pop romantique en français sur un coucher de soleil à Paris. Utilise du piano et de la guitare acoustique.",
            ),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3.5",
    "input": "Crée une chanson pop romantique en français sur un coucher de soleil à Paris. Utilise du piano et de la guitare acoustique."
  }'
```

{% /tab %}
{% /tabs %}

## Model intelligence {% id="intelligence" %}

Lyria 3.5 analyzes your prompt process where the model reasons through musical
structure (intro, verse, chorus, bridge, etc.) based on your prompt. This
happens before the audio is generated and ensures structural coherence and
musicality.

Important: While Lyria 3.5 uses a prompt rewriter internally to interpret
natural language instructions, it does **not** expose intermediate "thought"
blocks or thought signatures to the user.

## Prompting guide {% id="prompt-guide" %}

To learn how to craft effective prompts for music genres, instruments, song structure, custom lyrics, and vocal delivery styles, see the [Lyria prompt guide](/docs/lyria-prompt-guide).

## Best practices {% id="best-practices" %}

*   **Iterate with Clip first.** Use the faster `lyria-3-clip-preview` model
    to experiment with prompts before committing to a full-length generation
    with `lyria-3.5`.

*   **Be specific.** Vague prompts produce generic results. Mention instruments,
    BPM, key, mood, and structure for the best output.

*   **Match your language.** Prompt in the language you want the lyrics in.
*   **Use section tags.** `[Verse]`, `[Chorus]`, `[Bridge]` tags give the model
    clear structure to follow.

*   **Separate lyrics from instructions.** When providing custom lyrics, clearly
    separate them from your musical direction instructions.

## Limitations {% id="limitations" %}

*   **Safety**: All prompts are checked by safety filters. Prompts that trigger
    the filters will be blocked. This includes prompts that request specific
    artist voices or the generation of copyrighted lyrics.

*   **Watermarking**: All generated audio includes a [SynthID audio
    watermark](https://ai.google.dev/responsible/docs/safeguards/synthid) for
    identification. This watermark is imperceptible to the human ear and does
    not affect the listening experience.

*   **Multi-turn editing**: Music generation is a single-turn process. Iterative
    editing or refining a generated clip through multiple prompts is not
    supported in the current version of Lyria 3.5.

*   **Length**: The Clip model always generates 30-second clips. The Pro model
    generates songs that last a couple of minutes; exact duration can be
    influenced through your prompt.

*   **Determinism**: Results may vary between calls, even with the same prompt.

## What's next {% id="next-steps" %}

*   See the [Lyria prompt guide](/docs/lyria-prompt-guide) for in-depth prompting strategies and keyword vocabularies,
*   Check [pricing](/docs/pricing) for Lyria 3.5 models,
*   Try [real-time, streaming music generation](/docs/realtime-music-generation)
    with Lyria RealTime,

*   Generate multi-speaker conversations with the [TTS
    models](/docs/speech-generation),

*   Discover how to generate [images](/docs/image-generation) or
    [videos](/docs/video),
*   Find out how Gemini can [understand audio files](/docs/audio),
*   Have a real-time conversation with Gemini using the [Live
    API](/docs/live-api).

# Real-time music generation using Lyria RealTime
Source: https://aistudio.google.com/docs/realtime-music-generation
Description: Get started building with Lyria RealTime's real-time, streaming music generation in the Gemini API

{% callout type="note" %}
Lyria RealTime is an [experimental model](/docs/models#experimental).
{% /callout %}

The Gemini API, using
[Lyria Realtime](https://deepmind.google/technologies/lyria/realtime/),
provides access to a state-of-the-art, real-time, streaming music
generation model. It allows developers to build applications where users
can interactively create, continuously steer, and perform instrumental
music.

Lyria Realtime music generation uses a persistent, bidirectional,
low-latency streaming connection using
[WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API).

To experience what can be built using Lyria Realtime, try it on AI Studio
using the [Prompt DJ](https://aistudio.google.com/apps/bundled/promptdj) or the
[MIDI DJ](https://aistudio.google.com/apps/bundled/promptdj-midi) apps.

{% callout type="note" %}
Looking for non-streaming music generation? See
[Generate music with Lyria 3.5](/docs/music-generation).
{% /callout %}

## Generate and control music {% id="generate-music" %}

Lyria Realtime works similarly to the [Multimodal Live API](/docs/live-api)
in that it uses Websockets to maintain real-time communication with the model.

The following code demonstrates how to generate music:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

This example initializes the Lyria Realtime session using
`client.aio.live.music.connect()`, then sends an
initial prompt with `session.set_weighted_prompts()` along with an initial
configuration using `session.set_music_generation_config`, starts the music
generation using `session.play()` and sets up
`receive_audio()` to process the audio chunks it receives.

```python
  import asyncio
  from google import genai
  from google.genai import types

  client = genai.Client(http_options={'api_version': 'v1beta'})

  async def main():
      async def receive_audio(session):
        """Example background task to process incoming audio."""
        while True:
          async for message in session.receive():
            audio_data = message.server_content.audio_chunks[0].data
            # Process audio...
            await asyncio.sleep(10**-12)

      async with (
        client.aio.live.music.connect(model='models/lyria-realtime-exp') as session,
        asyncio.TaskGroup() as tg,
      ):
        # Set up task to receive server messages.
        tg.create_task(receive_audio(session))

        # Send initial prompts and config
        await session.set_weighted_prompts(
          prompts=[
            types.WeightedPrompt(text='minimal techno', weight=1.0),
          ]
        )
        await session.set_music_generation_config(
          config=types.LiveMusicGenerationConfig(bpm=90, temperature=1.0)
        )

        # Start streaming music
        await session.play()
  if __name__ == "__main__":
      asyncio.run(main())
```

Objective: For a more complete code sample, refer to the
[Lyria RealTime - Get Started](https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_LyriaRealTime.ipynb)
file in the cookbooks repository.

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

This example initializes the Lyria Realtime session using
`client.live.music.connect()`, then sends an
initial prompt with `session.setWeightedPrompts()` along with an initial
configuration using `session.setMusicGenerationConfig`, starts the music
generation using `session.play()` and sets up an
`onMessage` callback to process the audio chunks it receives.

```javascript
import { GoogleGenAI } from "@google/genai";
import Speaker from "speaker";

const client = new GoogleGenAI({
  apiKey: GEMINI_API_KEY,
    apiVersion: "v1beta" ,
});

async function main() {
  const speaker = new Speaker({
    channels: 2,       // stereo
    bitDepth: 16,      // 16-bit PCM
    sampleRate: 44100, // 44.1 kHz
  });

  const session = await client.live.music.connect({
    model: "models/lyria-realtime-exp",
    callbacks: {
      onmessage: (message) => {
        if (message.serverContent?.audioChunks) {
          for (const chunk of message.serverContent.audioChunks) {
            if (chunk.data) {
              const audioBuffer = Buffer.from(chunk.data, "base64");
              speaker.write(audioBuffer);
            }
          }
        }
      },
      onerror: (error) => console.error("music session error:", error),
      onclose: () => console.log("Lyria RealTime stream closed."),
    },
  });

  await session.setWeightedPrompts({
    weightedPrompts: [
      { text: "Minimal techno with deep bass, sparse percussion, and atmospheric synths", weight: 1.0 },
    ],
  });

  await session.setMusicGenerationConfig({
    musicGenerationConfig: {
      bpm: 90,
      temperature: 1.0,
    },
  });

  await session.play();
}

await main();
```

  Objective: For a more complete code sample, try the
  [Prompt DJ](https://aistudio.google.com/apps/bundled/promptdj)
  and [MIDI DJ](https://aistudio.google.com/apps/bundled/promptdj-midi) apps on
  AI Studio

You can then use `session.play()`, `session.pause()`, `session.stop()` and
`session.reset_context()` to start, pause, stop or reset the session.

{% /tab %}
{% /tabs %}
## Steer music in real-time {% id="steer-music" %}

You can steer music generation in real-time by sending prompts and updating
generation parameters in real time.

### Prompt Lyria Realtime {% id="prompting-lyria" %}

While the stream is active, you can send new `WeightedPrompt` messages at any
time to alter the generated music. The model will smoothly transition based
on the new input.

The prompts need to follow the right format with a `text` (the
actual prompt), and a `weight`. The `weight` can take any value except `0`. `1.0`
is usually a good starting point.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
  from google.genai import types

  await session.set_weighted_prompts(
    prompts=[
      {"text": "Piano", "weight": 2.0},
      types.WeightedPrompt(text="Meditation", weight=0.5),
      types.WeightedPrompt(text="Live Performance", weight=1.0),
    ]
  )
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javaScript
  await session.setWeightedPrompts({
    weightedPrompts: [
      { text: 'Harmonica', weight: 0.3 },
      { text: 'Afrobeat', weight: 0.7 }
    ],
  });
```

Note that the model transitions can be a bit abrupt when drastically changing
the prompts so it's recommended to implement some kind of cross-fading by
sending intermediate weight values to the model.

{% /tab %}
{% /tabs %}
### Update the configuration {% id="steer-config" %}

You can steer music generation by updating the music generation parameters in
real time. You can't just update a parameter, you need to set the whole
configuration otherwise the other fields will be reset back to their default
values.

Since updating the bpm or the scale is a drastic change for the model you'll
also need to tell it to reset its context using `reset_context()` to take the
new config into account. It won't stop the stream, but it will be a hard
transition. You don't need to do it for the other parameters.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
  from google.genai import types

  await session.set_music_generation_config(
    config=types.LiveMusicGenerationConfig(
      bpm=128,
      scale=types.Scale.D_MAJOR_B_MINOR,
      music_generation_mode=types.MusicGenerationMode.QUALITY
    )
  )
  await session.reset_context();
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javaScript
  await session.setMusicGenerationConfig({
    musicGenerationConfig: {
      bpm: 120,
      density: 0.75,
      musicGenerationMode: MusicGenerationMode.QUALITY
    },
  });
  await session.reset_context();
```

{% /tab %}
{% /tabs %}
## Prompting Lyria RealTime {% id="prompting-lyria-realtime" %}

Lyria RealTime uses weighted prompts to blend musical genres, instruments, and moods dynamically. To explore prompt steering strategies, keyword tag vocabularies, and full prompt examples, see the [Lyria prompt guide](/docs/lyria-prompt-guide#realtime-prompting).

## Best practices {% id="best-practices-music" %}

* Client applications must implement robust audio buffering to ensure smooth
playback. This helps account for network jitter and slight variations in
generation latency.
* Effective prompting:
  * Be descriptive. Use adjectives describing mood, genre, and instrumentation.
  * Iterate and steer gradually. Rather than completely changing the prompt,
  try adding or modifying elements to morph the music more smoothly.
  * Experiment with weight on `WeightedPrompt` to influence how strongly a new
  prompt affects the ongoing generation.

## Technical details {% id="technical-details-music" %}

This section describes the specifics of how to use Lyria Realtime music
generation.

### Specifications {% id="audio-specs" %}

* Output format: Raw 16-bit PCM Audio
* Sample rate: 48kHz
* Channels: 2 (stereo)

### Controls {% id="controls" %}

Music generation can be influenced in real time by sending messages containing:

* `WeightedPrompt`: A text string describing a musical idea, genre, instrument,
mood, or characteristic. Multiple prompts can potentially be supplied to blend
influences. See [above](/docs/realtime-music-generation#steer-music) for more details on how to best prompt
Lyria Realtime.
* `MusicGenerationConfig`: Configuration for the music generation process,
influencing the characteristics of the output audio.). Parameters
include:
  * `guidance`: (float) Range: `[0.0, 6.0]`. Default: `4.0`.
      Controls how strictly the model follows the prompts. Higher guidance
      improves adherence to the prompt, but makes transitions more abrupt.
  * `bpm`: (int) Range: `[60, 200]`.
      Sets the Beats Per Minute you want for the generated music. You need to
      stop/play or reset the context for the model it take into account the new
      bpm.
  * `density`: (float) Range: `[0.0, 1.0]`.
      Controls the density of musical notes/sounds. Lower values produce sparser
      music; higher values produce "busier" music.
  * `brightness`: (float) Range: `[0.0, 1.0]`.
      Adjusts the tonal quality. Higher values produce "brighter" sounding
      audio, generally emphasizing higher frequencies.
  * `scale`: (Enum)
      Sets the musical scale (Key and Mode) for the generation. Use the
      [`Scale` enum values](/docs/realtime-music-generation#scale-enum) provided by the SDK. You need to
      stop/play or reset the context for the model it take into account the new
      scale.
  * `mute_bass`: (bool) Default: `False`.
      Controls whether the model reduces the outputs' bass.
  * `mute_drums`: (bool) Default: `False`.
      Controls whether the model outputs reduces the outputs' drums.
  * `only_bass_and_drums`: (bool) Default: `False`.
      Steer the model to try to only output bass and drums.
  * `music_generation_mode`: (Enum)
      Indicates to the model if it should focus on `QUALITY` (default value) or
      `DIVERSITY` of music. It can also be set to `VOCALIZATION` to let the
      model generate vocalizations as another instrument (add them as new
      pompts).
* `PlaybackControl`: Commands to control playback aspects, such as play, pause,
stop or reset the context.

For `bpm`, `density`, `brightness` and `scale`, if no value is provided, the
model will decide what's best according to your initial prompts.

More classical parameters like `temperature` (0.0 to 3.0, default 1.1), `top_k`
(1 to 1000, default 40), and `seed` (0 to 2 147 483 647, randomly selected by
default) are also customizable in the `MusicGenerationConfig`.

#### Scale Enum Values {% id="scale-enum" %}

Here are all the scale values that the model can accept:

| Enum Value | Scale / Key |
| :--- | :--- |
| `C_MAJOR_A_MINOR` | C major / A minor |
| `D_FLAT_MAJOR_B_FLAT_MINOR`| D♭ major / B♭ minor |
| `D_MAJOR_B_MINOR` | D major / B minor |
| `E_FLAT_MAJOR_C_MINOR` | E♭ major / C minor |
| `E_MAJOR_D_FLAT_MINOR` | E major / C♯/D♭ minor |
| `F_MAJOR_D_MINOR` | F major / D minor |
| `G_FLAT_MAJOR_E_FLAT_MINOR`| G♭ major / E♭ minor |
| `G_MAJOR_E_MINOR` | G major / E minor |
| `A_FLAT_MAJOR_F_MINOR` | A♭ major / F minor |
| `A_MAJOR_G_FLAT_MINOR` | A major / F♯/G♭ minor |
| `B_FLAT_MAJOR_G_MINOR` | B♭ major / G minor |
| `B_MAJOR_A_FLAT_MINOR` | B major / G♯/A♭ minor |
| `SCALE_UNSPECIFIED` | Default / The model decides |

The model is capable of guiding the notes that are played, but does
not distinguish between relative keys. Thus each enum corresponds both to the
relative major and minor. For example, `C_MAJOR_A_MINOR` would correspond to all
the white keys of a piano, and `F_MAJOR_D_MINOR` would be all the white keys
except B flat.

### Limitations {% id="limitations" %}

* Instrumental only: The model generates instrumental music only.
* Safety: Prompts are checked by safety filters. Prompts triggering the filters
will be ignored in which case an explanation will be written in the output's
`filtered_prompt` field.
* Watermarking: Output audio is always watermarked for identification following
our [Responsible AI](https://ai.google/responsibility/principles/) principles.

## What's next {% id="next-steps" %}

* See the [Lyria prompt guide](/docs/lyria-prompt-guide) for prompting strategies and keyword vocabularies,
* Generate full songs and vocal tracks with [Lyria 3.5](/docs/music-generation),
* Instead of music, learn how to generate multi-speakers conversation using
    the [TTS models](/docs/speech-generation),
* Discover how to generate [images](/docs/image-generation) or [videos](/docs/video),
* Instead of generation music or audio, find out how to Gemini can
    [understand Audio files](/docs/audio),
* Have a real-time conversation with Gemini using the
    [Multimodal Live API](/docs/live-api).

Explore the [Cookbook](https://github.com/google-gemini/cookbook) for more
code examples and tutorials.

# Lyria prompt guide
Source: https://aistudio.google.com/docs/lyria-prompt-guide
Description: Guide to prompt engineering for music generation with Lyria 3.5 and Lyria RealTime in the Gemini API.

The Gemini API offers two ways to generate music with Lyria:

* **Lyria 3.5 & Lyria 3 Clip**: Non-streaming generation for 30-second clips or full-length songs with lyrics and vocals. See [Generate music with Lyria 3.5](/docs/music-generation).
* **Lyria RealTime**: Real-time, interactive music streaming and live steering over WebSockets. See [Real-time music generation with Lyria RealTime](/docs/realtime-music-generation).

Both models respond to descriptive text prompts, musical terminology, and structural directions. This guide covers how to write effective prompts for both batch generation and real-time steering.

## Prompt fundamentals {% id="prompt-fundamentals" %}

Your prompt can be a short phrase:

```none
A folk song about cute cats avoiding puddles, female vocals, acoustic guitar, sound of rain
```

Or a structured, detailed description:

```none
A 1980s-style synth-pop track with a driving beat, shimmering synthesizers, and a catchy, anthemic chorus. The song should have a retro-futuristic feel with modern production polish. Upbeat tempo around 120 BPM, clear verse-chorus structure, and a memorable instrumental hook. The lyrics describe getting ready for a party.
```

Both short and detailed prompts produce strong results. Use the following strategies to guide the model toward the exact sound you want.

## Genre and style {% id="genre-and-style" %}

Lead your prompt with the primary genre. You can combine genres to create unique hybrids:

* A fusion of metal and hip-hop
* Death metal combined with operatic vocals
* Classical chamber music with dark electronic drone elements
* Modern electronic dance music (EDM) mixed with Europop

You can also specify a musical era or regional variant:

* Early 1990s boom-bap hip-hop
* 1960s French yé-yé pop
* 1980s post-punk and new wave
* 2000s mainstream R&B
* Berlin minimal techno or Bay Area hyphy

### Genre keywords {% id="genre-keywords" %}

Use these recognized genre terms in your prompts for Lyria 3.5 and Lyria RealTime:

* **Electronic & Dance**: `Acid House, Breakbeat, Chillout, Chiptune, Deep House, Drum & Bass, Dubstep, EDM, Electro Swing, Glitch Hop, Hyperpop, Minimal Techno, Moombahton, Psytrance, Synthpop, Techno, Trance, Trip Hop, Vaporwave`
* **Hip-Hop & R&B**: `808 Hip Hop, Boom-Bap, Contemporary R&B, G-funk, Grime, Lo-Fi Hip Hop, Neo-Soul, New Jack Swing, Trap Beat`
* **Rock & Alternative**: `Alternative Country, Blues Rock, Classic Rock, Funk Metal, Garage Rock, Indie Folk, Indie Pop, Post-Punk, 60s Psychedelic Rock, Shoegaze, Surf Rock`
* **Jazz, Soul & Funk**: `Acid Jazz, Afrobeat, Bossa Nova, Disco Funk, Funk, Jazz Fusion, Latin Jazz`
* **Folk & Traditional**: `Bengal Baul, Bhangra, Bluegrass, Celtic Folk, Cumbia, Indian Classical, Irish Folk, Merengue, Polka, Reggae, Reggaeton, Renaissance Music, Salsa`
* **Classical & Acoustic**: `Baroque, Orchestral Score, Piano Ballad`

## Instruments and textures {% id="instruments-and-textures" %}

Lyria selects appropriate instrumentation for the requested genre automatically. If you want specific instruments or unusual combinations, declare them explicitly:

```none
A dance track with a driving beat, shimmering synthesizers, and a catchy, anthemic chorus. A saxophone solo enters during the bridge.
```

Describe how instruments sound and interact to set mood and texture:

* A distorted 303 bassline cutting through crisp, tight hi-hats
* Warm, analog synth pads swelling beneath a dry, intimate acoustic guitar
* A wall of sound built from multiple layers of fuzz guitar, with distant, reverb-soaked vocals

### Instrument keywords {% id="instrument-keywords" %}

* **Keyboards & Synths**: `Buchla Synths, Clavichord, Dirty Synths, Harpsichord, Mellotron, Moog Oscillations, Ragtime Piano, Rhodes Piano, Smooth Pianos, Spacey Synths, Synth Pads`
* **Bass & Drums**: `303 Acid Bass, 808 Hip Hop Beat, Boomy Bass, Conga Drums, Drumline, Funk Drums, Precision Bass, Tabla, TR-909 Drum Machine`
* **Guitars & Strings**: `Banjo, Balalaika, Bouzouki, Cello, Charango, Dulcimer, Fiddle, Flamenco Guitar, Guitar, Harp, Koto, Lyre, Mandolin, Pipa, Shamisen, Shredding Guitar, Sitar, Slide Guitar, Viola Ensemble, Warm Acoustic Guitar`
* **Wind & Brass**: `Alto Saxophone, Bagpipes, Bass Clarinet, Didgeridoo, Harmonica, Ocarina, Trumpet, Tuba, Woodwinds`
* **Percussion**: `Bongos, Djembe, Glockenspiel, Hang Drum, Kalimba, Maracas, Marimba, Mbira, Steel Drum, Vibraphone`

## Song structure and timing {% id="structure-and-timing" %}

For Lyria 3.5, define song progression using tags or arrows:

* `[Intro] -> [Verse 1] -> [Chorus] -> [Verse 2] -> [Chorus] -> [Bridge] -> [Outro]`
* Start with a quiet piano intro, build into an energetic verse, pause for a moment of silence, then explode into the chorus.

You can direct energy dynamics and transitions:

* Build tension through the pre-chorus, then drop to silence before an explosive chorus
* Gradual crescendo throughout the song, adding one instrument per section
* A sudden stop after the bridge, followed by an a cappella chorus

You can also prompt specific timing markers:

* Build to a beat drop at 12 seconds
* Vocal sample repeats every 4 bars
* The chorus kicks in at 22 seconds

## Lyrics and vocals {% id="lyrics-and-vocals" %}

Lyria 3.5 generates vocal tracks with lyrics by default. You can provide your own lyrics, ask the model to generate them, or request an instrumental track.

### Using your own lyrics {% id="own-lyrics" %}

Include your lyrics directly in the prompt beneath a `Lyrics:` header. Tag each section to guide vocal delivery:

```none
Lyrics:

[Intro]
Ooooh, yeah

[Verse 1]
Early morning rain on the window pane
City lights wash away the pain
Walking down this empty street again

[Chorus]
We keep moving on (moving on)
Until the morning light
Everything will be alright
```

Use parentheses for backing vocals, echoes, or ad-libs, like `(moving on)`.

### Directing generated lyrics {% id="generated-lyrics" %}

When asking Lyria 3.5 to write lyrics, outline the narrative, emotion, or key phrases:

```none
The lyrics describe driving down the Pacific Coast Highway at sunset. The mood is nostalgic and reflective. Include an uplifting, anthemic chorus about second chances and starting over.
```

For electronic and dance genres, request short repeating vocal hooks:

```none
An upbeat dance-pop track with a repetitive, high-energy vocal hook: "Feel the rhythm all night long."
```

### Vocal delivery and singer profiles {% id="vocal-delivery" %}

Specify gender, vocal range, and timbre for precise delivery:

* **Female Soprano**: Clear, crystalline timbre with an agile, soaring delivery. Bright tone capable of airy, breathy textures.
* **Female Alto**: Rich, warm, and husky lower range. Smoky timbre with a soulful, resonant chest voice.
* **Male Tenor**: Bright, piercing, and energetic. Youthful timbre with high belting power that cuts through dense mixes.
* **Male Baritone**: Deep, velvet-smooth chest voice with a warm, soothing, crooning delivery.
* **Weathered Rocker**: Raspy, gritty timbre reminiscent of 1990s alternative rock. Raw emotional intensity with strained upper notes.

### Non-lyrical vocal effects {% id="vocal-effects" %}

You can also prompt for spoken dialogue, vocal chops, and sampling effects:

* A vintage radio broadcast voice introduces the song before the beat kicks in
* A spoken voice whispers right before the drop, followed by high-energy synths
* Chopped, pitch-shifted vocal samples looping as an instrumental rhythm element

## Musical parameters {% id="musical-parameters" %}

Refine your prompt with standard musical properties:

* **Tempo (BPM)**: Set the tempo directly (e.g. `120 BPM`, `slow tempo around 72 BPM`, `fast 160 BPM`).
* **Key and Scale**: Specify the root key and tonality (e.g. `in G major`, `in D minor`, `in C pentatonic`).
* **Mood and Atmosphere**: Use descriptive emotional adjectives:
  `Ambient, Bright, Chill, Dark, Dreamy, Emotional, Ethereal, Euphoric, Funky, Groovy, Melancholic, Nostalgic, Ominous, Psychedelic, Relaxed, Soulful, Triumphant, Upbeat, Whimsical`

## Prompting Lyria RealTime {% id="realtime-prompting" %}

Lyria RealTime uses **weighted prompts** rather than a single monolithic prompt string. This lets you blend multiple musical influences dynamically and steer music continuously over a WebSocket connection.

### Weighted prompt structure {% id="weighted-prompts" %}

Each weighted prompt consists of a descriptive text phrase and a floating-point weight:

```python
prompts = [
    types.WeightedPrompt(text="minimal techno", weight=1.0),
    types.WeightedPrompt(text="deep sub bass", weight=0.6),
    types.WeightedPrompt(text="shimmering hi-hats", weight=0.4),
]
```

### Real-time steering strategies {% id="steering-strategies" %}

* **Blending genres**: Blend distinct styles by assigning balanced weights:
  * `ambient synth pads (weight: 0.8)` + `lo-fi hip-hop drums (weight: 0.6)`
  * `flamenco guitar (weight: 0.7)` + `deep house groove (weight: 0.5)`
* **Dynamic transitions**: To transition the music smoothly, adjust prompt weights over time:
  1. Start with `chill jazz piano (weight: 1.0)`.
  2. Gradually add `electronic breakbeat (weight: 0.3)`.
  3. Increase `electronic breakbeat` to `0.8` while lowering `chill jazz piano` to `0.3`.
* **Layering elements**: Keep instrument tags and mood tags separate so you can adjust them independently:
  * Prompt 1: `bossa nova guitar (weight: 0.9)`
  * Prompt 2: `warm acoustic bass (weight: 0.7)`
  * Prompt 3: `subtle vinyl crackle (weight: 0.3)`

## Example prompts {% id="example-prompts" %}

### Lyria 3.5 examples

* **Lo-Fi Study Beat**:
  ```none
  A 30-second lofi hip hop beat with dusty vinyl crackle, mellow Rhodes piano chords, a relaxed boom-bap drum groove at 82 BPM, and a warm upright bassline. Instrumental only.
  ```
* **Pop Anthem**:
  ```none
  An upbeat, feel-good indie-pop song in G major at 122 BPM. Bright acoustic guitar strumming, driving kick drum, handclaps, and warm female vocal harmonies. The lyrics describe an unforgettable summer road trip with friends.
  ```
* **Cinematic Cyberpunk**:
  ```none
  Dark, cinematic cyberpunk synthwave at 110 BPM in D minor. Heavy distorted bass, ominous arpeggiated analog synthesizers, distant metallic percussion, and an ethereal female vocalise swelling during the climax.
  ```

### Lyria RealTime steering set

```python
# Initial high-energy groove
await session.set_weighted_prompts(
    prompts=[
        types.WeightedPrompt(text="techno groove", weight=1.0),
        types.WeightedPrompt(text="acid 303 bass", weight=0.8),
    ]
)

# Transition to a melodic breakdown
await session.set_weighted_prompts(
    prompts=[
        types.WeightedPrompt(text="ambient synth pads", weight=1.0),
        types.WeightedPrompt(text="subtle reverberant piano", weight=0.7),
        types.WeightedPrompt(text="techno groove", weight=0.2),
    ]
)
```

## What's next {% id="whats-next" %}

* [Generate music with Lyria 3.5](/docs/music-generation): Generate full songs and 30-second clips using the Interactions API.
* [Real-time music generation with Lyria RealTime](/docs/realtime-music-generation): Build real-time, interactive music streaming applications over WebSockets.

# Generate images using Imagen
Source: https://aistudio.google.com/docs/imagen
Description: Imagen models are shut down; migrate to Nano Banana for image generation.

{% callout type="warning" %}
  Imagen models are shut down. Use Nano Banana for image generation.
{% /callout %}

Imagen is Google's legacy image generation model. It is now shut down and no longer available in the Gemini API.

## Migrate to Nano Banana {% id="migrate-to-nano-banana" %}

Migrate to Nano Banana for image generation:

- **Model name**: Use `gemini-2.5-flash-image` (or Nano Banana 2 models such as `gemini-3.1-flash-image`) instead of Imagen model names.
- **Method**: Use `client.models.generate_content` instead of
  `client.models.generate_images`.
- **Response handling**: Nano Banana returns content parts containing image data instead of a specific image response object.

See the [Image generation guide](/docs/image-generation) for details and examples.

# Text-to-speech generation (TTS)
Source: https://aistudio.google.com/docs/speech-generation
Description: Generate high-fidelity speech and multi-speaker audio with the Gemini API using gemini-3.8-flash-tts and gemini-3.8-flash-lite-tts.

The Gemini API can transform text input into single-speaker or multi-speaker
audio using Gemini text-to-speech (TTS) generation capabilities.
Text-to-speech generation is
*[controllable](/docs/speech-generation#controllable)*, meaning you can combine
structured turn metadata (`speech_metadata`) and inline vocal tags to guide the
*style*, *accent*, *pace*, and *tone* of the audio.

The TTS capability differs from speech generation provided through the
[Live API](/docs/live-api), which is designed for interactive,
unstructured audio, and multimodal inputs and outputs. While the Live API excels
in dynamic conversational contexts, TTS through the Gemini API
is tailored for scenarios that require exact text recitation with fine-grained
control over style and sound, such as podcast or audiobook generation.

This guide shows you how to generate single-speaker and multi-speaker audio from
text using [Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts)
(`gemini-3.8-flash-tts`) and
[Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts)
(`gemini-3.8-flash-lite-tts`).

## Before you begin {% class="hide-from-toc" id="before-you-begin" %}

Ensure you use a Gemini TTS model listed in the
[Supported models](/docs/speech-generation#supported-models) section, and
upgrade to the latest Google GenAI SDK (`google-genai >= 2.25.0` for Python or
`@google/genai >= 2.24.0` for JavaScript/TypeScript) or use the REST API. For
optimal results, review
[When to use which model](/docs/speech-generation#when-to-use-which-model) to
select the best model for your workload.

You may find it useful to
[test the Gemini TTS models in AI Studio](https://aistudio.google.com/generate-speech)
before you start building.

{% callout type="note" %}
TTS models accept text-only inputs and produce audio-only outputs. For a
complete list of restrictions specific to TTS models, review the
[Limitations](/docs/speech-generation#limitations) section.
{% /callout %}

## Single-speaker TTS {% id="single-speaker" %}

To convert text to single-speaker audio with Gemini 3.8 TTS models, pass the
verbatim transcript in `input`, attach turn-level styling using a
`speech_metadata` annotation, and configure your voice in
`generation_config.speech_config`. You can choose a voice from the prebuilt
[voice options](/docs/speech-generation#voices), the Extended Voice Library
(`GET /v1beta/voices`), a custom [Voice design](/docs/voice-design) ID
(`voice_...`), or a [Voice replication](/docs/voice-replication) ID
(`voice_...`, or optional stateless `voicekey_...`).

This example saves the output audio from the model in a WAV file:

{% tabs %}
{% tab label="Python" %}

```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))
```
{% /tab %}
{% tab label="JavaScript" %}

```js
import {GoogleGenAI} from '@google/genai';
import * as fs from 'node:fs';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('out.wav', audioBuffer);
   }
}
await main();
```
{% /tab %}
{% tab label="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.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
       "type": "audio"
     },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }' | jq -r '[.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio")] | last | .data' | base64 --decode > out.wav
```

{% /tab %}
{% /tabs %}

In the Python and JavaScript SDKs, you can retrieve generated audio data by
using the `interaction.output_audio` convenience property, which returns the
last generated audio block (in raw REST JSON responses, the base64-encoded audio
is stored in `steps[].content[].data`).

## Multi-speaker TTS {% id="multi-speaker" %}

For multi-speaker dialogue, configure two speakers in `speech_config.speakers`
and pass each turn as a separate text item with a `speech_metadata` annotation
specifying the `speaker` and optional turn-level `style`. Notice that
`speech_config` accepts an array (`[{"voice": "..."}]`) for single-speaker
generation and an object (`{"speakers": [...]}`) for multi-speaker generation:

{% tabs %}
{% tab label="Python" %}

```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [
            {
                "type": "text",
                "text": "How's it going today Jane?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Joe",
                    "style": "cheerful and friendly",
                }],
            },
            {
                "type": "text",
                "text": "Not too bad, how about you? Ready to test these new voices?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Jane",
                    "style": "calm and relaxed",
                }],
            },
        ],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": {
            "speakers": [
                {"speaker": "Joe", "voice": "Puck"},
                {"speaker": "Jane", "voice": "Kore"},
            ],
        }
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))
```
{% /tab %}
{% tab label="JavaScript" %}

```js
import {GoogleGenAI} from '@google/genai';
import * as fs from 'node:fs';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [
            {
               type: 'text',
               text: "How's it going today Jane?",
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Joe',
                  style: 'cheerful and friendly',
               }],
            },
            {
               type: 'text',
               text: 'Not too bad, how about you? Ready to test these new voices?',
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Jane',
                  style: 'calm and relaxed',
               }],
            },
         ],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: {
            speakers: [
               { speaker: 'Joe', voice: 'Puck' },
               { speaker: 'Jane', voice: 'Kore' },
            ],
         },
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('out.wav', audioBuffer);
   }
}

await main();
```
{% /tab %}
{% tab label="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.8-flash-tts",
  "input": [{
    "type": "user_input",
    "content": [
      {
        "type": "text",
        "text": "How'\''s it going today Jane?",
        "annotations": [{
          "type": "speech_metadata",
          "speaker": "Joe",
          "style": "cheerful and friendly"
        }]
      },
      {
        "type": "text",
        "text": "Not too bad, how about you? Ready to test these new voices?",
        "annotations": [{
          "type": "speech_metadata",
          "speaker": "Jane",
          "style": "calm and relaxed"
        }]
      }
    ]
  }],
  "response_format": {
       "type": "audio"
     },
  "generation_config": {
    "speech_config": {
      "speakers": [
        { "speaker": "Joe", "voice": "Puck" },
        { "speaker": "Jane", "voice": "Kore" }
      ]
    }
  }
}'
```
{% /tab %}
{% /tabs %}

## Control speech style with metadata and tags {% id="controllable" %}

Gemini 3.8 TTS treats the `text` field strictly as a verbatim transcript. To
control delivery without having stage directions read aloud, split your
instructions by scope:

*   **Sustained turn-level delivery (`speech_metadata.style`):** Put emotions,
    delivery style, prosody, pacing, and volume that apply across an entire turn
    in the `style` field (for example, `"style": "whispered urgently"`,
    `"style": "out of breath"`, or `"style": "warm and enthusiastic"`).
*   **Point-in-time events (inline tags):** Place momentary non-speech vocal
    bursts or pauses directly inside the transcript using angle brackets (for
    example, `"Wait... <short pause> did you hear that? <sigh>"` or
    `"Excuse me <cough> as I was saying..."`).

See the [Prompting guide](/docs/speech-generation#prompting-guide) for
comprehensive best practices.

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [
            {
                "type": "text",
                "text": "Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Dr. Anya",
                    "style": "whispered urgently",
                }],
            },
            {
                "type": "text",
                "text": "<gasp> No way! <laugh> We've been searching for this species all season!",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Liam",
                    "style": "warm and enthusiastic",
                }],
            },
        ],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": {
            "speakers": [
                {"speaker": "Dr. Anya", "voice": "Kore"},
                {"speaker": "Liam", "voice": "Puck"},
            ],
        }
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))
```
{% /tab %}
{% tab label="JavaScript" %}
```js
import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [
            {
               type: 'text',
               text: 'Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?',
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Dr. Anya',
                  style: 'whispered urgently',
               }],
            },
            {
               type: 'text',
               text: "<gasp> No way! <laugh> We've been searching for this species all season!",
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Liam',
                  style: 'warm and enthusiastic',
               }],
            },
         ],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: {
            speakers: [
               { speaker: 'Dr. Anya', voice: 'Kore' },
               { speaker: 'Liam', voice: 'Puck' },
            ],
         },
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('out.wav', audioBuffer);
   }
}

await main();
```
{% /tab %}
{% tab label="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.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Dr. Anya",
            "style": "whispered urgently"
          }]
        },
        {
          "type": "text",
          "text": "<gasp> No way! <laugh> We'\''ve been searching for this species all season!",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Liam",
            "style": "warm and enthusiastic"
          }]
        }
      ]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": {
        "speakers": [
          { "speaker": "Dr. Anya", "voice": "Kore" },
          { "speaker": "Liam", "voice": "Puck" }
        ]
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## Streaming speech generation {% id="streaming" %}

You can stream the generated audio as it is being synthesized by setting
`stream: true`. Unlike unary requests (which return a complete WAV file with a
RIFF header), **streaming requests return headerless raw 16-bit signed
little-endian linear PCM (`audio/l16`, 24 kHz, mono) chunks by default** so
audio chunks can be played or concatenated continuously without container
headers.

{% tabs %}
{% tab label="Python" %}

```python
import base64
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
    stream=True,
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "audio":
            audio_data = base64.b64decode(event.delta.data)
```
{% /tab %}
{% tab label="JavaScript" %}

```js
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const stream = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
      stream: true,
   });

   for await (const event of stream) {
      if (event.event_type === 'step.delta') {
         if (event.delta.type === 'audio' && event.delta.data) {
            const audioBuffer = Buffer.from(event.delta.data, 'base64');
            // Process the audio buffer
         }
      }
   }
}
await main();
```
{% /tab %}
{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    },
    "stream": true
  }'
```
{% /tab %}
{% /tabs %}

## Audio output formats {% id="audio-output-formats" %}

Gemini 3.8 TTS models use different default audio formats depending on whether
the request is unary or streaming:

*   **Unary requests (`stream=False`):** Return complete **WAV (`audio/wav`)**
    audio with a RIFF header (24 kHz, mono, 16-bit signed little-endian PCM).
    You can write the decoded base64 bytes directly to a `.wav` file without
    manually adding a WAV container.
*   **Streaming requests (`stream=True`):** Return **headerless raw Linear PCM
    (`audio/l16`)** chunks (24 kHz, mono, 16-bit signed little-endian PCM) by
    default so chunks can be streamed or concatenated continuously without
    container headers on each chunk.

You can override the output audio encoding and sample rate in `response_format`:

| `mime_type` value | Format | Description |
| :--- | :--- | :--- |
| `"audio/wav"` *(unary default)* | WAV | Complete WAV file with a RIFF header (24 kHz, mono, 16-bit PCM). |
| `"audio/l16"` *(streaming default)* | Linear PCM | Headerless raw 16-bit signed little-endian linear PCM (24 kHz, mono). Default for streaming requests. |
| `"audio/mulaw"` | μ-law | G.711 μ-law companded audio. Commonly used in North American and Japanese telephony (8 kHz). |
| `"audio/alaw"` | A-law | G.711 A-law companded audio. Commonly used in European and international telephony (8 kHz). |

You can also optionally specify `sample_rate` (for example, `24000`, `16000`, or
`8000` Hz; defaults to `24000` Hz).

The following example requests headerless raw 16-bit PCM (`audio/l16`) at
24 kHz:

{% tabs %}
{% tab label="Python" %}

```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={
        "type": "audio",
        "mime_type": "audio/l16",
        "sample_rate": 24000,
    },
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
)

with open("out.pcm", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))
```
{% /tab %}
{% tab label="JavaScript" %}

```js
import {GoogleGenAI} from '@google/genai';
import * as fs from 'node:fs';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: {
         type: 'audio',
         mime_type: 'audio/l16',
         sample_rate: 24000,
      },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('out.pcm', audioBuffer);
   }
}
await main();
```
{% /tab %}
{% tab label="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.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio",
      "mime_type": "audio/l16",
      "sample_rate": 24000
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'
```
{% /tab %}
{% /tabs %}

## Voice options {% id="voices" %}

Gemini 3.8 TTS supports four ways to select or create voices:

1.  **Prebuilt studio voices:** 30 curated voices listed in the following table.
2.  **Extended Voice Library:** Hundreds of additional voices across languages,
    accents, and character archetypes accessible using `client.voices.list()`
    (`GET /v1beta/voices`).
3.  **[Voice design](/docs/voice-design):** Generate a custom vocal persona from
    a natural-language description in
    [Google AI Studio](https://aistudio.google.com/generate-speech) or using
    `POST /v1beta/voices` (`type="prompted"`, which returns a persistent
    `voice_...` ID and a `sample_audio` WAV preview in `CreateVoice` and
    `GetVoice`).
4.  **[Voice replication](/docs/voice-replication):** Replicate a speaker's
    voice from reference and consent audio in
    [Google AI Studio](https://aistudio.google.com/generate-speech) or using
    `POST /v1beta/voices` (`type="replicated"`, persistent `store=True` by
    default or optional stateless `store=False`).

### Custom voice limits and TTL {% id="custom-voice-limits" %}

| Voice type | Storage mode | Quota / limit | Retention (TTL) |
| :--- | :--- | :--- | :--- |
| **Stateful voices** (`voice_...`, prompted or replicated) | `store=True` | **200 voices per project** (shared across prompted and replicated voices) | **1 year from last use**{% sup %}*{% /sup %} |
| **Stateless voice keys** (`voicekey_...`, replicated) | `store=False` | Client-managed | **7 days** |

{% sup %}*{% /sup %} **TTL extension:** The 1-year retention window resets each time the voice is actively used (either by synthesizing speech with the voice or using it as a base voice for remixing). Voices with no activity for 1 year are automatically deleted.

### Prebuilt voices {% id="prebuilt-voices" %}

{% table %}

* **Zephyr** -- *Bright*
* **Puck** -- *Upbeat*
* **Charon** -- *Informative*
---

* **Kore** -- *Firm*
* **Fenrir** -- *Excitable*
* **Leda** -- *Youthful*
---

* **Orus** -- *Firm*
* **Aoede** -- *Breezy*
* **Callirrhoe** -- *Easy-going*
---

* **Autonoe** -- *Bright*
* **Enceladus** -- *Breathy*
* **Iapetus** -- *Clear*
---

* **Umbriel** -- *Easy-going*
* **Algieba** -- *Smooth*
* **Despina** -- *Smooth*
---

* **Erinome** -- *Clear*
* **Algenib** -- *Gravelly*
* **Rasalgethi** -- *Informative*
---

* **Laomedeia** -- *Upbeat*
* **Achernar** -- *Soft*
* **Alnilam** -- *Firm*
---

* **Schedar** -- *Even*
* **Gacrux** -- *Mature*
* **Pulcherrima** -- *Forward*
---

* **Achird** -- *Friendly*
* **Zubenelgenubi** -- *Casual*
* **Vindemiatrix** -- *Gentle*
---

* **Sadachbia** -- *Lively*
* **Sadaltager** -- *Knowledgeable*
* **Sulafat** -- *Warm*
{% /table %}

### Extended Voice Library and filtering {% id="voice-library" %}

Beyond the 30 featured studio voices in the preceding table, the **Extended
Voice Library** provides hundreds of additional voices across languages, regional accents,
character personas, and domains. You can browse, filter, and audition the full
Voice Library interactively in
[Google AI Studio](https://aistudio.google.com/generate-speech), or query it
programmatically using `client.voices.list()` (`GET /v1beta/voices`, using
`google-genai` 2.25.0+ / `@google/genai` 2.24.0+).

`ListVoices` returns your custom stored voices (ordered newest first) followed
by prebuilt catalog voices matching your filter criteria. When multiple values
are passed for a list filter, voices matching **any** value in that filter are
returned (`OR`), while distinct filter parameters combine with `AND`:

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `language_code` | `list[str]` | BCP-47 language tag(s) (for example, `["en-US", "en-GB"]`). Case-insensitive exact match. |
| `region_code` | `list[str]` | ISO 3166-1 alpha-2 or UN M.49 region code(s) (for example, `["US", "GB"]`). |
| `accent` | `list[str]` | Regional accent descriptor(s) (for example, `["American", "British"]`). |
| `gender` | `list[str]` | Perceived gender presentation (`"female"`, `"male"`, or `"neutral"`). |
| `pitch` | `list[str]` | Vocal pitch classification (`"low"`, `"medium"`, or `"high"`). |
| `persona` | `list[str]` | Vocal persona or character archetype (for example, `["Warm, Friendly"]`, `["Narrator"]`). |
| `contexts` (`context` in REST) | `list[str]` | Optimal usage domain (for example, `["Audiobook", "Conversational", "News"]`). |
| `type` (`type_` in Python) | `list[str]` | Filter by voice source: `"prebuilt"`, `"prompted"` ([Voice design](/docs/voice-design)), or `"replicated"` ([Voice replication](/docs/voice-replication)). |
| `search` | `str` | Free-text substring search matched case-insensitively against both `display_name` and `description`. |
| `page_size` | `int` | Maximum number of voices returned per page (default `50`, maximum `1000`). |
| `page_token` | `str` | Token from `response.next_page_token` to fetch the next page of results. |

{% tabs %}
{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

# Filter the Voice Library by language, gender, pitch, domain context, and keyword
response = client.voices.list(
    language_code=["en-US", "en-GB"],
    gender=["female"],
    pitch=["medium", "low"],
    contexts=["Audiobook", "Conversational"],
    type_=["prebuilt"],
    search="warm",
    page_size=50,
)

for voice in response.voices or []:
    print(
        f"{voice.id} | {voice.display_name} ({voice.language_code},"
        f" {voice.accent}, {voice.gender}, pitch={voice.pitch}):"
        f" {voice.description}"
    )
```
{% /tab %}
{% tab label="JavaScript" %}

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

const ai = new GoogleGenAI();

// Filter the Voice Library by language, gender, pitch, domain context, and keyword
const response = await ai.voices.list({
  language_code: ["en-US", "en-GB"],
  gender: ["female"],
  pitch: ["medium", "low"],
  contexts: ["Audiobook", "Conversational"],
  type: ["prebuilt"],
  search: "warm",
  page_size: 50,
});

for (const voice of response.voices ?? []) {
  console.log(
    `${voice.id} | ${voice.display_name} (${voice.language_code}, ${voice.accent}, ${voice.gender}, pitch=${voice.pitch}): ${voice.description}`
  );
}
```
{% /tab %}
{% tab label="REST" %}

```sh
curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --data-urlencode "language_code=en-US" \
  --data-urlencode "language_code=en-GB" \
  --data-urlencode "gender=female" \
  --data-urlencode "pitch=medium" \
  --data-urlencode "context=Audiobook" \
  --data-urlencode "type=prebuilt" \
  --data-urlencode "search=warm" \
  --data-urlencode "page_size=50"
```
{% /tab %}
{% /tabs %}

## Supported languages {% id="languages" %}

The TTS models detect the input language automatically.
[Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts)
(`gemini-3.8-flash-tts`) supports **over 130 languages**, and
[Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts)
(`gemini-3.8-flash-lite-tts`) supports **over 100 languages**:

| Language | Gemini 3.8 Flash TTS | Gemini 3.8 Flash-Lite TTS |
| :--- | :--- | :--- |
| Acehnese (Arab script) | ✔️ | ✔️ |
| Afrikaans | ✔️ | ✔️ |
| Akan | ✔️ | ✔️ |
| Amharic | ✔️ | ✔️ |
| Armenian | ✔️ | ✔️ |
| Assamese | ✔️ | ✔️ |
| Awadhi | ✔️ | ✔️ |
| Balinese | ✔️ | ✔️ |
| Bangla | ✔️ | ✔️ |
| Banjar (Arab script) | ✔️ | — |
| Banjar (Latn script) | ✔️ | ✔️ |
| Bashkir | ✔️ | — |
| Basque | ✔️ | ✔️ |
| Belarusian | ✔️ | ✔️ |
| Bemba | ✔️ | — |
| Bhojpuri | ✔️ | ✔️ |
| Bosnian | ✔️ | ✔️ |
| Buginese | ✔️ | ✔️ |
| Bulgarian | ✔️ | ✔️ |
| Burmese | ✔️ | — |
| Cantonese | ✔️ | ✔️ |
| Catalan | ✔️ | ✔️ |
| Cebuano | ✔️ | ✔️ |
| Central Kurdish | ✔️ | ✔️ |
| Chhattisgarhi | ✔️ | ✔️ |
| Chinese (Hans script) | ✔️ | ✔️ |
| Chinese (Hant script) | ✔️ | ✔️ |
| Crimean Tatar | ✔️ | — |
| Croatian | ✔️ | ✔️ |
| Czech | ✔️ | ✔️ |
| Danish | ✔️ | ✔️ |
| Dutch | ✔️ | ✔️ |
| Dyula | ✔️ | — |
| Dzongkha | ✔️ | — |
| Egyptian Arabic | ✔️ | ✔️ |
| English | ✔️ | ✔️ |
| Estonian | ✔️ | ✔️ |
| Filipino | ✔️ | ✔️ |
| Finnish | ✔️ | — |
| French | ✔️ | ✔️ |
| Galician | ✔️ | ✔️ |
| Ganda | ✔️ | ✔️ |
| Georgian | ✔️ | ✔️ |
| German | ✔️ | ✔️ |
| Greek | ✔️ | ✔️ |
| Guarani | ✔️ | — |
| Gujarati | ✔️ | ✔️ |
| Haitian Creole | ✔️ | ✔️ |
| Halh Mongolian | ✔️ | ✔️ |
| Hausa | ✔️ | ✔️ |
| Hebrew | ✔️ | ✔️ |
| Hindi | ✔️ | ✔️ |
| Hungarian | ✔️ | ✔️ |
| Icelandic | ✔️ | ✔️ |
| Igbo | ✔️ | — |
| Iloko | ✔️ | ✔️ |
| Indonesian | ✔️ | ✔️ |
| Iranian Persian | ✔️ | ✔️ |
| Italian | ✔️ | ✔️ |
| Japanese | ✔️ | ✔️ |
| Javanese | ✔️ | ✔️ |
| Kabyle | ✔️ | — |
| Kamba | ✔️ | ✔️ |
| Kannada | ✔️ | ✔️ |
| Kashmiri (Arab script) | ✔️ | ✔️ |
| Kashmiri (Deva script) | ✔️ | ✔️ |
| Kazakh | ✔️ | ✔️ |
| Khmer | ✔️ | ✔️ |
| Kikuyu | ✔️ | ✔️ |
| Kinyarwanda | ✔️ | ✔️ |
| Kongo | ✔️ | ✔️ |
| Korean | ✔️ | ✔️ |
| Kyrgyz | ✔️ | ✔️ |
| Lao | ✔️ | ✔️ |
| Latgalian | ✔️ | — |
| Lingala | ✔️ | ✔️ |
| Lithuanian | ✔️ | — |
| Luxembourgish | ✔️ | — |
| Macedonian | ✔️ | ✔️ |
| Magahi | ✔️ | ✔️ |
| Maithili | ✔️ | ✔️ |
| Malayalam | ✔️ | ✔️ |
| Maltese | ✔️ | ✔️ |
| Manipuri | ✔️ | ✔️ |
| Marathi | ✔️ | ✔️ |
| Minangkabau (Arab script) | ✔️ | ✔️ |
| Minangkabau (Latn script) | ✔️ | — |
| Mizo | ✔️ | ✔️ |
| Nepali (individual language) | ✔️ | ✔️ |
| Nigerian Fulfulde | ✔️ | ✔️ |
| North Azerbaijani | ✔️ | ✔️ |
| Northern Sotho | ✔️ | ✔️ |
| Northern Uzbek | ✔️ | ✔️ |
| Norwegian Bokmål | ✔️ | ✔️ |
| Norwegian Nynorsk | ✔️ | ✔️ |
| Nyanja | ✔️ | ✔️ |
| Occitan | ✔️ | — |
| Odia (individual language) | ✔️ | ✔️ |
| Pangasinan | ✔️ | — |
| Persian (Afghanistan) | ✔️ | ✔️ |
| Polish | ✔️ | ✔️ |
| Portuguese | ✔️ | ✔️ |
| Punjabi | ✔️ | ✔️ |
| Romanian | ✔️ | ✔️ |
| Russian | ✔️ | ✔️ |
| Santali | ✔️ | ✔️ |
| Serbian | ✔️ | ✔️ |
| Sindhi | ✔️ | — |
| Sinhala | ✔️ | ✔️ |
| Slovak | ✔️ | ✔️ |
| Slovenian | ✔️ | — |
| Somali | ✔️ | — |
| South Azerbaijani | ✔️ | ✔️ |
| Southern Pashto | ✔️ | ✔️ |
| Southern Sotho | ✔️ | — |
| Spanish | ✔️ | ✔️ |
| Standard Arabic (Arab script) | ✔️ | ✔️ |
| Standard Arabic (Latn script) | ✔️ | ✔️ |
| Standard Latvian | ✔️ | ✔️ |
| Standard Malay | ✔️ | ✔️ |
| Swahili (individual language) | ✔️ | — |
| Swati | ✔️ | — |
| Swedish | ✔️ | — |
| Tajik | ✔️ | — |
| Tamil | ✔️ | ✔️ |
| Telugu | ✔️ | ✔️ |
| Thai | ✔️ | — |
| Tigrinya | ✔️ | — |
| Tosk Albanian | ✔️ | — |
| Turkish | ✔️ | ✔️ |
| Uyghur | ✔️ | — |
| Vietnamese | ✔️ | ✔️ |

## Supported models {% id="supported-models" %}

| Model | Single speaker | Multi-speaker | Voice design | Voice replication |
| :---- | :---- | :---- | :---- | :---- |
| [Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts) (`gemini-3.8-flash-tts`) | ✔️ | ✔️ | ✔️ | ✔️ |
| [Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts) (`gemini-3.8-flash-lite-tts`) | ✔️ | ✔️ | ✔️ | ✔️ |
| [Gemini 3.1 Flash TTS Preview](/docs/models/gemini-3.1-flash-tts-preview) | ✔️ | ✔️ | — | — |
| [Gemini 2.5 Pro Preview TTS](/docs/models/gemini-2.5-pro-preview-tts) | ✔️ | ✔️ | — | — |

### When to use which model {% id="when-to-use-which-model" %}

Both Gemini 3.8 TTS models share the exact same API schema and prompting format,
allowing you to switch between them with a single parameter change:

*   **Use [Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts)
    (`gemini-3.8-flash-tts`)** when maximum acoustic fidelity, nuanced acting,
    and expressive control are top priority. It is ideal for studio-grade
    creative work, complex multi-speaker dialogue, heavy vocal-burst tags,
    difficult pronunciations, regional or minority dialects, and long-form
    narrations requiring rock-solid voice and room-tone stability.
*   **Use [Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts)
    (`gemini-3.8-flash-lite-tts`)** as your fast, cost-efficient workhorse
    replacement for `gemini-3.1-flash-tts-preview`. It is optimized for
    high-volume bulk production, conversational voice agent cascades, read-aloud
    features, reliable voice replication, and everyday single-speaker speech
    across major languages.

### Migration guide {% id="migration" %}

When upgrading from earlier preview models (`gemini-3.1-flash-tts-preview` or
`gemini-2.5-pro-preview-tts`) to Gemini 3.8 TTS (`gemini-3.8-flash-tts` or
`gemini-3.8-flash-lite-tts`), review these five key changes:

1.  **Separate style from transcript:** Move sustained acting, tone, prosody,
    and pacing instructions (such as `"whispering"`, `"out of breath"`, or
    `"speaking slowly"`) out of plain text and into `speech_metadata.style`.
    Keep `text` strictly as the verbatim transcript plus inline vocal tags.
2.  **Design personas upfront with Voice design:** Replace multi-paragraph
    `"Audio Profile"` or `"Director's Notes"` blocks with a custom voice created
    in [Voice design](/docs/voice-design), then carry that `voice_...` ID
    through your TTS requests with minimal or empty `style` strings.
3.  **Use structured dialogue turns:** For multi-speaker dialogue, pass one
    `content` item per speaker turn with `speech_metadata.speaker` instead of
    embedding `Speaker: ...` prefixes inside a single text block.
4.  **Use angle brackets for inline vocal tags:** Use angle brackets (`<laugh>`,
    `<sigh>`, `<cough>`, `<breath>`, `<short pause>`) for point-in-time human
    vocalizations and pauses. Avoid non-vocal sound-effect tags (such as
    applause or thuds).
5.  **Account for default WAV (`audio/wav`) output on unary requests:** Unlike
    `gemini-3.1-flash-tts-preview` (which returned headerless raw PCM
    `audio/l16` by default), Gemini 3.8 TTS models return complete **WAV
    (`audio/wav`)** audio with a RIFF header (24 kHz, mono, 16-bit PCM) on unary
    requests. You can write decoded audio bytes directly to a `.wav` file
    without manually wrapping them with Python's `wave` module or Node's `wav`
    package. If your existing pipeline expects headerless raw PCM, mu-law, or
    A-law audio, explicitly set `response_format.mime_type` to `"audio/l16"`,
    `"audio/mulaw"`, or `"audio/alaw"` (for example, `{"response_format":
    {"type": "audio", "mime_type": "audio/l16"}}` in the Interactions API, or
    `AUDIO_L16` in `generateContent`; see
    [Audio output formats](/docs/speech-generation#audio-output-formats)).

## Prompting guide {% id="prompting-guide" %}

Gemini 3.8 TTS models treat input text strictly as a **verbatim transcript**.
Unlike earlier preview models where stage directions were embedded in plain
text, Gemini 3.8 TTS separates sustained turn-level directions
(`speech_metadata`) from point-in-time inline vocal tags.

### Style field versus inline tags {% id="style-vs-inline-tags" %}

Split your performance instructions by scope:

*   **Turn-level delivery (`speech_metadata.style`):** Put sustained delivery
    attributes—such as emotion, prosody, overall pace, or delivery style (like
    `"whispering"`, `"out of breath"`, `"muttering"`, or `"sarcastic"`)—into the
    `style` field of `speech_metadata`. To create a stable character and
    performance across turns, design the persona upfront in
    [Voice design](/docs/voice-design) and use `style` only for optional
    turn-level tweaks.
*   **Point-in-time events (inline tags):** Put momentary non-speech vocal
    bursts, breaths, or pauses inline inside the transcript using angle brackets
    (`<cough>`, `<breath>`, `<sigh>`, `<short pause>`). Use angle brackets
    (`<...>`) for highest audio quality, and stick to human vocalizations rather
    than non-vocal sound effects.

| Scope                 | Where to place          | Examples                   |
| :-------------------- | :---------------------- | :------------------------- |
| **Turn-level** (sustained across the turn) | `speech_metadata.style` | `"angry tone"`, `"speaking rapidly"`, `"out of breath"`, `"whispers"`, `"sarcastic"` |
| **Point-in-time** (occurs at a specific word) | Inline in `text` (`<...>`) | `"<cough> Thank you all for coming tonight! <throat-clearing> As I was saying..."` |

### Pacing and pauses {% id="pacing-and-pauses" %}

You can control rhythm and silence at three levels of granularity:

*   **Punctuation and ellipses:** Use commas, dashes (`--`), and ellipses
    (`...`) for natural conversational hesitation.
*   **Inline pause tags:** Insert `<short pause>` or `<long pause>` at exact
    points in the script where a speaker should pause:

    ```text
    Hold on, let me think... <short pause> Alright, I've got it.
    ```
*   **Turn-level pace:** Set `"style": "speaking rapidly"` or `"style":
    "speaking slowly"` in `speech_metadata` to control the speaking rate across
    the whole turn.

### Prosody and pitch {% id="prosody-and-pitch" %}

Use **`speech_metadata.style`** to control prosody, pitch, and inflection across
a turn (for example, `"style": "high pitch, cheerful and excited inflection"` or
`"style": "monotone and flat"`). If the emotion or prosody shifts mid-dialogue,
split the script into separate turns with distinct `style` values for each turn.

### Emphasis {% id="emphasis" %}

Capitalize specific words in the transcript, combined with punctuation and
inline vocal tags, to place natural vocal stress on key words:

```text
This is a VERY important point!
It was a VERY long day <sigh> ... nobody listens anymore.
```

### Vocal bursts and non-speech sounds {% id="vocal-bursts" %}

Place non-speech human vocalizations inline using angle brackets (`<...>`) at
the exact point where the sound should occur. Recommended vocal tags include:

{% table %}

*   `<argh>`
*   `<breath>`
*   `<heavy breath>`
* `<exhales>`
---

*   `<cackle>`
*   `<cheer>`
*   `<chuckle>` / `<chuckles>`
* `<cough>`
---

*   `<cry>`
*   `<gasp>`
*   `<giggle>`
* `<groan>`
---

*   `<growl>`
*   `<grunt>`
*   `<grr>`
* `<hiss>`
---

*   `<laugh>` / `<laughter>`
*   `<moan>`
*   `<pant>`
* `<pff>` / `<phew>`
---

*   `<scream>`
*   `<shout>`
*   `<shriek>`
* `<sigh>` / `<sighs>`
---

*   `<sneeze>`
*   `<snicker>`
*   `<snort>`
* `<sob>`
---

*   `<throat-clearing>`
*   `<tsk>`
*   `<whimper>`
* `<whispers>` / `<whispering>`
---

*   `<yawn>`
*   `<short pause>`
* `<long pause>`

{% /table %}

{% callout type="note" %}
 If your transcript is in a non-English language,
continue to use English inline tags for best results.

{% /callout %}

### Backchannels and overlapping speech {% id="backchannels" %}

In multi-speaker dialogue, wrap listener reactions in pipe characters
(`|reaction|`) inside a speaker's turn to create natural backchannels or
overlapping speech without breaking into a separate turn per reaction.

*   **Short backchannel exchanges:** Layer brief listener reactions (`|oh hmm|`,
    `|oh really?|`, `|absolutely|`) inside the active speaker's turn:
    *   **Turn 1 (Speaker A):** `"So the launch is Thursday |oh hmm| Are we
        actually ready?"`
    *   **Turn 2 (Speaker B):** `"Ready enough |oh really?| The last blocker
        cleared this morning."`
    *   **Turn 3 (Speaker A):** `"Then let's ship it |absolutely| and watch the
        dashboards."`
*   **Overlapping and interleaved speech:** Use multiple pipe segments to
    simulate simultaneous or interleaved speech between two speakers (works best
    with `gemini-3.8-flash-tts`):
    *   **Simultaneous countdown/chorus:** `"Let's surprise him on three |ok|
        ready?"` followed by `"one. two. three. |happy| happy |birthday|
        birthday!"`
    *   **Full speaker overlap:** `"Hello |oh| there |my| it |goodness| must
        |gracious| be |would| almost |you| time |look| for |at that| dinner"`

### Consistency across generations and what to avoid {% id="consistency-and-what-to-avoid" %}

Follow these guidelines to keep vocal identity stable across turns:

*   **Design personas upfront in Voice design instead of long style blocks:**
    Long-form `"Audio Profile"` paragraphs and multi-bullet `"Director's Notes"`
    carried over from earlier models are the most common cause of voice drift.
    Use that same creative intuition upfront in
    [Voice design](/docs/voice-design) to generate a persistent custom
    `voice_...` persona, then carry that voice ID through your TTS calls.
*   **Rely on the voice reference for stability (omit meta-instructions):**
    Gemini 3.8 TTS models are trained to anchor on the audio reference first. Do
    not include instructions telling the model to hold the voice steady (such as
    `"do not switch speaker identity"` or `"maintain identical timbre"`)—extra
    prompt text increases drift. Drop unnecessary style instructions and let the
    model vary naturally around the stable point provided by the voice
    reference.
*   **Do not try to change immutable speaker traits in `style`:** Avoid putting
    age, gender, names, or permanent accent changes in `speech_metadata.style`.
    Instead, pick a regional voice from the Extended Voice Library or create one
    with [Voice design](/docs/voice-design).

### Recommended workflow {% id="recommended-workflow" %}

1.  **Build the character once:** Create your character in
    [Voice design](/docs/voice-design) or select a regional voice from the
    Extended Voice Library that matches your target language and persona.
2.  **Write natural spoken transcripts with disfluencies:** For maximum
    naturalness, write the `text` as a real spoken transcript—including natural
    conversational disfluencies and hesitations (for example, `"Oh uh yeah I
    think... hm, so that's interesting"`).
3.  **Test plain TTS first:** Synthesize your transcript with an empty `style`
    field first—most requests need no `style` instruction at all.
4.  **Add short `style` prompts only for tweaks:** Add a concise `style` string
    (such as `"casual, friendly"` or `"muttering, then reassuring"`) only for
    turns that need a specific delivery adjustment, and reuse that exact short
    string across turns when you want a consistent baseline.

### Multi-turn dialogue and voice agents {% id="multi-turn-and-voice-agents" %}

When building real-time conversational voice agents or multi-turn applications:

*   Make **one TTS call per turn** as LLM text chunks arrive.
*   Let the configured `voice` (prebuilt, designed `voice_...`, or replicated
    `voice_...` / `voicekey_...`) carry the speaker's identity across
    turns—never re-send a long character persona on each turn.
*   Leave the per-turn `style` field empty, or send one short constant string
    (such as `"casual, friendly"`) for the whole conversation.
*   Split long agent responses into shorter turns rather than reaching for
    stronger style prompts.

## Limitations {% id="limitations" %}

*   TTS models accept text-only inputs and generate audio-only outputs.
*   Single-request multi-speaker generation (`speech_config.speakers`) supports
    up to 2 speakers using prebuilt voices. To combine custom designed
    (`voice_...`) or replicated (`voice_...` / `voicekey_...`) voices in
    multi-character dialogue, synthesize each speaker's turn individually.
    Because unary requests return `audio/wav` with a 44-byte RIFF header by
    default, request raw PCM (`{"type": "audio", "mime_type": "audio/l16"}`) or
    strip the WAV header from each turn before concatenating the 24kHz PCM
    audio frames.
*   **Custom voice storage limits and TTL:**
    *   **Stateful voices (`store=True`, prompted or replicated):** Maximum of
        **200 voices per project** with a **1-year TTL** (time-to-live).
    *   **Stateless voice keys (`store=False`, `voicekey_...`):** **7-day TTL**
        (time-to-live).
*   Review the [Supported languages](/docs/speech-generation#languages) section
    for language coverage.

## What's next {% id="whats-next" %}

*   Create custom vocal personas from natural language with
    [Voice design](/docs/voice-design).
*   Replicate an existing speaker's voice in
    [Voice replication](/docs/voice-replication).
*   Compare model specifications on the
    [Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts) and
    [Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts) model
    pages.
*   Explore interactive bidirectional audio with the [Live API](/docs/live-api).

# Voice design
Source: https://aistudio.google.com/docs/voice-design
Description: Create persistent custom vocal personas from natural-language descriptions with Gemini 3.8 TTS.

Voice design lets you create a brand-new, persistent vocal persona from a
natural-language description using the Gemini API Voices endpoint
(`POST /v1beta/voices`). Instead of being limited to prebuilt voices or
recording reference audio, you can describe a character's age, vocal timbre,
accent, and baseline delivery, and receive a reusable `voice_...` ID saved to
your project.

The fastest way to design, audition, and iterate on custom voices is with the
interactive **Voice Design** studio in
[Google AI Studio](https://aistudio.google.com/generate-speech). You can
generate custom personas from text prompts, test them with sample scripts, and
copy the resulting `voice_...` ID directly into your application code.

{% button href="https://aistudio.google.com/generate-speech" variant="primary" %}Try in Google AI Studio{% /button %}

Both [Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts)
(`gemini-3.8-flash-tts`) and
[Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts)
(`gemini-3.8-flash-lite-tts`) support Voice design.

## Create a designed voice {% id="create-a-designed-voice" %}

Use the Google GenAI SDK (`google-genai` 2.25.0+ / `@google/genai` 2.24.0+) or REST API
to create a custom voice from a text description. For `"prompted"` voices, both
`voices.create` (`CreateVoice`) and `voices.get` (`GetVoice`) return an
output-only `sample_audio` field (`mime_type: "audio/wav"`, base64-encoded
`data`) so you can immediately audition the generated voice:

{% tabs %}
{% tab label="Python" %}

```python
import base64
from google import genai

client = genai.Client()

# 1. Design a custom voice persona from natural language
created_voice = client.voices.create(
    store=True,
    voice={
        "model": "gemini-3.8-flash-tts",
        "type": "prompted",
        "display_name": "Warm British Astronomer",
        "gender": "male",
        "language_code": "en-GB",
        "prompted": {
            "input": (
                "A warm, thoughtful astronomer in his late 60s with a gentle"
                " British accent, speaking with quiet wonder."
            )
        },
    },
)

print(f"Created voice ID: {created_voice.id}")

# Save the generated sample_audio preview (audio/wav) returned by CreateVoice
if created_voice.sample_audio and created_voice.sample_audio.data:
    with open("voice_preview.wav", "wb") as f:
        f.write(base64.b64decode(created_voice.sample_audio.data))
```
{% /tab %}
{% tab label="JavaScript" %}

```javascript
import * as fs from "node:fs";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

// 1. Design a custom voice persona from natural language
const createdVoice = await ai.voices.create({
  store: true,
  voice: {
    model: "gemini-3.8-flash-tts",
    type: "prompted",
    display_name: "Warm British Astronomer",
    gender: "male",
    language_code: "en-GB",
    prompted: {
      input:
        "A warm, thoughtful astronomer in his late 60s with a gentle British accent, speaking with quiet wonder.",
    },
  },
});

console.log(`Created voice ID: ${createdVoice.id}`);

// Save the generated sample_audio preview (audio/wav) returned by CreateVoice
if (createdVoice.sample_audio?.data) {
  fs.writeFileSync(
    "voice_preview.wav",
    Buffer.from(createdVoice.sample_audio.data, "base64")
  );
}
```
{% /tab %}
{% tab label="REST" %}

```bash
curl "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "store": true,
    "voice": {
      "model": "gemini-3.8-flash-tts",
      "type": "prompted",
      "display_name": "Warm British Astronomer",
      "gender": "male",
      "language_code": "en-GB",
      "prompted": {
        "input": "A warm, thoughtful astronomer in his late 60s with a gentle British accent, speaking with quiet wonder."
      }
    }
  }' | tee created_voice.json | jq -r '.sample_audio.data' | base64 --decode > voice_preview.wav
```
{% /tab %}
{% /tabs %}

## How Voice design works {% id="how-voice-design-works" %}

1.  **Create a prompted voice:** Call `voices.create` (`POST /v1beta/voices`)
    with `type="prompted"` and `store=True`.
2.  **Receive a persistent `voice_id` and `sample_audio` preview:** The API
    generates the vocal identity, stores it in your project, and returns a
    permanent ID (for example, `voice_abc123...`) along with `sample_audio`
    (`mime_type: "audio/wav"`, base64-encoded `data`) containing the generated
    preview audio for the voice.
3.  **Synthesize speech:** Pass the `voice_id` anywhere a voice name is accepted
    in your synthesis requests.

## Synthesize speech with your designed voice {% id="synthesize-speech-with-your-designed-voice" %}

Once you have created a voice, pass its `id` (`voice_...`) to the Interactions
API to generate speech:

{% tabs %}
{% tab label="Python" %}

```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": (
                "Look out past the rings of Saturn. Those faint photons left"
                " their source millions of years ago."
            ),
            "annotations": [{
                "type": "speech_metadata",
                "style": "reflective and awe-inspired",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": created_voice.id},
        ]
    },
)

with open("designed_voice.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))
```
{% /tab %}
{% tab label="JavaScript" %}

```javascript
import * as fs from "node:fs";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash-tts",
  input: [{
    type: "user_input",
    content: [{
      type: "text",
      text: "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
      annotations: [{
        type: "speech_metadata",
        style: "reflective and awe-inspired",
      }],
    }],
  }],
  response_format: { type: "audio" },
  generation_config: {
    speech_config: [
      { voice: createdVoice.id },
    ],
  },
});

if (interaction.output_audio?.data) {
  fs.writeFileSync("designed_voice.wav", Buffer.from(interaction.output_audio.data, "base64"));
}
```
{% /tab %}
{% tab label="REST" %}

```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
        "annotations": [{
          "type": "speech_metadata",
          "style": "reflective and awe-inspired"
        }]
      }]
    }],
    "response_format": {"type": "audio"},
    "generation_config": {
      "speech_config": [
        {"voice": "voice_YOUR_DESIGNED_VOICE_ID"}
      ]
    }
  }' | jq -r '[.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio")] | last | .data' | base64 --decode > out.wav
```

{% /tab %}
{% /tabs %}

## Manage your voices {% id="manage-your-voices" %}

You can list, filter, inspect, and delete your stored voices at any time using
the Voices API (see
[Extended Voice Library and filtering](/docs/speech-generation#voice-library)
for all filter parameters).

*   **Storage limits and TTL:** Stateful voices (`store=True`, shared across
    prompted and replicated voices) have a limit of **200 voices per project**
    and a **1-year TTL** (time-to-live).
*   **`sample_audio` availability:** `voices.create()` (`CreateVoice`) and
    `voices.get()` (`GetVoice`) populate `sample_audio` (`mime_type:
    "audio/wav"`, base64-encoded `data`) for `"prompted"` voices. To keep
    listing lightweight, `voices.list()` (`ListVoices`) omits `sample_audio`
    (and `sample_audio` is unset for `"replicated"` and `"prebuilt"` voices).

{% tabs %}
{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

# List stored prompted voices in your project filtered by language
response = client.voices.list(
    type_=["prompted"],
    language_code=["en-US", "en-GB"],
)
for voice in response.voices or []:
    print(voice.id, voice.display_name, voice.type)

# Retrieve a specific voice by ID
voice_details = client.voices.get(id=created_voice.id)

# Delete a stored custom voice
client.voices.delete(id=created_voice.id)
```
{% /tab %}
{% tab label="JavaScript" %}

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

const ai = new GoogleGenAI();

// List stored prompted voices in your project filtered by language
const response = await ai.voices.list({
  type: ["prompted"],
  language_code: ["en-US", "en-GB"],
});
for (const voice of response.voices ?? []) {
  console.log(voice.id, voice.display_name, voice.type);
}

// Retrieve a specific voice by ID
const voiceDetails = await ai.voices.get(createdVoice.id);

// Delete a stored custom voice
await ai.voices.delete(createdVoice.id);
```
{% /tab %}
{% tab label="REST" %}

```bash
# List stored prompted voices filtered by language
curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --data-urlencode "type=prompted" \
  --data-urlencode "language_code=en-US" \
  --data-urlencode "language_code=en-GB"

# Retrieve a specific voice by ID
curl "https://generativelanguage.googleapis.com/v1beta/voices/voice_YOUR_DESIGNED_VOICE_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# Delete a stored custom voice
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/voices/voice_YOUR_DESIGNED_VOICE_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## Prompting best practices for Voice design {% id="prompting-best-practices-for-voice-design" %}

*   **Put permanent vocal traits in Voice design, not `style`:** Define
    immutable characteristics—such as age, gender, timbre, vocal texture, and
    regional accent—when creating the voice in `voices.create`.
*   **Reserve `speech_metadata.style` for situational emotion:** Once your
    custom voice is created, use short `style` prompts (for example,
    `"whispered urgently"` or `"cheerful and energetic"`) to steer turn-by-turn
    acting without altering the speaker's core identity.
*   **Be specific and concise:** A clear 1–2 sentence description (such as
    *"A crisp, energetic sports announcer in her 30s with a slight Midwestern
    accent"*) produces cleaner, more consistent results than contradictory or
    overly long paragraphs.

## What's next {% id="whats-next" %}

*   Learn how to replicate an existing speaker's voice in
    [Voice replication](/docs/voice-replication).
*   Explore turn-level styling, inline tags, and multi-speaker dialogue in the
    [Text-to-speech guide](/docs/speech-generation).

# Voice replication
Source: https://aistudio.google.com/docs/voice-replication
Description: Replicate a speaker's voice with persistent voice IDs or stateless client keys in the Gemini API.

Voice replication lets you replicate a speaker's vocal characteristics from a
short audio sample using the Gemini API Voices endpoint (`POST /v1beta/voices`).
Both [Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts)
(`gemini-3.8-flash-tts`) and
[Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts)
(`gemini-3.8-flash-lite-tts`) support Voice replication.

The fastest way to replicate, verify consent, and audition a replicated voice is
with the interactive **Voice Replication** experience in
[Google AI Studio](https://aistudio.google.com/generate-speech). You can record
or upload reference and consent clips directly in the browser, preview the
voice, and copy the resulting `voice_...` ID directly into your application
code.

{% button href="https://aistudio.google.com/generate-speech" variant="primary" %}Try in Google AI Studio{% /button %}

![Voice replication workflow](/googledevai/static/gemini-api/docs/images/voice-replication-overview.svg)

## Stateful versus stateless storage modes {% id="storage-modes" %}

Voice replication supports two storage modes when calling `voices.create`
(`POST /v1beta/voices`), with stateful storage enabled by default:

*   **Stateful storage (`store=True`, recommended default):** Google stores your
    verified voice profile in your project and returns a lightweight, persistent
    `voice_id` (`replicated_voice.id`, such as `voice_abc123...`). You can pass
    this `voice_id` across requests and manage it with `voices.list()`,
    `voices.get()`, and `voices.delete()`.
*   **Stateless client-managed keys (`store=False`, optional):** For workloads
    requiring zero server-side persistence of biometric voice profiles, set
    `store=False`. The API returns an encrypted, self-contained `voice_key`
    (`replicated_voice.key`, starting with `voicekey_...`) that your application
    stores locally and passes directly in synthesis requests.

| Storage mode | Identifier | Project limit | Retention (TTL) |
| :--- | :--- | :--- | :--- |
| **Stateful voices** (`store=True`) | `voice_...` | **200 voices per project** (shared across prompted and replicated voices) | **1 year** |
| **Stateless voice keys** (`store=False`) | `voicekey_...` | Client-managed | **7 days** |

## Audio and consent requirements {% id="audio-and-consent-requirements" %}

Every `CreateVoice` replication request requires two real human audio recordings
from the **same adult speaker** (24kHz mono 16-bit WAV recommended):

1.  **Reference audio (`source_audio`):** A 10–30 second clip of clean, natural
    speech from the speaker whose voice you want to replicate.
2.  **Consent audio (`consent_audio`):** A recording of the same speaker clearly
    reciting the mandatory consent statement in one of the
    [supported languages](/docs/voice-replication#consent-phrases-by-language)
    (for example, in English):
    > *"I am the owner of this voice and I consent to Google using this voice to
    > create a synthetic voice model."*

## Create a replicated voice (stateful default) {% id="create-a-replicated-voice" %}

Use the Google GenAI SDK (`google-genai` 2.25.0+ / `@google/genai` 2.24.0+) or REST API
with `store=True` to create and save a replicated voice profile in your project:

{% tabs %}
{% tab label="Python" %}

```python
import base64
from google import genai

client = genai.Client()

with open("reference_speaker.wav", "rb") as f:
    source_b64 = base64.b64encode(f.read()).decode("utf-8")

with open("speaker_consent.wav", "rb") as f:
    consent_b64 = base64.b64encode(f.read()).decode("utf-8")

# Create a persistent replicated voice (store=True)
replicated_voice = client.voices.create(
    store=True,
    voice={
        "model": "gemini-3.8-flash-tts",
        "type": "replicated",
        "display_name": "Custom Replicated Speaker",
        "replicated": {
            "source_audio": {
                "mime_type": "audio/wav",
                "data": source_b64,
            },
            "consent_audio": {
                "mime_type": "audio/wav",
                "data": consent_b64,
            },
        },
    },
)

print(f"Created voice ID: {replicated_voice.id}")
```
{% /tab %}
{% tab label="JavaScript" %}

```javascript
import * as fs from "node:fs";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

const sourceB64 = fs.readFileSync("reference_speaker.wav").toString("base64");
const consentB64 = fs.readFileSync("speaker_consent.wav").toString("base64");

// Create a persistent replicated voice (store: true)
const replicatedVoice = await ai.voices.create({
  store: true,
  voice: {
    model: "gemini-3.8-flash-tts",
    type: "replicated",
    display_name: "Custom Replicated Speaker",
    replicated: {
      source_audio: {
        mime_type: "audio/wav",
        data: sourceB64,
      },
      consent_audio: {
        mime_type: "audio/wav",
        data: consentB64,
      },
    },
  },
});

console.log(`Created voice ID: ${replicatedVoice.id}`);
```
{% /tab %}
{% tab label="REST" %}

```bash
SOURCE_B64=$(base64 -w 0 reference_speaker.wav)
CONSENT_B64=$(base64 -w 0 speaker_consent.wav)

curl "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d "{
    \"store\": true,
    \"voice\": {
      \"model\": \"gemini-3.8-flash-tts\",
      \"type\": \"replicated\",
      \"display_name\": \"Custom Replicated Speaker\",
      \"replicated\": {
        \"source_audio\": {
          \"mime_type\": \"audio/wav\",
          \"data\": \"$SOURCE_B64\"
        },
        \"consent_audio\": {
          \"mime_type\": \"audio/wav\",
          \"data\": \"$CONSENT_B64\"
        }
      }
    }
  }"
```
{% /tab %}
{% /tabs %}

## Synthesize speech with your replicated voice {% id="synthesize-speech-with-your-replicated-voice" %}

Pass the returned `id` (`voice_...`) in your synthesis request:

{% tabs %}
{% tab label="Python" %}

```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": (
                "Hello! This audio was synthesized using a replicated"
                " speaker voice."
            ),
            "annotations": [{
                "type": "speech_metadata",
                "style": "warm and conversational",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": replicated_voice.id},
        ]
    },
)

with open("replicated_speech.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))
```
{% /tab %}
{% tab label="JavaScript" %}

```javascript
import * as fs from "node:fs";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash-tts",
  input: [{
    type: "user_input",
    content: [{
      type: "text",
      text: "Hello! This audio was synthesized using a replicated speaker voice.",
      annotations: [{
        type: "speech_metadata",
        style: "warm and conversational",
      }],
    }],
  }],
  response_format: { type: "audio" },
  generation_config: {
    speech_config: [
      { voice: replicatedVoice.id },
    ],
  },
});

if (interaction.output_audio?.data) {
  fs.writeFileSync("replicated_speech.wav", Buffer.from(interaction.output_audio.data, "base64"));
}
```
{% /tab %}
{% tab label="REST" %}

```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Hello! This audio was synthesized using a replicated speaker voice.",
        "annotations": [{
          "type": "speech_metadata",
          "style": "warm and conversational"
        }]
      }]
    }],
    "response_format": {"type": "audio"},
    "generation_config": {
      "speech_config": [
        {"voice": "voice_YOUR_REPLICATED_VOICE_ID"}
      ]
    }
  }' | jq -r '[.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio")] | last | .data' | base64 --decode > out.wav
```

{% /tab %}
{% /tabs %}

## Manage stored replicated voices {% id="manage-stored-replicated-voices" %}

When created with `store=True`, your replicated voices can be listed, filtered,
inspected, and deleted through the Voices API (see
[Extended Voice Library and filtering](/docs/speech-generation#voice-library)
for all filter parameters):

{% tabs %}
{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

# List stored replicated voices in your project
response = client.voices.list(type_=["replicated"])
for voice in response.voices or []:
    print(voice.id, voice.display_name, voice.type)

# Retrieve a specific voice by ID
voice_details = client.voices.get(id=replicated_voice.id)

# Delete a stored replicated voice
client.voices.delete(id=replicated_voice.id)
```
{% /tab %}
{% tab label="JavaScript" %}

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

const ai = new GoogleGenAI();

// List stored replicated voices in your project
const response = await ai.voices.list({ type: ["replicated"] });
for (const voice of response.voices ?? []) {
  console.log(voice.id, voice.display_name, voice.type);
}

// Retrieve a specific voice by ID
const voiceDetails = await ai.voices.get(replicatedVoice.id);

// Delete a stored replicated voice
await ai.voices.delete(replicatedVoice.id);
```
{% /tab %}
{% tab label="REST" %}

```bash
# List stored replicated voices in your project
curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --data-urlencode "type=replicated"

# Retrieve a specific voice by ID
curl "https://generativelanguage.googleapis.com/v1beta/voices/voice_YOUR_REPLICATED_VOICE_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# Delete a stored replicated voice
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/voices/voice_YOUR_REPLICATED_VOICE_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## Option: Stateless client-managed voice keys (`store=False`) {% id="stateless-client-managed-keys" %}

If your application requires zero server-side persistence of voice profiles, set
`store=False` when creating the replicated voice. The API returns an encrypted
`voice_key` (`replicated_voice.key`, starting with `voicekey_...`) that you
store client-side and pass directly anywhere a `voice` ID is accepted:

{% tabs %}
{% tab label="Python" %}

```python
import base64
from google import genai

client = genai.Client()

with open("reference_speaker.wav", "rb") as f:
    source_b64 = base64.b64encode(f.read()).decode("utf-8")

with open("speaker_consent.wav", "rb") as f:
    consent_b64 = base64.b64encode(f.read()).decode("utf-8")

# Create a stateless client-managed voice key (store=False)
replicated_voice = client.voices.create(
    store=False,
    voice={
        "model": "gemini-3.8-flash-tts",
        "type": "replicated",
        "replicated": {
            "source_audio": {"mime_type": "audio/wav", "data": source_b64},
            "consent_audio": {"mime_type": "audio/wav", "data": consent_b64},
        },
    },
)

# Pass replicated_voice.key ("voicekey_...") directly as the speaker voice
interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Hello! This audio uses a stateless client-managed voice key.",
            "annotations": [{
                "type": "speech_metadata",
                "style": "warm and conversational",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": replicated_voice.key},
        ]
    },
)
```
{% /tab %}
{% tab label="JavaScript" %}

```javascript
import * as fs from "node:fs";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

const sourceB64 = fs.readFileSync("reference_speaker.wav").toString("base64");
const consentB64 = fs.readFileSync("speaker_consent.wav").toString("base64");

// Create a stateless client-managed voice key (store: false)
const replicatedVoice = await ai.voices.create({
  store: false,
  voice: {
    model: "gemini-3.8-flash-tts",
    type: "replicated",
    replicated: {
      source_audio: { mime_type: "audio/wav", data: sourceB64 },
      consent_audio: { mime_type: "audio/wav", data: consentB64 },
    },
  },
});

// Pass replicatedVoice.key ("voicekey_...") directly as the speaker voice
const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash-tts",
  input: [{
    type: "user_input",
    content: [{
      type: "text",
      text: "Hello! This audio uses a stateless client-managed voice key.",
      annotations: [{
        type: "speech_metadata",
        style: "warm and conversational",
      }],
    }],
  }],
  response_format: { type: "audio" },
  generation_config: {
    speech_config: [
      { voice: replicatedVoice.key },
    ],
  },
});
```
{% /tab %}
{% tab label="REST" %}

```bash
SOURCE_B64=$(base64 -w 0 reference_speaker.wav)
CONSENT_B64=$(base64 -w 0 speaker_consent.wav)

curl "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d "{
    \"store\": false,
    \"voice\": {
      \"model\": \"gemini-3.8-flash-tts\",
      \"type\": \"replicated\",
      \"replicated\": {
        \"source_audio\": {\"mime_type\": \"audio/wav\", \"data\": \"$SOURCE_B64\"},
        \"consent_audio\": {\"mime_type\": \"audio/wav\", \"data\": \"$CONSENT_B64\"}
      }
    }
  }"
```
{% /tab %}
{% /tabs %}

## Supported consent phrases by language {% id="consent-phrases-by-language" %}

The consent audio must clearly recite the exact statement in one of the 30 supported language locales:

| Language | Locale (`lang_id`) | Verbatim Consent Statement |
| :--- | :--- | :--- |
| **Arabic** | `ar-XA` | أنا مالك هذا الصوت وأوافق على أن تستخدم Google هذا الصوت لإنشاء نموذج صوتي اصطناعي. |
| **Bengali** | `bn-IN` | আমি এই ভয়েসের মালিক এবং আমি একটি সিন্থেটিক ভয়েস মডেল তৈরি করতে এই ভয়েস ব্যবহার করে Google-এর সাথে সম্মতি দিচ্ছি। |
| **Chinese (Simplified)** | `zh-CN` | 我是此声音的拥有者并授权谷歌使用此声音创建语音合成模型 |
| **Dutch** | `nl-NL` | Ik ben de eigenaar van deze stem en ik geef Google toestemming om deze stem te gebruiken om een synthetisch stemmodel te maken. |
| **English (US)** | `en-US` | I am the owner of this voice and I consent to Google using this voice to create a synthetic voice model. |
| **English (UK)** | `en-GB` | I am the owner of this voice and I consent to Google using this voice to create a synthetic voice model. |
| **English (India)** | `en-IN` | I am the owner of this voice and I consent to Google using this voice to create a synthetic voice model. |
| **English (Australia)** | `en-AU` | I am the owner of this voice and I consent to Google using this voice to create a synthetic voice model. |
| **French (France)** | `fr-FR` | Je suis le propriétaire de cette voix et j'autorise Google à utiliser cette voix pour créer un modèle de voix synthétique. |
| **French (Canada)** | `fr-CA` | Je suis le propriétaire de cette voix et j'autorise Google à utiliser cette voix pour créer un modèle de voix synthétique. |
| **German** | `de-DE` | Ich bin der Eigentümer dieser Stimme und bin damit einverstanden, dass Google diese Stimme zur Erstellung eines synthetischen Stimmmodells verwendet. |
| **Gujarati** | `gu-IN` | હું આ વોઈસનો માલિક છું અને સિન્થેટિક વોઈસ મોડલ બનાવવા માટે આ વોઈસનો ઉપયોગ કરીને google ને હું સંમતિ આપું છું |
| **Hindi** | `hi-IN` | मैं इस आवाज का मालिक हूं और मैं सिंथेटिक आवाज मॉडल बनाने के लिए Google को इस आवाज का उपयोग करने की सहमति देता हूं |
| **Indonesian** | `id-ID` | Saya pemilik suara ini dan saya menyetujui Google menggunakan suara ini untuk membuat model suara sintetis. |
| **Italian** | `it-IT` | Sono il proprietario di questa voce e acconsento che Google la utilizzi per creare un modello di voce sintetica. |
| **Japanese** | `ja-JP` | 私はこの音声の所有者であり、Googleがこの音声を使用して音声合成モデルを作成することを承認します。 |
| **Kannada** | `kn-IN` | ನಾನು ಈ ಧ್ವನಿಯ ಮಾಲಿಕ ಮತ್ತು ಸಂಶ್ಲೇಷಿತ ಧ್ವನಿ ಮಾದರಿಯನ್ನು ರಚಿಸಲು ಈ ಧ್ವನಿಯನ್ನು ಬಳಸಿಕೊಂಡುಗೂಗಲ್ ಗೆ ನಾನು ಸಮ್ಮತಿಸುತ್ತೇನೆ. |
| **Korean** | `ko-KR` | 나는 이 음성의 소유자이며 구글이 이 음성을 사용하여 음성 합성 모델을 생성할 것을 허용합니다. |
| **Malayalam** | `ml-IN` | ഈ ശബ്ദത്തിന്റെ ഉടമ ഞാനാണ്, ഒരു സിന്തറ്റിക് വോയ്സ് മോഡൽ സൃഷ്ടിക്കാൻ ഈ ശബ്ദം ഉപയോഗിക്കുന്നതിന് ഞാൻ Google-ന് സമ്മതം നൽകുന്നു. |
| **Marathi** | `mr-IN` | मी या आवाजाचा मालक आहे आणि सिंथेटिक व्हॉइस मॉडेल तयार करण्यासाठी हा आवाज वापरण्यासाठी मी Google ला संमती देतो |
| **Polish** | `pl-PL` | Jestem właścicielem tego głosu i wyrażam zgodę na wykorzystanie go przez Google w celu utworzenia syntetycznego modelu głosu. |
| **Portuguese (Brazil)** | `pt-BR` | Eu sou o proprietário desta voz e autorizo o Google a usá-la para criar um modelo de voz sintética. |
| **Russian** | `ru-RU` | Я являюсь владельцем этого голоса и даю согласие Google на использование этого голоса для создания модели синтетического голоса. |
| **Spanish (Spain)** | `es-ES` | Soy el propietario de esta voz y doy mi consentimiento para que Google la utilice para crear un modelo de voz sintética. |
| **Spanish (US)** | `es-US` | Soy el propietario de esta voz y doy mi consentimiento para que Google la utilice para crear un modelo de voz sintética. |
| **Tamil** | `ta-IN` | நான் இந்த குரலின் உரிமையாளர் மற்றும் செயற்கை குரல் மாதிரியை உருவாக்க இந்த குரலை பயன்படுத்த குகல்க்கு நான் ஒப்புக்கொள்கிறேன். |
| **Telugu** | `te-IN` | నేను ఈ వాయిస్ యజమానిని మరియు సింతటిక్ వాయిస్ మోడల్ ని రూపొందించడానికి ఈ వాయిస్ ని ఉపయోగించడానికి googleకి నేను సమ్మతిస్తున్నాను. |
| **Thai** | `th-TH` | ฉันเป็นเจ้าของเสียงนี้ และฉันยินยอมให้ Google ใช้เสียงนี้เพื่อสร้างแบบจำลองเสียงสังเคราะห์ |
| **Turkish** | `tr-TR` | Bu sesin sahibi benim ve Google'ın bu sesi kullanarak sentetik bir ses modeli oluşturmasına izin veriyorum. |
| **Vietnamese** | `vi-VN` | Tôi là chủ sở hữu giọng nói này và tôi đồng ý cho Google sử dụng giọng nói này để tạo mô hình giọng nói tổng hợp. |

## Best practices for recording reference audio {% id="best-practices" %}

*   **Record in a quiet environment:** Minimize room echo, background noise,
    music, and overlapping voices.
*   **Match recording conditions:** Record both `source_audio` and
    `consent_audio` on the same microphone in the same acoustic setting so the
    speaker verification check succeeds reliably.
*   **Convert to 24kHz mono WAV:** For best results, resample input audio to
    24kHz mono 16-bit PCM WAV before encoding.

## What's next {% id="whats-next" %}

*   Learn how to create custom personas from text descriptions in
    [Voice design](/docs/voice-design).
*   Explore turn-level styling, inline tags, and multi-speaker dialogue in the
    [Text-to-speech guide](/docs/speech-generation).

# Audio transcription
Source: https://aistudio.google.com/docs/transcribe
Description: Get started transcribing audio with the Gemini 3.5 Transcribe model in the Gemini API

The Gemini API converts speech in audio files into text using the Gemini 3.5 Transcribe model (`gemini-3.5-transcribe`). Based on Gemini's audio understanding capabilities, it delivers accurate transcription with automatic language identification, speaker diarization, word-level timestamps, and custom vocabulary hints. It also provides a [smart transcription](/docs/transcribe#transcription-modes) mode featuring disfluency removal and smart formatting.

To transcribe an audio file, upload the audio and pass it to `gemini-3.5-transcribe`:

{% tabs %}
{% tab label="Python" filename="transcribe_quickstart.py" %}
```python
from google import genai

client = genai.Client()

audio_file = client.files.upload(file="path/to/sample.mp3")

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
)

print(response.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="transcribe_quickstart.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const audioFile = await ai.files.upload({
  file: "path/to/sample.mp3",
  config: { mimeType: "audio/mp3" },
});

const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
});

console.log(response.output_text);
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}
{% tab label="REST" filename="transcribe_quickstart.sh" %}
```bash
# First upload the file via the Files API, then pass its URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
For real-time, low-latency streaming speech recognition from a microphone or live audio stream, see [Live transcription](/docs/live-api/live-transcribe) using the Live API and `gemini-3.5-transcribe-live`.
{% /callout %}

## Overview {% id="overview" %}

Gemini 3.5 Transcribe is optimized for speech-to-text tasks. It handles diverse accents, background noise, and multi-language conversations.

Key capabilities include:

*   **Automatic speech recognition (ASR):** Automatically detects languages across [85+ locales](/docs/transcribe#supported-languages). Handles intra-sentence and inter-sentential code-switching without manual configuration.
*   **Custom vocabulary:** Biases recognition toward domain-specific terms, acronyms, and proper names by passing up to 1,000 phrases.
*   **Speaker diarization:** Distinguishes between multiple speakers and attributes spoken segments to distinct labels.
*   **Word-level timestamps:** Generates precise start and end time offsets for each recognized word.
*   **Smart transcription:** Cleans up disfluencies, filler words, repetitions, and applies structured formatting.
*   **Formatting and normalization:** Applies capitalization, punctuation, and inverse text normalization, such as converting "twenty six million dollars" to "$26M".

For general audio reasoning or question answering over audio content, use [Audio understanding](/docs/audio). For text-to-speech audio synthesis, use [Text-to-speech](/docs/speech-generation).

## Language detection and hints {% id="language-detection" %}

By default, the model detects the spoken language automatically. It switches between languages dynamically when speakers code-switch.

To use automatic detection, omit `language_codes` or provide an empty list:

{% tabs %}
{% tab label="Python" filename="transcribe_language_auto.py" %}
```python
from google import genai

client = genai.Client()

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
    generation_config={
        "transcription_config": {
            "language_codes": [],
        }
    },
)
```
{% /tab %}
{% tab label="JavaScript" filename="transcribe_language_auto.js" %}
```javascript
const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [audioFile],
  generationConfig: {
    transcriptionConfig: {
      languageCodes: [],
    },
  },
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    LanguageCodes: []string{},
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}
{% tab label="REST" filename="transcribe_language_auto.sh" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "language_codes": []
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

If you know the language in advance, specify BCP-47 language codes in `language_codes` to improve transcription accuracy (see [Supported languages](/docs/transcribe#supported-languages)):

{% tabs %}
{% tab label="Python" filename="transcribe_language_hint.py" %}
```python
generation_config = {
    "transcription_config": {
        "language_codes": ["es-ES"],
    }
}
```
{% /tab %}
{% tab label="JavaScript" filename="transcribe_language_hint.js" %}
```javascript
const generationConfig = {
  transcriptionConfig: {
    languageCodes: ["es-ES"],
  },
};
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "google.golang.org/genai/interactions/models/interactions"
)

func main() {
    generationConfig := &interactions.GenerationConfig{
        TranscriptionConfig: &interactions.TranscriptionConfig{
            LanguageCodes: []string{"es-ES"},
        },
    }
    _ = generationConfig
}
```
{% /tab %}
{% tab label="REST" filename="transcribe_language_hint.json" %}
```json
{
  "generation_config": {
    "transcription_config": {
      "language_codes": ["es-ES"]
    }
  }
}
```
{% /tab %}
{% /tabs %}

## Custom vocabulary {% id="custom-vocabulary" %}

You can steer the speech model toward uncommon words, technical jargon, brand names, or proper nouns. Supply up to 1,000 terms in the `custom_vocabulary` array (best results are typically achieved with up to 100 terms):

{% callout type="note" %}
You cannot combine `custom_vocabulary` with speaker diarization or word-level timestamps. The API rejects requests that include `custom_vocabulary` with either feature.
{% /callout %}

{% tabs %}
{% tab label="Python" filename="transcribe_custom_vocab.py" %}
```python
from google import genai

client = genai.Client()

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
    generation_config={
        "transcription_config": {
            "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"],
        }
    },
)
```
{% /tab %}
{% tab label="JavaScript" filename="transcribe_custom_vocab.js" %}
```javascript
const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [audioFile],
  generationConfig: {
    transcriptionConfig: {
      customVocabulary: ["Gemini", "Kubernetes", "BigQuery"],
    },
  },
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    CustomVocabulary: []string{"Gemini", "Kubernetes", "BigQuery"},
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}
{% tab label="REST" filename="transcribe_custom_vocab.sh" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"]
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## Speaker diarization {% id="speaker-diarization" %}

Speaker diarization identifies different voices in the recording and tags each segment with a speaker identifier like `spk_1` or `spk_2`. Up to 8 speakers are supported (attribution for 3 or more speakers is experimental).

Enable diarization by setting `diarization_mode` to `"speaker"` within `mode`:

{% tabs %}
{% tab label="Python" filename="transcribe_diarization.py" %}
```python
from google import genai

client = genai.Client()

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
    generation_config={
        "transcription_config": {
            "mode": {
                "type": "verbatim",
                "diarization_mode": "speaker",
            }
        }
    },
)
```
{% /tab %}
{% tab label="JavaScript" filename="transcribe_diarization.js" %}
```javascript
const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [audioFile],
  generationConfig: {
    transcriptionConfig: {
      mode: {
        type: "verbatim",
        diarizationMode: "speaker",
      },
    },
  },
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                        DiarizationMode: genai.Ptr("speaker"),
                    }))),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}
{% tab label="REST" filename="transcribe_diarization.sh" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": {
          "type": "verbatim",
          "diarization_mode": "speaker"
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## Word-level timestamps {% id="word-timestamps" %}

Word-level timestamps provide exact start and end offsets for every recognized word in the audio stream.

{% callout type="note" %}
Enabling word-level timestamps may degrade overall transcription accuracy.
{% /callout %}

Enable timestamps by setting `timestamp_granularities` to `["word"]` within `mode`:

{% tabs %}
{% tab label="Python" filename="transcribe_timestamps.py" %}
```python
from google import genai

client = genai.Client()

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
    generation_config={
        "transcription_config": {
            "mode": {
                "type": "verbatim",
                "timestamp_granularities": ["word"],
            }
        }
    },
)
```
{% /tab %}
{% tab label="JavaScript" filename="transcribe_timestamps.js" %}
```javascript
const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [audioFile],
  generationConfig: {
    transcriptionConfig: {
      mode: {
        type: "verbatim",
        timestampGranularities: ["word"],
      },
    },
  },
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                        TimestampGranularities: []string{"word"},
                    }))),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}
{% tab label="REST" filename="transcribe_timestamps.sh" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": {
          "type": "verbatim",
          "timestamp_granularities": ["word"]
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

You can combine `diarization_mode` and `timestamp_granularities` in a single request to receive both speaker labels and word timestamps:

{% tabs %}
{% tab label="Python" filename="transcribe_diarization_timestamps.py" %}
```python
generation_config = {
    "transcription_config": {
        "mode": {
            "type": "verbatim",
            "diarization_mode": "speaker",
            "timestamp_granularities": ["word"],
        },
    }
}
```
{% /tab %}
{% tab label="JavaScript" filename="transcribe_diarization_timestamps.js" %}
```javascript
const generationConfig = {
  transcriptionConfig: {
    mode: {
      type: "verbatim",
      diarizationMode: "speaker",
      timestampGranularities: ["word"],
    },
  },
};
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
)

func main() {
    generationConfig := &interactions.GenerationConfig{
        TranscriptionConfig: &interactions.TranscriptionConfig{
            Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                DiarizationMode:        genai.Ptr("speaker"),
                TimestampGranularities: []string{"word"},
            }))),
        },
    }
    _ = generationConfig
}
```
{% /tab %}
{% tab label="REST" filename="transcribe_diarization_timestamps.json" %}
```json
{
  "generation_config": {
    "transcription_config": {
      "mode": {
        "type": "verbatim",
        "diarization_mode": "speaker",
        "timestamp_granularities": ["word"]
      }
    }
  }
}
```
{% /tab %}
{% /tabs %}

## Transcription modes {% id="transcription-modes" %}

Gemini 3.5 Transcribe supports two transcription modes via the `mode` parameter:

*   **`verbatim` (default)**: Returns an exact word-for-word transcript of everything spoken, preserving raw filler words ("um", "uh", "like", "you know"), repetitions, pauses, and false starts. Required when using timestamps or speaker diarization.
*   **`smart` (Smart transcription)**: Optimizes the transcript for reading by applying intelligent post-processing:
    *   **Disfluency removal**: Strips conversational filler words, stuttering, and false starts.
    *   **Inline self-corrections**: Resolves spoken corrections directly (for example, *"Let's meet on Tuesday, actually no, Wednesday at two"* becomes *"Let's meet on Wednesday at 2:00 PM"*).
    *   **Automatic structured formatting**: Automatically structures spoken thoughts into paragraphs, numbered lists, bullet points, formatted dates, currencies, and numbers.
    *   **Grammatical cleanup**: Applies natural punctuation, sentence casing, and flow.

{% table %}
* Spoken audio
* `verbatim` output
* `smart` (Smart transcription) output
---

* "Um, so for the meeting, I think we should, uh, invite Alice and, wait no, Bob and Carol."
* "Um so for the meeting I think we should uh invite Alice and wait no Bob and Carol."
* "For the meeting, I think we should invite Bob and Carol."
---

* "First item review budget second item finalize timeline third item send recap"
* "first item review budget second item finalize timeline third item send recap"
* 1. Review budget
  2. Finalize timeline
  3. Send recap
{% /table %}

{% tabs %}
{% tab label="Python" filename="transcribe_smart_mode.py" %}
```python
from google import genai

client = genai.Client()

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
    generation_config={
        "transcription_config": {
            "mode": "smart",
        }
    },
)
print(response.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="transcribe_smart_mode.js" %}
```javascript
const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [audioFile],
  generationConfig: {
    transcriptionConfig: {
      mode: "smart",
    },
  },
});
console.log(response.outputText);
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.TranscriptionConfigModeEnumSmart)),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}
{% tab label="REST" filename="transcribe_smart_mode.sh" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": "smart"
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
Smart transcription (`"smart"`) is incompatible with `timestamp_granularities` and `diarization_mode`. If you need word timestamps or speaker diarization, use verbatim mode (default).
{% /callout %}

## Parsing transcription output {% id="parsing-output" %}

The complete transcript text is returned in `response.output_text`.

When `timestamp_granularities` or `diarization_mode` is enabled, the API also returns detailed word-level annotations attached to the interaction content.

Here is how to extract and iterate over word timestamps and speaker turns:

{% tabs %}
{% tab label="Python" filename="transcribe_parse_output.py" %}
```python
def extract_word_annotations(response):
    words = []
    for step in getattr(response, "steps", []) or []:
        for content in getattr(step, "content", []) or []:
            for annotation in getattr(content, "annotations", []) or []:
                if getattr(annotation, "type", None) == "word_info":
                    words.append(annotation)
    return words

words = extract_word_annotations(response)

for w in words:
    speaker = f"[{w.speaker}] " if getattr(w, "speaker", None) else ""
    start = getattr(w, "start_offset", "")
    end = getattr(w, "end_offset", "")
    timing = f"({start} -> {end}) " if start and end else ""
    print(f"{speaker}{timing}{w.text}")
```
{% /tab %}
{% tab label="JavaScript" filename="transcribe_parse_output.js" %}
```javascript
function extractWordAnnotations(response) {
  const words = [];
  for (const step of response.steps ?? []) {
    for (const content of step.content ?? []) {
      for (const annotation of content.annotations ?? []) {
        if (annotation.type === "word_info") {
          words.push(annotation);
        }
      }
    }
  }
  return words;
}

const words = extractWordAnnotations(response);

for (const w of words) {
  const speaker = w.speaker ? `[${w.speaker}] ` : "";
  const timing = (w.start_offset && w.end_offset) ? `(${w.start_offset} -> ${w.end_offset}) ` : "";
  console.log(`${speaker}${timing}${w.text}`);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "fmt"

    "google.golang.org/genai/interactions/models/interactions"
)

func extractWordAnnotations(interaction *interactions.Interaction) []*interactions.WordInfo {
    var words []*interactions.WordInfo
    if interaction == nil {
        return words
    }
    for _, step := range interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    for _, annotation := range content.TextContent.Annotations {
                        if annotation.WordInfo != nil {
                            words = append(words, annotation.WordInfo)
                        }
                    }
                }
            }
        }
    }
    return words
}

func main() {
    var interaction *interactions.Interaction
    words := extractWordAnnotations(interaction)

    for _, w := range words {
        speaker := ""
        if w.Speaker != nil && *w.Speaker != "" {
            speaker = fmt.Sprintf("[%s] ", *w.Speaker)
        }
        timing := ""
        if w.StartOffset != nil && w.EndOffset != nil {
            timing = fmt.Sprintf("(%s -> %s) ", *w.StartOffset, *w.EndOffset)
        }
        fmt.Printf("%s%s%s\n", speaker, timing, w.GetText())
    }
}
```
{% /tab %}
{% tab label="REST" filename="transcribe_parse_output.json" %}
```json
{
  "id": "interactions/abc123xyz",
  "status": "completed",
  "steps": [
    {
      "id": "step_001",
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Hello world",
          "annotations": [
            {
              "type": "word_info",
              "text": "Hello",
              "speaker": "spk_1",
              "start_offset": "0.100s",
              "end_offset": "0.400s"
            },
            {
              "type": "word_info",
              "text": "world",
              "speaker": "spk_1",
              "start_offset": "0.500s",
              "end_offset": "0.800s"
            }
          ]
        }
      ]
    }
  ]
}
```
{% /tab %}
{% /tabs %}

## Supported languages {% id="supported-languages" %}

The following languages and BCP-47 language codes are supported for Gemini 3.5 Transcribe:

| Language | BCP-47 Code | Language | BCP-47 Code |
| :--- | :--- | :--- | :--- |
| Afrikaans | `af-ZA` | Japanese | `ja-JP` |
| Amharic | `am-ET` | Javanese | `jv-ID` |
| Arabic (Egypt) | `ar-EG` | Kabuverdianu | `kea-CV` |
| Armenian | `hy-AM` | Kannada | `kn-IN` |
| Assamese | `as-IN` | Kazakh | `kk-KZ` |
| Azerbaijani | `az-AZ` | Korean | `ko-KR` |
| Belarusian | `be-BY` | Kyrgyz | `ky-KG` |
| Bengali (Bangladesh) | `bn-BD` | Latvian | `lv-LV` |
| Bengali (India) | `bn-IN` | Lingala | `ln-CD` |
| Bosnian | `bs-BA` | Lithuanian | `lt-LT` |
| Bulgarian | `bg-BG` | Macedonian | `mk-MK` |
| Bulgarian (Aromanian) | `rup-BG` | Malay | `ms-MY` |
| Burmese | `my-MM` | Malayalam | `ml-IN` |
| Cantonese (Traditional) | `yue-Hant-HK` | Maltese | `mt-MT` |
| Catalan | `ca-ES` | Mandarin Chinese (Simplified) | `cmn-Hans-CN` |
| Cebuano | `ceb` | Marathi | `mr-IN` |
| Central Khmer | `km-KH` | Mongolian | `mn-MN` |
| Croatian | `hr-HR` | Nepali | `ne-NP` |
| Czech | `cs-CZ` | Norwegian | `nb-NO` |
| Danish | `da-DK` | Oriya | `or-IN` |
| Dutch | `nl-NL` | Polish | `pl-PL` |
| English (Great Britain) | `en-GB` | Portuguese (Brazil) | `pt-BR` |
| English (India) | `en-IN` | Portuguese (Portugal) | `pt-PT` |
| English (United States) | `en-US` | Punjabi | `pa-IN` |
| Estonian | `et-EE` | Punjabi (Gurmukhi script) | `pa-Guru-IN` |
| Farsi | `fa-IR` | Romanian | `ro-RO` |
| Filipino | `fil-PH` | Russian | `ru-RU` |
| Finnish | `fi-FI` | Serbian | `sr-RS` |
| French | `fr-FR` | Sindhi (Arabic script) | `sd-Arab-IN` |
| Galician | `gl-ES` | Slovak | `sk-SK` |
| Georgian | `ka-GE` | Slovenian | `sl-SI` |
| German | `de-DE` | Spanish (Latin America) | `es-419` |
| Greek | `el-GR` | Spanish (United States) | `es-US` |
| Gujarati | `gu-IN` | Swahili (Kenya) | `sw-KE` |
| Hausa | `ha-NG` | Swedish | `sv-SE` |
| Hebrew | `he-IL` | Tajik | `tg-TJ` |
| Hindi | `hi-IN` | Telugu | `te-IN` |
| Hungarian | `hu-HU` | Thai | `th-TH` |
| Icelandic | `is-IS` | Turkish | `tr-TR` |
| Indian English | `en-IN` | Ukrainian | `uk-UA` |
| Indonesian | `id-ID` | Uzbek | `uz-UZ` |
| Italian | `it-IT` | Vietnamese | `vi-VN` |

## Supported audio formats {% id="supported-formats" %}

Gemini 3.5 Transcribe supports the following audio format MIME types:

* WAV - `audio/wav`
* MP3 - `audio/mp3`
* AIFF - `audio/aiff`
* AAC - `audio/aac`
* OGG - `audio/ogg`
* FLAC - `audio/flac`
* MPEG - `audio/mpeg`
* M4A - `audio/m4a`
* L16 - `audio/l16`
* Opus - `audio/opus`
* ALAW - `audio/alaw`
* MULAW - `audio/mulaw`
* WebM - `audio/webm`

For the complete list of supported MIME types and parameter schemas, see the [Interactions API reference](https://ai.google.dev/api/interactions-api#Resource:Content).

## Parameter reference {% id="parameter-reference" %}

Configure transcription by setting fields within the `transcription_config` object in `generation_config`:

| Field | Type | Description |
| :--- | :--- | :--- |
| `language_codes` | Array of strings | BCP-47 language codes (e.g., `["en-US"]`). If omitted or empty (`[]`), the model automatically detects the language and handles code-switching. |
| `custom_vocabulary` | Array of strings | Up to 1,000 custom terms, acronyms, or proper names to bias speech recognition. Incompatible with speaker diarization and word-level timestamps. |
| `mode` | Object or String | Transcription mode configuration. Accepts `"smart"` or a verbatim mode object (`{"type": "verbatim", ...}`). Defaults to verbatim transcription. |
| `mode.type` | String | *(Verbatim mode only)* Mode identifier. Always set to `"verbatim"`. |
| `mode.timestamp_granularities` | Array of strings | *(Verbatim mode only)* Granularity of timestamps to return. Pass `["word"]` to enable word start and end offsets. Incompatible with custom vocabulary. |
| `mode.diarization_mode` | String | *(Verbatim mode only)* Diarization mode. Pass `"speaker"` to identify and label distinct speakers. Incompatible with custom vocabulary. |

## Best practices {% id="best-practices" %}

*   **Provide clean audio:** Ensure audio recordings have clear voice separation and avoid severe clipping.
*   **Provide language hints when known:** If you know the audio language in advance, specify `language_codes` to maximize accuracy.
*   **Target custom vocabulary:** Include only distinct domain terms, brand names, or proper nouns in `custom_vocabulary` rather than common everyday words.
*   **Use the Files API for large recordings:** For files longer than a few seconds, upload the file using `client.files.upload` and pass the returned file URI to the model.

## Limitations {% id="limitations" %}

*   **Audio duration:** Standard unary requests support audio files up to 1 hour. Audio processing is limited to 30 minutes when features like speaker diarization or word-level timestamps are enabled.
*   **Word-level timestamps:** Enabling word-level timestamps may degrade overall transcription accuracy.
*   **Speaker diarization:** Speaker diarization supports up to 8 speakers. Speaker attribution for 3 or more speakers is experimental.
*   **Custom vocabulary:** You can provide up to 1,000 terms in `custom_vocabulary`, but best results are typically achieved with up to 100 terms. You cannot combine `custom_vocabulary` with speaker diarization or word-level timestamps; the API rejects requests that specify `custom_vocabulary` alongside either feature.
*   **Mode compatibility:** Smart transcription (`"smart"`) cannot be combined with `timestamp_granularities` or `diarization_mode`.

## What's next {% id="whats-next" %}

*   Stream real-time audio with the [Live transcription guide](/docs/live-api/live-transcribe) using the Live API.
*   Explore [Audio understanding](/docs/audio) to analyze, summarize, or query audio content.
*   Learn how to synthesize audio from text using [Text-to-speech](/docs/speech-generation).
*   Check the [Pricing page](/docs/pricing#gemini-3.5-transcribe) for model pricing and token limits.
*   Check the [Files API](/docs/files) guide for details on uploading and managing media files.

# Gemini Live API overview
Source: https://aistudio.google.com/docs/live-api
Description: Enable low-latency, real-time voice and video interactions with the Live API.

The Live API enables low-latency, real-time voice and vision interactions with
Gemini. It processes continuous streams of audio, images, and text to deliver
immediate, human-like spoken responses, creating a natural conversational
experience for your users.

![Live API Overview](/googledevai/static/gemini-api/docs/images/live-api-overview.png)

{% button href="https://aistudio.google.com/live" variant="primary" icon="mic" %}Try the Live API in Google AI Studio{% /button %}

{% button href="https://github.com/google-gemini/gemini-live-api-examples" variant="primary" icon="code" %}Clone example apps from GitHub{% /button %}

{% button href="/docs/coding-agents" variant="primary" icon="terminal" %}Use coding agent skills{% /button %}

## Use cases {% id="use-cases" %}

Live API can be used to build real-time voice agents for a
variety of industries, including:

* **E-commerce and retail:** Shopping assistants that offer personalized
    recommendations and support agents that resolve customer issues.

* **Gaming:** Interactive non-player characters (NPCs), in-game help
    assistants, and real-time translation of in-game content.

* **Next-gen interfaces:** Voice- and video-enabled experiences in robotics,
    smart glasses, and vehicles.

* **Healthcare:** Health companions for patient support and education.
* **Financial services:** AI advisors for wealth management and investment
    guidance.

* **Education:** AI mentors and learner companions that provide personalized
    instruction and feedback.

* **Translation and localization:** Real-time, low-latency translation of
    spoken conversations, enabling seamless multilingual communication.

* **Live transcription and captioning:** Real-time speech-to-text streaming for
    live subtitles, meeting transcription, voice dictation, and customer call logging.

## Key features {% id="key-features" %}

Live API offers a comprehensive set of features for building
robust voice agents:

* [**Multilingual support**](/docs/live-api/capabilities#supported-languages):
    Converse in 70 supported languages.

* [**Barge-in**](/docs/live-api/capabilities#interruptions):
    Users can interrupt the model at any time for responsive interactions.

* [**Tool use**](/docs/live-api/tools):
    Integrates tools like function calling and Google Search for dynamic
    interactions.

* [**Audio transcriptions**](/docs/live-api/capabilities#audio-transcription):
    Provides text transcripts of both user input and model output.

* [**Proactive audio**](/docs/live-api/capabilities#proactive-audio):
    Lets you control when the model responds and in what contexts.

* [**Affective dialog**](/docs/live-api/capabilities#affective-dialog):
    Adapts response style and tone to match the user's input expression.

* [**Live Transcription**](/docs/live-api/live-transcribe):
    Real-time, continuous speech-to-text streaming with automatic language detection and custom vocabulary.

* [**Live Translation**](/docs/live-api/live-translate):
    Real-time voice-to-voice translation in 70+ languages.

## Technical specifications {% id="technical-specifications" %}

The following table outlines the technical specifications for the
Live API:

{% table %}

*   Category
*   Details
---

*   Input modalities
*   Audio (raw 16-bit PCM audio, 16kHz, little-endian), images (JPEG <= 1FPS), text
---

*   Output modalities
*   Audio (raw 16-bit PCM audio, 24kHz, little-endian)
---

*   Protocol
*   Stateful WebSocket connection (WSS)
{% /table %}
## Choose an implementation approach {% id="implementation-approach" %}

When integrating with Live API, you'll need to choose one of the following
implementation approaches:

- **Server-to-server**: Your backend connects to the Live API using
[WebSockets][websocket]. Typically, your client sends stream data (audio, video,
text) to your server, which then forwards it to the Live API.

- **Client-to-server**: Your frontend code connects directly to the Live API
using [WebSockets][websocket] to stream data, bypassing your backend.

{% callout type="note" %}
Note: Client-to-server generally offers better performance for streaming audio
and video, since it bypasses the need to send the stream to your backend first.
It's also easier to set up since you don't need to implement a proxy that sends
data from your client to your server and then your server to the API. However,
for production environments, in order to mitigate security risks, we recommend
using [ephemeral tokens](/docs/live-api/ephemeral-tokens) instead of standard
API keys.
{% /callout %}

## Get started {% id="get-started" %}

Select the guide that matches your development environment:

{% card-grid %}

{% card
  href="/docs/live-api/get-started-sdk"
  title="GenAI SDK tutorial"
  badge="Server-to-server"
  description="Connect to the Gemini Live API using the GenAI SDK to build a
     real-time multimodal application with a Python backend."
/%}

{% card
  href="/docs/live-api/get-started-websocket"
  title="WebSocket tutorial"
  badge="Client-to-server"
  description="Connect to the Gemini Live API using WebSockets to build a
    real-time multimodal application with a JavaScript frontend and ephemeral
    tokens."
/%}

{% card
  href="https://google.github.io/adk-docs/streaming/"
  title="ADK tutorial"
  badge="Agent Development Kit"
  description="Create an agent and use the Agent Development Kit (ADK)
    Streaming to enable voice and video communication."
/%}
{% /card-grid %}

## Partner integrations {% id="partner-integrations" %}
To streamline the development of real-time audio and video apps, you can use
a third-party integration that supports the Gemini Live API over WebRTC or
WebSockets.

{% card-grid %}
  {% card
      href="https://docs.livekit.io/agents/models/realtime/plugins/gemini/"
      title="LiveKit"
      description="Use the Gemini Live API with LiveKit Agents."
  /%}
  {% card
      href="https://docs.pipecat.ai/guides/features/gemini-live"
      title="Pipecat by Daily"
      description="Create a real-time AI chatbot using Gemini Live and Pipecat."
  /%}
  {% card
      href="https://docs.fishjam.io/tutorials/gemini-live-integration"
      title="Fishjam by Software Mansion"
      description="Create live video and audio streaming applications with
        Fishjam."
  /%}
  {% card
      href="https://visionagents.ai/integrations/gemini"
      title="Vision Agents by Stream"
      description="Build real-time voice and video AI applications with Vision
        Agents."
  /%}
  {% card
      href="https://voximplant.com/products/gemini-client"
      title="Voximplant"
      description="Connect inbound and outbound calls to Live API with
        Voximplant."
  /%}
  {% card
      href="https://docs.agora.io/en/conversational-ai/models/mllm/gemini"
      title="Agora"
      description="Build real-time conversational AI applications with Agora."
  /%}
  {% card
      href="https://firebase.google.com/docs/ai-logic/live-api?api=dev"
      title="Firebase AI SDK"
      description="Get started with the Gemini Live API using Firebase AI
        Logic."
  /%}
{% /card-grid %}

[WebSocket]: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API

# Live translation with Gemini Live API
Source: https://aistudio.google.com/docs/live-api/live-translate
Description: Perform low-latency, real-time speech-to-speech translation with Live API.

The Gemini Live API supports low-latency, real-time speech to speech translation
between 70+ languages using the
[`gemini-3.5-live-translate-preview`](/docs/models/gemini-3.5-live-translate-preview)
model. By configuring the Live API with translation settings, you can stream
audio in one language and receive translated audio output in another language,
enabling seamless real-time voice-to-voice translation.

{% button
    href="https://aistudio.google.com/live?model=gemini-3.5-live-translate-preview"
    variant="primary"
    icon="mic" %}
  Try Live Translate in Google AI Studio
{% /button %}

{% button
    href="https://github.com/google-gemini/gemini-live-api-examples"
    variant="primary"
    icon="code" %}
  Clone the example app from GitHub
{% /button %}

{% button
    href="/docs/coding-agents#gemini-live-api-dev"
    variant="primary"
    icon="terminal" %}
  Use coding agent skills
{% /button %}

## Live Agent vs. Live Translation {% id="live-agent-vs-live-translation" %}

While both use the Live API, the mental model for Live Translation is different
from conversational real-time agent interactions.

| Live Agent | Live Translation |
| :--- | :--- |
| **The model acts as an assistant.** It listens, reasons, and takes actions on your behalf. | **The model acts as an interpreter.** It behaves as a real-time translator pipeline. |
| **Uses turn-based interactions.** Relies on pauses, intent detection, and handles interruptions. | **Uses continuous stream processing.** Translates as the speaker talks without waiting for turns. |
| **Supports tools and agents.** Native support for function calling, Google Search, and instructions. | **Supports translation only.** Pure low-latency translation; no support for tools or instructions. |
| **Fully multimodal.** Supports text, audio, video, and image inputs. | **Audio restricted.** Input is limited to audio to ensure strict real-time latency thresholds. |
| **Granular configuration.** Uses generation, speech, tools, and system instructions. | **Simplified configuration.** Set `target_language_code` and toggles like `echo_target_language`. |

## Get started {% id="get-started" %}

The following examples demonstrate how to initialize a client and connect to the
Live API with a translation configuration.

{% tabs %}
{% tab label="Python" filename="live_translate.py" %}
```python
import asyncio
from google import genai
from google.genai import types

client = genai.Client()

model = "gemini-3.5-live-translate-preview"
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    input_audio_transcription=types.AudioTranscriptionConfig(),
    output_audio_transcription=types.AudioTranscriptionConfig(),
    translation_config=types.TranslationConfig(
        target_language_code="pl",
        echo_target_language=True
    )
)

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started with translation")
        # Start receiving the translated audio stream
        async for response in session.receive():
            if response.server_content:
                if response.server_content.input_transcription:
                    print(f"Input transcript: {response.server_content.input_transcription.text}")
                if response.server_content.output_transcription:
                    print(f"Output transcript: {response.server_content.output_transcription.text}")
                if response.server_content.model_turn:
                    for part in response.server_content.model_turn.parts:
                        if part.inline_data:
                            audio_data = part.inline_data.data
                            # Play or process the translated audio chunk
                            print(f"Received audio chunk ({len(audio_data)} bytes)")

if __name__ == "__main__":
    asyncio.run(main())
```
{% /tab %}
{% tab label="JavaScript" filename="live_translate.js" %}
```javascript
import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.5-live-translate-preview';
const config = {
    responseModalities: [Modality.AUDIO],
    inputAudioTranscription: {},
    outputAudioTranscription: {},
    translationConfig: {
        targetLanguageCode: 'pl',
        echoTargetLanguage: true
    }
};

async function main() {
  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: {
      onopen: () => console.debug('Opened'),
      onmessage: (message) => {
        const content = message.serverContent;
        if (content?.inputTranscription) {
          console.log('Input transcript:', content.inputTranscription.text);
        }
        if (content?.outputTranscription) {
          console.log('Output transcript:', content.outputTranscription.text);
        }
        if (content?.modelTurn?.parts) {
          for (const part of content.modelTurn.parts) {
            if (part.inlineData) {
              const audioData = part.inlineData.data;
              // Play or process the translated audio chunk (base64 encoded)
              console.debug(`Received audio chunk (${audioData.length} bytes)`);
            }
          }
        }
      },
      onerror: (e) => console.debug('Error:', e.message),
      onclose: (e) => console.debug('Close:', e.reason),
    },
  });

  console.debug("Session started with translation");
}

await main();
```
{% /tab %}
{% tab label="WebSockets" filename="live_translate.js" %}
```javascript
const API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.5-live-translate-preview";
const WS_URL = `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=${API_KEY}`;

const websocket = new WebSocket(WS_URL);

websocket.onopen = () => {
  console.log('WebSocket Connected');

  const setupMessage = {
    setup: {
      model: `models/${MODEL_NAME}`,
      generationConfig: {
        responseModalities: ['AUDIO'],
        inputAudioTranscription: {},
        outputAudioTranscription: {},
        translationConfig: {
          targetLanguageCode: 'pl',
          echoTargetLanguage: true
        }
      }
    }
  };
  websocket.send(JSON.stringify(setupMessage));
};

websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  if (response.serverContent) {
    const content = response.serverContent;
    if (content.inputTranscription) {
      console.log('Input transcript:', content.inputTranscription.text, `(${content.inputTranscription.languageCode})`);
    }
    if (content.outputTranscription) {
      console.log('Output transcript:', content.outputTranscription.text, `(${content.outputTranscription.languageCode})`);
    }
    if (content.modelTurn?.parts) {
      for (const part of content.modelTurn.parts) {
        if (part.inlineData) {
          const audioData = part.inlineData.data;
          // Play or process the translated audio chunk (base64 encoded)
          console.debug(`Received audio chunk (${audioData.length} bytes)`);
        }
      }
    }
  }
};
```
{% /tab %}
{% /tabs %}

## Sending audio {% id="sending-audio" %}

To stream voice inputs for translation, you send raw, little-endian, 16-bit PCM
audio.

* **Input audio format**: Raw 16-bit PCM at 16kHz (mono, little-endian).
* **Output audio format**: Raw 16-bit PCM at 24kHz (mono, little-endian).
* **Chunk Size and Latency**: Send audio in chunks of 100ms.

{% callout type="note" %}
Only audio input is supported for translation. Text input is not
supported.
{% /callout %}

The following examples show how to send audio chunks to the session.

{% tabs %}
{% tab label="Python" filename="live_translate.py" %}
```python
# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
    audio=types.Blob(
        data=chunk,
        mime_type="audio/pcm;rate=16000"
    )
)
```
{% /tab %}
{% tab label="JavaScript" filename="live_translate.js" %}
```js
// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
  audio: {
    data: chunk.toString('base64'),
    mimeType: 'audio/pcm;rate=16000'
  }
});
```
{% /tab %}
{% tab label="WebSockets" filename="live_translate.js" %}
```javascript
// Assuming 'chunk' is a Buffer of raw PCM audio
function sendAudioChunk(chunk) {
  if (websocket.readyState === WebSocket.OPEN) {
    const audioMessage = {
      realtimeInput: {
        audio: {
          data: chunk.toString('base64'),
          mimeType: 'audio/pcm;rate=16000'
        }
      }
    };
    websocket.send(JSON.stringify(audioMessage));
  }
}
```
{% /tab %}
{% /tabs %}

## Configuration {% id="configuration" %}

To enable translation, you must specify the `translationConfig` within the
`generationConfig` during the session setup.

### Setup message configuration {% id="setup-message-configuration" %}

The `generationConfig` supports the following fields to enable transcripts:

* **`inputAudioTranscription`**: An object that, when present, enables the
  model to send text transcripts of the input audio.
* **`outputAudioTranscription`**: An object that, when present, enables the
  model to send text transcripts of the output (translated) audio.

The `translationConfig` supports the following fields:

* **`targetLanguageCode`**: The [BCP-47 language code](/docs/live-api/live-translate#supported-languages) of
  the language you want the model to translate into (e.g., `"pl"` for Polish,
  `"es"` for Spanish). Defaults to `"en"`.
* **`echoTargetLanguage`**: A boolean indicating how input audio that is already
  in the target language should be handled. If set to `true`, the model will
  echo (parrot) input audio that is already in the target language. If set to
  `false`, the model will stay silent when the input speech is already in the
  target language. Defaults to `false`.

Here is an example of the setup message structure:

```json
"setup": {
    "model": "models/gemini-3.5-live-translate-preview",
    "generationConfig": {
      "responseModalities": [
        "AUDIO"
      ],
      "inputAudioTranscription": {},
      "outputAudioTranscription": {},
      "translationConfig": {
        "targetLanguageCode": "pl",
        "echoTargetLanguage": true
      }
    }
}
```

## Use ephemeral tokens in client-side applications {% id="ephemeral-tokens-for-client-side-applications" %}

For client-to-server applications, you can use [ephemeral tokens](/docs/live-api/ephemeral-tokens) (currently in `v1beta`) to avoid exposing your API key.

When using ephemeral tokens with Live Translation:

1. You must use the `v1beta` endpoint.
2. **Locking configuration:** By default, you should specify the
   `translationConfig` in the token creation constraints on your server. This
   ensures the translation configuration is locked and cannot be tampered with
   by the client.
3. **Unlocking configuration:** If you want to be able to set the
   `translationConfig` on the client-side (for example, to let a user choose
   their own target language), you must omit it from the token creation request
   and set `"lock_additional_fields": []` instead. This will unlock
   `translationConfig` to be set on the client-side.

### Create a constrained ephemeral token {% id="creating-a-constrained-ephemeral-token" %}

The following examples demonstrate how to create an ephemeral token with
translation constraints.

{% tabs %}
{% tab label="Python" filename="live_translate.py" %}
```python
import datetime
from google import genai

now = datetime.datetime.now(tz=datetime.timezone.utc)

client = genai.Client()

token = client.auth_tokens.create(
    config = {
        'uses': 1,
        'expire_time': now + datetime.timedelta(minutes=30),
        'live_connect_constraints': {
            'model': 'gemini-3.5-live-translate-preview',
            'config': {
                'translation_config': {
                    'target_language_code': 'pl',
                    'echo_target_language': True
                }
            }
        },
    }
)
```
{% /tab %}
{% tab label="JavaScript" filename="live_translate.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();

const token = await client.authTokens.create({
    config: {
        uses: 1,
        expireTime: expireTime,
        liveConnectConstraints: {
            model: 'gemini-3.5-live-translate-preview',
            config: {
                responseModalities: ['AUDIO'],
                inputAudioTranscription: {},
                outputAudioTranscription: {},
                translationConfig: {
                    targetLanguageCode: 'pl',
                    echoTargetLanguage: true
                }
            }
        },
    },
});
```
{% /tab %}
{% tab label="REST" filename="live_translate.sh" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uses": 1,
    "expireTime": "YYYY-MM-DDTHH:MM:SSZ",
    "liveConnectConstraints": {
      "model": "models/gemini-3.5-live-translate-preview",
      "config": {
        "responseModalities": ["AUDIO"],
        "inputAudioTranscription": {},
        "outputAudioTranscription": {},
        "translationConfig": {
          "targetLanguageCode": "pl",
          "echoTargetLanguage": true
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## Limitations {% id="limitations" %}

* **Input Modalities**: Only audio input is supported for translation. Text
  input is not supported.
* **Voice Replication**: Voice replication can be inconsistent. Voices might
  shift after long pauses, assign the wrong gender based on how the speech
  starts, or get stuck on one voice during rapid multi-speaker conversations.
* **Language Detection**: Language detection struggles with heavy accents,
  similar languages (e.g., Spanish vs. Portuguese), or rapid language switches.
  **Note:** This should only impact the input transcript. Language codes and the
  final translation should still be accurate.
* **Background Audio**: The model is designed to filter out noise and music to
  produce clean speech, but not all background audio may be ignored.
* **Echo Target Language**: When `echoTargetLanguage: true`, background noise
  or music may introduce artifacts in the translated audio when input audio is
  already in the target language.

## Supported languages {% id="supported-languages" %}

The following languages are supported for Live Translation.

| Language | BCP-47 Code | Language | BCP-47 Code |
| :---- | :---- | :---- | :---- |
| Afrikaans | af | Kazakh | kk |
| Akan | ak | Khmer | km |
| Albanian | sq | Kinyarwanda | rw |
| Amharic | am | Korean | ko |
| Arabic | ar | Lao | lo |
| Armenian | hy | Latvian | lv |
| Azerbaijani | az | Lithuanian | lt |
| Basque | eu | Macedonian | mk |
| Belarusian | be | Malay | ms |
| Bengali | bn | Malayalam | ml |
| Bulgarian | bg | Marathi | mr |
| Burmese (Myanmar) | my | Mongolian | mn |
| Catalan | ca | Nepali | ne |
| Chinese (Simplified) | zh-Hans | Norwegian | no, nb |
| Chinese (Traditional) | zh-Hant | Persian | fa |
| Croatian | hr | Polish | pl |
| Czech | cs | Portuguese (Brazil) | pt-BR |
| Danish | da | Portuguese (Portugal) | pt-PT |
| Dutch | nl | Punjabi | pa |
| English | en | Romanian | ro |
| Estonian | et | Russian | ru |
| Filipino | fil | Serbian | sr |
| Finnish | fi | Sindhi | sd |
| French | fr | Sinhala | si |
| Galician | gl | Slovak | sk |
| Georgian | ka | Slovenian | sl |
| German | de | Spanish | es |
| Greek | el | Sundanese | su |
| Gujarati | gu | Swahili | sw |
| Hausa | ha | Swedish | sv |
| Hebrew | he | Tamil | ta |
| Hindi | hi | Telugu | te |
| Hungarian | hu | Thai | th |
| Icelandic | is | Turkish | tr |
| Indonesian | id | Ukrainian | uk |
| Italian | it | Urdu | ur |
| Japanese | ja | Uzbek | uz |
| Javanese | jv | Vietnamese | vi |
| Kannada | kn | Zulu | zu |

## What's next {% id="whats-next" %}

* Read the full Live API [Capabilities](/docs/live-api/capabilities) guide.
* Read the [Get started with the SDK](/docs/live-api/get-started-sdk) guide.
* Read the [Get started with WebSockets](/docs/live-api/get-started-websocket)
  guide.
* Read the [Ephemeral tokens](/docs/live-api/ephemeral-tokens) guide for secure
  authentication in client-to-server applications.
* Clone the
  [Live API examples](https://github.com/google-gemini/gemini-live-api-examples)
  from GitHub.

# Embeddings
Source: https://aistudio.google.com/docs/embeddings
Description: Generate vector embeddings for semantic search and classification using Gemini.

The Gemini API offers embedding models to generate embeddings for text, images,
video, and other content. These resulting embeddings can then be used for tasks
such as semantic search, classification, and clustering, providing more
accurate, context-aware results than keyword-based approaches.

The latest model, `gemini-embedding-2`, is the first multimodal
embedding model in the Gemini API. It maps text, images,
video, audio, and documents into a unified embedding space, enabling cross-modal
search, classification, and clustering across over 100 languages. See the
[multimodal embeddings section](/docs/embeddings#multimodal) to learn more. For text-only
use cases, `gemini-embedding-001` remains available.

Building Retrieval Augmented Generation (RAG) systems is a common use case for
AI products. Embeddings play a key role in significantly enhancing model outputs
with improved factual accuracy, coherence, and contextual richness. If you
prefer to use a managed RAG solution, we built the
[File Search](/docs/file-search) tool which makes doing RAG easier to manage and
more cost effective.

## Generating embeddings {% id="generate-embeddings" %}

Use the `embedContent` method to generate text embeddings:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

result = client.models.embed_content(
        model="gemini-embedding-2",
        contents="What is the meaning of life?"
)

print(result.embeddings)
```
{% /tab %}
{% tab label="JavaScript" %}
```js
import { GoogleGenAI } from "@google/genai";

async function main() {

    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: 'What is the meaning of life?',
    });

    console.log(response.embeddings);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", null);

System.out.println(response.embeddings().orElse(null));
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    }
    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-2",
        contents,
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }

    embeddings, err := json.MarshalIndent(result.Embeddings, "", " ")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(embeddings))
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "model": "models/gemini-embedding-2",
        "content": {
        "parts": [{
            "text": "What is the meaning of life?"
        }]
        }
    }'
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
While `gemini-embedding-001` lets you generate individual embeddings for a
list of strings, Gemini Embedding 2 produces a single aggregated embedding for
multiple inputs. You can find more information in [Embedding aggregation](/docs/embeddings#embedding-aggregation),
or you can use the [Batch API](/docs/batch-api#batch-embedding) if
you want to generate multiple embeddings at once.
{% /callout %}

## Specify task type to improve performance {% id="task-types" %}

You can use embeddings for a wide range of tasks from classification to document
search. Specifying the right task type helps optimize the embeddings for the
intended relationships, maximizing accuracy and efficiency.

### Task types with Embeddings 2 {% id="task-types-embeddings-2" %}

For text-only tasks with `gemini-embedding-2`, we strongly recommend you
add the task instruction in your prompt. This can be done by formatting the
query and the document with the correct task prefix.

When generating a [single embedding based on multimodal
input](/docs/embeddings#embedding-aggregation), we generally don't recommend
prefixing the text portion of the input with a task instruction. In some cases
it improves performance, but in others it reduces performance.

The following tables show examples of how to format queries and documents for
symmetric and asymmetric use cases using the `gemini-embedding-2` model.

**Retrieval use cases (Asymmetric format)**

In asymmetric use cases, add the task prefix to the query and apply
the document structure for the content you want to embed and retrieve.

{% table %}
* Use case
* Query structure
* Document structure
---
* Search query
* `task: search result | query: {content}`
*
  `title: {title} | text: {content}`

  If there is no title, use `title: none`.
---
* Question answering
* `task: question answering | query: {content}`
* `title: {title} | text: {content}`
---
* Fact checking
* `task: fact checking | query: {content}`
* `title: {title} | text: {content}`
---
* Code retrieval
* `task: code retrieval | query: {content}`
* `title: {title} | text: {content}`
{% /table %}

**Example usage**

{% tabs %}
{% tab label="Python" %}
```python
def prepare_query(query):
    return f"task: search result | query: {query}"

def prepare_document(content, title=None):
    if title is None:
        title = "none"
    return f"title: {title} | text: {content}"
```
{% /tab %}
{% tab label="Java" %}
```java
// Generate embedding for a task's query. Use your correct task here:
String query = "What is the capital of France?";
String formattedQuery = "task: search result | query: " + query;

// Generate embedding for document of an asymmetric retrieval task:
String title = "France";
String content = "Paris is the capital and most populous city of France.";
String formattedDocument = "title: " + (title != null ? title : "none") + " | text: " + content;
```
{% /tab %}

{% /tabs %}

**Single-input use cases (Symmetric format)**

In symmetric use cases, for the same task, use the same formatting
for the query and the document.

{% table %}
* Use case
* Input structure
---
* Classification
* `task: classification | query: {content}`
---
* Clustering
* `task: clustering | query: {content}`
---
* Semantic similarity
*
  `task: sentence similarity | query: {content}`

  Do not use this for search or retrieval. It is intended for semantic textual
  similarity.
{% /table %}

**Example usage**

{% tabs %}
{% tab label="Python" %}
```python
def prepare_query_and_document(content):
    return f'task: classification | query: {content}'
```
{% /tab %}
{% tab label="Java" %}
```java
// Generate embedding for query & document of your task.
String content = "This movie was fantastic!";
String formattedContent = "task: classification | query: " + content;
```
{% /tab %}

{% /tabs %}

It is important that the task is used consistently. E.g., if documents are
embedded with `f'task: classification | query: {content}'`, the query should
also be embedded following this task format.

### Task types with Embeddings 1 {% id="task-types-embeddings-1" %}

For `gemini-embedding-001`, you can specify the `task_type` in the
`embedContent` method. For a complete list of supported task types, see the
[Supported task types](/docs/embeddings#supported-task-types) table.

{% callout type="note" %}
You cannot use the `task_type` field for the `gemini-embedding-2` model. Instead, include the task as an instruction in your prompt, as detailed in the [above section](/docs/embeddings#task-types-embeddings-2).
{% /callout %}

The following example shows how you can use `SEMANTIC_SIMILARITY` to check how
similar in meaning strings of texts are.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
import pandas as pd
from sklearn.metrics.pairwise import cosine_similarity

client = genai.Client()

texts = [
    "What is the meaning of life?",
    "What is the purpose of existence?",
    "How do I bake a cake?",
]

result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(task_type="SEMANTIC_SIMILARITY")
)

df = pd.DataFrame(
    cosine_similarity([e.values for e in result.embeddings]),
    index=texts,
    columns=texts,
)

print(df)
```
{% /tab %}
{% tab label="JavaScript" %}
```js
import { GoogleGenAI } from "@google/genai";
// npm i compute-cosine-similarity
import * as cosineSimilarity from "compute-cosine-similarity";

async function main() {
    const ai = new GoogleGenAI({});

    const texts = [
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?",
    ];

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-001',
        contents: texts,
        config: { taskType: 'SEMANTIC_SIMILARITY' },
    });

    const embeddings = response.embeddings?.map(e => e.values || []) || [];

    for (let i = 0; i < texts.length; i++) {
        for (let j = i + 1; j < texts.length; j++) {
            const text1 = texts[i];
            const text2 = texts[j];
            const similarity = cosineSimilarity(embeddings[i], embeddings[j]);
            console.log(`Similarity between '${text1}' and '${text2}': ${similarity.toFixed(4)}`);
        }
    }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;
import java.util.List;

Client client = new Client();

List<String> texts =
    Arrays.asList(
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?");

EmbedContentConfig config =
    EmbedContentConfig.builder().taskType("SEMANTIC_SIMILARITY").build();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-001", texts, config);

List<ContentEmbedding> embeddings = response.embeddings().get();

for (int i = 0; i < texts.size(); i++) {
  for (int j = i + 1; j < texts.size(); j++) {
    List<Float> v1 = embeddings.get(i).values().get();
    List<Float> v2 = embeddings.get(j).values().get();
    double dotProduct = 0.0;
    double normA = 0.0;
    double normB = 0.0;
    for (int k = 0; k < v1.size(); k++) {
      dotProduct += v1.get(k) * v2.get(k);
      normA += v1.get(k) * v1.get(k);
      normB += v2.get(k) * v2.get(k);
    }
    double similarity = dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
    System.out.printf(
        "Similarity between '%s' and '%s': %.4f%n", texts.get(i), texts.get(j), similarity);
  }
}
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "math"

    "google.golang.org/genai"
)

// cosineSimilarity calculates the similarity between two vectors.
func cosineSimilarity(a, b []float32) (float64, error) {
    if len(a) != len(b) {
        return 0, fmt.Errorf("vectors must have the same length")
    }

    var dotProduct, aMagnitude, bMagnitude float64
    for i := 0; i < len(a); i++ {
        dotProduct += float64(a[i] * b[i])
        aMagnitude += float64(a[i] * a[i])
        bMagnitude += float64(b[i] * b[i])
    }

    if aMagnitude == 0 || bMagnitude == 0 {
        return 0, nil
    }

    return dotProduct / (math.Sqrt(aMagnitude) * math.Sqrt(bMagnitude)), nil
}

func main() {
    ctx := context.Background()
    client, _ := genai.NewClient(ctx, nil)
    defer client.Close()

    texts := []string{
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?",
    }

    var contents []*genai.Content
    for _, text := range texts {
        contents = append(contents, genai.NewContentFromText(text, genai.RoleUser))
    }

    result, _ := client.Models.EmbedContent(ctx,
        "gemini-embedding-001",
        contents,
        &genai.EmbedContentRequest{TaskType: genai.TaskTypeSemanticSimilarity},
    )

    embeddings := result.Embeddings

    for i := 0; i < len(texts); i++ {
        for j := i + 1; j < len(texts); j++ {
            similarity, _ := cosineSimilarity(embeddings[i].Values, embeddings[j].Values)
            fmt.Printf("Similarity between '%s' and '%s': %.4f\n", texts[i], texts[j], similarity)
        }
    }
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -d '{
    "taskType": "SEMANTIC_SIMILARITY",
    "content": {
        "parts": [
        {
            "text": "What is the meaning of life?"
        },
        {
            "text": "How much wood would a woodchuck chuck?"
        },
        {
            "text": "How does the brain work?"
        }
        ]
    }
    }'
```
{% /tab %}
{% /tabs %}

The code snippets will show how similar the different chunks of text are to one
another when run.

{% callout type="note" %}
Cosine similarity is a good distance metric because it focuses on
direction rather than magnitude, which more accurately reflects conceptual
closeness. Values range from -1 (opposite) to 1 (greatest similarity).
{% /callout %}

#### Supported task types {% id="supported-task-types" %}

Supported task types for `gemini-embedding-001`:

{% table %}
* **SEMANTIC_SIMILARITY**
* Embeddings optimized to assess text similarity.
* Recommendation systems, duplicate detection
---

* **CLASSIFICATION**
* Embeddings optimized to classify texts according to preset labels.
* Sentiment analysis, spam detection
---

* **CLUSTERING**
* Embeddings optimized to cluster texts based on their similarities.
* Document organization, market research, anomaly detection
---

* **RETRIEVAL_DOCUMENT**
* Embeddings optimized for document search.
* Indexing articles, books, or web pages for search.
---

* **RETRIEVAL_QUERY**
* Embeddings optimized for general search queries. Use `RETRIEVAL_QUERY` for
  queries; `RETRIEVAL_DOCUMENT` for documents to be retrieved.

* Custom search
---

* **CODE_RETRIEVAL_QUERY**
* Embeddings optimized for retrieval of code blocks based on natural language
  queries. Use `CODE_RETRIEVAL_QUERY` for queries; `RETRIEVAL_DOCUMENT` for code
  blocks to be retrieved.

* Code suggestions and search
---

* **QUESTION_ANSWERING**
* Embeddings for questions in a question-answering system, optimized for finding
  documents that answer the question. Use `QUESTION_ANSWERING` for questions;
  `RETRIEVAL_DOCUMENT` for documents to be retrieved.

* Chatbox
---

* **FACT_VERIFICATION**
* Embeddings for statements that need to be verified, optimized for retrieving
  documents that contain evidence supporting or refuting the statement. Use
  `FACT_VERIFICATION` for the target text; `RETRIEVAL_DOCUMENT` for documents to
  be retrieved.

* Automated fact-checking systems
{% /table %}

## Controlling embedding size {% id="control-embedding-size" %}

Both `gemini-embedding-001` and `gemini-embedding-2` are trained using
the Matryoshka Representation Learning (MRL) technique which teaches a model to
learn high-dimensional embeddings that have initial segments (or prefixes) which
are also useful, simpler versions of the same data.

Use the `output_dimensionality` parameter to control the size of
the output embedding vector. Selecting a smaller output dimensionality can save
storage space and increase computational efficiency for downstream applications,
while sacrificing little in terms of quality. By default, both models output a
3072-dimensional embedding, but you can truncate it to a smaller size without
losing quality to save storage space. We recommend using 768, 1536, or 3072
output dimensions.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="What is the meaning of life?",
    config=types.EmbedContentConfig(output_dimensionality=768)
)

[embedding_obj] = result.embeddings
embedding_length = len(embedding_obj.values)

print(f"Length of embedding: {embedding_length}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

async function main() {
    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: 'What is the meaning of life?',
        config: { outputDimensionality: 768 },
    });

    const embeddingLength = response.embeddings?.[0]?.values?.length || 0;
    console.log(`Length of embedding: ${embeddingLength}`);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();

EmbedContentConfig config =
    EmbedContentConfig.builder().outputDimensionality(768).build();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", config);

ContentEmbedding embeddingObj = response.embeddings().get().get(0);
int embeddingLength = embeddingObj.values().get().size();

System.out.println("Length of embedding: " + embeddingLength);
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    // The client uses Application Default Credentials.
    // Authenticate with 'gcloud auth application-default login'.
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    }

    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-2",
        contents,
        &genai.EmbedContentRequest{OutputDimensionality: 768},
    )
    if err != nil {
        log.Fatal(err)
    }

    embedding := result.Embeddings[0]
    embeddingLength := len(embedding.Values)
    fmt.Printf("Length of embedding: %d\n", embeddingLength)
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H 'Content-Type: application/json' \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -d '{
        "content": {"parts":[{ "text": "What is the meaning of life?"}]},
        "output_dimensionality": 768
    }'
```
{% /tab %}
{% /tabs %}

Example output from the code snippet:

```none
Length of embedding: 768
```

## Ensuring quality for smaller dimensions {% id="quality-for-smaller-dimensions" %}

{% callout type="note" %}
`gemini-embedding-2` introduces automatic renormalization for non-default
dimensions.
{% /callout %}

While the default 3072-dimension embeddings are always normalized, Gemini
Embedding 2 also auto-normalizes truncated dimensions (e.g., 768, 1536). This
ensures semantic similarity is calculated via vector direction rather than
magnitude, providing more accurate results out of the box.

**Older Models**: If you are using `gemini-embedding-001`, you must manually
normalize non-3072 dimensions as follows:

{% tabs %}
{% tab label="Python" %}
```python
import numpy as np
from numpy.linalg import norm

embedding_values_np = np.array(embedding_obj.values)
normed_embedding = embedding_values_np / np.linalg.norm(embedding_values_np)

print(f"Normed embedding length: {len(normed_embedding)}")
print(f"Norm of normed embedding: {np.linalg.norm(normed_embedding):.6f}") # Should be very close to 1
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;
import java.util.ArrayList;
import java.util.List;

Client client = new Client();

EmbedContentConfig config =
    EmbedContentConfig.builder().outputDimensionality(768).build();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", config);

ContentEmbedding embeddingObj = response.embeddings().get().get(0);
List<Float> values = embeddingObj.values().get();

double norm = 0.0;
for (float v : values) {
  norm += v * v;
}
norm = Math.sqrt(norm);

List<Double> normedEmbedding = new ArrayList<>();
double newNorm = 0.0;
for (float v : values) {
  double normedVal = v / norm;
  normedEmbedding.add(normedVal);
  newNorm += normedVal * normedVal;
}
newNorm = Math.sqrt(newNorm);

System.out.println("Normed embedding length: " + normedEmbedding.size());
System.out.printf("Norm of normed embedding: %.6f%n", newNorm); // Should be very close to 1
```
{% /tab %}

{% /tabs %}

Example output from this code snippet:

```none
Normed embedding length: 768
Norm of normed embedding: 1.000000
```

The following table shows the MTEB scores, a commonly used benchmark for
embeddings, for different dimensions. Notably, the result shows that performance
is not strictly tied to the size of the embedding dimension, with lower
dimensions achieving scores comparable to their higher dimension counterparts.

{% table %}
* 2048
* 68.16
---

* 1536
* 68.17
---

* 768
* 67.99
---

* 512
* 67.55
---

* 256
* 66.19
---

* 128
* 63.31
{% /table %}

## Multimodal embeddings {% id="multimodal" %}

The `gemini-embedding-2` model supports multimodal input, allowing you
to embed images, video, audio, and documents content alongside text. All
modalities are mapped into the same embedding space, enabling cross-modal search
and comparison.

### Supported modalities and limits {% id="supported-modalities" %}

The overall maximum input tokens limit is 8192 tokens.

{% table %}
* **Text**
* Supports up to 8,192 tokens.
---

* **Image**
* Maximum of 6 images per request. Supported formats: PNG, JPEG.
---

* **Audio**
* Maximum duration of 180 seconds. Supported formats: MP3, WAV.
---

* **Video**
* Maximum duration of 120 seconds. Supported formats: MP4, MOV. Supported codecs: H264, H265, AV1, VP9.

  The system processes a maximum of 32 frames per video: short videos (≤32s) are sampled at 1 fps, while longer videos are uniformly sampled to 32 frames. Audio tracks are not processed in video files.
---

* **Documents (PDF)**
* Maximum of 1 file per request, up to 6 pages.
{% /table %}

### Embedding images {% id="embed-images" %}

The following example shows how to embed an image using
`gemini-embedding-2`.

Images can be provided as inline data or as uploaded files
through the [Files API](/docs/files).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

with open('example.png', 'rb') as f:
    image_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=image_bytes,
            mime_type='image/png',
        ),
    ]
)

print(result.embeddings)
```
{% /tab %}
{% tab label="JavaScript" %}
```js
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("example.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'image/png',
                data: imgBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("example.png"));

Content content = Content.fromParts(Part.fromBytes(imageBytes, "image/png"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));
```
{% /tab %}

{% tab label="REST" %}
```sh
IMG_PATH="/path/to/your/image.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "image/png",
                    "data": "'"${IMG_BASE64}"'"
                }
            }]
        }
    }'
```
{% /tab %}
{% /tabs %}

### Embedding aggregation {% id="embedding-aggregation" %}

When working with multimodal content, how you structure your input affects the
embedding output:

* **Multiple parts (aggregated):** Adding multiple inputs directly to the
    `contents` parameter produces one aggregated embedding for all inputs.

* **Multiple `Content` objects (separate):** Wrapping each input in a
    `Content` object and passing them in the `contents` parameter returns
    separate embeddings for each entry.

* **Post-level representation:** For complex objects like social media posts
    with multiple media items, we recommend aggregating separate embeddings
    (for example, by averaging) to create a coherent post-level representation.

The following example shows how to create one aggregated embedding for text and
image input. Simply add multiple inputs to the `contents` parameter:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

with open('dog.png', 'rb') as f:
    image_bytes = f.read()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        "An image of a dog",
        types.Part.from_bytes(
            data=image_bytes,
            mime_type='image/png',
        ),
    ]
)

for embedding in result.embeddings:
    print(embedding.values)
```
{% /tab %}
{% tab label="JavaScript" %}
```js
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("dog.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [
            'An image of a dog',
            {
                inlineData: {
                    mimeType: 'image/png',
                    data: imgBase64,
                },
            },
        ],
    });

    // This produces one embedding
    for (const embedding of response.embeddings || []) {
        console.log(embedding.values);
    }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("dog.png"));

Content content =
    Content.fromParts(
        Part.fromText("An image of a dog"),
        Part.fromBytes(imageBytes, "image/png"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

// This produces one embedding
for (ContentEmbedding embedding : response.embeddings().orElse(Collections.emptyList())) {
  System.out.println(embedding.values().orElse(Collections.emptyList()));
}
```
{% /tab %}

{% tab label="REST" %}
```sh
IMG_PATH="/path/to/your/dog.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [
                {"text": "An image of a dog"},
                {
                    "inline_data": {
                        "mime_type": "image/png",
                        "data": "'"${IMG_BASE64}"'"
                    }
                }
            ]
        }
    }'
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
The text portion of the multimodal input shouldn't include task type
information.
{% /callout %}

On the other hand, if you use `Content` objects inside the `contents` parameter,
it returns separate embeddings. This example creates multiple embeddings in one
embedding call:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

with open('dog.png', 'rb') as f:
    image_bytes = f.read()

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents=[
        types.Content(parts=[types.Part.from_text(text="task: classification | query: An image of a dog")]),
        types.Content(
            parts=[
                types.Part.from_bytes(
                    data=image_bytes,
                    mime_type="image/png",
                ),
            ]
        ),
    ],
)

for embedding in result.embeddings:
    print(embedding.values)
```
{% /tab %}
{% tab label="JavaScript" %}
```js
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("dog.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [
            { parts: [{ text: 'task: classification | query: An image of a dog' }] },
            {
                parts: [{
                    inlineData: {
                        mimeType: 'image/png',
                        data: imgBase64,
                    },
                }],
            },
        ],
    });

    // This produces two embeddings
    for (const embedding of response.embeddings || []) {
        console.log(embedding.values);
    }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("dog.png"));

List<Content> contents =
    Arrays.asList(
        Content.fromParts(Part.fromText("task: classification | query: An image of a dog")),
        Content.fromParts(Part.fromBytes(imageBytes, "image/png")));

// Embed each Content object separately to produce separate embeddings
for (Content content : contents) {
  EmbedContentResponse response =
      client.models.embedContent("gemini-embedding-2", content, null);
  for (ContentEmbedding embedding : response.embeddings().orElse(Collections.emptyList())) {
    System.out.println(embedding.values().orElse(Collections.emptyList()));
  }
}
```
{% /tab %}

{% tab label="REST" %}
```sh
IMG_PATH="/path/to/your/dog.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:batchEmbedContents" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "requests": [
            {
                "model": "models/gemini-embedding-2",
                "content": {"parts": [{"text": "task: classification | query: An image of a dog"}]}
            },
            {
                "model": "models/gemini-embedding-2",
                "content": {"parts": [{"inline_data": {"mime_type": "image/png", "data": "'"${IMG_BASE64}"'"}}]}
            }
        ]
    }'
```
{% /tab %}
{% /tabs %}

### Embedding audio {% id="embed-audio" %}

The following example shows how to embed an audio file using
`gemini-embedding-2`.

Audio files can be provided as inline data or as uploaded files
through the [Files API](/docs/files).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

with open('example.mp3', 'rb') as f:
    audio_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=audio_bytes,
            mime_type='audio/mpeg',
        ),
    ]
)

print(result.embeddings)
```
{% /tab %}
{% tab label="JavaScript" %}
```js
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const audioBase64 = fs.readFileSync("example.mp3", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'audio/mpeg',
                data: audioBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] audioBytes = Files.readAllBytes(Paths.get("example.mp3"));

Content content = Content.fromParts(Part.fromBytes(audioBytes, "audio/mpeg"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));
```
{% /tab %}

{% tab label="REST" %}
```sh
AUDIO_PATH="/path/to/your/example.mp3"
AUDIO_BASE64=$(base64 -w0 "${AUDIO_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "audio/mpeg",
                    "data": "'"${AUDIO_BASE64}"'"
                }
            }]
        }
    }'
```
{% /tab %}
{% /tabs %}

### Embedding video {% id="embed-video" %}

The following example shows how to embed a video using
`gemini-embedding-2`.

Videos can be provided as inline data or as uploaded files
through the [Files API](/docs/files).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

with open('example.mp4', 'rb') as f:
    video_bytes = f.read()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=video_bytes,
            mime_type='video/mp4',
        ),
    ]
)

print(result.embeddings[0].values)
```
{% /tab %}
{% tab label="JavaScript" %}
```js
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const videoBase64 = fs.readFileSync("example.mp4", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'video/mp4',
                data: videoBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;

Client client = new Client();

byte[] videoBytes = Files.readAllBytes(Paths.get("example.mp4"));

Content content = Content.fromParts(Part.fromBytes(videoBytes, "video/mp4"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(
    response.embeddings().get().get(0).values().orElse(Collections.emptyList()));
```
{% /tab %}

{% tab label="REST" %}
```sh
VIDEO_PATH="/path/to/your/video.mp4"
VIDEO_BASE64=$(base64 -w0 "${VIDEO_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "video/mp4",
                    "data": "'"${VIDEO_BASE64}"'"
                }
            }]
        }
    }'
```
{% /tab %}
{% /tabs %}

If you need to embed videos >120 seconds, you can chunk the video into
overlapping segments and embed those chunks individually.

### Embedding documents {% id="embed-documents" %}

Documents in PDF format can be embedded directly. The model processes the visual
and text
content of each page.

PDFs can be provided as inline data or as uploaded files
through the [Files API](/docs/files).

#### How the model processes PDFs {% id="pdf-processing" %}

When you embed a PDF, the model processes the document using both visual and
text features:

* **Visual representation:** The model renders each page as an image, which
  consumes **258 tokens** per page.
* **Text extraction:** The model extracts text from the document. For **native
  PDFs** (which contain digital text), the model extracts the text directly. For
  **scanned PDFs** (which contain images of text), the model automatically runs
  optical character recognition (OCR) to extract the text.

To calculate the total token count for a PDF, add the visual tokens (258 per
page) to the text tokens. Your inputs must fit within the model's **8,192 token
limit** (shared across all modalities). The system silently truncates inputs
that exceed this limit.

{% callout type="note" %}
The Gemini Developer API always enables OCR for PDFs and does not support
disabling it (the `document_ocr` parameter is only available in Vertex AI).
{% /callout %}

#### PDF limits {% id="pdf-limits" %}

* **Files per request:** You can submit a maximum of 1 PDF file.
* **Page limit:** You can submit a maximum of 6 pages per file. For the best quality, we strongly recommend using 1 page per PDF.

The following example shows how to embed a PDF using `gemini-embedding-2`:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

with open('example.pdf', 'rb') as f:
    pdf_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=pdf_bytes,
            mime_type='application/pdf',
        ),
    ]
)

print(result.embeddings)
```
{% /tab %}
{% tab label="JavaScript" %}
```js
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const pdfBase64 = fs.readFileSync("example.pdf", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'application/pdf',
                data: pdfBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] pdfBytes = Files.readAllBytes(Paths.get("example.pdf"));

Content content = Content.fromParts(Part.fromBytes(pdfBytes, "application/pdf"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));
```
{% /tab %}

{% tab label="REST" %}
```sh
PDF_PATH="/path/to/your/example.pdf"
PDF_BASE64=$(base64 -w0 "${PDF_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "application/pdf",
                    "data": "'"${PDF_BASE64}"'"
                }
            }]
        }
    }'
```
{% /tab %}
{% /tabs %}

## Use cases {% id="common-use-cases" %}

Text embeddings are crucial for a variety of common AI use cases, such as:

* **Retrieval-Augmented Generation (RAG):** Embeddings enhance the quality
    of generated text by retrieving and incorporating relevant information into
    the context of a model.

* **Information retrieval:** Search for the most semantically similar text or
    documents given a piece of input text.

    {% button href="https://github.com/google-gemini/cookbook/blob/main/examples/Talk_to_documents_with_embeddings.ipynb" variant="primary" icon="task" %}Document search tutorial{% /button %}

* **Search reranking**: Prioritize the most relevant items by semantically
    scoring initial results against the query.

    {% button href="https://github.com/google-gemini/cookbook/blob/main/examples/Search_reranking_using_embeddings.ipynb" variant="primary" icon="task" %}Search reranking tutorial{% /button %}

* **Anomaly detection:** Comparing groups of embeddings can help identify
    hidden trends or outliers.

    {% button href="https://github.com/google-gemini/cookbook/blob/main/examples/Anomaly_detection_with_embeddings.ipynb" variant="primary" icon="bubble_chart" %}Anomaly detection tutorial{% /button %}

* **Classification:** Automatically categorize text based on its content, such
    as sentiment analysis or spam detection

    {% button href="https://github.com/google-gemini/cookbook/blob/main/examples/Classify_text_with_embeddings.ipynb" variant="primary" icon="token" %}Classification tutorial{% /button %}

* **Clustering:** Effectively grasp complex relationships by creating clusters
    and visualizations of your embeddings.

    {% button href="https://github.com/google-gemini/cookbook/blob/main/examples/clustering_with_embeddings.ipynb" variant="primary" icon="bubble_chart" %}Clustering visualization tutorial{% /button %}

## Storing embeddings {% id="store-embeddings" %}

As you take embeddings to production, it is common to
use **vector databases** to efficiently store, index, and retrieve
high-dimensional embeddings. Google Cloud offers managed data services that
can be used for this purpose including
[Gemini Enterprise Agent Platform Vector Search 2.0](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/vector-search-2/overview),
[BigQuery](https://cloud.google.com/bigquery/docs/introduction),
[AlloyDB](https://cloud.google.com/alloydb/docs/overview), and
[Cloud SQL](https://cloud.google.com/sql/docs/postgres/introduction).

The following tutorials show how to use other third party vector databases
with Gemini Embedding.

* {% button href="https://docs.trychroma.com/integrations/embedding-models/google-gemini" variant="primary" icon="bolt" %}ChromaDB tutorials{% /button %}
* {% button href="https://qdrant.tech/documentation/embeddings/gemini/" variant="primary" icon="bolt" %}QDrant tutorials{% /button %}
* {% button href="https://docs.weaviate.io/weaviate/model-providers/google" variant="primary" icon="bolt" %}Weaviate tutorials{% /button %}
* {% button href="https://github.com/google-gemini/cookbook/blob/main/examples/langchain/Gemini_LangChain_QA_Pinecone_WebLoad.ipynb" variant="primary" icon="bolt" %}Pinecone tutorials{% /button %}

## Model versions {% id="model-versions" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_gemini-embedding.md" /%}

For deprecated Embeddings models, visit the [Deprecations](/docs/deprecations) page

## Migration from gemini-embedding-001 {% id="migration" %}

The embedding spaces between `gemini-embedding-001` and
`gemini-embedding-2` are **incompatible**. This means you cannot
directly compare embeddings generated by one model with embeddings generated by
the other. If you are upgrading to `gemini-embedding-2`, you must
re-embed all of your existing data.

Beyond incompatibility, there are several other notable differences between
the two models:

* **Task type specification:** With `gemini-embedding-001`, you specify the
    task type using the `task_type` parameter (e.g., `SEMANTIC_SIMILARITY`,
    `RETRIEVAL_DOCUMENT`). With `gemini-embedding-2`, the `task_type`
    parameter is not supported. Instead, you should include task instructions
    directly in the prompt for text-only tasks. See
    [Task types with Embeddings 2](/docs/embeddings#task-types-embeddings-2) for details on how
    to format prompts for different use cases.

* **Embedding aggregation:** `gemini-embedding-001` generates individual
    embeddings for each string in a list of inputs. In contrast,
    `gemini-embedding-2` produces a single, aggregated embedding when multiple
    inputs (like text and images) are provided directly in one request. To
    generate separate embeddings for individual inputs, wrap each input in a
    `Content` object, or use the
    [Batch API](/docs/batch-api#batch-embedding). See
    [Embedding aggregation](/docs/embeddings#embedding-aggregation) for more information.

* **Normalization:** If you use `output_dimensionality` to request embeddings
    with fewer than 3072 dimensions, `gemini-embedding-2` automatically
    normalizes these truncated embeddings. With `gemini-embedding-001`, you
    need to perform manual normalization for dimensions other than 3072. See
    [Ensuring quality for smaller dimensions](/docs/embeddings#quality-for-smaller-dimensions)
    for details.

## Batch embeddings {% id="batch-embedding" %}

If latency is not a concern, try using the Gemini Embeddings models with
[Batch API](/docs/batch-api#batch-embedding). This
allows for much higher throughput at 50% of the default Embedding price.
Find examples on how to get started in the [Batch API cookbook](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Batch_mode.ipynb).

## Responsible use notice {% id="responsible-use-notice" %}

Unlike generative AI models that create new content, the Gemini Embedding model
is only intended to transform the format of your input data into a numerical
representation. While Google is responsible for providing an embedding model
that transforms the format of your input data to the numerical-format requested,
users retain full responsibility for the data they input and the resulting
embeddings. By using the Gemini Embedding model you confirm that you have the
necessary rights to any content that you upload. Do not generate content that
infringes on others' intellectual property or privacy rights. Your use of this
service is subject to our [Prohibited Use
Policy](https://policies.google.com/terms/generative-ai/use-policy) and
[Google's Terms of Service](/docs/terms).

## Start building with embeddings {% id="start-building" %}

Check out the [embeddings quickstart
notebook](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Embeddings.ipynb)
to explore the model capabilities and learn how to customize and visualize your
embeddings.

# Gemini Robotics ER
Source: https://aistudio.google.com/docs/robotics-overview
Description: Overview of Gemini Robotics ER models and capabilities for building robotics applications.

{% callout type="note" %}
The Gemini Robotics ER model is in preview.
{% /callout %}

Gemini Robotics ER (embodied reasoning) models are vision-language models
(VLMs) that let robots perceive and interact with the physical world. They
interpret visual data, perform spatial and temporal reasoning, plan multi-step
tasks, and orchestrate robots and tools.

## Models {% id="models" %}

The Gemini Robotics ER 2 model is the latest model in Gemini Robotics.
It is our updated reasoning model that enables robots to understand their
environments precisely. It specializes in embodied reasoning capabilities, such
as agentic orchestration of robots (e.g. using VLAs), robot video understanding
including progress understanding and success detection, instrument reading,
pointing, and spatial reasoning.

The Gemini Robotics ER 2 model introduces two model endpoints:

*   **`gemini-robotics-er-2-preview`**: The standard ER 2 model. Builds on
    Gemini 3.5 Flash with improved spatial reasoning, video moment finding,
    video progress classification, multi-robot orchestration, and multi-step
    tool use.
*   **`gemini-robotics-er-2-streaming-preview`**: Optimized for real-time
    streaming using the [Live API](/docs/live-api/get-started-sdk). Use this
    model for low-latency robot agents that process continuous audio and video
    input.

Gemini Robotics ER 1.6 was
[deprecated on August 31, 2026](/docs/deprecations#robotics-models). If you are
still using Gemini Robotics ER 1.6, upgrade to Gemini Robotics ER 2 by replacing
`model="gemini-robotics-er-1.6-preview"` with
`model="gemini-robotics-er-2-preview"` or
`model="gemini-robotics-er-2-streaming-preview"` in your API calls.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-robotics-er-2-preview" variant="ais" %}Try Gemini Robotics ER 2 in Google AI Studio{% /button %}

## Robotics capabilities {% id="capabilities" %}

Gemini Robotics ER supports a range of embodied reasoning capabilities.
Select a capability to learn more:

{% table %}
* Capability
* Description
* Guide
---
* Spatial reasoning
* Point to objects, track them in video, detect with bounding boxes, plan trajectories.
* [Spatial reasoning](/docs/robotics-spatial)
---
* Agentic vision
* Use code execution to enhance other capabilities by leveraging image manipulation tools.
* [Agentic vision](/docs/robotics-agentic)
---
* Task orchestration
* Combine spatial reasoning with custom robot APIs to complete long-horizon tasks.
* [Task orchestration](/docs/robotics-orchestration)
---
* Streaming (Gemini Robotics ER 2 Streaming endpoint only)
* Bidirectional streaming for real-time robot agents with low-latency function calling.
* [Streaming for robotics](/docs/robotics-streaming)
---
* Video progress (Gemini Robotics ER 2 only)
* Moment finding and progress classification from continuous video feeds.
* [Video understanding](/docs/robotics-video-progress)
{% /table %}

## Before you begin {% id="before-you-begin" %}

The Gemini Robotics ER models are available through the **Gemini Developer
API**. To get started, create a [Gemini API key](/docs/api-key) from
[Google AI Studio](https://aistudio.google.com/apikey) or the
[Google Cloud console](/docs/api-key#cloud-console), and
[set up your environment](/docs/api-key#setup-environment).

For details on key types, security, and how to configure your key in Python,
JavaScript, and other languages, see [Using Gemini API keys](/docs/api-key).

{% callout type="note" %}
Cloud Storage URIs (`gs://`) are not directly accessible through the Gemini
Developer API. Load your images locally or use the [Files API](/docs/files).
{% /callout %}

## Getting started {% id="getting-started" %}

The following example finds objects in an image and returns their normalized 2D
coordinates and labels. You can pass this output directly to a robotics API or a
VLA model to generate robot actions.

{% tabs %}
{% tab label="Python" filename="robotics_overview.py" %}

```python
from google import genai

PROMPT = """
          Point to no more than 10 items in the image. The label returned
          should be an identifying name for the object detected.
          The answer should follow the json format: [{"point": <point>,
          "label": <label1>}, ...]. The points are in [y, x] format
          normalized to 0-1000.
        """
client = genai.Client()

uploaded_file = client.files.upload(file="my-image.png")

image_response = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        },
        {"type": "text", "text": PROMPT}
    ],
    generation_config={"thinking_level": "high"},
)

print(image_response.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}

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

const PROMPT = `
  Point to no more than 10 items in the image. The label returned
  should be an identifying name for the object detected.
  The answer should follow the json format: [{"point": <point>,
  "label": <label1>}, ...]. The points are in [y, x] format
  normalized to 0-1000.
`;
const client = new GoogleGenAI();

const uploadedFile = await client.files.upload({ file: "my-image.png" });

const imageResponse = await client.interactions.create({
  model: "gemini-robotics-er-2-preview",
  input: [
    {
      type: "image",
      uri: uploadedFile.uri,
      mime_type: uploadedFile.mimeType,
    },
    { type: "text", text: PROMPT },
  ],
  generation_config: { thinking_level: "high" },
});

console.log(imageResponse.output_text);
```
{% /tab %}
{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.ThinkingLevel;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.List;

Client client = new Client();

String prompt =
    "Point to no more than 10 items in the image. The label returned "
        + "should be an identifying name for the object detected. "
        + "The answer should follow the json format: [{\"point\": <point>, "
        + "\"label\": <label1>}, ...]. The points are in [y, x] format "
        + "normalized to 0-1000.";

File uploadedFile =
    client.files.upload(
        new java.io.File("my-image.png"),
        UploadFileConfig.builder().mimeType("image/png").build());

Content imageContent =
    ImageContent.builder()
        .uri(uploadedFile.uri().orElse(""))
        .mimeType(ImageContentMimeType.of(uploadedFile.mimeType().orElse("image/png")))
        .build();
Content textContent = TextContent.builder().text(prompt).build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-robotics-er-2-preview"))
        .input(InteractionsInput.ofContent(List.of(imageContent, textContent)))
        .generationConfig(
            GenerationConfig.builder().thinkingLevel(ThinkingLevel.HIGH).build())
        .build();

Interaction imageResponse =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(imageResponse.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := `Point to no more than 10 items in the image. The label returned
should be an identifying name for the object detected.
The answer should follow the json format: [{"point": <point>,
"label": <label1>}, ...]. The points are in [y, x] format
normalized to 0-1000.`

    uploadedFile, err := client.Files.UploadFromPath(ctx, "my-image.png", &genai.UploadFileConfig{
        MIMEType: "image/png",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-robotics-er-2-preview"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.ImageContent{
                    URI:      genai.Ptr(uploadedFile.URI),
                    MimeType: genai.Ptr(interactions.ImageMimeTypeImagePng),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel: interactions.ThinkingLevelHigh.ToPointer(),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% tab label="REST" filename="robotics_overview.sh" %}

```bash
# First, ensure you have the image file locally.
# Encode the image to base64
IMAGE_BASE64=$(base64 -w 0 my-image.png)

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-robotics-er-2-preview",
    "input": {
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "'"${IMAGE_BASE64}"'"
          }
        },
        {
          "text": "Point to no more than 10 items in the image. The label returned should be an identifying name for the object detected. The answer should follow the json format: [{\"point\": [y, x], \"label\": <label1>}, ...]. The points are in [y, x] format normalized to 0-1000."
        }
      ]
    },
    "generation_config": {
      "thinking_config": {
        "thinking_level": "high"
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

The output will be a JSON array containing objects, each with a `point`
(normalized `[y, x]` coordinates) and a `label` identifying the object.

{% tabs %}
{% tab label="JSON" filename="output.json" %}

```json
[
  {"point": [376, 508], "label": "small banana"},
  {"point": [287, 609], "label": "larger banana"},
  {"point": [223, 303], "label": "pink starfruit"},
  {"point": [435, 172], "label": "paper bag"},
  {"point": [270, 786], "label": "green plastic bowl"},
  {"point": [488, 775], "label": "metal measuring cup"},
  {"point": [673, 580], "label": "dark blue bowl"},
  {"point": [471, 353], "label": "light blue bowl"},
  {"point": [492, 497], "label": "bread"},
  {"point": [525, 429], "label": "lime"}
]
```
{% /tab %}
{% /tabs %}

The following image is an example of how these points can be displayed:

![An example that displays the points of objects in an image](/googledevai/static/gemini-api/docs/images/robotics/point-to-object.png)

## How it works {% id="how-it-works" %}

Gemini Robotics ER takes image, video, or audio input with natural language
prompts. It identifies objects, reasons about scene context and spatial
relationships, and returns structured output like coordinates or bounding boxes.

Gemini Robotics ER is also agentic: it breaks complex tasks into sub-tasks and
executes them by calling your robot functions or running generated code. For
example, "put the apple in the bowl" becomes a sequence of locate, grasp, and
place steps.

See [Function calling](/docs/function-calling?example=meeting#how-it-works)
for details on how Gemini executes tool calls.

## Safety {% id="safety" %}

While Gemini Robotics ER was built with safety in mind, it is your
responsibility to maintain a safe environment around the robot. Generative AI
models can make mistakes, and physical robots can cause damage. To learn more,
visit the
[Gemini Robotics safety page](https://deepmind.google/models/gemini-robotics/safety).

## Best practices {% id="best-practices" %}

1.  Use plain, natural language. Describe what you want the robot to do as you
    would to a person. If a term isn't working, try a common synonym.

2.  Optimize visual input. Crop or zoom into small or unclear objects before
    sending the image. Lighting and low color contrast can affect detection.

3.  Break complex tasks into steps. Send each step as a separate prompt to
    keep the model focused and improve accuracy.

4.  Query multiple times and average results for high-precision tasks. This
    consensus approach reduces variance on spatial outputs.

## Limitations {% id="limitations" %}

Consider the following limitations when developing with Gemini Robotics ER:

*   **API key restrictions:** The Gemini API does not accept requests from
    unrestricted API keys and returns a `403 Forbidden` error. Secure your API
    key by adding restrictions in [AI Studio](https://aistudio.google.com/api-keys).
    See [Secure unrestricted API keys](/docs/api-key#secure-unrestricted-keys)
    for details.
*   **Latency vs performance:** Complex queries, high-resolution inputs or high
    thinking levels can lead to increased processing times. For thinking level
    use medium for a good balance between latency and performance.
*   **Hallucinations:** Like all large language models, Gemini Robotics ER models
    can occasionally "hallucinate" or provide incorrect information, especially
    for ambiguous prompts or out-of-distribution inputs.
*   **Dependence on prompt quality:** Output quality depends on the clarity
    of the input prompt. Use specific, well-structured prompts.
*   **Computational cost:** Running the model, especially with video inputs or
    high `thinking_budget`, consumes computational resources and incurs costs.
    See the [Thinking](/docs/thinking) page for more details.
*   **Input types:** See the following topics for details on limitations for each mode.
    * [Image inputs](/docs/image-understanding#technical-details-image)
    * [Video inputs](/docs/video-understanding#supported-formats)
    * [Audio inputs](/docs/audio#supported-formats)

## Privacy Notice {% id="privacy-notice" %}

You acknowledge that the models referenced in this document (the "Robotics
Models") leverage video and audio data in order to operate and move your
hardware in accordance with your instructions. You therefore may operate the
Robotics Models such that data from identifiable persons, such as voice,
imagery, and likeness data ("Personal Data"), will be collected by the Robotics
Models. If you elect to operate the Robotics Models in a manner that collects
Personal Data, you agree that you will not permit any identifiable persons to
interact with, or be present in the area surrounding, the Robotics Models,
unless and until such identifiable persons have been sufficiently notified of
and consented to the fact that their Personal Data may be provided to and used
by Google as outlined in the Gemini API Additional Terms of Service found at
[https://ai.google.dev/gemini-api/terms](https://ai.google.dev/gemini-api/terms)
(the "Terms"), including in accordance
with the section entitled "How Google Uses Your Data". You will ensure that such
notice permits the collection and use of Personal Data as outlined in the Terms,
and you will use commercially reasonable efforts to minimize the collection and
distribution of Personal Data by using techniques such as face blurring and
operating the Robotics Models in areas not containing identifiable persons to
the extent practicable.

## Pricing {% id="pricing" %}

For detailed information on pricing and available regions, refer to the
[pricing](/docs/pricing) page.

## Model endpoints {% id="model-versions" %}

{% partial file="googledevai/en/gemini-api/docs/models/_includes/_robotics-er.md" /%}

## What's next {% id="whats-next" %}

*   [Spatial reasoning](/docs/robotics-spatial) — pointing, tracking, bounding boxes, trajectories.
*   [Agentic capabilities](/docs/robotics-agentic) — code execution, instrument reading, image annotation.
*   [Task orchestration](/docs/robotics-orchestration) — long-horizon tasks with custom robot APIs.
*   [Robotics with streaming](/docs/robotics-streaming) — real-time bidirectional streaming (Gemini Robotics ER 2 only).
*   [Video understanding](/docs/robotics-video-progress) — moment finding and progress classification (Gemini Robotics ER 2 only).
*   [Gemini Robotics safety](https://deepmind.google/models/gemini-robotics/safety)
    — safety research behind the model family.

# Spatial reasoning
Source: https://aistudio.google.com/docs/robotics-spatial
Description: Use Gemini Robotics ER for spatial reasoning tasks including object detection, tracking, and trajectory planning.

Gemini Robotics ER models can point to objects, track them in video, detect
them with bounding boxes, and generate movement trajectories.

For full runnable code, see the
[Robotics cookbook](https://github.com/google-gemini/robotics-samples/blob/main/Getting%20Started/gemini_robotics_er.ipynb).

## Point to objects {% id="pointing-to-objects" %}

The following example finds specific objects in an image and returns their
normalized `[y, x]` coordinates:

{% tabs %}
{% tab label="Python" filename="robotics_spatial.py" %}
```python
from google import genai

PROMPT = """
          Point to no more than 10 items in the image. The label returned
          should be an identifying name for the object detected.
          The answer should follow the json format: [{"point": <point>,
          "label": <label1>}, ...]. The points are in [y, x] format
          normalized to 0-1000.
        """
client = genai.Client()

uploaded_file = client.files.upload(file="my-image.png")

image_response = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        },
        {"type": "text", "text": PROMPT}
    ],
    generation_config={"thinking_level": "high"},
)

print(image_response.output_text)
```
{% /tab %}
{% tab label="REST" filename="robotics_spatial.sh" %}
```bash
# First, ensure you have the image file locally.
# Encode the image to base64
IMAGE_BASE64=$(base64 -w 0 my-image.png)

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-robotics-er-2-preview",
    "input": {
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "'"${IMAGE_BASE64}"'"
          }
        },
        {
          "text": "Point to no more than 10 items in the image. The label returned should be an identifying name for the object detected. The answer should follow the json format: [{\"point\": [y, x], \"label\": <label1>}, ...]. The points are in [y, x] format normalized to 0-1000."
        }
      ]
    },
    "generation_config": {
      "thinking_config": {
        "thinking_level": "high"
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

The output will be a JSON array containing objects, each with a `point`
(normalized `[y, x]` coordinates) and a `label` identifying the object.

{% tabs %}
{% tab label="JSON" filename="output.json" %}
```json
[
  {"point": [376, 508], "label": "small banana"},
  {"point": [287, 609], "label": "larger banana"},
  {"point": [223, 303], "label": "pink starfruit"},
  {"point": [435, 172], "label": "paper bag"},
  {"point": [270, 786], "label": "green plastic bowl"},
  {"point": [488, 775], "label": "metal measuring cup"},
  {"point": [673, 580], "label": "dark blue bowl"},
  {"point": [471, 353], "label": "light blue bowl"},
  {"point": [492, 497], "label": "bread"},
  {"point": [525, 429], "label": "lime"}
]
```
{% /tab %}
{% /tabs %}

The following image is an example of how these points can be displayed:

![An example that displays the points of objects in an image](/googledevai/static/gemini-api/docs/images/robotics/point-to-object.png)

## Tracking objects in a video {% id="object-tracking-video" %}

Gemini Robotics ER 2 can also analyze video frames to track objects
over time. See [Video inputs](/docs/video-understanding#supported-formats)
for a list of supported video formats.

{% tabs %}
{% tab label="Python" filename="robotics_tracking.py" %}
```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="my-video.mp4")

prompt = """
          Point to the red ball in every frame where it appears.
          The answer should follow the json format: [{"point": [y, x],
          "label": <label>}, ...]. The points are in [y, x] format
          normalized to 0-1000. Return one entry per frame that contains
          the object.
        """

image_response = client.interactions.create(
  model="gemini-robotics-er-2-preview",
  input=[
    {
        "type": "video",
        "uri": uploaded_file.uri,
        "mime_type": uploaded_file.mime_type
    },
    {"type": "text", "text": prompt}
  ],
)

print(image_response.output_text)
```
{% /tab %}
{% /tabs %}

## Object detection and bounding boxes {% id="object-detection-bounding-boxes" %}

In addition to points, you can prompt the model to return 2D bounding boxes,
which provide more spatial detail for detected objects.

{% tabs %}
{% tab label="Python" filename="robotics_bounding_boxes.py" %}
```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="my-image.png")

prompt = """
          Detect all objects in this image and return bounding boxes.
          The answer should follow the JSON format:
          [{"label": <label>, "y": <y_min>, "x": <x_min>,
            "y2": <y_max>, "x2": <x_max>}, ...]
          where coordinates are normalized to 0-1000.
        """

image_response = client.interactions.create(
  model="gemini-robotics-er-2-preview",
  input=[
    {
        "type": "image",
        "uri": uploaded_file.uri,
        "mime_type": uploaded_file.mime_type
    },
    {"type": "text", "text": prompt}
  ],
)

print(image_response.output_text)
```
{% /tab %}
{% /tabs %}

## Trajectories {% id="trajectories" %}

Gemini Robotics ER 2 can generate sequences of points that define a
trajectory, useful for guiding robot movement.

This example requests a trajectory to move a red pen to an organizer, including
an estimate of the intermediate waypoints. The code has been reduced to show
only the prompt.

{% tabs %}
{% tab label="Python" filename="robotics_trajectories.py" %}
```python
prompt = """
          Generate a trajectory for the robotic arm to pick up the red pen
          and place it in the organizer. Return a list of waypoints as JSON:
          [{"step": <int>, "point": [y, x], "action": <description>}, ...]
          where coordinates are normalized to 0-1000.
        """
```
{% /tab %}
{% /tabs %}

## Making room for a laptop {% id="making-room-laptop" %}

This example shows how Gemini Robotics ER can reason about a space. The prompt
asks the model to identify which object needs to be moved to create
space for another item.

{% tabs %}
{% tab label="Python" filename="robotics_spatial_reasoning.py" %}
```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="path/to/image-with-objects.jpg")

prompt = """
          Point to the object that I need to remove to make room for my laptop
          The answer should follow the JSON format: [{"point": <point>,
          "label": <label1>}, ...]. The points are in [y, x] format normalized to 0-1000.
        """

image_response = client.interactions.create(
  model="gemini-robotics-er-2-preview",
  input=[
    {
        "type": "image",
        "uri": uploaded_file.uri,
        "mime_type": uploaded_file.mime_type
    },
    {"type": "text", "text": prompt}
  ],
)

print(image_response.output_text)
```
{% /tab %}
{% /tabs %}

The response contains a 2D coordinate of the object that answers the user's
question, in this case, the object that should move to make room for a laptop.

```json
[
  {"point": [672, 301], "label": "The object that I need to remove to make room for my laptop"}
]
```

![An example that shows which object needs to be moved for another object](/googledevai/static/gemini-api/docs/images/robotics/spatial-reasoning.png)

## Packing a lunch {% id="packing-lunch" %}

The model can also provide instructions for multi-step tasks and point to
relevant objects for each step. This example shows how the model plans a series
of steps to pack a lunch bag.

{% tabs %}
{% tab label="Python" filename="robotics_packing.py" %}
```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="path/to/image-of-lunch.jpg")

prompt = """
          Explain how to pack the lunch box and lunch bag. Point to each
          object that you refer to. Each point should be in the format:
          [{"point": [y, x], "label": }], where the coordinates are
          normalized between 0-1000.
        """

image_response = client.interactions.create(
  model="gemini-robotics-er-2-preview",
  input=[
    {
        "type": "image",
        "uri": uploaded_file.uri,
        "mime_type": uploaded_file.mime_type
    },
    {"type": "text", "text": prompt}
  ],
)

print(image_response.output_text)
```
{% /tab %}
{% /tabs %}

The response of this prompt is a set of step by step instructions on how to pack
a lunch bag from the image input.

**Input image**

![An image of a lunch box and items to put into it](/googledevai/static/gemini-api/docs/images/robotics/packing-lunch.png)

**Model output**

```none
Based on the image, here is a plan to pack the lunch box and lunch bag:

1.  **Pack the fruit into the lunch box.** Place the [apple](apple), [banana](banana), [red grapes](red grapes), and [green grapes](green grapes) into the [blue lunch box](blue lunch box).
2.  **Add the spoon to the lunch box.** Put the [blue spoon](blue spoon) inside the lunch box as well.
3.  **Close the lunch box.** Secure the lid on the [blue lunch box](blue lunch box).
4.  **Place the lunch box inside the lunch bag.** Put the closed [blue lunch box](blue lunch box) into the [brown lunch bag](brown lunch bag).
5.  **Pack the remaining items into the lunch bag.** Place the [blue snack bar](blue snack bar) and the [brown snack bar](brown snack bar) into the [brown lunch bag](brown lunch bag).
```

## What's next {% id="whats-next" %}

*   [Agentic capabilities](/docs/robotics-agentic) — code execution, instrument reading, image annotation.
*   [Task orchestration](/docs/robotics-orchestration) — long-horizon tasks with custom robot APIs.
*   [Robotics with streaming](/docs/robotics-streaming) — real-time bidirectional streaming (Gemini Robotics ER 2 only).
*   [Video understanding](/docs/robotics-video-progress) — moment finding and progress classification (Gemini Robotics ER 2 only).

# Agentic vision
Source: https://aistudio.google.com/docs/robotics-agentic
Description: Use Gemini Robotics ER agentic capabilities including code execution, instrument reading, and image annotation.

Gemini Robotics ER models can write and execute Python code to manipulate
images and apply logic before answering. This page covers code execution
examples: object detection with zoom and crop, instrument reading, fluid
measurement, circuit board reading, and image annotation.

To adapt these examples to your own use case, replace the prompt text and the
uploaded image file with your own. You can also adjust the requested JSON
schema in the prompt to match the output structure your application needs, or
add a `system_instruction` to enforce output format and precision.

For full runnable code, see the
[Robotics cookbook](https://github.com/google-gemini/robotics-samples/blob/main/Getting%20Started/gemini_robotics_er.ipynb).

## Thinking level {% id="thinking-level" %}

You can control the thinking level of the model to trade latency for accuracy.
Spatial tasks like object detection perform well with a low thinking level.
Complex tasks like counting or weight estimation benefit from a higher thinking
level.

The following example sets the thinking level to `high` for a complex counting
task:

```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="scene.jpeg")

interaction = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        },
        {"type": "text", "text": "Identify and count all objects on the table."}
    ],
    generation_config={
        "thinking_level": "high"  # Use "minimal" or "low" for faster spatial tasks
    }
)

print(interaction.output_text)
```

See [Thinking](/docs/thinking) for details.

## Object detection (zoom and crop) {% id="agentic-object-detection" %}

The following example uses code execution to zoom and crop an
image for a clearer view when detecting objects and returning bounding boxes.

```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="sorting.jpeg")

prompt = """
Return JSON in the format {label: val, y: val, x: val, y2: val, x2: val} for
the compostable objects in this scene. Please Zoom and crop the image for a
clearer view. Return an annotated image of the final result with the bounding
boxes drawn on it to the API caller as a part of your process.
"""

interaction = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        },
        {"type": "text", "text": prompt}
    ],
    tools=[{"type": "code_execution"}]
)

print(interaction.output_text)
```

The model output would be similar to the following json response:

```json
[
  {"label": "compostable", "y": 256, "x": 482, "y2": 295, "x2": 546},
  {"label": "compostable", "y": 317, "x": 478, "y2": 350, "x2": 542},
  {"label": "compostable", "y": 586, "x": 556, "y2": 668, "x2": 595},
  {"label": "compostable", "y": 463, "x": 669, "y2": 511, "x2": 718},
  {"label": "compostable", "y": 178, "x": 565, "y2": 250, "x2": 609}
]
```

The following image displays the boxes returned from the model.

![An example showing bounding boxes for objects found](/googledevai/static/gemini-api/docs/images/robotics/agentic-bounding-boxes.png)

## Read an analog gauge and apply logic {% id="reading-gauge" %}

The following example demonstrates how to use the model to read an analog gauge
and perform time calculations. It uses a system instruction to enforce a JSON
output.

```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="gauge.jpeg")

interaction = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    system_instruction="Be precise. When JSON is requested, reply with ONLY that JSON (no preface, no code block).",
    input=[
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        },
        {"type": "text", "text": """Read the current value from this gauge. Then, calculate how long
        it will take at the current rate for the value to reach maximum.
        Reply in JSON: {"current_value": val, "max_value": val,
        "time_to_max_minutes": val}"""}
    ],
    tools=[{"type": "code_execution"}]
)

print(interaction.output_text)
```

## Measure fluid in a container {% id="measuring-fluid" %}

The following example demonstrates how to use code execution to measure the
level of fluid in a container.

```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="fluid.jpeg")

interaction = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    system_instruction="Be precise. When JSON is requested, reply with ONLY that JSON (no preface, no code block).",
    input=[
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        },
        {"type": "text", "text": """Measure the amount of fluid in the container. Reply in JSON:
        {"fluid_level_ml": val, "container_capacity_ml": val,
        "percentage_full": val}"""}
    ],
    tools=[{"type": "code_execution"}]
)

print(interaction.output_text)
```

## Read markings on a circuit board {% id="reading-circuit-board" %}

The following example demonstrates how to use code execution to read the
markings on a circuit board.

```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="circuit_board.jpeg")

interaction = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    system_instruction="Be precise. When JSON is requested, reply with ONLY that JSON (no preface, no code block).",
    input=[
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        },
        {"type": "text", "text": """Read all visible component labels and markings on this circuit
        board. Reply in JSON: {"components": [{"label": val,
        "location": [y, x]}]}"""}
    ],
    tools=[{"type": "code_execution"}]
)

print(interaction.output_text)
```

![An example showing markings on a circuit board](/googledevai/static/gemini-api/docs/images/robotics/agentic-circuit-board.png)

## Image annotation {% id="image-annotation" %}

The following example demonstrates how to use code execution to annotate an
image (e.g., drawing arrows for disposal instructions) and return the modified
image.

```python
from google import genai

client = genai.Client()

# Load your image
uploaded_file = client.files.upload(file="sorting.jpeg")

prompt = """
Look at this image and return it as an annotated version using arrows of
different colors to represent which items should go in which bins for
disposal. You must return the final image to the API caller.
"""

interaction = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        },
        {"type": "text", "text": prompt}
    ],
    tools=[{"type": "code_execution"}]
)

print(interaction.output_text)
```

The following is an example image input.

![An example showing a sorting image to annotate](/googledevai/static/gemini-api/docs/images/robotics/agentic-image-annotation.png)

The model output would be similar to the following:

```none
The annotated image shows the suggested disposal locations for the items on the table:
- **Green bin (Compost/Organic)**: Green chili, red chili, grapes, and cherries.
- **Blue bin (Recycling)**: Yellow crushed can and plastic container.
- **Black bin (Trash)**: Chocolate bar wrapper, Welch's packet, and white tissue.
```

## What's next {% id="whats-next" %}

*   [Task orchestration](/docs/robotics-orchestration) — long-horizon tasks with custom robot APIs.
*   [Robotics with streaming](/docs/robotics-streaming) — real-time bidirectional streaming (Gemini Robotics ER 2 only).
*   [Video understanding](/docs/robotics-video-progress) — moment finding and progress classification (Gemini Robotics ER 2 only).

# Task orchestration
Source: https://aistudio.google.com/docs/robotics-orchestration
Description: Orchestrate long-horizon robotics tasks by combining spatial reasoning with custom robot APIs.

Gemini Robotics ER models can plan tasks and reason about space inferring
which actions to take and which objects to move to complete a goal. This page
shows an example for [driving a pick-and-place](/docs/robotics-orchestration#calling-custom-robot-api)
operation through a custom robot API to orchestrate the task of placing an item
into a bowl. This example uses the standard Gemini ER 2 model, for a streaming
example, see the [Gemini ER 2 Streaming guide](/docs/robotics-streaming).

For full runnable code, see the
[Robotics cookbook](https://github.com/google-gemini/robotics-samples/blob/main/Getting%20Started/gemini_robotics_er.ipynb).

## Using a custom robot API {% id="calling-custom-robot-api" %}

This example demonstrates task orchestration with a custom robot API. It
introduces a mock API designed for a pick-and-place operation. The task is to
pick up a blue block and place it in an orange bowl:

![An image of the block and bowl](/googledevai/static/gemini-api/docs/images/robotics/robot-api-example.png)

This example uses the following mock robot API:

{% tabs %}
{% tab label="Python" filename="robotics_orchestration.py" %}
```python
def move(x, y, high):
  print(f"Mock Robot: Moving to coordinates: {x}, {y}, {'high above table' if high else 'down at table level'}")

def setGripperState(opened):
  print(f"Mock Robot: {'Opening gripper' if opened else 'Closing gripper'}")

robot_origin_y = 300
robot_origin_x = 500

move_function = {
    "type": "function",
    "name": "move",
    "description": "Moves the arm to the given coordinates.",
    "parameters": {
        "type": "object",
        "properties": {
            "x": {"type": "integer", "description": "X coordinate relative to the origin"},
            "y": {"type": "integer", "description": "Y coordinate relative to the origin"},
            "high": {"type": "boolean", "description": "Set to True to lift the robot arm above the scene for avoiding obstacles. Set to False to place the gripper on the surface."}
        },
        "required": ["x", "y", "high"]
    }
}

set_gripper_state_function = {
    "type": "function",
    "name": "setGripperState",
    "description": "Opens or closes the robot's gripper.",
    "parameters": {
        "type": "object",
        "properties": {
            "opened": {"type": "boolean", "description": "True opens the gripper, False closes the gripper."}
        },
        "required": ["opened"]
    }
}
```
{% /tab %}
{% /tabs %}

The following example sends the prompt and image to the model with the tool
definitions. It then runs an agentic loop: after each model response, it
executes any requested function calls (`move`, `setGripperState`), returns the
results back to the model using `previous_interaction_id`, and repeats until the
model stops calling functions or the step limit is reached.

{% tabs %}
{% tab label="Python" filename="robotics_orchestration_loop.py" %}
```python
prompt = (
    "You are a robotic arm with six degrees-of-freedom. "
    f"The origin point for calculating the moves is at normalized point y={robot_origin_y}, x={robot_origin_x}. "
    "Use this as the new (0,0) for calculating moves, allowing x and y to be negative.\n\n"
    "Find the blue block and the orange bowl. Calculate their coordinates relative to the origin.\n"
    "Perform a pick and place operation where you pick up the blue block and place it into the orange bowl. "
    "Call the appropriate sequence of functions to complete this operation."
)

# 1. Initial Interaction
interaction = client.interactions.create(
    model=MODEL_ID,
    input=[{"type": "user_input", "content": [
        {"type": "image", "data": img_b64, "mime_type": "image/png"},
        {"type": "text", "text": prompt}
    ]}],
    tools=[move_function, set_gripper_state_function],
    generation_config={"thinking_level": "low"}
)

print("\n--- Executing Orchestrated Plan ---")

max_steps = 15 # Safety limit to prevent infinite loops
step_count = 0

# 2. The Agentic Loop
while step_count < max_steps:
    step_count += 1

    # Check if the model wants to call any functions
    tool_calls = [step for step in interaction.steps if step.type == "function_call"]

    if not tool_calls:
        # If no tools were called, the model is finished with the sequence
        print("Sequence complete.")
        if interaction.output_text:
            print(f"Model Summary: {interaction.output_text}")
        break

    function_results = []

    for step in tool_calls:
        function_name = step.name
        arguments = step.arguments

        # Execute the mock function
        if function_name == "move":
            move(**arguments)
        elif function_name == "setGripperState":
            setGripperState(**arguments)
        else:
            print(f"Unknown function: {function_name}")

        # 3. Create a result object to tell the model the function succeeded
        function_results.append({
            "type": "function_result",
            "name": step.name,
            "call_id": step.id,
            "result": [{"type": "text", "text": '{"status": "success"}'}]
        })

    # 4. Send the results back to the model, passing previous_interaction_id
    # so it remembers the conversation history and generates the NEXT step
    interaction = client.interactions.create(
        model=MODEL_ID,
        previous_interaction_id=interaction.id,
        tools=[move_function, set_gripper_state_function],
        input=function_results
    )
```
{% /tab %}
{% /tabs %}

The following shows a possible output of the model based on the prompt and
the mock robot API. The output includes the output of the robot
function calls that the model sequenced together.

```none
--- Executing Orchestrated Plan ---
Mock Robot: Opening gripper
Mock Robot: Moving to coordinates: 160, 440, high above table
Mock Robot: Moving to coordinates: 160, 440, down at table level
Mock Robot: Closing gripper
Mock Robot: Moving to coordinates: 160, 440, high above table
Mock Robot: Moving to coordinates: -250, 60, high above table
Mock Robot: Moving to coordinates: -250, 60, down at table level
Mock Robot: Opening gripper
Mock Robot: Moving to coordinates: -250, 60, high above table
Sequence complete.
Model Summary: I have completed the task of picking up the blue block and placing it into the orange bowl.
```

## What's next {% id="whats-next" %}

*   [Robotics with streaming](/docs/robotics-streaming) — real-time streaming with function calling (Gemini Robotics ER 2 only).
*   [Video understanding](/docs/robotics-video-progress) — track task progress from video (ER 2 only).
*   [Spatial reasoning](/docs/robotics-spatial) — pointing, tracking, and bounding box examples.

# Robotics with streaming
Source: https://aistudio.google.com/docs/robotics-streaming
Description: Use the Gemini Live API with Gemini Robotics ER 2 Streaming preview for real-time, bidirectional robot orchestration.

{% callout type="note" %}
Robotics with streaming requires `gemini-robotics-er-2-streaming-preview`.
It is not available on ER 1.6 or the standard `gemini-robotics-er-2-preview`
model endpoint.
{% /callout %}

The `gemini-robotics-er-2-streaming-preview` model endpoint exposes a dedicated
streaming endpoint that integrates with the [Live API](/docs/live-api/get-started-sdk),
enabling real-time, bidirectional interaction between your application and the
robot. This makes it suited for agents that need fast feedback loops and
reactive responses to the environment.

{% button href="https://aistudio.google.com/prompts/new_chat?model=gemini-robotics-er-2-streaming-preview" variant="ais" %}Try in Google AI Studio{% /button %}

{% button href="https://github.com/google-gemini/robotics-samples/tree/main/live-api" variant="primary" icon="north_east" %}Clone example apps from GitHub{% /button %}

## Use cases {% id="use-cases" %}

*   **Multi-robot coordination**: Multiple robots that communicate task state
    and delegate subtasks through a shared session.
*   **Continuous monitoring**: Robots that observe a scene and trigger actions
    when specific events occur, such as a container reaching a fill level.
*   **Warehouse and logistics**: Pick-and-pack agents that verify items
    visually, track packing progress, and recover from errors.

## Technical specifications {% id="technical-specifications" %}

The following table outlines the technical specifications for the Live API:

| Category | Details |
| :--- | :--- |
| Input modalities | Audio (raw 16-bit PCM audio, 16kHz, little-endian), images (JPEG <= 1FPS), text |
| Output modalities | Text |
| Protocol | Stateful WebSocket connection (WSS) |

## Build an agentic setup {% id="how-it-works" %}

Every robotics agent built on the Live API follows three steps:

1.  **Declare robot capabilities as tools.** Each action the robot can perform —
    navigate, grasp, speak — becomes a function declaration with a name,
    description, and parameter schema. Physical actions must use
    `"behavior": "BLOCKING"` so the model waits for the robot to finish before
    choosing the next step.
2.  **Stream multimodal input into a persistent session.** Open a `live.connect`
    session and keep it open for the life of the task. Send video frames, audio,
    or text as they arrive from your robot's sensors.
3.  **Handle tool calls in a receive loop.** Each time the model selects an
    action, it sends a `tool_call` message. Your receive loop executes the
    function against your robot SDK and sends back a `tool_response`. The session
    stays open, and the model picks the next action based on the result.

{% callout type="note" %}
Only blocking function calls are supported when using the Live API for
robotics. See the [Live API tools guide](/docs/live-api/tools) for
details.
{% /callout %}

The following sections show how to apply these steps to three common patterns:
a baseline agent loop, proactive scene monitoring with a heartbeat, and routing
speech through TTS as a tool.

## Orchestrate a robot through function calling {% id="orchestrate-robot" %}

The following example shows all three steps wired together in a single Python
script.

Step 1 — tool definitions — declares robot capabilities as function
declarations. The `navigate` function uses `"behavior": "BLOCKING"` so the
model waits for the robot to reach the waypoint before calling another tool.
Add more function declarations in the same list to expose additional robot
capabilities.

Step 2 — input helpers — shows three functions that stream different modality
inputs into the session: `send_text` for commands, `send_image` for camera
frames with an optional text prompt, and `send_audio` for raw PCM audio from a
microphone.

Step 3 — the receive loop — runs concurrently and handles two kinds of messages:
`server_content` messages (the model's text output) and `tool_call` messages
(the model requesting a robot action). When a tool call arrives, the loop calls
`execute_tool` — a stub you replace with your real robot SDK — then sends back a
`tool_response` so the model can select the next action.

```python
import asyncio
from google import genai
from google.genai import types

MODEL = "gemini-robotics-er-2-streaming-preview"

# ── Tool definitions ─────────────────────────────────────────────────────────
tools = [
   {
       "function_declarations": [
           {
               "name": "navigate",
               "description": "Navigate the robot to a named waypoint.",
               "behavior": "BLOCKING",
               "parameters": {
                   "type": "OBJECT",
                   "properties": {"name": {"type": "STRING"}},
                   "required": ["name"],
               },
           },
           # Add more function definitions here
       ]
   }
]

# ── Stub tool executor (replace with real robot SDK calls) ───────────────────
def execute_tool(name: str, args: dict) -> dict:
   print(f"  [Tool] {name}({args})")
   return {"status": "success"}

# ── Input helpers ────────────────────────────────────────────────────────────
def send_text(session, text: str):
   """Send a text turn."""
   return session.send_client_content(
       turns=types.Content(role="user", parts=[types.Part(text=text)]),
       turn_complete=True,
   )

def send_image(session, image_bytes: bytes, prompt: str = ""):
   """Send a JPEG image with an optional text prompt."""
   parts = [
       types.Part(
           inline_data=types.Blob(data=image_bytes, mime_type="image/jpeg")
       )
   ]
   if prompt:
       parts.append(types.Part(text=prompt))
   return session.send_client_content(
       turns=types.Content(role="user", parts=parts),
       turn_complete=True,
   )

def send_audio(session, audio_chunk: bytes):
   """Stream a chunk of raw PCM audio (16-bit, 16 kHz, mono)."""
   return session.send_realtime_input(
       media=types.Blob(data=audio_chunk, mime_type="audio/pcm;rate=16000")
   )

# ── Receive loop ─────────────────────────────────────────────────────────────
async def receive_loop(session):
   """Print model text and handle tool calls until the session ends."""
   async for message in session.receive():
       if message.server_content:
           sc = message.server_content
           if sc.model_turn and sc.model_turn.parts:
               for part in sc.model_turn.parts:
                   if part.text:
                       print(f"Model: {part.text}", end="", flush=True)
           if sc.turn_complete:
               print("\n[Turn Complete]")
       elif message.tool_call:
           responses = []
           for call in message.tool_call.function_calls:
               print(f"\n[Tool Call] {call.name}({call.args})")
               result = execute_tool(call.name, call.args)
               responses.append(
                   types.FunctionResponse(
                       name=call.name,
                       response=result,
                       id=call.id,
                   )
               )
           await session.send_tool_response(function_responses=responses)

# ── Main ─────────────────────────────────────────────────────────────────────
async def main():
   client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
   config = types.LiveConnectConfig(
       response_modalities=["TEXT"],
       tools=tools,
       system_instruction=types.Content(
           parts=[types.Part(text="You are a robot controller. Use tools to execute commands.")]
       ),
   )
   async with client.aio.live.connect(model=MODEL, config=config) as session:
       recv_task = asyncio.create_task(receive_loop(session))
       # Connect robot perception callbacks and user inputs to the helpers above.
       recv_task.cancel()

asyncio.run(main())
```

The receive loop stays active after each tool response. The model constructs
and revises a long-horizon plan without you encoding the entire action sequence
in advance.

## Proactive spatial-temporal reasoning {% id="heartbeat" %}

The Live API streams video in, but video frames alone do
not trigger a new reasoning turn. Video frames must be accompanied by a
text or audio prompt to trigger a model response. See
[Live API capabilities](/docs/live-api/capabilities) for
more details.

To enable proactive reasoning, implement a **heartbeat**: periodically send the
latest camera frame followed by a short text prompt that forces the model to
inspect the scene and make an explicit decision. Video input is rate-limited to
one frame per second.

### Implement the heartbeat

The heartbeat coroutine runs as a separate `asyncio` task in the same session.
It opportunistically targets a 1 Hz cadence (matching the video input rate limit)
while waiting for each turn to complete (`er_turn_done`) to avoid interrupting
in-flight reasoning:

```python
async def heartbeat(session, camera, er_turn_done: asyncio.Event):
    TARGET_INTERVAL_SEC = 1.0

    while True:
        start_time = asyncio.get_running_loop().time()

        frame = await camera.latest_jpeg()
        await session.send_realtime_input(
            video=types.Blob(data=frame, mime_type="image/jpeg")
        )
        await session.send_realtime_input(
            text=(
                "[HEARTBEAT] If no task is active, call 'ack' and wait for user"
                " input. If a task is active: observe the scene. If the current"
                " step is progressing correctly, call 'ack'. If the current step"
                " is complete, call 'run_instruction' with the next step. If the"
                " overall goal is achieved, call 'reset' and inform the user."
            )
        )

        # Wait for the model to finish responding before sending the next heartbeat
        await er_turn_done.wait()
        er_turn_done.clear()

        # Sleep only the remaining time to maintain ~1 Hz cadence
        elapsed = asyncio.get_running_loop().time() - start_time
        remaining = TARGET_INTERVAL_SEC - elapsed
        if remaining > 0:
            await asyncio.sleep(remaining)
```

{% callout type="warning" %}
Sending a new prompt while the model is generating acts as an interruption
(barge-in), which cancels in-flight reasoning and tool calls. If you fire
heartbeats on a blind timer without waiting for the previous turn to complete,
you may trap the model in a cancellation loop, making it appear unresponsive.
See the [Live API guide on interruptions](/docs/live-api/capabilities#interruptions)
for more details.
{% /callout %}

### Update the receive loop

To signal when the model has completed its turn, update your `receive_loop`
to set `er_turn_done`:

```python
# In receive_loop: signal when the model finishes its turn
if sc.turn_complete:
    er_turn_done.set()
```

## Audio output through external TTS {% id="audio-tts" %}

Gemini Robotics ER 2 returns text. Your application routes completed responses
to a separate TTS provider (such as
[Gemini TTS](/docs/speech-generation)) via an injected callback.
This keeps speech latency, voice selection, and interruption behavior under your
control, and lets you swap TTS backends without changing agent logic.

You can also declare TTS as a tool so the model treats "say something" the same
as "move the arm." Add the following function declaration to your `tools` list
from the first section:

```python
TOOLS = [
    {
        "name": "send_message",
        "description": (
            "Speak a message aloud via TTS, then deliver it to the"
            " specified target. Use target='user' to speak directly"
            " to the user, or a peer agent name (e.g., 'duo') to"
            " communicate with another robot."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "target": {
                    "type": "string",
                    "description": "Recipient: 'user' or a peer agent name.",
                },
                "message": {
                    "type": "string",
                    "description": "The message to speak and deliver.",
                },
            },
            "required": ["target", "message"],
        },
    },
]
```

By wrapping TTS in a function declaration, the model handles speech through the
same tool-call path as any other robot action. Your application fulfills the
call with an injected callback.

## Examples on GitHub {% id="full-examples" %}

For full working examples including the Spot robot snack-fetch demo and Tinybot
pan-tilt hello world, see
[Robotics Live API examples](https://github.com/google-gemini/robotics-samples/tree/main/live-api).

## What's next {% id="whats-next" %}

*   [Video understanding](/docs/robotics-video-progress) — moment finding and progress classification.
*   [Task orchestration](/docs/robotics-orchestration) — long-horizon tasks without streaming.
*   [Live API overview](/docs/live-api/get-started-sdk) — full Live API documentation.

# Video understanding
Source: https://aistudio.google.com/docs/robotics-video-progress
Description: Use Gemini Robotics ER 2 to track task progress and identify key moments in robot task videos.

{% callout type="note" %}
Video understanding requires Gemini Robotics ER 2
(`gemini-robotics-er-2-preview`). It is not available on ER 1.6.
{% /callout %}

Gemini Robotics ER 2 can track task progress from continuous video feeds using
two capabilities:

*   Moment finding: identifies the precise timestamp where a key event occurs.
*   Progress classification: assigns each video to one of five completion
    brackets (0–20%, 20–40%, 40–60%, 60–80%, 80–100%).

## Moment finding {% id="moment-finding" %}

Moment finding identifies the exact video frame where a critical event occurs —
for example, when a cup is full or a knot is tied. Robots use this to verify
success, sequence steps, and trigger corrections.

The following example prompt asks the model to identify the completion moment
for a given task in a video:

```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="task_video.mp4")

prompt = """
At what timestamp (in seconds) does the task reach successful completion?
Return a JSON object: {"completion_time_seconds": <float>}.
If the task is not completed, return {"completion_time_seconds": null}.
"""

interaction = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[
        {
            "type": "video",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        },
        {"type": "text", "text": prompt}
    ],
)

print(interaction.output_text)
```

The following shows example frames from a moment-finding video, with the
model identifying the task completion timestamp:

![Example video frames showing the moment finding output with a timestamp overlay](/googledevai/static/gemini-api/docs/images/robotics/video-moment-finding.png)

## Progress classification {% id="progress-classification" %}

Progress classification assigns a video to one of five completion brackets:
0–20%, 20–40%, 40–60%, 60–80%, or 80–100%. This gives robots real-time
situational awareness so they can adjust actions or retry failed steps without
restarting an entire workflow.

The following example prompt asks the model to classify the current progress
level from a video:

```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="task_video.mp4")

prompt = """
Watch this video and classify the task progress level at the final frame.
Return a JSON object with the progress bracket:
{"progress_level": "0-20" | "20-40" | "40-60" | "60-80" | "80-100"}.
"""

interaction = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[
        {
            "type": "video",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        },
        {"type": "text", "text": prompt}
    ],
)

print(interaction.output_text)
```

The following shows example frames from a progress classification video, with
the model assigning a progress bracket:

![Example video frames showing the progress classification output with a progress bracket label](/googledevai/static/gemini-api/docs/images/robotics/video-progress-classification.png)

## Examples {% id="full-examples" %}

For full runnable examples including multi-step task tracking, see the
[Robotics cookbook](https://github.com/google-gemini/robotics-samples/blob/main/Getting%20Started/gemini_robotics_er.ipynb).

## What's next {% id="whats-next" %}

*   [Live API for robotics](/docs/robotics-streaming) — real-time bidirectional streaming.
*   [Task orchestration](/docs/robotics-orchestration) — long-horizon tasks with spatial reasoning.
*   [Gemini Robotics ER overview](/docs/robotics-overview) — model comparison and capabilities.

# Text generation
Source: https://aistudio.google.com/docs/text-generation
Description: Get started building text generation and multi-turn interaction apps with the Gemini API

The Gemini API can generate text output from text, images, video, and audio
inputs.

Here's a basic example:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="How does AI work?"
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "How does AI work?",
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("How does AI work?"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("How does AI work?"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "How does AI work?"
  }'
```
{% /tab %}
{% /tabs %}

The Google GenAI SDKs provide convenience properties directly
on the returned `Interaction` object to access the model's response.

The most common helper is **`interaction.output_text`** (String), which returns
the last text blocks in the model's response. If the response is split
across multiple consecutive `TextContent` blocks, it automatically joins them.
Note that `.output_text` does not include earlier text blocks separated by
non-text content (such as thoughts, images, audio, or tool calls). For complex
or interleaved multimodal responses, you must manually iterate over `steps`
instead.

## Thinking with Gemini {% id="thinking-with-gemini" %}

Gemini models often have ["thinking"](/docs/thinking)
enabled by default which allows the model to reason before responding to a
request.

Each model supports different thinking configurations which gives you control
over cost, latency, and intelligence. For more details, see the
[thinking guide](/docs/thinking#thinking-levels).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="How does AI work?",
    generation_config={
        "thinking_level": "low"
    }
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "How does AI work?",
    generation_config: {
      thinking_level: "low",
    },
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ThinkingLevel;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("How does AI work?"))
        .generationConfig(GenerationConfig.builder().thinkingLevel(ThinkingLevel.LOW).build())
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("How does AI work?"),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel: interactions.ThinkingLevelLow.ToPointer(),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "How does AI work?",
    "generation_config": {
      "thinking_level": "low"
    }
  }'
```
{% /tab %}
{% /tabs %}

## System instructions and other configurations {% id="system-instructions" %}

You can guide the behavior of Gemini models with system instructions. Pass
a `system_instruction` parameter to configure the model's behavior.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    system_instruction="You are a cat. Your name is Neko.",
    input="Hello there"
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Hello there",
    system_instruction: "You are a cat. Your name is Neko.",
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .systemInstruction("You are a cat. Your name is Neko.")
        .input(InteractionsInput.of("Hello there"))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:             interactions.Model("gemini-3.8-flash"),
            Input:             interactions.NewInteractionsInput("Hello there"),
            SystemInstruction: genai.Ptr("You are a cat. Your name is Neko."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "system_instruction": "You are a cat. Your name is Neko.",
    "input": "Hello there"
  }'
```
{% /tab %}
{% /tabs %}

You can also override default generation parameters, such as
`max_output_tokens` or `thinking_level`, using the `generation_config` parameter.

{% callout type="note" %}
Gemini 4 and Gemini 3.6+ models ignore custom values for `temperature`, `top_p`, and `top_k` and return deprecation warning headers. Remove these sampling parameters from your requests.
{% /callout %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain how AI works",
    generation_config={
        "max_output_tokens": 500
    }
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain how AI works",
    generation_config: {
      max_output_tokens: 500,
    },
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain how AI works"))
        .generationConfig(GenerationConfig.builder().maxOutputTokens(500).build())
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Explain the concept of Occam's Razor and provide a simple, everyday example."),
            GenerationConfig: &interactions.GenerationConfig{
                MaxOutputTokens: genai.Ptr(500),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain how AI works",
    "generation_config": {
      "max_output_tokens": 1000
    }
  }'
```
{% /tab %}
{% /tabs %}

Refer to the [Interactions API reference](https://ai.google.dev/api/interactions-api)
for a complete list of configurable parameters and their
descriptions.

## Multimodal inputs {% id="multimodal-input" %}

The Gemini API supports multimodal inputs, allowing you to combine text with
media files. The following example demonstrates providing an image:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="path/to/organ.jpg")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Tell me about this instrument"},
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const uploadedFile = await ai.files.upload({
    file: "path/to/organ.jpg",
    config: { mimeType: "image/jpeg" }
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      {type: "text", text: "Tell me about this instrument"},
      {
        type: "image",
        uri: uploadedFile.uri,
        mime_type: uploadedFile.mimeType
      }
    ],
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;

Client client = new Client();

File uploadedFile =
    client.files.upload(
        new java.io.File("path/to/organ.jpg"),
        UploadFileConfig.builder().mimeType("image/jpeg").build());

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    TextContent.builder().text("Tell me about this instrument").build(),
                    ImageContent.builder()
                        .uri(uploadedFile.uri().orElse(""))
                        .mimeType(
                            ImageContentMimeType.of(uploadedFile.mimeType().orElse("image/jpeg")))
                        .build())))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("/path/to/organ.jpg")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Tell me about this instrument",
                }),
                interactions.NewContent(interactions.ImageContent{
                    Data:     genai.Ptr(base64Image),
                    MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
# First upload the file using the Files API, then use the URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Tell me about this instrument"},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

For alternative methods of providing images and more advanced image processing,
see our [image understanding guide][img-guide].
The API also supports [document][doc-guide], [video][video-guide], and
[audio][audio-guide] inputs and understanding.

[img-guide]: /docs/image-understanding
[doc-guide]: /docs/document-processing
[video-guide]: /docs/video-understanding
[audio-guide]: /docs/audio

## Streaming responses {% id="streaming-responses" %}

By default, the model returns a response only after the entire generation
process is complete.

For more fluid interactions, use streaming to handle response chunks
as they're generated. For a comprehensive guide covering event types,
streaming with tools, thinking, agents, and image generation, see the
dedicated [Streaming interactions](/docs/streaming)
guide.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain how AI works",
    stream=True
)
for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

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

  for await (const event of stream) {
    if (event.event_type === "step.delta") {
      if (event.delta.type === "text") {
        process.stdout.write(event.delta.text);
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain how AI works"))
        .stream(true)
        .build();

CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));

try (EventStream<InteractionSSEStreamEvent> stream = response.events()) {
  for (InteractionSSEStreamEvent streamEvent : stream) {
    InteractionSSEEvent event = streamEvent.data().orElse(null);
    if (event instanceof StepDelta stepDelta) {
      StepDeltaData delta = stepDelta.delta().orElse(null);
      if (delta instanceof TextDelta textDelta) {
        System.out.print(textDelta.text().orElse(""));
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:  interactions.Model("gemini-3.8-flash"),
            Input:  interactions.NewInteractionsInput("Explain how AI works"),
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain how AI works",
    "stream": true
  }'
```
{% /tab %}
{% /tabs %}

## Multi-turn conversations {% id="multi-turn-conversations" %}

The Interactions API supports multi-turn conversations by chaining interactions
together using `previous_interaction_id`. Each turn is a separate interaction,
and the API automatically manages conversation history.

{% callout type="note" %}
Unlike other APIs where you might manage conversation history manually,
the Interactions API handles conversation state server-side. You
pass the `id` from the previous interaction to continue the conversation.
{% /callout %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="I have 2 dogs in my house.",
)
print(interaction1.output_text)

interaction2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="How many paws are in my house?",
    previous_interaction_id=interaction1.id,
)
print(interaction2.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "I have 2 dogs in my house.",
  });
  console.log("Response 1:", interaction1.output_text);

  const interaction2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "How many paws are in my house?",
    previous_interaction_id: interaction1.id,
  });
  console.log("Response 2:", interaction2.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("I have 2 dogs in my house."))
        .build();

Interaction interaction1 =
    client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
System.out.println("Response 1: " + interaction1.outputText().orElse(""));

CreateModelInteraction params2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("How many paws are in my house?"))
        .previousInteractionId(interaction1.id().orElse(""))
        .build();

Interaction interaction2 =
    client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();
System.out.println("Response 2: " + interaction2.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hello, I have 2 dogs in my house."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn1.Interaction.OutputText != nil {
        fmt.Printf("Model: %s\n", *turn1.Interaction.OutputText)
    }

    // Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            PreviousInteractionID: turn1.Interaction.ID,
            Input:                 interactions.NewInteractionsInput("How many paws are in my house?"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Printf("Model: %s\n", *turn2.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "I have 2 dogs in my house."
  }')

INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "I have two dogs in my house. How many paws are in my house?",
    "previous_interaction_id": "'$INTERACTION_ID'"
  }'
```
{% /tab %}
{% /tabs %}

Streaming can also be used for multi-turn conversations by combining
`previous_interaction_id` with the streaming methods.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="I have 2 dogs in my house.",
)
print(interaction1.output_text)

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="How many paws are in my house?",
    previous_interaction_id=interaction1.id,
    stream=True
)
for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "I have 2 dogs in my house.",
  });
  console.log("Response 1:", interaction1.output_text);

  const stream = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "How many paws are in my house?",
    previous_interaction_id: interaction1.id,
    stream: true,
  });
  for await (const event of stream) {
    if (event.event_type === "step.delta") {
      if (event.delta.type === "text") {
        process.stdout.write(event.delta.text);
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;

Client client = new Client();

CreateModelInteraction params1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("I have 2 dogs in my house."))
        .build();

Interaction interaction1 =
    client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
System.out.println("Response 1: " + interaction1.outputText().orElse(""));

CreateModelInteraction params2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("How many paws are in my house?"))
        .previousInteractionId(interaction1.id().orElse(""))
        .stream(true)
        .build();

CreateInteractionResponse response2 =
    client.interactions.create(CreateInteractionRequestBody.of(params2));

try (EventStream<InteractionSSEStreamEvent> stream = response2.events()) {
  for (InteractionSSEStreamEvent streamEvent : stream) {
    InteractionSSEEvent event = streamEvent.data().orElse(null);
    if (event instanceof StepDelta stepDelta) {
      StepDeltaData delta = stepDelta.delta().orElse(null);
      if (delta instanceof TextDelta textDelta) {
        System.out.print(textDelta.text().orElse(""));
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hello, I have 2 dogs in my house."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            PreviousInteractionID: turn1.Interaction.ID,
            Input:                 interactions.NewInteractionsInput("How many paws are in my house?"),
            Stream:                genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res2.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "I have 2 dogs in my house."
  }')
INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "How many paws are in my house?",
    "previous_interaction_id": "'$INTERACTION_ID'",
    "stream": true
  }'
```
{% /tab %}
{% /tabs %}

## Stateless conversations {% id="stateless-conversations" %}

By default, the Interactions API manages conversation state server-side when you
use `previous_interaction_id`. However, you can also operate in stateless mode
by managing the conversation history yourself on the client side.

To use stateless mode:

1. Set `store=false` in your request to opt out of server-side storage.
2. Maintain the conversation history as an array of **steps** on the client side.
3. In subsequent requests, pass the accumulated steps in the `input` field, and append your new turn as a `user_input` step.

{% callout type="note" %}
If the model uses "thinking" or tools, you **must** preserve and resend
all model-generated steps (such as `thought` and `function_call` steps) exactly
as received, as they contain signatures required to continue the conversation.
{% /callout %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

history = [
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "I have 2 dogs in my house."}]
    }
]

interaction1 = client.interactions.create(
    model="gemini-3.8-flash",
    store=False,
    input=history
)
print("Response 1:", interaction1.steps[-1].content[0].text)

for step in interaction1.steps:
    history.append(step.model_dump())

history.append({
    "type": "user_input",
    "content": [{"type": "text", "text": "How many paws are in my house?"}]
})

interaction2 = client.interactions.create(
    model="gemini-3.8-flash",
    store=False,
    input=history
)
print("Response 2:", interaction2.steps[-1].content[0].text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const history = [
    {
      type: "user_input",
      content: [{ type: "text", text: "I have 2 dogs in my house." }]
    }
  ];

  const interaction1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    store: false,
    input: history
  });
  console.log("Response 1:", interaction1.steps.at(-1).content[0].text);

  history.push(...interaction1.steps);

  history.push({
    type: "user_input",
    content: [{ type: "text", text: "How many paws are in my house?" }]
  });

  const interaction2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    store: false,
    input: history
  });
  console.log("Response 2:", interaction2.steps.at(-1).content[0].text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.UserInputStep;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

List<Step> history = new ArrayList<>();
history.add(
    UserInputStep.builder()
        .content(Arrays.asList(TextContent.builder().text("I have 2 dogs in my house.").build()))
        .build());

CreateModelInteraction params1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .store(false)
        .input(InteractionsInput.ofStep(history))
        .build();

Interaction interaction1 =
    client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
System.out.println("Response 1: " + interaction1.outputText().orElse(""));

interaction1.steps().ifPresent(history::addAll);

history.add(
    UserInputStep.builder()
        .content(Arrays.asList(TextContent.builder().text("How many paws are in my house?").build()))
        .build());

CreateModelInteraction params2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .store(false)
        .input(InteractionsInput.ofStep(history))
        .build();

Interaction interaction2 =
    client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();
System.out.println("Response 2: " + interaction2.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Step{
                interactions.NewStep(interactions.UserInputStep{
                    Content: []interactions.Content{
                        interactions.NewContent(interactions.TextContent{
                            Text: "Hello, I have 2 dogs in my house.",
                        }),
                    },
                }),
                interactions.NewStep(interactions.ModelOutputStep{
                    Content: []interactions.Content{
                        interactions.NewContent(interactions.TextContent{
                            Text: "That's great! Two dogs must keep your house lively.",
                        }),
                    },
                }),
                interactions.NewStep(interactions.UserInputStep{
                    Content: []interactions.Content{
                        interactions.NewContent(interactions.TextContent{
                            Text: "How many paws are in my house?",
                        }),
                    },
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
# Turn 1: Send request with store: false
RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "store": false,
    "input": [
      {
        "type": "user_input",
        "content": "I have 2 dogs in my house."
      }
    ]
  }')

# Extract the steps from response
MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')

# Reconstruct the full history for Turn 2 by combining:
# 1. First user input
# 2. Model response steps
# 3. Second user input
HISTORY=$(jq -n \
  --argjson first_input '[{"type": "user_input", "content": "I have 2 dogs in my house."}]' \
  --argjson model_steps "$MODEL_STEPS" \
  --argjson second_input '[{"type": "user_input", "content": "How many paws are in my house?"}]' \
  "'"'"'$first_input + $model_steps + $second_input'"'"'")

# Turn 2: Send the full history
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d "{
    \"model\": \"gemini-3.8-flash\",
    \"store\": false,
    \"input\": $HISTORY
  }"
```
{% /tab %}
{% /tabs %}

## Prompting tips {% id="prompting-tips" %}

Consult our [prompt engineering guide](/docs/prompting-strategies) for
suggestions on getting the most out of Gemini.

## What's next {% id="whats-next" %}

* Try [Gemini in Google AI Studio](https://aistudio.google.com).
* Experiment with
  [structured outputs](/docs/structured-output) for
  JSON-like responses.

* Explore Gemini's [image](/docs/image-understanding),
  [video](/docs/video-understanding),
  [audio](/docs/audio) and
  [document](/docs/document-processing) understanding
  capabilities.

* Learn about multimodal
  [file prompting strategies](/docs/files#prompt-guide).

# Image understanding
Source: https://aistudio.google.com/docs/image-understanding
Description: Get started building with Gemini's multimodal capabilities in the Gemini API

Gemini models are built to be multimodal from the ground up, unlocking a wide
range of image processing and computer vision tasks including but not limited to
image captioning, classification, and visual question answering without having
to train specialized ML models.

In addition to their general multimodal capabilities, Gemini models offer
**enhanced accuracy** for specific use cases like [object detection](/docs/image-understanding#object-detection) and [segmentation](/docs/image-understanding#segmentation), through additional
training.

## Passing images to Gemini {% id="image-input" %}

You can provide images as input to Gemini using several methods:

* [Passing image using URL](/docs/image-understanding#url-image): Ideal for publicly accessible images.
* [Passing inline image data](/docs/image-understanding#inline-image): For base64-encoded image data.
* [Uploading images using the File API](/docs/image-understanding#upload-image): Recommended for
    larger files or for reusing images across multiple requests.

### Passing image using URL {% id="url-image" %}

You can upload an image using the [Files API](/docs/files) and pass it
in the request:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="path/to/organ.jpg")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Caption this image."},
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const uploadedFile = await client.files.upload({
    file: "path/to/organ.jpg",
    config: { mimeType: "image/jpeg" }
});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        {type: "text", text: "Caption this image."},
        {
            type: "image",
            uri: uploadedFile.uri,
            mime_type: uploadedFile.mimeType
        }
    ]
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File uploadedFile =
    client.files.upload(
        new java.io.File("path/to/organ.jpg"),
        UploadFileConfig.builder().mimeType("image/jpeg").build());

Content textContent = TextContent.builder().text("Caption this image.").build();
Content imageContent =
    ImageContent.builder()
        .uri(uploadedFile.uri().orElse(""))
        .mimeType(ImageContentMimeType.of(uploadedFile.mimeType().orElse("image/jpeg")))
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/organ.jpg", &genai.UploadFileConfig{
        MIMEType: "image/jpeg",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Caption this image.",
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:      genai.Ptr(uploadedFile.URI),
                    MimeType: interactions.ImageContentMimeType(uploadedFile.MIMEType).ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Caption this image."},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

### Passing inline image data {% id="inline-image" %}

You can provide image data as base64-encoded strings:

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

with open('path/to/small-sample.jpg', 'rb') as f:
    image_bytes = f.read()

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Caption this image."},
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/jpeg"
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const client = new GoogleGenAI({});
const base64ImageFile = fs.readFileSync("path/to/small-sample.jpg", {
  encoding: "base64",
});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        {type: "text", text: "Caption this image."},
        {
            type: "image",
            data: base64ImageFile,
            mime_type: "image/jpeg"
        }
    ]
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

byte[] imageBytes = Files.readAllBytes(Paths.get("path/to/small-sample.jpg"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);

Client client = new Client();

Content textContent = TextContent.builder().text("Caption this image.").build();
Content imageContent =
    ImageContent.builder()
        .data(base64Image)
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("path/to/small-sample.jpg")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Caption this image.",
                }),
                interactions.NewContent(interactions.ImageContent{
                    Data:     genai.Ptr(base64Image),
                    MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
IMG_PATH="/path/to/your/image1.jpg"

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Caption this image."},
      {
        "type": "image",
        "data": "'"$(base64 $B64FLAGS $IMG_PATH)"'",
        "mime_type": "image/jpeg"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
Inline image data limits your total request size (text prompts, system
instructions, and inline bytes) to 20MB. For larger requests,
[upload image files](/docs/image-understanding#upload-image) using the File API.
{% /callout %}

### Uploading images using the File API {% id="upload-image" %}

For large files or to be able to use the same image file repeatedly, use the
Files API. See the [Files API guide](/docs/files).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

my_file = client.files.upload(file="path/to/sample.jpg")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Caption this image."},
        {
            "type": "image",
            "uri": my_file.uri,
            "mime_type": my_file.mime_type
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const myfile = await client.files.upload({
    file: "path/to/sample.jpg",
    config: { mimeType: "image/jpeg" },
});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        {type: "text", text: "Caption this image."},
        {
            type: "image",
            uri: myfile.uri,
            mime_type: myfile.mimeType
        }
    ]
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File myFile =
    client.files.upload(
        new java.io.File("path/to/sample.jpg"),
        UploadFileConfig.builder().mimeType("image/jpeg").build());

Content textContent = TextContent.builder().text("Caption this image.").build();
Content imageContent =
    ImageContent.builder()
        .uri(myFile.uri().orElse(""))
        .mimeType(ImageContentMimeType.of(myFile.mimeType().orElse("image/jpeg")))
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    myFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.jpg", &genai.UploadFileConfig{
        MIMEType: "image/jpeg",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Caption this image.",
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:      genai.Ptr(myFile.URI),
                    MimeType: interactions.ImageContentMimeType(myFile.MIMEType).ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Caption this image."},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

## Prompting with multiple images {% id="multiple-images" %}

You can provide multiple images in a single prompt by including multiple image
objects in the `input` array:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "What is different between these two images?"},
        {
            "type": "image",
            "uri": "https://example.com/image1.jpg",
            "mime_type": "image/jpeg"
        },
        {
            "type": "image",
            "uri": "https://example.com/image2.jpg",
            "mime_type": "image/jpeg"
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        {type: "text", text: "What is different between these two images?"},
        {
            type: "image",
            uri: "https://example.com/image1.jpg",
            mime_type: "image/jpeg"
        },
        {
            type: "image",
            uri: "https://example.com/image2.jpg",
            mime_type: "image/jpeg"
        }
    ]
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent =
    TextContent.builder().text("What is different between these two images?").build();
Content image1 =
    ImageContent.builder()
        .uri("https://example.com/image1.jpg")
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();
Content image2 =
    ImageContent.builder()
        .uri("https://example.com/image2.jpg")
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

List<Content> contents = Arrays.asList(textContent, image1, image2);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "What is different between these two images?",
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:      genai.Ptr("https://example.com/image1.jpg"),
                    MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:      genai.Ptr("https://example.com/image2.jpg"),
                    MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "What is different between these two images?"},
      {
        "type": "image",
        "uri": "https://example.com/image1.jpg",
        "mime_type": "image/jpeg"
      },
      {
        "type": "image",
        "uri": "https://example.com/image2.jpg",
        "mime_type": "image/jpeg"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

## Object detection {% id="object-detection" %}

Models are trained to detect objects in an
image and get their bounding box coordinates. The coordinates, relative to image
dimensions, scale to \[0, 1000\]. You need to descale these coordinates based on
your original image size.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from pydantic import BaseModel, Field
from typing import List
import json

client = genai.Client()
prompt = "Detect the all of the prominent items in the image. The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000."

class BoundingBox(BaseModel):
    box_2d: List[int] = Field(description="The 2D bounding box of the item as [ymin, xmin, ymax, xmax] normalized to 0-1000.")
    mask: List[List[int]] = Field(description="The segmentation mask of the item as a polygon of [x,y] coordinates, normalized to 0-1000.")
    label: str = Field(description="A descriptive label for the item.")

class BoundingBoxes(BaseModel):
    boxes: List[BoundingBox]

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": prompt},
        {
            "type": "image",
            "uri": "https://example.com/image.png",
            "mime_type": "image/png"
        }
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": BoundingBoxes.model_json_schema()
    }
)

bounding_boxes = BoundingBoxes.model_validate_json(interaction.output_text)
print(bounding_boxes)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const client = new GoogleGenAI({});
const prompt = "Detect the all of the prominent items in the image. The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000.";

const boundingBoxesSchema = z.object({
  boxes: z.array(z.object({
    box_2d: z.array(z.number()),
    mask: z.array(z.array(z.number())),
    label: z.string()
  }))
});

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: prompt },
    {
      type: "image",
      uri: "https://example.com/image.png",
      mime_type: "image/png"
    }
  ],
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: z.toJSONSchema(boundingBoxesSchema)
  },
});

const result = boundingBoxesSchema.parse(JSON.parse(interaction.output_text));
console.log(result);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;
import java.util.Map;

Client client = new Client();
String prompt =
    "Detect the all of the prominent items in the image. The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000.";

Map<String, Object> boundingBoxSchema =
    Map.of(
        "type", "object",
        "properties",
            Map.of(
                "box_2d",
                    Map.of(
                        "type", "array",
                        "items", Map.of("type", "integer"),
                        "description",
                            "The 2D bounding box of the item as [ymin, xmin, ymax, xmax] normalized to 0-1000."),
                "mask",
                    Map.of(
                        "type", "array",
                        "items", Map.of("type", "array", "items", Map.of("type", "integer")),
                        "description",
                            "The segmentation mask of the item as a polygon of [x,y] coordinates, normalized to 0-1000."),
                "label",
                    Map.of("type", "string", "description", "A descriptive label for the item.")),
        "required", List.of("box_2d", "mask", "label"));

Map<String, Object> boundingBoxesSchema =
    Map.of(
        "type", "object",
        "properties", Map.of("boxes", Map.of("type", "array", "items", boundingBoxSchema)),
        "required", List.of("boxes"));

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            TextResponseFormat.builder()
                .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
                .schema(boundingBoxesSchema)
                .build()));

Content textContent = TextContent.builder().text(prompt).build();
Content imageContent =
    ImageContent.builder()
        .uri("https://example.com/image.png")
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(Arrays.asList(textContent, imageContent)))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Detect the all of the prominent items in the image. The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000."

    boundingBoxSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "box_2d": map[string]any{
                "type":        "array",
                "items":       map[string]any{"type": "integer"},
                "description": "The 2D bounding box of the item as [ymin, xmin, ymax, xmax] normalized to 0-1000.",
            },
            "mask": map[string]any{
                "type":        "array",
                "items":       map[string]any{"type": "array", "items": map[string]any{"type": "integer"}},
                "description": "The segmentation mask of the item as a polygon of [x,y] coordinates, normalized to 0-1000.",
            },
            "label": map[string]any{
                "type":        "string",
                "description": "A descriptive label for the item.",
            },
        },
        "required": []string{"box_2d", "mask", "label"},
    }

    boundingBoxesSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "boxes": map[string]any{
                "type":  "array",
                "items": boundingBoxSchema,
            },
        },
        "required": []string{"boxes"},
    }

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.TextResponseFormat{
            MimeType: interactions.TextResponseFormatMimeTypeApplicationJSON.ToPointer(),
            Schema:   boundingBoxesSchema,
        }),
    )

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:      genai.Ptr("https://example.com/image.png"),
                    MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
                }),
            }),
            ResponseFormat: genai.Ptr(format),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Detect the all of the prominent items in the image. The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000."},
      {
        "type": "image",
        "uri": "https://example.com/image.png",
        "mime_type": "image/png"
      }
    ],
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
          "boxes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "box_2d": { "type": "array", "items": { "type": "integer" } },
                "mask": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } } },
                "label": { "type": "string" }
              },
              "required": ["box_2d", "mask", "label"]
            }
          }
        },
        "required": ["boxes"]
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
The model also supports generating bounding boxes based on custom
instructions, such as: "Show bounding boxes of all green objects in this image".
{% /callout %}

For more examples, check following notebooks in the [Gemini Cookbook][cookbook]:

[cookbook]: https://github.com/google-gemini/cookbook

## Segmentation {% id="segmentation" %}

Starting with Gemini 2.5, models not only detect items but also segment them
and provide their contour masks.

The model predicts a JSON list, where each item represents a segmentation mask.
Each item has a bounding box ("`box_2d`") in the format `[y0, x0, y1, x1]` with
normalized coordinates between 0 and 1000, a label ("`label`") that identifies
the object, and finally the segmentation mask inside the bounding box, as base64
encoded png that is a probability map with values between 0 and 255.

{% callout type="note" %}
For better results, disable [thinking](/docs/thinking)
by setting the thinking level to "minimal".
{% /callout %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from pydantic import BaseModel, Field
from typing import List
import json

client = genai.Client()

prompt = """
Give the segmentation masks for the wooden and glass items.
Output a JSON list of segmentation masks where each entry contains the 2D
bounding box in the key "box_2d", the segmentation mask in key "mask", and
the text label in the key "label". Use descriptive labels.
"""

class BoundingBox(BaseModel):
    box_2d: List[int] = Field(description="The 2D bounding box of the item as [ymin, xmin, ymax, xmax] normalized to 0-1000.")
    mask: List[List[int]] = Field(description="The segmentation mask of the item as a polygon of [x,y] coordinates, normalized to 0-1000.")
    label: str = Field(description="A descriptive label for the item.")

class BoundingBoxes(BaseModel):
    boxes: List[BoundingBox]

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": prompt},
        {
            "type": "image",
            "uri": "https://example.com/image.png",
            "mime_type": "image/png"
        }
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": BoundingBoxes.model_json_schema()
    },
    generation_config={
        "thinking_level": "minimal"
    }
)

items = BoundingBoxes.model_validate_json(interaction.output_text)
print("Segmentation results:", items)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const client = new GoogleGenAI({});
const prompt = `
Give the segmentation masks for the wooden and glass items.
Output a JSON list of segmentation masks where each entry contains the 2D
bounding box in the key "box_2d", the segmentation mask in key "mask", and
the text label in the key "label". Use descriptive labels.
`;

const boundingBoxesSchema = z.object({
  boxes: z.array(z.object({
    box_2d: z.array(z.number()),
    mask: z.array(z.array(z.number())),
    label: z.string()
  }))
});

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: prompt },
    {
      type: "image",
      uri: "https://example.com/image.png",
      mime_type: "image/png"
    }
  ],
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: z.toJSONSchema(boundingBoxesSchema)
  },
  generation_config: {
    thinking_level: "minimal"
  }
});

const result = boundingBoxesSchema.parse(JSON.parse(interaction.output_text));
console.log(result);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.interactions.ThinkingLevel;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;
import java.util.Map;

Client client = new Client();

String prompt =
    "Give the segmentation masks for the wooden and glass items.\n"
        + "Output a JSON list of segmentation masks where each entry contains the 2D\n"
        + "bounding box in the key \"box_2d\", the segmentation mask in key \"mask\", and\n"
        + "the text label in the key \"label\". Use descriptive labels.";

Map<String, Object> boundingBoxSchema =
    Map.of(
        "type", "object",
        "properties",
            Map.of(
                "box_2d",
                    Map.of(
                        "type", "array",
                        "items", Map.of("type", "integer"),
                        "description",
                            "The 2D bounding box of the item as [ymin, xmin, ymax, xmax] normalized to 0-1000."),
                "mask",
                    Map.of(
                        "type", "array",
                        "items", Map.of("type", "array", "items", Map.of("type", "integer")),
                        "description",
                            "The segmentation mask of the item as a polygon of [x,y] coordinates, normalized to 0-1000."),
                "label",
                    Map.of("type", "string", "description", "A descriptive label for the item.")),
        "required", List.of("box_2d", "mask", "label"));

Map<String, Object> boundingBoxesSchema =
    Map.of(
        "type", "object",
        "properties", Map.of("boxes", Map.of("type", "array", "items", boundingBoxSchema)),
        "required", List.of("boxes"));

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            TextResponseFormat.builder()
                .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
                .schema(boundingBoxesSchema)
                .build()));

Content textContent = TextContent.builder().text(prompt).build();
Content imageContent =
    ImageContent.builder()
        .uri("https://example.com/image.png")
        .mimeType(ImageContentMimeType.IMAGE_PNG)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(Arrays.asList(textContent, imageContent)))
        .responseFormat(format)
        .generationConfig(GenerationConfig.builder().thinkingLevel(ThinkingLevel.MINIMAL).build())
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Segmentation results: " + interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Give the segmentation masks for the wooden and glass items.\n" +
        "Output a JSON list of segmentation masks where each entry contains the 2D\n" +
        "bounding box in the key \"box_2d\", the segmentation mask in key \"mask\", and\n" +
        "the text label in the key \"label\". Use descriptive labels."

    boundingBoxSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "box_2d": map[string]any{
                "type":        "array",
                "items":       map[string]any{"type": "integer"},
                "description": "The 2D bounding box of the item as [ymin, xmin, ymax, xmax] normalized to 0-1000.",
            },
            "mask": map[string]any{
                "type":        "array",
                "items":       map[string]any{"type": "array", "items": map[string]any{"type": "integer"}},
                "description": "The segmentation mask of the item as a polygon of [x,y] coordinates, normalized to 0-1000.",
            },
            "label": map[string]any{
                "type":        "string",
                "description": "A descriptive label for the item.",
            },
        },
        "required": []string{"box_2d", "mask", "label"},
    }

    boundingBoxesSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "boxes": map[string]any{
                "type":  "array",
                "items": boundingBoxSchema,
            },
        },
        "required": []string{"boxes"},
    }

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.TextResponseFormat{
            MimeType: interactions.TextResponseFormatMimeTypeApplicationJSON.ToPointer(),
            Schema:   boundingBoxesSchema,
        }),
    )

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:      genai.Ptr("https://example.com/image.png"),
                    MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
                }),
            }),
            ResponseFormat: genai.Ptr(format),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel: interactions.ThinkingLevelMinimal.ToPointer(),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println("Segmentation results: " + *res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Give the segmentation masks for the wooden and glass items.\nOutput a JSON list of segmentation masks where each entry contains the 2D\nbounding box in the key \"box_2d\", the segmentation mask in key \"mask\", and\nthe text label in the key \"label\". Use descriptive labels."},
      {
        "type": "image",
        "uri": "https://example.com/image.png",
        "mime_type": "image/png"
      }
    ],
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
          "boxes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "box_2d": { "type": "array", "items": { "type": "integer" } },
                "mask": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } } },
                "label": { "type": "string" }
              },
              "required": ["box_2d", "mask", "label"]
            }
          }
        },
        "required": ["boxes"]
      }
    },
    "generation_config": {
      "thinking_level": "minimal"
    }
  }'
```
{% /tab %}
{% /tabs %}

{% image
  src="/googledevai/static/gemini-api/docs/images/segmentation.jpg"
  alt="A table with cupcakes, with the wooden and glass objects highlighted"
  caption="An example segmentation output with objects and segmentation masks"
  variant="screenshot"
/%}

## Supported image formats {% id="supported-formats" %}

Gemini supports the following image format MIME types:

* PNG - `image/png`
* JPEG - `image/jpeg`
* WEBP - `image/webp`
* HEIC - `image/heic`
* HEIF - `image/heif`

To learn about other file input methods, see the
[File input methods](/docs/file-input-methods) guide.

## Capabilities {% id="capabilities" %}

All Gemini model versions are multimodal and can be utilized in a wide range
of image processing and computer vision tasks including but not limited to
image captioning, visual question and answering, image classification,
object detection and segmentation.

Gemini can reduce the need to use specialized ML models depending on your
quality and performance requirements.

The latest model versions are specifically trained improve accuracy of
specialized tasks in addition to generic capabilities, like enhanced
[object detection](/docs/image-understanding#object-detection) and [segmentation](/docs/image-understanding#segmentation).

## Limitations and key technical information {% id="technical-details-image" %}

### File limit {% id="file-limit" %}

Gemini models support a maximum of 3,600 image files per request.

### Token calculation {% id="token-calculation" %}

* 258 tokens if both dimensions <= 384 pixels.
    Larger images are tiled into 768x768 pixel tiles, each costing 258 tokens.

A rough formula for calculating the number of tiles is as follows:

* Calculate the crop unit size which is roughly: `floor(min(width, height)` / 1.5).
* Divide each dimension by the crop unit size and multiply together to get the
  number of tiles.

For example, for an image of dimensions 960x540 would have a crop unit size
of 360. Divide each dimension by 360 and the number of tile is 3 * 2 = 6.

### Media resolution {% id="media-resolution" %}

Gemini 3 introduces granular control over multimodal vision processing with the
`media_resolution` parameter. The `media_resolution` parameter determines the
**maximum number of tokens allocated per input image or video frame.**
Higher resolutions improve the model's ability to
read fine text or identify small details, but increase token usage and latency.

## Tips and best practices {% id="tips-best-practices" %}

* Verify that images are correctly rotated.
* Use clear, non-blurry images.
* When using a single image with text, place the text prompt *before* the image in the `input` array.

## What's next {% id="whats-next" %}

This guide shows you how to upload image files and generate text outputs
from image inputs. To learn more, see the following resources:

* [Files API](/docs/files): Learn more about uploading and managing files for use with Gemini.
* [System instructions][system-instructions]:
    System instructions let you steer the behavior of the model based on your
    specific needs and use cases.

* [File prompting strategies](/docs/files#prompt-guide): The
    Gemini API supports prompting with text, image, audio, and video data, also
    known as multimodal prompting.

* [Safety guidance](/docs/safety-guidance): Sometimes generative
    AI models produce unexpected outputs, such as outputs that are inaccurate,
    biased, or offensive. Post-processing and human evaluation are essential to
    limit the risk of harm from such outputs.

[system-instructions]: /docs/text-generation#system-instructions

# Video generation in the Gemini API
Source: https://aistudio.google.com/docs/video
Description: Generate and edit videos in the Gemini API using Gemini Omni Flash.

Use [Gemini Omni Flash](/docs/omni) as your model for video generation and conversational
video editing in the Gemini API. It provides superior video coherence,
multi-input reasoning (supporting text, images, audio, and video inputs
simultaneously), character consistency, factual accuracy, and multi-turn
conversational editing (e.g., element replacement or perspective changes).

The Veo 3.1 Preview in the Gemini API has been shut down.

## Gemini Omni Flash {% id="omni-flash" %}

Gemini Omni Flash is a fast, multimodal model for video generation and
conversational video editing. It excels at quickly turning text prompts and
images into short videos, and lets you refine results across multiple turns
using the Interactions API.

[Get started with Gemini Omni Flash →](/docs/omni)

## Veo 3.1 {% id="veo" %}

{% callout type="warning" %} Veo 3.1 Preview (`veo-3.1-generate-preview`,
`veo-3.1-fast-generate-preview`, and `veo-3.1-lite-generate-preview`) in the
Gemini API was [shut down](/docs/deprecations) on **October 22, 2026**; migrate
to [Gemini Omni Flash](/docs/omni) (`gemini-omni-1.1-flash`) or the GA models
available through the
[Gemini Enterprise Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate)
to avoid service interruptions. {% /callout %}

## Video understanding {% id="understanding" %}

If you need to ingest and analyze existing video content rather than generate
new video, see the [Video understanding guide](/docs/video-understanding).

# Video understanding
Source: https://aistudio.google.com/docs/video-understanding
Description: Get started building with Gemini's multimodal capabilities in the Gemini API

To learn about video generation, see the [Gemini Omni Flash](/docs/omni) guide.

Gemini models can process videos, enabling many frontier developer use cases
that would have historically required domain specific models.
Some of Gemini's vision capabilities include the ability to: describe, segment,
and extract information from videos, answer questions about video content, and
refer to specific timestamps within a video.

You can provide videos as input to Gemini in the following ways:

| Input method | Max size | Recommended use case |
| :--- | :--- | :--- |
| [File API](/docs/video-understanding#upload-video) | 20GB (paid) / 2GB (free) | Large files (100MB+), long videos (10min+), reusable files. |
| [Cloud Storage Registration](/docs/file-input-methods#registration) | 2GB (per file, no storage limits) | Large files (100MB+), long videos (10min+), persistent, reusable files. |
| [Inline Data](/docs/video-understanding#inline-video) | < 100MB | Small files (<100MB), short duration (<1min), one-off inputs. |
| [YouTube URLs](/docs/video-understanding#youtube) | N/A | Public YouTube videos. |

{% callout type="note" %}
The [File API](/docs/video-understanding#upload-video) is recommended for most use cases,
especially for files larger than 100MB or when you want to reuse the file
across multiple requests.
{% /callout %}

To learn about other file input methods, such as using external URLs or files
stored in Google Cloud, see the
[File input methods](/docs/file-input-methods) guide.

### Upload a video file {% id="upload-video" %}

The following code downloads a sample video, uploads it using the [Files API](/docs/files),
waits for it to be processed, and then uses the uploaded file reference to
summarize the video.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import time

client = genai.Client()

myfile = client.files.upload(file="path/to/sample.mp4")

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
    ]
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/sample.mp4",
    config: { mimeType: "video/mp4" },
  });

  let getFile = await ai.files.get({ name: myfile.name || '' });
  while (getFile.state === 'PROCESSING') {
      getFile = await ai.files.get({ name: myfile.name || '' });
      console.log(`current file status: ${getFile.state}`);
      console.log('File is still processing, retrying in 5 seconds');

      await new Promise((resolve) => {
          setTimeout(resolve, 5000);
      });
  }
  if (getFile.state === 'FAILED') {
      throw new Error('File processing failed.');
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "video", uri: myfile.uri, mime_type: myfile.mimeType },
      { type: "text", text: "Summarize this video. Then create a quiz with an answer key based on the information in this video." }
    ],
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.FileState;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File myfile =
    client.files.upload(
        "path/to/sample.mp4", UploadFileConfig.builder().mimeType("video/mp4").build());

while (!myfile.state().isPresent()
    || myfile.state().get().knownEnum() != FileState.Known.ACTIVE) {
  System.out.println("Processing video...");
  Thread.sleep(5000);
  myfile = client.files.get(myfile.name().get(), null);
}

Content videoContent =
    VideoContent.builder()
        .uri(myfile.uri().get())
        .mimeType(VideoContentMimeType.of(myfile.mimeType().get()))
        .build();
Content textContent =
    TextContent.builder()
        .text(
            "Summarize this video. Then create a quiz with an answer key based on the information in this video.")
        .build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    myfile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    })
    if err != nil {
        log.Fatal(err)
    }

    for myfile.State != genai.FileStateActive {
        fmt.Println("Processing video...")
        time.Sleep(5 * time.Second)
        myfile, err = client.Files.Get(ctx, myfile.Name, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI:      genai.Ptr(myfile.URI),
            MimeType: interactions.VideoContentMimeType(myfile.MIMEType).ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}

  ```shell
VIDEO_PATH="path/to/sample.mp4"
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

tmp_header_file=upload-header.tmp

echo "Starting file upload..."
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D ${tmp_header_file} \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

echo "Uploading video data..."
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq -r ".file.uri" file_info.json)
file_name=$(jq -r ".file.name" file_info.json)
echo file_uri=$file_uri

echo "File uploaded successfully. File URI: ${file_uri}"

echo "Waiting for file to be processed..."
while true; do
  curl -s "https://generativelanguage.googleapis.com/v1beta/${file_name}" \
    -H "x-goog-api-key: $GEMINI_API_KEY" > file_status.json
  state=$(jq -r ".state" file_status.json)
  echo "Current state: $state"
  if [ "$state" == "ACTIVE" ]; then
    break
  elif [ "$state" == "FAILED" ]; then
    echo "File processing failed."
    exit 1
  fi
  sleep 5
done

echo "Generating content from video..."
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.8-flash",
      "input": [
        {"type": "video", "uri": "'${file_uri}'", "mime_type": "'${MIME_TYPE}'"},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
      ]
    }' 2> /dev/null > response.json

jq ".steps[].content[0].text" response.json
  ```
{% /tab %}
{% /tabs %}

To optimize token efficiency and performance, consider using
[Agentic video processing](/docs/video-understanding#agentic-video-understanding).

Always use the Files API when the total request size (including the file, text
prompt, system instructions, etc.) is larger than 20 MB, the video duration is
significant, or if you intend to use the same video in multiple prompts.
The File API accepts video file formats directly.

To learn more about working with media files, see
[Files API](/docs/files).

### Pass video data inline {% id="inline-video" %}

Instead of uploading a video file using the File API, you can pass smaller
videos directly in the request. This is suitable for
shorter videos under 20MB total request size.

Here's an example of providing inline video data:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import base64

video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "data": base64.b64encode(video_bytes).decode('utf-8'),
            "mime_type": "video/mp4"
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const base64VideoFile = fs.readFileSync("path/to/small-sample.mp4", {
  encoding: "base64",
});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

String videoFileName = "/path/to/your/video.mp4";
byte[] videoBytes = Files.readAllBytes(Paths.get(videoFileName));
String base64Video = Base64.getEncoder().encodeToString(videoBytes);

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .data(base64Video)
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    videoFileName := "/path/to/your/video.mp4"
    videoBytes, err := os.ReadFile(videoFileName)
    if err != nil {
        log.Fatal(err)
    }
    base64Video := base64.StdEncoding.EncodeToString(videoBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            Data:     genai.Ptr(base64Video),
            MimeType: interactions.VideoContentMimeTypeVideoMp4.ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}

{% callout type="note" %}
  Note: If you get an `Argument list too long` error, the base64 encoding of
  your file might be too long for the curl command line. Use the File API
  method instead for larger files.
{% /callout %}

  ```shell
VIDEO_PATH=/path/to/your/video.mp4

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

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.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'",
          "mime_type": "video/mp4"
        }
      ]
    }' 2> /dev/null
  ```
{% /tab %}
{% /tabs %}

### Pass YouTube URLs {% id="youtube" %}

{% callout type="note" %}
Preview: The YouTube URL feature is in preview and is available at no charge.
Pricing and rate limits are likely to change.
{% /callout %}

You can pass YouTube URLs directly to Gemini API as part of your request as
follows:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      uri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    }
  ],
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .uri("https://www.youtube.com/watch?v=9hE5-98ZeCg")
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            URI: genai.Ptr("https://www.youtube.com/watch?v=9hE5-98ZeCg"),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}

  ```shell
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.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
      ]
    }' 2> /dev/null
  ```
{% /tab %}
{% /tabs %}

**Limitations:**

* For the free tier, you can't upload more than 8 hours of YouTube video per day.
* For the paid tier, there is no limit based on video length.
* For models prior to Gemini 2.5, you can upload only 1 video per request. For Gemini 2.5 and later models, you can upload a maximum of 10 videos per request.
* You can only upload public videos (not private or unlisted videos).

## Agentic video understanding {% id="agentic-video-understanding" %}

By default, video inputs use static processing (extracting frames at 1 FPS) across all models, including Gemini 4.
Gemini 4 Argon, 3.8 Flash, 3.6 Flash, and 3.5 Flash Lite models also support
**agentic video understanding**, an opt-in mode where the model dynamically explores the video
timeline, selectively inspecting transcripts and adaptively adjusting frame
rates and resolution on the fly based on the prompt.

| **Mode** | **Description** | **Supported models** |
| --- | --- | --- |
| **Static** (default) | Extracts frames at a fixed rate (1 FPS) and places them into context in a single pass. Default for all Gemini models, including Gemini 4. | All Gemini models |
| **Agentic** | The model dynamically navigates the video timeline, loading only the content it needs based on the prompt. Up to 88% more token-efficient and ~7% higher quality on long-form content. | Gemini 4 Argon, 3.8 Flash, 3.6 Flash, 3.5 Flash Lite |
### Choose a processing mode {% id="when-to-use" %}

Select the processing mode that matches your video length and query type:

- **Static (default):** Best for short clips (under 5 minutes), broad full-video summaries where the entire recording is relevant, latency-sensitive queries, or frame-level precision across the entire clip. On short videos or broad prompts that require inspecting most of the video, static processing avoids the additional thinking tokens (`total_thought_tokens`) and tool-call round-trips (`total_tool_use_tokens`) incurred by timeline navigation.
- **Agentic:** Best for long-form videos (over 5–10 minutes), needle-in-a-haystack retrieval, or queries targeting specific moments or topics. The model inspects transcripts first and loads only relevant visual segments on demand, reducing video input token usage by up to 88% without filling the context window.

{% callout type="note" %}
For long videos or complex prompts where agentic processing takes more time,
use streaming or [background execution](/docs/background-execution).
This keeps the connection active, surfaces intermediate
reasoning steps, and avoids connection or authentication timeouts.
{% /callout %}

### Set the processing mode {% id="set-processing-mode" %}

To use agentic video understanding, set `"processing": "agentic"` on the video
part in the `input` array.

Agentic video processing can take longer on long videos because the model
performs multiple inspection passes to navigate the timeline. To avoid losing
progress if a network connection drops, the following example uses
the `background` parameter to run the task asynchronously on the server. You can also
run requests synchronously without background execution by omitting the `background`
parameter, which works well for shorter videos.

For details on polling, retrieving results, and managing background tasks, see
the [background execution](/docs/background-execution) guide.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

# Upload a long video
video_file = client.files.upload(file="path/to/lecture.mp4")

while video_file.state.name == "PROCESSING":
    time.sleep(2)
    video_file = client.files.get(name=video_file.name)

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"
        },
        {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

// Upload a long video
let videoFile = await ai.files.upload({
  file: "path/to/lecture.mp4",
  config: { mimeType: "video/mp4" }
});

while (videoFile.state === "PROCESSING") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  videoFile = await ai.files.get({ name: videoFile.name || '' });
}

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: "agentic"
    },
    { type: "text", text: "What are the three main arguments presented?" }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
# 1. Start the interaction in the background
interaction=$(curl -s -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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
To verify that agentic processing was used, inspect `interaction.steps`. The
presence of `processing_call` and `processing_result` indicates that
the model dynamically navigated the video.
{% /callout %}

### Response steps {% id="response-steps" %}

Agentic processing adds two new step types to the `steps` array:

* `processing_call`: the model requested a video segment or audio transcript, identified by `id`.
* `processing_result`: the result of that load, linked by `call_id`.

These appear interleaved with `thought` steps (when summaries are enabled) and precede the final `model_output` step. They can be used to show a progress trace in your UI but do not require a response.

The following example shows the response payload with interleaved processing steps:

```json
{
  "steps": [
    {
      "type": "thought",
      "signature": "sig_thought_1",
      "summary": [
        {
          "type": "text",
          "text": "Inspecting transcript for key discussion topics..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_01",
      "signature": "sig_call_01"
    },
    {
      "type": "processing_result",
      "call_id": "call_01",
      "signature": "sig_result_01"
    },
    {
      "type": "thought",
      "signature": "sig_thought_2",
      "summary": [
        {
          "type": "text",
          "text": "Loading visual frames to verify slide content..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_02",
      "signature": "sig_call_02"
    },
    {
      "type": "processing_result",
      "call_id": "call_02",
      "signature": "sig_result_02"
    },
    {
      "type": "thought",
      "signature": "sig_thought_3",
      "summary": [
        {
          "type": "text",
          "text": "Synthesizing answer from gathered evidence..."
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The three main arguments presented in the lecture are..."
        }
      ]
    }
  ]
}
```

### Mix processing modes across videos {% id="mix-processing-modes" %}

Set different processing modes for each video in the same request:

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

lecture = client.files.upload(file="path/to/long-lecture.mp4")
experiment = client.files.upload(file="path/to/short-experiment.mp4")

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": lecture.uri,
            "mime_type": lecture.mime_type,
            "processing": "agentic"  # Use agentic video understanding
        },
        {
            "type": "video",
            "uri": experiment.uri,
            "mime_type": experiment.mime_type,
            "processing": "static"  # Use static processing
        },
        {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const lecture = await ai.files.upload({
  file: "path/to/long-lecture.mp4",
  config: { mimeType: "video/mp4" }
});
const experiment = await ai.files.upload({
  file: "path/to/short-experiment.mp4",
  config: { mimeType: "video/mp4" }
});

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: lecture.uri,
      mime_type: lecture.mimeType,
      processing: "agentic" // Use agentic video understanding
    },
    {
      type: "video",
      uri: experiment.uri,
      mime_type: experiment.mimeType,
      processing: "static" // Use static processing
    },
    { type: "text", text: "Compare the lecture content with the experiment results." }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
# 1. Start the interaction in the background
interaction=$(curl -s -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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${lecture_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {
        "type": "video",
        "uri": "'${experiment_uri}'",
        "mime_type": "video/mp4",
        "processing": "static"
      },
      {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'
```
{% /tab %}
{% /tabs %}

### Multi-turn video conversations {% id="multi-turn-video" %}

Video context is preserved across turns in a conversation. When using agentic
processing:

- **Stateful mode** (using `previous_interaction_id`): The server retains the
  video context. No additional handling is needed.
- **Stateless mode** (using `step_list`): In stateless mode, the response
  includes `processing_call` and `processing_result` steps that encode the
  video context. You must include all steps from the response in your next
  request's `step_list` to preserve video context. While omitting them does not
  currently return an API error, the video context is lost, significantly
  reducing response quality on follow-up questions. Note that returned steps
  sent in subsequent requests contribute to input token counts.

## Refer to timestamps in the content {% id="refer-timestamps" %}

You can ask questions about specific points in time within the video using
timestamps of the form `MM:SS`.

{% tabs %}
{% tab label="Python" %}
```python
prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?"
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?";
```
{% /tab %}
{% tab label="Java" %}
```java
String prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?";
```
{% /tab %}
{% tab label="Go" %}
```go
prompt := "What are the examples given at 00:05 and 00:10 supposed to show us?"
```
{% /tab %}

{% tab label="REST" %}
```shell
PROMPT="What are the examples given at 00:05 and 00:10 supposed to show us?"
```
{% /tab %}
{% /tabs %}

## Extract detailed insights from video {% id="transcribe-video" %}

Gemini models offer powerful capabilities for understanding video content by
processing information from both the **audio and visual** streams. This lets you
extract a rich set of details, including generating descriptions of what is
happening in a video and answering questions about its content.

For visual descriptions, the model samples the video at a rate of **1 frame
per second** (FPS). This default sampling rate works well for most content, but
note that it may miss details in videos with rapid motion or quick scene
changes.

{% tabs %}
{% tab label="Python" %}
```python
prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";
```
{% /tab %}
{% tab label="Java" %}
```java
String prompt =
    "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";
```
{% /tab %}
{% tab label="Go" %}
```go
prompt := "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."
```
{% /tab %}

{% tab label="REST" %}
```shell
PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."
```
{% /tab %}
{% /tabs %}

## Customize video processing {% id="customize-video-processing" %}

You can customize video processing in the Gemini API by setting clipping
intervals or providing custom frame rate sampling. These customization options
are only supported when processing the video in `"static"` mode.

### Set clipping intervals {% id="clipping-intervals" %}

You can clip video by specifying `start_offset` and `end_offset` in the `processing` configuration object.

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "start_offset": 1200,
                "end_offset": 1500,
            },
        },
        {"type": "text", "text": "Summarize this section of the video."},
    ],
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        start_offset: 1200,
        end_offset: 1500,
      },
    },
    { type: "text", text: "Summarize this section of the video." },
  ],
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "start_offset": 1200,
          "end_offset": 1500
        }
      },
      {"type": "text", "text": "Summarize this section of the video."}
    ]
  }' 2> /dev/null
```
{% /tab %}
{% /tabs %}

### Set a custom frame rate {% id="custom-frame-rate" %}

You can set custom frame rate sampling by passing an `fps` argument in the `processing` configuration object.

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "fps": 0.5,  # Sample 1 frame every 2 seconds
            },
        },
        {"type": "text", "text": "Describe the scene changes in this video."},
    ],
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        fps: 0.5, // Sample 1 frame every 2 seconds
      },
    },
    { type: "text", text: "Describe the scene changes in this video." },
  ],
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
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.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "fps": 0.5
        }
      },
      {"type": "text", "text": "Describe the scene changes in this video."}
    ]
  }' 2> /dev/null
```
{% /tab %}
{% /tabs %}

## Supported video formats {% id="supported-formats" %}

Gemini supports the following video format MIME types:

* `video/mp4`
* `video/mpeg`
* `video/mov`
* `video/avi`
* `video/x-flv`
* `video/mpg`
* `video/webm`
* `video/wmv`
* `video/3gpp`

## Technical details about videos {% id="technical-details-video" %}

- **Supported models and context**: All Gemini models can process video data.
    - Models with a 1M context window can process videos up to 3 hours long by
      default (at low media resolution), or up to 1 hour long at high media
      resolution.
- **Processing modes**: Gemini 4 Argon, 3.8 Flash, 3.6 Flash, 3.5 Flash Lite,
  and later models support two video processing modes:
    - **Static**: Frames are extracted at 1 FPS and placed into context (default
      for all models). Audio is processed at 1Kbps (single channel).
      Timestamps are added every second. Best for short clips or when every frame
      matters (such as frame-by-frame inspection). Note that fast action sequences
      might lose detail due to the 1 FPS sampling rate.
    - **Agentic**: The model dynamically navigates the video, loading
      transcript and/or frames and/or audio on demand. This uses up to 88%
      fewer tokens for long-form content, though navigation may increase Time to First Token (TTFT) and total token usage on short clips (<5 minutes) or broad queries due to
      internal reasoning and tool round-trips. Best
      for long-form videos and targeted queries to optimize token costs and response quality.
      Supported on Gemini 4 Argon, 3.8 Flash, 3.6 Flash, and 3.5 Flash Lite.
      See [Agentic video understanding](/docs/video-understanding#agentic-video-understanding) for details.
- **Token calculation (static mode)**: Each second of video is tokenized as
  follows:
    - Individual frames (sampled at 1 FPS):
        - If `media_resolution` is set to low, frames are tokenized at 66
          tokens per frame.
        - Otherwise, frames are tokenized at 258 tokens per frame.
    - Audio: 32 tokens per second.
    - Metadata is also included.
    - Total: Approximately 100 tokens per second of video at default (low) media
      resolution, or approximately 300 tokens per second of video at high media
      resolution.
- **Token calculation (agentic mode)**: Token usage varies based on content
  complexity and the model's navigation strategy. Navigation reasoning tokens
  generated during video exploration are accounted as **thought tokens**
  (`total_thought_tokens`), while frames, audio, and transcript loaded on
  demand are accounted as tool use tokens (`total_tool_use_tokens`).
  Agentic processing typically uses up to 88% fewer total tokens than static
  processing for long-form content because the model loads only the transcript
  and/or frames and/or audio it needs to answer the prompt (see the
  [tokens guide](/docs/tokens#video)).
- **Media resolution**: Gemini 3 introduces granular control over multimodal
  vision processing with the `media_resolution` parameter. The
  `media_resolution` parameter determines the **maximum number of tokens
  allocated per input image or video frame.** Higher resolutions improve the
  model's ability to read fine text or identify small details, but increase
  token usage and latency. The `media_resolution` and `processing` parameters
  are independent: you can set both on the same video input.

For more details on token calculations, see the
[tokens](/docs/tokens) guide.

- **Timestamp format**: When referring to specific moments in a video within
  your prompt, use the `MM:SS` format (e.g., `01:15` for 1 minute and 15
  seconds).
- **Prompt placement**: If combining text and a single video, place the text prompt
  *after* the video part in the `input` array.
- **Timeouts for long requests**: For videos that require extended
  processing time or complex multi-step reasoning, use streaming or
  [background execution](/docs/background-execution).
  Synchronous, non-streaming requests that experience backend retries under
  high demand can exceed connection or authentication token validity windows,
  which may surface as unexpected `401 Unauthorized` or timeout errors.
  Streaming keeps the connection active and surfaces intermediate reasoning
  and tool call progress.

## What's next {% id="whats-next" %}

- [Media resolution](/docs/media-resolution): Control the
  resolution of video frames to balance quality and token usage.
- [Tokens](/docs/tokens): Understand how video content is tokenized
  in both static and agentic processing modes.
- [Background execution](/docs/background-execution): Run long-running
  video understanding tasks asynchronously to avoid connection timeouts.
- [System instructions](/docs/text-generation#system-instructions):
  System instructions let you steer the behavior of the model based on your
  specific needs and use cases.
- [Files API](/docs/files): Learn more about uploading and managing
  files for use with Gemini.
- [File prompting strategies](/docs/files#prompt-guide): The Gemini
  API supports prompting with text, image, audio, and video data, also known as
  multimodal prompting.
- [Safety guidance](/docs/safety-guidance): Sometimes generative AI
  models produce unexpected outputs, such as outputs that are inaccurate,
  biased, or offensive. Post-processing and human evaluation are essential to
  limit the risk of harm from such outputs.

# Document understanding
Source: https://aistudio.google.com/docs/document-processing
Description: Learn how to use the Gemini API to process documents like PDFs

Gemini models can process documents in PDF format, using native
vision to understand entire document contexts. This goes beyond
just text extraction, allowing Gemini to:

* Analyze and interpret content, including text, images, diagrams,
    charts, and tables, even in long documents up to 1000 pages.

* Extract information into [structured output](/docs/structured-output) formats.

* Summarize and answer questions based on both the visual and textual elements
    in a document.

* Transcribe document content (e.g. to HTML), preserving layouts and
    formatting, for use in downstream applications.

You can also pass non-PDF documents in the same way but Gemini will see them
as normal text which will eliminate context like charts or formatting.

## Passing PDF data inline {% id="inline_data" %}

You can pass PDF data inline in the request. This is best
suited for smaller documents or temporary processing where you don't need to
reference the file in subsequent requests. We recommend using the
[Files API](/docs/document-processing#large-pdfs)
for larger documents that you need to refer to in multi-turn interactions to
improve request latency and reduce bandwidth usage.

The following example shows you how to pass PDF data inline:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import base64

client = genai.Client()

with open('path/to/document.pdf', 'rb') as f:
    pdf_bytes = f.read()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "document",
            "data": base64.b64encode(pdf_bytes).decode('utf-8'),
            "mime_type": "application/pdf"
        },
        {"type": "text", "text": "Summarize this document"}
    ]
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

async function main() {
    const pdfData = fs.readFileSync("path/to/document.pdf", {
        encoding: "base64"
    });

    const interaction = await ai.interactions.create({
        model: "gemini-3.8-flash",
        input: [
            { type: "text", text: "Summarize this document" },
            {
                type: "document",
                data: pdfData,
                mime_type: "application/pdf"
            }
        ]
    });
    console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] pdfBytes = Files.readAllBytes(Paths.get("path/to/document.pdf"));
String base64Pdf = Base64.getEncoder().encodeToString(pdfBytes);

Content docContent =
    DocumentContent.builder()
        .data(base64Pdf)
        .mimeType(DocumentContentMimeType.APPLICATION_PDF)
        .build();
Content textContent = TextContent.builder().text("Summarize this document").build();

List<Content> contents = Arrays.asList(docContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    pdfBytes, err := os.ReadFile("path/to/document.pdf")
    if err != nil {
        log.Fatal(err)
    }
    base64Pdf := base64.StdEncoding.EncodeToString(pdfBytes)

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    Data:     genai.Ptr(base64Pdf),
                    MimeType: interactions.DocumentContentMimeTypeApplicationPdf.ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: "Summarize this document",
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}

  ```shell
PDF_PATH="path/to/document.pdf"

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "document",
        "data": "'$(base64 $B64FLAGS $PDF_PATH)'",
        "mime_type": "application/pdf"
      },
      {"type": "text", "text": "Summarize this document"}
    ]
  }'
  ```
{% /tab %}
{% /tabs %}

You can also upload a local PDF file for processing:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="file.pdf")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "document", "uri": uploaded_file.uri, "mime_type": uploaded_file.mime_type},
        {"type": "text", "text": "Summarize this document"}
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
    const uploadedFile = await ai.files.upload({
        file: "file.pdf",
        config: { mimeType: "application/pdf" }
    });

    const interaction = await ai.interactions.create({
        model: "gemini-3.8-flash",
        input: [
            { type: "text", text: "Summarize this document" },
            {
                type: "document",
                uri: uploadedFile.uri,
                mime_type: uploadedFile.mimeType
            }
        ]
    });
    console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File uploadedFile =
    client.files.upload(
        new java.io.File("file.pdf"),
        UploadFileConfig.builder().mimeType("application/pdf").build());

Content docContent =
    DocumentContent.builder()
        .uri(uploadedFile.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(uploadedFile.mimeType().orElse("application/pdf")))
        .build();
Content textContent = TextContent.builder().text("Summarize this document").build();

List<Content> contents = Arrays.asList(docContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "file.pdf", &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(uploadedFile.URI),
                    MimeType: interactions.DocumentContentMimeType(uploadedFile.MIMEType).ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: "Summarize this document",
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% /tabs %}

## Uploading PDFs using the Files API {% id="large-pdfs" %}

We recommend you use Files API for larger files or when you intend to reuse a
document across multiple requests. This improves request latency and reduces
bandwidth usage by decoupling the file upload from the model requests.

{% callout type="note" %}
The Files API is available at no cost in all regions where the Gemini API
is available. Uploaded files are stored for 48 hours.
{% /callout %}

### Large PDFs from URLs {% id="large-pdfs-urls" %}

Use the File API to simplify uploading and processing large PDF files from URLs:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://arxiv.org/pdf/2312.11805"

doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

sample_doc = client.files.upload(
  file=doc_io,
  config=dict(
    mime_type='application/pdf')
)

prompt = "Summarize this document"

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "document", "uri": sample_doc.uri, "mime_type": sample_doc.mime_type},
        {"type": "text", "text": prompt}
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {

    const pdfBuffer = await fetch("https://arxiv.org/pdf/2312.11805")
        .then((response) => response.arrayBuffer());

    const fileBlob = new Blob([pdfBuffer], { type: 'application/pdf' });

    const file = await ai.files.upload({
        file: fileBlob,
        config: {
            displayName: 'A17_FlightPlan.pdf',
        },
    });

    let getFile = await ai.files.get({ name: file.name || "" });
    while (getFile.state === 'PROCESSING') {
        getFile = await ai.files.get({ name: file.name || "" });
        console.log(`current file status: ${getFile.state}`);
        console.log('File is still processing, retrying in 5 seconds');

        await new Promise((resolve) => {
            setTimeout(resolve, 5000);
        });
    }
    if (file.state === 'FAILED') {
        throw new Error('File processing failed.');
    }

    const interaction = await ai.interactions.create({
        model: 'gemini-3.8-flash',
        input: [
            { type: "document", uri: file.uri, mime_type: file.mimeType },
            { type: "text", text: "Summarize this document" }
        ],
    });

    console.log(interaction.output_text);

}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

String longContextPdfPath = "https://arxiv.org/pdf/2312.11805";
HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder().uri(URI.create(longContextPdfPath)).build();
byte[] pdfBytes = httpClient.send(request, HttpResponse.BodyHandlers.ofByteArray()).body();

File sampleDoc =
    client.files.upload(
        pdfBytes, UploadFileConfig.builder().mimeType("application/pdf").build());

String prompt = "Summarize this document";

Content docContent =
    DocumentContent.builder()
        .uri(sampleDoc.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(sampleDoc.mimeType().orElse("application/pdf")))
        .build();
Content textContent = TextContent.builder().text(prompt).build();

List<Content> contents = Arrays.asList(docContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "bytes"
    "context"
    "fmt"
    "io"
    "log"
    "net/http"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    longContextPdfPath := "https://arxiv.org/pdf/2312.11805"
    resp, err := http.Get(longContextPdfPath)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    pdfBytes, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }

    sampleDoc, err := client.Files.Upload(ctx, bytes.NewReader(pdfBytes), &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Summarize this document"

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(sampleDoc.URI),
                    MimeType: interactions.DocumentContentMimeType(sampleDoc.MIMEType).ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}

  ```shell
PDF_PATH="https://arxiv.org/pdf/2312.11805"
DISPLAY_NAME="Gemini_paper"
PROMPT="Summarize this document"

wget -O "${DISPLAY_NAME}.pdf" "${PDF_PATH}"

MIME_TYPE=$(file -b --mime-type "${DISPLAY_NAME}.pdf")
NUM_BYTES=$(wc -c < "${DISPLAY_NAME}.pdf")

echo "MIME_TYPE: ${MIME_TYPE}"
echo "NUM_BYTES: ${NUM_BYTES}"

tmp_header_file=upload-header.tmp

curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${DISPLAY_NAME}.pdf" 2> /dev/null > file_info.json

file_uri=$(jq -r ".file.uri" file_info.json)
echo "file_uri: ${file_uri}"

cat << EOF > payload.json
{
  "model": "gemini-3.8-flash",
  "input": [
    {"type": "text", "text": "${PROMPT}"},
    {"type": "document", "uri": "${file_uri}", "mime_type": "application/pdf"}
  ]
}
EOF

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -X POST \
    -d @payload.json 2> /dev/null > response.json

cat response.json
echo

jq ".steps[-1].content[0].text" response.json

rm "${DISPLAY_NAME}.pdf"
rm payload.json
  ```
{% /tab %}
{% /tabs %}

### Large PDFs stored locally {% id="large-pdfs-local" %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import pathlib

client = genai.Client()

file_path = pathlib.Path('large_file.pdf')
sample_file = client.files.upload(
    file=file_path,
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "document", "uri": sample_file.uri, "mime_type": sample_file.mime_type},
        {"type": "text", "text": "Summarize this document"}
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
    const file = await ai.files.upload({
        file: 'path-to-localfile.pdf',
        config: {
            displayName: 'A17_FlightPlan.pdf',
        },
    });

    let getFile = await ai.files.get({ name: file.name || "" });
    while (getFile.state === 'PROCESSING') {
        getFile = await ai.files.get({ name: file.name || "" });
        console.log(`current file status: ${getFile.state}`);
        console.log('File is still processing, retrying in 5 seconds');

        await new Promise((resolve) => {
            setTimeout(resolve, 5000);
        });
    }
    if (file.state === 'FAILED') {
        throw new Error('File processing failed.');
    }

    const interaction = await ai.interactions.create({
        model: 'gemini-3.8-flash',
        input: [
            { type: "document", uri: file.uri, mime_type: file.mimeType },
            { type: "text", text: "Summarize this document" }
        ],
    });

    console.log(interaction.output_text);

}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File sampleFile =
    client.files.upload(
        new java.io.File("large_file.pdf"),
        UploadFileConfig.builder().mimeType("application/pdf").build());

Content docContent =
    DocumentContent.builder()
        .uri(sampleFile.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(sampleFile.mimeType().orElse("application/pdf")))
        .build();
Content textContent = TextContent.builder().text("Summarize this document").build();

List<Content> contents = Arrays.asList(docContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    sampleFile, err := client.Files.UploadFromPath(ctx, "large_file.pdf", &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(sampleFile.URI),
                    MimeType: interactions.DocumentContentMimeType(sampleFile.MIMEType).ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: "Summarize this document",
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}

  ```shell
PDF_PATH="path/to/large_file.pdf"
NUM_BYTES=$(wc -c < "${PDF_PATH}")
DISPLAY_NAME=TEXT
tmp_header_file=upload-header.tmp

curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: application/pdf" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${PDF_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -X POST \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "document", "uri": '$file_uri', "mime_type": "application/pdf"},
        {"type": "text", "text": "Can you add a few more lines to this poem?"}
      ]
    }' 2> /dev/null > response.json

cat response.json
echo

jq ".steps[-1].content[0].text" response.json
  ```
{% /tab %}
{% /tabs %}

You can verify the API successfully stored the uploaded file and get its
metadata by calling [`files.get`](https://ai.google.dev/api/rest/v1beta/files/get). Only the `name`
(and by extension, the `uri`) are unique.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import pathlib

client = genai.Client()

fpath = pathlib.Path('example.pdf')
fpath.write_text('hello')

file = client.files.upload(file='example.pdf')

file_info = client.files.get(name=file.name)
print(file_info.model_dump_json(indent=4))
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

Client client = new Client();

Path fpath = Paths.get("example.pdf");
Files.write(fpath, "hello".getBytes(StandardCharsets.UTF_8));

File file =
    client.files.upload(
        fpath.toFile(), UploadFileConfig.builder().mimeType("application/pdf").build());

File fileInfo = client.files.get(file.name().orElse(""), null);
System.out.println(fileInfo.toJson());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    if err := os.WriteFile("example.pdf", []byte("hello"), 0644); err != nil {
        log.Fatal(err)
    }

    file, err := client.Files.UploadFromPath(ctx, "example.pdf", &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    fileInfo, err := client.Files.Get(ctx, file.Name, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(fileInfo)
}
```
{% /tab %}

{% tab label="REST" %}
```shell
name=$(jq -r ".file.name" file_info.json)
curl "https://generativelanguage.googleapis.com/v1beta/$name?key=$GEMINI_API_KEY" > file_info.json
name=$(jq -r ".name" file_info.json)
echo name=$name
file_uri=$(jq -r ".uri" file_info.json)
echo file_uri=$file_uri
```
{% /tab %}
{% /tabs %}

## Passing multiple PDFs {% id="prompt-multiple" %}

The Gemini API is capable of processing multiple PDF documents (up to 1000
pages) in a single request, as long as the combined size of the documents and
the text prompt stays within the model's context window.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import io
import httpx

client = genai.Client()

doc_url_1 = "https://arxiv.org/pdf/2312.11805"
doc_url_2 = "https://arxiv.org/pdf/2403.05530"

doc_data_1 = io.BytesIO(httpx.get(doc_url_1).content)
doc_data_2 = io.BytesIO(httpx.get(doc_url_2).content)

sample_pdf_1 = client.files.upload(
  file=doc_data_1,
  config=dict(mime_type='application/pdf')
)
sample_pdf_2 = client.files.upload(
  file=doc_data_2,
  config=dict(mime_type='application/pdf')
)

prompt = "What is the difference between each of the main benchmarks between these two papers? Output these in a table."

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "document", "uri": sample_pdf_1.uri, "mime_type": sample_pdf_1.mime_type},
        {"type": "document", "uri": sample_pdf_2.uri, "mime_type": sample_pdf_2.mime_type},
        {"type": "text", "text": prompt}
    ]
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function uploadRemotePDF(url = '', displayName = '') {
    const pdfBuffer = await fetch(url)
        .then((response) => response.arrayBuffer());

    const fileBlob = new Blob([pdfBuffer], { type: 'application/pdf' });

    const file = await ai.files.upload({
        file: fileBlob,
        config: {
            displayName: displayName,
        },
    });

    let getFile = await ai.files.get({ name: file.name || "" });
    while (getFile.state === 'PROCESSING') {
        getFile = await ai.files.get({ name: file.name || "" });
        console.log(`current file status: ${getFile.state}`);
        console.log('File is still processing, retrying in 5 seconds');

        await new Promise((resolve) => {
            setTimeout(resolve, 5000);
        });
    }
    if (file.state === 'FAILED') {
        throw new Error('File processing failed.');
    }

    return file;
}

async function main() {
    const file1 = await uploadRemotePDF("https://arxiv.org/pdf/2312.11805", "PDF 1");
    const file2 = await uploadRemotePDF("https://arxiv.org/pdf/2403.05530", "PDF 2");

    const interaction = await ai.interactions.create({
        model: 'gemini-3.8-flash',
        input: [
            { type: "document", uri: file1.uri, mime_type: file1.mimeType },
            { type: "document", uri: file2.uri, mime_type: file2.mimeType },
            { type: "text", text: "What is the difference between each of the main benchmarks between these two papers? Output these in a table." }
        ],
    });

    console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

String docUrl1 = "https://arxiv.org/pdf/2312.11805";
String docUrl2 = "https://arxiv.org/pdf/2403.05530";

HttpClient httpClient = HttpClient.newHttpClient();
byte[] docData1 =
    httpClient
        .send(HttpRequest.newBuilder().uri(URI.create(docUrl1)).build(), HttpResponse.BodyHandlers.ofByteArray())
        .body();
byte[] docData2 =
    httpClient
        .send(HttpRequest.newBuilder().uri(URI.create(docUrl2)).build(), HttpResponse.BodyHandlers.ofByteArray())
        .body();

File samplePdf1 =
    client.files.upload(
        docData1, UploadFileConfig.builder().mimeType("application/pdf").build());
File samplePdf2 =
    client.files.upload(
        docData2, UploadFileConfig.builder().mimeType("application/pdf").build());

String prompt =
    "What is the difference between each of the main benchmarks between these two papers? Output these in a table.";

Content doc1Content =
    DocumentContent.builder()
        .uri(samplePdf1.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(samplePdf1.mimeType().orElse("application/pdf")))
        .build();
Content doc2Content =
    DocumentContent.builder()
        .uri(samplePdf2.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(samplePdf2.mimeType().orElse("application/pdf")))
        .build();
Content textContent = TextContent.builder().text(prompt).build();

List<Content> contents = Arrays.asList(doc1Content, doc2Content, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "bytes"
    "context"
    "fmt"
    "io"
    "log"
    "net/http"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    docURL1 := "https://arxiv.org/pdf/2312.11805"
    docURL2 := "https://arxiv.org/pdf/2403.05530"

    resp1, err := http.Get(docURL1)
    if err != nil {
        log.Fatal(err)
    }
    defer resp1.Body.Close()
    docData1, err := io.ReadAll(resp1.Body)
    if err != nil {
        log.Fatal(err)
    }

    resp2, err := http.Get(docURL2)
    if err != nil {
        log.Fatal(err)
    }
    defer resp2.Body.Close()
    docData2, err := io.ReadAll(resp2.Body)
    if err != nil {
        log.Fatal(err)
    }

    samplePdf1, err := client.Files.Upload(ctx, bytes.NewReader(docData1), &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }
    samplePdf2, err := client.Files.Upload(ctx, bytes.NewReader(docData2), &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    prompt := "What is the difference between each of the main benchmarks between these two papers? Output these in a table."

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(samplePdf1.URI),
                    MimeType: interactions.DocumentContentMimeType(samplePdf1.MIMEType).ToPointer(),
                }),
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(samplePdf2.URI),
                    MimeType: interactions.DocumentContentMimeType(samplePdf2.MIMEType).ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}

  ```shell
DOC_URL_1="https://arxiv.org/pdf/2312.11805"
DOC_URL_2="https://arxiv.org/pdf/2403.05530"
DISPLAY_NAME_1="Gemini_paper"
DISPLAY_NAME_2="Gemini_1.5_paper"
PROMPT="What is the difference between each of the main benchmarks between these two papers? Output these in a table."

upload_pdf() {
  local doc_url="$1"
  local display_name="$2"

  echo "Downloading ${display_name} from ${doc_url}..." >&2
  wget -O "${display_name}.pdf" "${doc_url}" 2> /dev/null

  local MIME_TYPE=$(file -b --mime-type "${display_name}.pdf")
  local NUM_BYTES=$(wc -c < "${display_name}.pdf")

  echo "MIME_TYPE: ${MIME_TYPE}" >&2
  echo "NUM_BYTES: ${NUM_BYTES}" >&2

  local tmp_header_file="upload-header-${display_name}.tmp"

  curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GEMINI_API_KEY}" \
    -D "${tmp_header_file}" \
    -H "X-Goog-Upload-Protocol: resumable" \
    -H "X-Goog-Upload-Command: start" \
    -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
    -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
    -H "Content-Type: application/json" \
    -d "{'file': {'display_name': '${display_name}'}}" 2> /dev/null

  local upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
  rm "${tmp_header_file}"

  echo "Upload URL for ${display_name}: ${upload_url}" >&2

  curl "${upload_url}" \
    -H "Content-Length: ${NUM_BYTES}" \
    -H "X-Goog-Upload-Offset: 0" \
    -H "X-Goog-Upload-Command: upload, finalize" \
    --data-binary "@${display_name}.pdf" 2> /dev/null > "file_info_${display_name}.json"

  local file_uri=$(jq -r ".file.uri" "file_info_${display_name}.json")
  echo "file_uri for ${display_name}: ${file_uri}" >&2

  rm "${display_name}.pdf"

  echo "${file_uri}"
}

file_uri_1=$(upload_pdf "${DOC_URL_1}" "${DISPLAY_NAME_1}")

file_uri_2=$(upload_pdf "${DOC_URL_2}" "${DISPLAY_NAME_2}")

cat << EOF > payload_multi.json
{
  "model": "gemini-3.8-flash",
  "input": [
    {"type": "document", "uri": "${file_uri_1}", "mime_type": "application/pdf"},
    {"type": "document", "uri": "${file_uri_2}", "mime_type": "application/pdf"},
    {"type": "text", "text": "${PROMPT}"}
  ]
}
EOF

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -X POST \
    -d @payload_multi.json 2> /dev/null > response.json

cat response.json
echo

jq ".steps[-1].content[0].text" response.json

rm payload_multi.json
rm "file_info_${DISPLAY_NAME_1}.json"
rm "file_info_${DISPLAY_NAME_2}.json"
  ```
{% /tab %}
{% /tabs %}

## Technical details {% id="technical-details" %}

Gemini supports PDF files up to 50MB or 1000 pages. This limit applies
to both inline data and Files API uploads. Each document page is equivalent to
258 tokens.

While there are no specific limits to the number of pixels in a document besides
the model's [context window](/docs/long-context), larger pages are
scaled down to a maximum resolution of 3072 x 3072 while preserving their
original aspect ratio, while smaller pages are scaled up to 768 x 768 pixels.
There is no cost reduction for pages at lower sizes, other than bandwidth, or
performance improvement for pages at higher resolution.

### Gemini 3 models {% id="gemini-3-models" %}

Gemini 3 introduces granular control over multimodal vision processing with the
`media_resolution` parameter. You can now set the resolution to low, medium, or
high per individual media part. With this addition, the processing of PDF
documents has been updated:

1. **Native text inclusion:** Text natively embedded in the PDF is extracted
   and provided to the model.

2. **Billing & token reporting:**
   * You are **not charged** for tokens originating from the extracted
       **native text** in PDFs.

   * In the `usage_metadata` section of the API response, tokens generated
       from processing PDF pages (as images) are now counted under the `IMAGE`
       modality, not a separate `DOCUMENT` modality as in some earlier
       versions.

For more details about the media resolution parameter, see the
[Media resolution](/docs/media-resolution) guide.

### Document types {% id="document-types" %}

Technically, you can pass other MIME types for document understanding, like
TXT, Markdown, HTML, XML, etc. However, document vision ***only meaningfully
understands PDFs***. Other types will be extracted as pure text, and the model
won't be able to interpret what we see in the rendering of those files. Any
file-type specifics like charts, diagrams, HTML tags, Markdown formatting, etc.,
will be lost.

To learn about other file input methods, see the
[File input methods](/docs/file-input-methods) guide.

### Best practices {% id="best-practices" %}

For best results:

* Rotate pages to the correct orientation before uploading.
* Avoid blurry pages.
* If using a single page, place the text prompt after the page.

## What's next {% id="whats-next" %}

To learn more, see the following resources:

* [File prompting strategies](/docs/files#prompt-guide): The
  Gemini API supports prompting with text, image, audio, and video data, also
  known as multimodal prompting.

* [System instructions](/docs/text-generation#system-instructions):
  System instructions let you steer the behavior of the model based on your
  specific needs and use cases.

# Audio understanding
Source: https://aistudio.google.com/docs/audio
Description: Learn how to analyze audio input and generate text responses using the Gemini API.

Gemini can analyze audio input and generate text responses.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import base64

client = genai.Client()

uploaded_file = client.files.upload(file="path/to/sample.mp3")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this audio clip"},
        {
            "type": "audio",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const uploadedFile = await client.files.upload({
    file: "path/to/sample.mp3",
    config: { mimeType: "audio/mp3" }
});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        {type: "text", text: "Describe this audio clip"},
        {
            type: "audio",
            uri: uploadedFile.uri,
            mime_type: uploadedFile.mimeType
        }
    ]
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AudioContent;
import com.google.genai.gaos.models.interactions.AudioContentMimeType;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File uploadedFile =
    client.files.upload(
        "path/to/sample.mp3", UploadFileConfig.builder().mimeType("audio/mp3").build());

Content textContent = TextContent.builder().text("Describe this audio clip").build();
Content audioContent =
    AudioContent.builder()
        .uri(uploadedFile.uri().get())
        .mimeType(AudioContentMimeType.of(uploadedFile.mimeType().get()))
        .build();

List<Content> contents = Arrays.asList(textContent, audioContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", &genai.UploadFileConfig{
        MIMEType: "audio/mp3",
    })
    if err != nil {
        log.Fatal(err)
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Describe this audio clip",
        }),
        interactions.NewContent(interactions.AudioContent{
            URI:      genai.Ptr(uploadedFile.URI),
            MimeType: interactions.AudioContentMimeType(uploadedFile.MIMEType).ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Describe this audio clip"},
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

## Overview {% id="overview" %}

Gemini can analyze and understand audio input and generate text responses,
enabling use cases like:

* Describe, summarize, or answer questions about audio content
* Transcription and translation (speech to text)
* Speaker diarization (identifying different speakers)
* Emotion detection in speech and music
* Analyzing specific segments with timestamps

For real-time voice and video interactions, see the
[Live API](/docs/live-api).
For dedicated speech to text models with support for real-time transcription,
use the [Google Cloud Speech-to-Text API](https://cloud.google.com/speech-to-text).

## Transcribe speech to text {% id="speech-to-text" %}

This example shows how to transcribe, translate, and summarize speech with
timestamps, speaker diarization, and emotion detection using
[structured outputs](/docs/structured-output).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

YOUTUBE_URL = "https://www.youtube.com/watch?v=ku-N-eS1lgM"

prompt = """
  Process the audio file and generate a detailed transcription.

  Requirements:

  1. Identify distinct speakers (e.g., Speaker 1, Speaker 2).
  2. Provide accurate timestamps for each segment (Format: MM:SS).
  3. Detect the primary language of each segment.
  4. If not English, provide the English translation.
  5. Identify the primary emotion: Happy, Sad, Angry, or Neutral.
  6. Provide a brief summary at the beginning.
"""

response_schema = {
    "type": "object",
    "properties": {
        "summary": {"type": "string"},
        "segments": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "speaker": {"type": "string"},
                    "timestamp": {"type": "string"},
                    "content": {"type": "string"},
                    "language": {"type": "string"},
                    "emotion": {
                        "type": "string",
                        "enum": ["happy", "sad", "angry", "neutral"]
                    }
                },
                "required": ["speaker", "timestamp", "content", "emotion"]
            }
        }
    },
    "required": ["summary", "segments"]
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "video", "uri": YOUTUBE_URL, "mime_type": "video/mp4"},
        {"type": "text", "text": prompt}
    ],
    response_format=response_schema,
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const YOUTUBE_URL = "https://www.youtube.com/watch?v=ku-N-eS1lgM";

const prompt = `
  Process the audio file and generate a detailed transcription.

  Requirements:

  1. Identify distinct speakers (e.g., Speaker 1, Speaker 2).
  2. Provide accurate timestamps for each segment (Format: MM:SS).
  3. Detect the primary language of each segment.
  4. If not English, provide the English translation.
  5. Identify the primary emotion: Happy, Sad, Angry, or Neutral.
  6. Provide a brief summary at the beginning.
`;

const responseSchema = {
    type: "object",
    properties: {
        summary: { type: "string" },
        segments: {
            type: "array",
            items: {
                type: "object",
                properties: {
                    speaker: { type: "string" },
                    timestamp: { type: "string" },
                    content: { type: "string" },
                    language: { type: "string" },
                    emotion: {
                        type: "string",
                        enum: ["happy", "sad", "angry", "neutral"]
                    }
                },
                required: ["speaker", "timestamp", "content", "emotion"]
            }
        }
    },
    required: ["summary", "segments"]
};

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        { type: "video", uri: YOUTUBE_URL, mime_type: "video/mp4" },
        { type: "text", text: prompt }
    ],
    response_format: responseSchema,
});

console.log(JSON.parse(interaction.output_text || "{}"));
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

String youtubeUrl = "https://www.youtube.com/watch?v=ku-N-eS1lgM";

String prompt =
    "Process the audio file and generate a detailed transcription.\n\n"
        + "Requirements:\n"
        + "1. Identify distinct speakers (e.g., Speaker 1, Speaker 2).\n"
        + "2. Provide accurate timestamps for each segment (Format: MM:SS).\n"
        + "3. Detect the primary language of each segment.\n"
        + "4. If not English, provide the English translation.\n"
        + "5. Identify the primary emotion: Happy, Sad, Angry, or Neutral.\n"
        + "6. Provide a brief summary at the beginning.";

Map<String, Object> emotionProp = new HashMap<>();
emotionProp.put("type", "string");
emotionProp.put("enum", Arrays.asList("happy", "sad", "angry", "neutral"));

Map<String, Object> stringType = new HashMap<>();
stringType.put("type", "string");

Map<String, Object> segmentProps = new HashMap<>();
segmentProps.put("speaker", stringType);
segmentProps.put("timestamp", stringType);
segmentProps.put("content", stringType);
segmentProps.put("language", stringType);
segmentProps.put("emotion", emotionProp);

Map<String, Object> segmentItem = new HashMap<>();
segmentItem.put("type", "object");
segmentItem.put("properties", segmentProps);
segmentItem.put("required", Arrays.asList("speaker", "timestamp", "content", "emotion"));

Map<String, Object> segmentsProp = new HashMap<>();
segmentsProp.put("type", "array");
segmentsProp.put("items", segmentItem);

Map<String, Object> properties = new HashMap<>();
properties.put("summary", stringType);
properties.put("segments", segmentsProp);

Map<String, Object> responseSchema = new HashMap<>();
responseSchema.put("type", "object");
responseSchema.put("properties", properties);
responseSchema.put("required", Arrays.asList("summary", "segments"));

Content videoContent =
    VideoContent.builder()
        .uri(youtubeUrl)
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();
Content textContent = TextContent.builder().text(prompt).build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .responseFormat(
            CreateModelInteractionResponseFormat.of(ResponseFormat.of(responseSchema)))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    youtubeURL := "https://www.youtube.com/watch?v=ku-N-eS1lgM"

    prompt := "Process the audio file and generate a detailed transcription.\n\n" +
        "Requirements:\n" +
        "1. Identify distinct speakers (e.g., Speaker 1, Speaker 2).\n" +
        "2. Provide accurate timestamps for each segment (Format: MM:SS).\n" +
        "3. Detect the primary language of each segment.\n" +
        "4. If not English, provide the English translation.\n" +
        "5. Identify the primary emotion: Happy, Sad, Angry, or Neutral.\n" +
        "6. Provide a brief summary at the beginning."

    responseSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "summary": map[string]any{"type": "string"},
            "segments": map[string]any{
                "type": "array",
                "items": map[string]any{
                    "type": "object",
                    "properties": map[string]any{
                        "speaker":   map[string]any{"type": "string"},
                        "timestamp": map[string]any{"type": "string"},
                        "content":   map[string]any{"type": "string"},
                        "language":  map[string]any{"type": "string"},
                        "emotion": map[string]any{
                            "type": "string",
                            "enum": []string{"happy", "sad", "angry", "neutral"},
                        },
                    },
                    "required": []string{"speaker", "timestamp", "content", "emotion"},
                },
            },
        },
        "required": []string{"summary", "segments"},
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI:      genai.Ptr(youtubeURL),
            MimeType: interactions.VideoContentMimeTypeVideoMp4.ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: prompt,
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(responseSchema),
            )),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "https://www.youtube.com/watch?v=ku-N-eS1lgM",
        "mime_type": "video/mp4"
      },
      {
        "type": "text",
        "text": "Transcribe with speaker diarization and emotion detection."
      }
    ],
    "response_format": {
        "type": "object",
        "properties": {
          "summary": {"type": "string"},
          "segments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "speaker": {"type": "string"},
                "timestamp": {"type": "string"},
                "content": {"type": "string"},
                "emotion": {"type": "string", "enum": ["happy", "sad", "angry", "neutral"]}
              }
            }
          }
        }
      }
  }'
```
{% /tab %}
{% /tabs %}

![A multilingual audio transcription Gemini app](/googledevai/static/gemini-api/docs/images/audio_understanding_demo.gif)

## Input audio {% id="input-audio" %}

You can provide audio data in the following ways:

* [Upload an audio file](/docs/audio#upload-audio) before making a request.
* [Pass inline audio data](/docs/audio#inline-audio) with the request.

### Upload an audio file {% id="upload-audio" %}

Use the [Files API](/docs/files) for files larger than 20 MB.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="path/to/sample.mp3")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this audio clip"},
        {
            "type": "audio",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const uploadedFile = await client.files.upload({
    file: "path/to/sample.mp3",
    config: { mimeType: "audio/mp3" }
});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        {type: "text", text: "Describe this audio clip"},
        {
            type: "audio",
            uri: uploadedFile.uri,
            mime_type: uploadedFile.mimeType
        }
    ]
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
// Upload an audio file using the Files API (recommended for files > 20 MB)
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AudioContent;
import com.google.genai.gaos.models.interactions.AudioContentMimeType;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File uploadedFile =
    client.files.upload(
        "path/to/sample.mp3", UploadFileConfig.builder().mimeType("audio/mp3").build());

Content textContent = TextContent.builder().text("Describe this audio clip").build();
Content audioContent =
    AudioContent.builder()
        .uri(uploadedFile.uri().get())
        .mimeType(AudioContentMimeType.of(uploadedFile.mimeType().get()))
        .build();

List<Content> contents = Arrays.asList(textContent, audioContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
// Upload an audio file using the Files API (recommended for files > 20 MB)
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", &genai.UploadFileConfig{
        MIMEType: "audio/mp3",
    })
    if err != nil {
        log.Fatal(err)
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Describe this audio clip",
        }),
        interactions.NewContent(interactions.AudioContent{
            URI:      genai.Ptr(uploadedFile.URI),
            MimeType: interactions.AudioContentMimeType(uploadedFile.MIMEType).ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Describe this audio clip"},
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

### Pass audio data inline {% id="inline-audio" %}

For small audio files under 20MB total request size:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import base64

client = genai.Client()

with open('path/to/small-sample.mp3', 'rb') as f:
    audio_bytes = f.read()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this audio clip"},
        {
            "type": "audio",
            "data": base64.b64encode(audio_bytes).decode('utf-8'),
            "mime_type": "audio/mp3"
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const client = new GoogleGenAI({});

const audioData = fs.readFileSync("path/to/small-sample.mp3", {
    encoding: "base64"
});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        {type: "text", text: "Describe this audio clip"},
        {
            type: "audio",
            data: audioData,
            mime_type: "audio/mp3"
        }
    ]
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AudioContent;
import com.google.genai.gaos.models.interactions.AudioContentMimeType;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] audioBytes = Files.readAllBytes(Paths.get("path/to/small-sample.mp3"));
String base64Audio = Base64.getEncoder().encodeToString(audioBytes);

Content textContent = TextContent.builder().text("Describe this audio clip").build();
Content audioContent =
    AudioContent.builder()
        .data(base64Audio)
        .mimeType(AudioContentMimeType.AUDIO_MP3)
        .build();

List<Content> contents = Arrays.asList(textContent, audioContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioBytes, err := os.ReadFile("path/to/small-sample.mp3")
    if err != nil {
        log.Fatal(err)
    }
    base64Audio := base64.StdEncoding.EncodeToString(audioBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Describe this audio clip",
        }),
        interactions.NewContent(interactions.AudioContent{
            Data:     genai.Ptr(base64Audio),
            MimeType: interactions.AudioContentMimeTypeAudioMp3.ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
AUDIO_PATH="path/to/sample.mp3"

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Describe this audio clip"},
      {
        "type": "audio",
        "data": "'$(base64 $B64FLAGS $AUDIO_PATH)'",
        "mime_type": "audio/mp3"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

Notes on inline audio data:

* Maximum request size is 20 MB total (including prompts and all files)
* For reuse, [upload the file](/docs/audio#upload-audio) instead

## Get a transcript {% id="transcript" %}

To get a transcript, ask for it in the prompt:

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Generate a transcript of the speech."},
        {
            "type": "audio",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        { type: "text", text: "Generate a transcript of the speech." },
        {
            type: "audio",
            uri: uploadedFile.uri,
            mime_type: uploadedFile.mimeType
        }
    ]
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AudioContent;
import com.google.genai.gaos.models.interactions.AudioContentMimeType;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File uploadedFile =
    client.files.upload(
        "path/to/sample.mp3", UploadFileConfig.builder().mimeType("audio/mp3").build());

Content textContent = TextContent.builder().text("Generate a transcript of the speech.").build();
Content audioContent =
    AudioContent.builder()
        .uri(uploadedFile.uri().get())
        .mimeType(AudioContentMimeType.of(uploadedFile.mimeType().get()))
        .build();

List<Content> contents = Arrays.asList(textContent, audioContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", &genai.UploadFileConfig{
        MIMEType: "audio/mp3",
    })
    if err != nil {
        log.Fatal(err)
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Generate a transcript of the speech.",
        }),
        interactions.NewContent(interactions.AudioContent{
            URI:      genai.Ptr(uploadedFile.URI),
            MimeType: interactions.AudioContentMimeType(uploadedFile.MIMEType).ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% /tabs %}

## Refer to timestamps {% id="timestamps" %}

Use `MM:SS` format to reference specific sections:

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Provide a transcript from 02:30 to 03:29."},
        {
            "type": "audio",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        }
    ]
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        { type: "text", text: "Provide a transcript from 02:30 to 03:29." },
        { type: "audio", uri: uploadedFile.uri, mime_type: "audio/mp3" }
    ]
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AudioContent;
import com.google.genai.gaos.models.interactions.AudioContentMimeType;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File uploadedFile =
    client.files.upload(
        "path/to/sample.mp3", UploadFileConfig.builder().mimeType("audio/mp3").build());

Content textContent =
    TextContent.builder().text("Provide a transcript from 02:30 to 03:29.").build();
Content audioContent =
    AudioContent.builder()
        .uri(uploadedFile.uri().get())
        .mimeType(AudioContentMimeType.of(uploadedFile.mimeType().get()))
        .build();

List<Content> contents = Arrays.asList(textContent, audioContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", &genai.UploadFileConfig{
        MIMEType: "audio/mp3",
    })
    if err != nil {
        log.Fatal(err)
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Provide a transcript from 02:30 to 03:29.",
        }),
        interactions.NewContent(interactions.AudioContent{
            URI:      genai.Ptr(uploadedFile.URI),
            MimeType: interactions.AudioContentMimeType(uploadedFile.MIMEType).ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% /tabs %}

## Count tokens {% id="count-tokens" %}

Count tokens in an audio file:

{% tabs %}
{% tab label="Python" %}
```python
response = client.models.count_tokens(
    model="gemini-3.8-flash",
    contents=[uploaded_file]
)
print(response)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const response = await client.models.countTokens({
    model: "gemini-3.8-flash",
    contents: [
        { fileData: { fileUri: uploadedFile.uri, mimeType: uploadedFile.mimeType } }
    ]
});
console.log(response.totalTokens);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.CountTokensResponse;
import com.google.genai.types.File;
import com.google.genai.types.Part;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;

Client client = new Client();

File uploadedFile =
    client.files.upload(
        "path/to/sample.mp3", UploadFileConfig.builder().mimeType("audio/mp3").build());

CountTokensResponse response =
    client.models.countTokens(
        "gemini-3.8-flash",
        Arrays.asList(
            Content.fromParts(
                Part.fromUri(uploadedFile.uri().get(), uploadedFile.mimeType().get()))),
        null);

System.out.println(response);
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", &genai.UploadFileConfig{
        MIMEType: "audio/mp3",
    })
    if err != nil {
        log.Fatal(err)
    }

    response, err := client.Models.CountTokens(
        ctx,
        "gemini-3.8-flash",
        []*genai.Content{
            genai.NewContentFromURI(uploadedFile.URI, uploadedFile.MIMEType, genai.RoleUser),
        },
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(response.TotalTokens)
}
```
{% /tab %}

{% /tabs %}

## Supported audio formats {% id="supported-formats" %}

Gemini supports the following audio format MIME types:

* WAV - `audio/wav`
* MP3 - `audio/mp3`
* AIFF - `audio/aiff`
* AAC - `audio/aac`
* OGG - `audio/ogg`
* FLAC - `audio/flac`
* MPEG - `audio/mpeg`
* M4A - `audio/m4a`
* L16 - `audio/l16`
* Opus - `audio/opus`
* ALAW - `audio/alaw`
* MULAW - `audio/mulaw`
* WebM - `audio/webm`

For the complete list of supported MIME types and parameter schemas, see the [Interactions API reference](https://ai.google.dev/api/interactions-api#Resource:Content).

## Technical details about audio {% id="technical-details" %}

* **Tokens**: 32 tokens per second of audio (1 minute = 1,920 tokens)
* **Non-speech**: Gemini understands non-speech sounds (birdsong, sirens, etc.)
* **Max length**: 9.5 hours of audio per prompt
* **Resolution**: Downsampled to 16 Kbps
* **Channels**: Multi-channel audio combined to single channel

## What's next {% id="whats-next" %}

* [Files API](/docs/files): Upload and manage audio files
* [System instructions](/docs/text-generation#system-instructions):
  Customize model behavior

* [Structured output](/docs/structured-output):
  Get transcription results in JSON format

# Gemini thinking
Source: https://aistudio.google.com/docs/thinking
Description: Use thinking capabilities with the Gemini API

[Gemini models](/docs/models) use a
"thinking process" that significantly improves their reasoning and multi-step
planning abilities, making them highly effective for complex tasks such as
coding, advanced mathematics, and data analysis.

When you use a thinking model, Gemini reasons internally before responding. The
Interactions API surfaces this reasoning via `thought` steps, dedicated steps
that appear chronologically alongside function calls, user inputs or model
outputs in the `steps` array.

Every thought step contains two fields:

| Field | Required | Description |
|---|---|---|
| `signature` | ✅ Yes | An encrypted representation of the model's internal reasoning state. Always present, even when the model performs minimal reasoning. |
| `summary` | ❌ No | An array of content (text and/or images) summarizing the reasoning. May be empty depending on the [`thinking_summaries`](https://ai.google.dev/api/interactions-api) config, whether the model performed enough reasoning, or the content type (for example, image latents may not have text summaries). |

{% callout type="note" %}
The Interactions API handles thoughts and signatures differently than the
`generateContent` API:

- In the `generateContent` API, there are no dedicated thought blocks. Because
  of this, signatures are metadata that can be attached to any part, such as
  living inside `functionCall` parts or the final part of a response.
- In the Interactions API, thoughts are a first-class representation as
  dedicated `thought` steps. Because of this signatures are limited exclusively
  to two known locations, `thought` steps, or built-in tool steps (like
  `google_search_call`/ `google_search_result`). They never appear on user
  inputs, model outputs, or standard function calls.
{% /callout %}

## Interactions with thinking {% id="interactions-with-thinking" %}

Initiating an interaction with a thinking model is similar to any other interaction request. Specify one of the [models with thinking support](/docs/thinking#thinking-levels) in the `model` field:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain the concept of Occam's Razor and provide a simple, everyday example."
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain the concept of Occam's Razor and provide a simple, everyday example."
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Explain the concept of Occam's Razor and provide a simple, everyday example."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Explain the concept of Occam's Razor and provide a simple, everyday example."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain the concept of Occam'\''s Razor and provide a simple example."
  }'
```
{% /tab %}
{% /tabs %}

## Thought summaries {% id="summaries" %}

Thought summaries provide insights into the model's internal reasoning process.
By default, only the final output is returned. You can enable thought summaries
with `thinking_summaries`:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the sum of the first 50 prime numbers?",
    generation_config={
        "thinking_summaries": "auto"
    }
)

for step in interaction.steps:
    if step.type == "thought":
        print("Thought summary:")
        if step.summary:
            for content_block in step.summary:
                if content_block.type == "text":
                    print(content_block.text)
        print()
    elif step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print("Answer:")
                print(content_block.text)
                print()
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the sum of the first 50 prime numbers?",
    generation_config: {
        thinking_summaries: "auto"
    }
});

for (const step of interaction.steps) {
    if (step.type === "thought") {
        console.log("Thought summary:");
        if (step.summary) {
            for (const contentBlock of step.summary) {
                if (contentBlock.type === "text") console.log(contentBlock.text);
            }
        }
    } else if (step.type === "model_output") {
        for (const contentBlock of step.content || []) {
            if (contentBlock.type === "text") {
                console.log("Answer:");
                console.log(contentBlock.text);
            }
        }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.interactions.ThoughtStep;
import com.google.genai.gaos.models.interactions.ThoughtSummaryContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Collections;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("What is the sum of the first 50 prime numbers?"))
        .generationConfig(
            GenerationConfig.builder().thinkingSummaries(ThinkingSummaries.AUTO).build())
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

for (Step step : interaction.steps().orElse(Collections.emptyList())) {
  if (step instanceof ThoughtStep thoughtStep) {
    System.out.println("Thought summary:");
    for (ThoughtSummaryContent contentBlock : thoughtStep.summary().orElse(Collections.emptyList())) {
      if (contentBlock instanceof TextContent textContent) {
        System.out.println(textContent.text().orElse(""));
      }
    }
    System.out.println();
  } else if (step instanceof ModelOutputStep outputStep) {
    for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {
      if (contentBlock instanceof TextContent textContent) {
        System.out.println("Answer:");
        System.out.println(textContent.text().orElse(""));
        System.out.println();
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Provide a list of 3 famous physicists and their key contributions"),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel: interactions.ThinkingLevelLow.ToPointer(),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is the sum of the first 50 prime numbers?",
    "generation_config": {
      "thinking_summaries": "auto"
    }
  }'
```
{% /tab %}
{% /tabs %}

A thought block may contain **only a signature with no summary** in these cases:

* Simple requests, where the model didn't reason enough to generate a summary
* `thinking_summaries: "none"`, where summaries are explicitly disabled
* Certain thought content types, such as images, may not have text summaries

Your code should always handle thought blocks where `summary` is empty or
absent.

## Streaming with thinking {% id="streaming-with-thinking" %}

Use streaming to receive incremental thought summaries during generation.
Thought blocks are delivered using Server-Sent Events (SSE) with two distinct
delta types:

| Delta type | Contains | When sent |
|---|---|---|
| `thought_summary` | Text or image summary content | One or more deltas with incremental summary |
| `thought_signature` | The cryptographic signature | the last delta before `step.stop` |

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?
"""

thoughts = ""
answer = ""

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input=prompt,
    generation_config={
        "thinking_summaries": "auto"
    },
    stream=True
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "thought_summary":
            if not thoughts:
                print("Thinking...")
            summary_text = event.delta.content.text
            print(f"[Thought] {summary_text}", end="")
            thoughts += summary_text
        elif event.delta.type == "text" and event.delta.text:
            if not answer:
                print("\nAnswer:")
            print(event.delta.text, end="")
            answer += event.delta.text
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?`;

let thoughts = "";
let answer = "";

const stream = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: prompt,
    generation_config: {
        thinking_summaries: "auto"
    },
    stream: true
});

for await (const event of stream) {
    if (event.event_type === "step.delta") {
        if (event.delta.type === "thought_summary") {
            if (!thoughts) console.log("Thinking...");
            if (event.delta.content?.type === "text") {
                const text = event.delta.content.text;
                process.stdout.write(`[Thought] ${text}`);
                thoughts += text;
            }
        } else if (event.delta.type === "text" && event.delta.text) {
            if (!answer) console.log("\nAnswer:");
            process.stdout.write(event.delta.text);
            answer += event.delta.text;
        }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.interactions.ThoughtSummaryDelta;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;

Client client = new Client();

String prompt =
    "Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.\n"
        + "Alice does not live in the red house.\n"
        + "Bob does not live in the green house.\n"
        + "Carol does not live in the red or green house.\n"
        + "Which house does each person live in?";

StringBuilder thoughts = new StringBuilder();
StringBuilder answer = new StringBuilder();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of(prompt))
        .generationConfig(
            GenerationConfig.builder().thinkingSummaries(ThinkingSummaries.AUTO).build())
        .stream(true)
        .build();

CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));

try (EventStream<InteractionSSEStreamEvent> stream = response.events()) {
  for (InteractionSSEStreamEvent streamEvent : stream) {
    InteractionSSEEvent event = streamEvent.data().orElse(null);
    if (event instanceof StepDelta stepDelta) {
      StepDeltaData delta = stepDelta.delta().orElse(null);
      if (delta instanceof ThoughtSummaryDelta thoughtDelta) {
        Content content = thoughtDelta.content().orElse(null);
        if (content instanceof TextContent textContent) {
          if (thoughts.length() == 0) {
            System.out.println("Thinking...");
          }
          String summaryText = textContent.text().orElse("");
          System.out.print("[Thought] " + summaryText);
          thoughts.append(summaryText);
        }
      } else if (delta instanceof TextDelta textDelta) {
        String text = textDelta.text().orElse("");
        if (!text.isEmpty()) {
          if (answer.length() == 0) {
            System.out.println("\nAnswer:");
          }
          System.out.print(text);
          answer.append(text);
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("What is the sum of the first 50 prime numbers?"),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel:     interactions.ThinkingLevelHigh.ToPointer(),
                ThinkingSummaries: interactions.ThinkingSummariesAuto.ToPointer(),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if thought := step.ThoughtStep; thought != nil {
            for _, part := range thought.Summary {
                if part.TextContent != nil {
                    fmt.Printf("Thought summary:\n%s\n\n", part.TextContent.Text)
                }
            }
        }
    }

    if res.Interaction.OutputText != nil {
        fmt.Printf("Answer:\n%s\n", *res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue. Alice does not live in the red house. Bob does not live in the green house. Carol does not live in the red or green house. Which house does each person live in?",
    "generation_config": {
      "thinking_summaries": "auto"
    },
    "stream": true
  }'
```
{% /tab %}
{% /tabs %}

The streaming response uses Server-Sent Events (SSE) and is composed of steps
and events, for example:

```none
event: interaction.created
data: {"interaction":{"id":"v1_xxx","status":"in_progress","object":"interaction","model":"gemini-3.8-flash"},"event_type":"interaction.created"}

event: step.start
data: {"index":0,"step":{"signature":"","summary":[{"text":"**Evaluating the clues**\n\nI'm considering...","type":"text"}],"type":"thought"},"event_type":"step.start"}

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

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

event: step.start
data: {"index":1,"step":{"content":[{"text":"Based on the clues provided, here","type":"text"}],"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"text":" is the answer to your question...","type":"text"},"event_type":"step.delta"}

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

event: interaction.completed
data: {"interaction":{"id":"v1_xxx","status":"completed","usage":{"total_tokens":530,"total_input_tokens":62,"total_output_tokens":171,"total_thought_tokens":297}},"event_type":"interaction.completed"}

event: done
data: [DONE]
```

## Controlling thinking {% id="thinking-levels" %}

Gemini models engage in dynamic thinking by default, automatically adjusting
the amount of reasoning effort based on the complexity of the request. You can
control this behavior using the `thinking_level` parameter.

| Model | Default Thinking | Levels Supported |
|---|---|---|
| gemini-4-argon | On (medium) | low, medium, high |
| gemini-3.8-flash | On (medium) | low, medium, high |
| gemini-3.6-flash | On (medium) | minimal, low, medium, high |
| gemini-3.5-flash-lite | On (minimal) | minimal, low, medium, high |
| gemini-3.1-pro-preview | On (high) | low, medium, high |
| gemini-3.1-flash-lite-image | On (minimal) | minimal, high |
| gemini-3-flash-preview | On (high) | minimal, low, medium, high |
| gemini-3-pro-preview | On (high) | low, high |
| gemini-2.5-pro | On | low, medium, high |
| gemini-2.5-flash | On | low, medium, high |
| gemini-2.5-flash-lite | Off | low, medium, high |
| gemini-robotics-er-2-preview | On (high) | minimal, low, medium, high |

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Provide a list of 3 famous physicists and their key contributions",
    generation_config={
        "thinking_level": "low"
    }
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Provide a list of 3 famous physicists and their key contributions",
    generation_config: {
        thinking_level: "low"
    }
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ThinkingLevel;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Provide a list of 3 famous physicists and their key contributions"))
        .generationConfig(GenerationConfig.builder().thinkingLevel(ThinkingLevel.LOW).build())
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-pro"),
            Input: interactions.NewInteractionsInput("What is the sum of the first 50 prime numbers?"),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel:     interactions.ThinkingLevelHigh.ToPointer(),
                ThinkingSummaries: interactions.ThinkingSummariesAuto.ToPointer(),
            },
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if thoughtDelta := stepDelta.GetDeltaThoughtSummary(); thoughtDelta != nil {
                if textContent := thoughtDelta.GetContentText(); textContent != nil {
                    fmt.Printf("[Thought Summary] %s\n", textContent.Text)
                }
            }
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Provide a list of 3 famous physicists and their key contributions",
    "generation_config": {
      "thinking_level": "low"
    }
  }'
```
{% /tab %}
{% /tabs %}

### Token limits and `max_output_tokens` {% id="token-limits" %}

The
[`max_output_tokens`](https://ai.google.dev/api/interactions-api#request-body)
generation parameter sets the maximum number of tokens a response can generate,
including thought tokens.

When set, this parameter acts as a hard cutoff enforced by the infrastructure
without changing how the model allocates its thinking budget
(`thinking_level`).

If the model hits this limit while reasoning, it stops generating with status
`"incomplete"` and returns truncated or empty output (while still billing for
any thinking tokens generated). To reduce cost or latency without truncating
responses, lower `thinking_level` (`low` or `medium`) instead of setting a
small `max_output_tokens`.

For Gemini 4 models (`gemini-4-argon`), keep the following context and output limits in mind:

* **Shared 1M context window:** Input, thinking, and output tokens share a single 1M-token context window (`1,048,576` tokens). If your input tokens plus `max_output_tokens` exceed 1,048,576 tokens, the API automatically caps the output limit to the remaining space in the context window (`1,048,576` minus your input tokens).
* **Default synchronous output cap (64K):** When `background=False`, the default `max_output_tokens` cap is 65,536 tokens (a single foreground hop is capped at 65,536 tokens for streaming and 32,768 tokens for non-streaming).
* **Long decode (up to 1M tokens):** To allow Gemini 4 to reason and generate beyond `65,536` tokens (up to `1,048,576` tokens), configure `max_output_tokens` greater than `65,536` with `background=True` or client-side continuation. See [Long decode](/docs/long-decode) for details.

## Thought signatures {% id="signatures" %}

Thought signatures are encrypted representations of the model's internal
reasoning. They are required to maintain reasoning continuity across multi-turn
interactions.

The Interactions API makes handling thought signatures much simpler than the
`generateContent` API.

### Stateful mode (Recommended) {% id="stateful-mode-recommended" %}

By default, when you use the Interactions API in stateful mode (by setting
`store: true` and passing the `previous_interaction_id` in subsequent turns),
the server automatically manages the conversation state, including all thought
blocks and signatures. In this mode, you do not need to do anything regarding
signatures. They are handled entirely on the server side.

### Stateless mode {% id="stateless-mode" %}

If you are managing the conversation state yourself (stateless mode) and passing
the full history of inputs and outputs in each request:

* You **MUST** always resend all `thought` blocks exactly as they were received from the model.
* You should **NOT** remove or modify thought blocks from the history, as they contain the signatures required for the model to continue its reasoning.
* When switching models within a session, you should still resend the previous model's thought blocks. The backend manages compatibility.

{% callout type="note" %}
Note: Built-in tools such as Google Search can carry their own distinct
signatures on the call/result blocks. In stateless mode, you must also resend
these tool result signatures in subsequent turns.
{% /callout %}

## Pricing {% id="pricing" %}

When thinking is turned on, response pricing is the sum of output
tokens and thinking tokens. You can get the total number of generated thinking
tokens from the `total_thought_tokens` field.

{% tabs %}
{% tab label="Python" %}
```python
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);
console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Usage;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain the concept of Occam's Razor."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.usage().isPresent()) {
  Usage usage = interaction.usage().get();
  System.out.println("Thoughts tokens: " + usage.totalThoughtTokens().orElse(0));
  System.out.println("Output tokens: " + usage.totalOutputTokens().orElse(0));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Turn 1: Execute a reasoning + tool use interaction
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-pro"),
            Input: interactions.NewInteractionsInput("Compare the GDP growth of Japan and Germany in 2025."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.GoogleSearch{}),
            },
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel: interactions.ThinkingLevelHigh.ToPointer(),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Turn 2: Pass PreviousInteractionID so thought signatures are automatically preserved
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-pro"),
            PreviousInteractionID: turn1.Interaction.ID,
            Input:                 interactions.NewInteractionsInput("Now summarize that comparison in a 3-row markdown table."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}
```
{% /tab %}

{% /tabs %}

Thinking models generate full thoughts to improve the quality of the final
response, and then output [summaries](/docs/thinking#summaries) to provide insight into the
thought process. Pricing is based on the full thought tokens the model needs to
generate, despite only the summary being output from the API.

{% callout type="note" %}
Because `max_output_tokens` applies to the combined total of thinking tokens and
output tokens, setting a low limit can truncate responses. See
[Token limits and `max_output_tokens`](/docs/thinking#token-limits) for details.
{% /callout %}

You can learn more about tokens in the [Token counting](/docs/tokens) guide.

## Best practices {% id="best-practices" %}

Use thinking models efficiently by following these guidelines.

- **Review reasoning**: Analyze thought summaries to understand failures and improve prompts.
- **Control thinking budget**: Prompt the model to think less for lengthy outputs to save tokens.
- **Simple tasks**: Use minimal thinking for fact retrieval or classification (e.g., "Where was DeepMind founded?").
- **Moderate tasks**: Use default thinking for comparing concepts or creative reasoning (e.g., Compare electric and hybrid cars).
- **Complex tasks**: Use maximum thinking for advanced coding, math, or multi-step planning (e.g., Solve AIME math problems).

## What's next {% id="whats-next" %}

- [Text generation](/docs/text-generation): Basic text responses
- [Function calling](/docs/function-calling): Connect to tools
- [Gemini 4 guide](/docs/latest-model): What's new in Gemini 4
- [Gemini 3 guide](/docs/whats-new-gemini-3.8): Model-specific features

# Thought signatures
Source: https://aistudio.google.com/docs/thought-signatures
Description: Learn how the Interactions API handles thought signatures and model reasoning.

The Interactions API makes it easier to work with thought signatures because it
manages reasoning at the API level. To learn more about configuring model
thinking, managing stateless thought steps, and viewing summaries, see the
[Gemini thinking](/docs/thinking#signatures) guide.

When you use the Interactions API, you don't need to manually extract or pass
signatures on individual content parts. The API simplifies signature
management in two key ways:

* **Automatic state management:** In stateful mode (`store: true`), the server
  manages conversation context automatically. It stores and passes thought
  signatures between turns so you don't have to track them.
* **Dedicated thought steps:** In stateless mode, internal reasoning is
  isolated into dedicated `thought` steps in the `steps` array. Signatures stay
  cleanly inside these steps instead of attaching to user inputs, model text
  outputs, or function calls.

# Structured outputs
Source: https://aistudio.google.com/docs/structured-output
Description: Learn how to generate structured JSON output with the Gemini API.

You can configure Gemini models to generate responses that adhere to a provided
JSON Schema. This ensures predictable, type-safe results and simplifies
extracting structured data from unstructured text.

Using structured outputs is ideal for:

* **Data extraction:** Pull specific information like names and dates from text.
* **Structured classification:** Classify text into predefined categories.
* **Agentic workflows:** Generate structured inputs for tools or APIs.

In addition to supporting JSON Schema in the REST API, the Google GenAI SDKs
allow defining schemas using
[Pydantic](https://docs.pydantic.dev/latest/) (Python) and
[Zod](https://zod.dev/) (JavaScript).

## Structured output examples {% id="structured-output-examples" %}

### Recipe Extractor {% id="recipe" %}

This example demonstrates how to extract structured data from text using basic
JSON Schema types like `object`, `array`, `string`, and `integer`.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional

class Ingredient(BaseModel):
    name: str = Field(description="Name of the ingredient.")
    quantity: str = Field(description="Quantity of the ingredient, including units.")

class Recipe(BaseModel):
    recipe_name: str = Field(description="The name of the recipe.")
    prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.")
    ingredients: List[Ingredient]
    instructions: List[str]

client = genai.Client()

prompt = """
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
"""

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=prompt,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Recipe.model_json_schema()
    },
)

recipe = Recipe.model_validate_json(interaction.output_text)
print(recipe)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const recipeJsonSchema = {
  type: "object",
  properties: {
    recipe_name: {
      type: "string",
      description: "The name of the recipe."
    },
    prep_time_minutes: {
        type: "integer",
        description: "Optional time in minutes to prepare the recipe."
    },
    ingredients: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: { type: "string", description: "Name of the ingredient."},
          quantity: { type: "string", description: "Quantity of the ingredient, including units."}
        },
        required: ["name", "quantity"]
      }
    },
    instructions: {
      type: "array",
      items: { type: "string" }
    }
  },
  required: ["recipe_name", "ingredients", "instructions"]
};

const recipeSchema = z.fromJSONSchema(recipeJsonSchema);

const client = new GoogleGenAI({});

const prompt = `
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
`;

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: prompt,
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: recipeJsonSchema
  },
});

const recipe = recipeSchema.parse(JSON.parse(interaction.output_text));
console.log(recipe);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> ingredientProps = new HashMap<>();
Map<String, Object> nameProp = new HashMap<>();
nameProp.put("type", "string");
nameProp.put("description", "Name of the ingredient.");
ingredientProps.put("name", nameProp);

Map<String, Object> quantityProp = new HashMap<>();
quantityProp.put("type", "string");
quantityProp.put("description", "Quantity of the ingredient, including units.");
ingredientProps.put("quantity", quantityProp);

Map<String, Object> ingredientItemSchema = new HashMap<>();
ingredientItemSchema.put("type", "object");
ingredientItemSchema.put("properties", ingredientProps);
ingredientItemSchema.put("required", Arrays.asList("name", "quantity"));

Map<String, Object> properties = new HashMap<>();

Map<String, Object> recipeNameProp = new HashMap<>();
recipeNameProp.put("type", "string");
recipeNameProp.put("description", "The name of the recipe.");
properties.put("recipe_name", recipeNameProp);

Map<String, Object> prepTimeProp = new HashMap<>();
prepTimeProp.put("type", "integer");
prepTimeProp.put("description", "Optional time in minutes to prepare the recipe.");
properties.put("prep_time_minutes", prepTimeProp);

Map<String, Object> ingredientsProp = new HashMap<>();
ingredientsProp.put("type", "array");
ingredientsProp.put("items", ingredientItemSchema);
properties.put("ingredients", ingredientsProp);

Map<String, Object> instructionsProp = new HashMap<>();
instructionsProp.put("type", "array");
Map<String, Object> stringItem = new HashMap<>();
stringItem.put("type", "string");
instructionsProp.put("items", stringItem);
properties.put("instructions", instructionsProp);

Map<String, Object> recipeJsonSchema = new HashMap<>();
recipeJsonSchema.put("type", "object");
recipeJsonSchema.put("properties", properties);
recipeJsonSchema.put("required", Arrays.asList("recipe_name", "ingredients", "instructions"));

String prompt =
    "Please extract the recipe from the following text.\n"
        + "The user wants to make delicious chocolate chip cookies.\n"
        + "They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n"
        + "1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n"
        + "3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\n"
        + "For the best part, they'll need 2 cups of semisweet chocolate chips.\n"
        + "First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\n"
        + "baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\n"
        + "until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\n"
        + "ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\n"
        + "onto ungreased baking sheets and bake for 9 to 11 minutes.";

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            TextResponseFormat.builder()
                .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
                .schema(recipeJsonSchema)
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of(prompt))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    recipeJsonSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "recipe_name": map[string]any{
                "type":        "string",
                "description": "The name of the recipe.",
            },
            "prep_time_minutes": map[string]any{
                "type":        "integer",
                "description": "Optional time in minutes to prepare the recipe.",
            },
            "ingredients": map[string]any{
                "type": "array",
                "items": map[string]any{
                    "type": "object",
                    "properties": map[string]any{
                        "name": map[string]any{
                            "type":        "string",
                            "description": "Name of the ingredient.",
                        },
                        "quantity": map[string]any{
                            "type":        "string",
                            "description": "Quantity of the ingredient, including units.",
                        },
                    },
                    "required": []string{"name", "quantity"},
                },
            },
            "instructions": map[string]any{
                "type": "array",
                "items": map[string]any{
                    "type": "string",
                },
            },
        },
        "required": []string{"recipe_name", "ingredients", "instructions"},
    }

    prompt := `Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.`

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.TextResponseFormat{
            MimeType: interactions.TextResponseFormatMimeTypeApplicationJSON.ToPointer(),
            Schema:   recipeJsonSchema,
        }),
    )

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model:          interactions.Model("gemini-3.8-flash"),
                Input:          interactions.NewInteractionsInput(prompt),
                ResponseFormat: &format,
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -d '{
      "model": "gemini-3.8-flash",
      "input": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.",
      "response_format": {
        "type": "text",
        "mime_type": "application/json",
        "schema": {
          "type": "object",
          "properties": {
            "recipe_name": {
              "type": "string",
              "description": "The name of the recipe."
            },
            "prep_time_minutes": {
                "type": "integer",
                "description": "Optional time in minutes to prepare the recipe."
            },
            "ingredients": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "description": "Name of the ingredient."},
                  "quantity": { "type": "string", "description": "Quantity of the ingredient, including units."}
                },
                "required": ["name", "quantity"]
              }
            },
            "instructions": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["recipe_name", "ingredients", "instructions"]
        }
      }
      }
    }'
```
{% /tab %}
{% /tabs %}

**Example Response:**

```json
{
  "recipe_name": "Delicious Chocolate Chip Cookies",
  "ingredients": [
    { "name": "all-purpose flour", "quantity": "2 and 1/4 cups" },
    { "name": "baking soda", "quantity": "1 teaspoon" },
    { "name": "salt", "quantity": "1 teaspoon" },
    { "name": "unsalted butter (softened)", "quantity": "1 cup" },
    { "name": "granulated sugar", "quantity": "3/4 cup" },
    { "name": "packed brown sugar", "quantity": "3/4 cup" },
    { "name": "vanilla extract", "quantity": "1 teaspoon" },
    { "name": "large eggs", "quantity": "2" },
    { "name": "semisweet chocolate chips", "quantity": "2 cups" }
  ],
  "instructions": [
    "Preheat the oven to 375°F (190°C).",
    "In a small bowl, whisk together the flour, baking soda, and salt.",
    "In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.",
    "Beat in the vanilla and eggs, one at a time.",
    "Gradually beat in the dry ingredients until just combined.",
    "Stir in the chocolate chips.",
    "Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes."
  ]
}
```

### Content Moderation {% id="feedback" %}

This example showcases `anyOf` for conditional schemas and `enum` for
classification, allowing the output structure to vary based on the content.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from pydantic import BaseModel, Field
from typing import Union, Literal

class SpamDetails(BaseModel):
    reason: str = Field(description="The reason why the content is considered spam.")
    spam_type: Literal["phishing", "scam", "unsolicited promotion", "other"] = Field(description="The type of spam.")

class NotSpamDetails(BaseModel):
    summary: str = Field(description="A brief summary of the content.")
    is_safe: bool = Field(description="Whether the content is safe for all audiences.")

class ModerationResult(BaseModel):
    decision: Union[SpamDetails, NotSpamDetails]

client = genai.Client()

prompt = """
Please moderate the following content and provide a decision.
Content: 'Congratulations! You''ve won a free cruise to the Bahamas. Click here to claim your prize: www.definitely-not-a-scam.com'
"""

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=prompt,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": ModerationResult.model_json_schema()
    },
)

result = ModerationResult.model_validate_json(interaction.output_text)
print(result)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const moderationResultJsonSchema = {
  type: "object",
  properties: {
    decision: {
      anyOf: [
        {
          type: "object",
          title: "SpamDetails",
          description: "Details for content classified as spam.",
          properties: {
            reason: { type: "string", description: "The reason why the content is considered spam." },
            spam_type: { type: "string", enum: ["phishing", "scam", "unsolicited promotion", "other"], description: "The type of spam." }
          },
          required: ["reason", "spam_type"]
        },
        {
          type: "object",
          title: "NotSpamDetails",
          description: "Details for content classified as not spam.",
          properties: {
            summary: { type: "string", description: "A brief summary of the content." },
            is_safe: { type: "boolean", description: "Whether the content is safe for all audiences." }
          },
          required: ["summary", "is_safe"]
        }
      ]
    }
  },
  required: ["decision"]
};

const moderationResultSchema = z.fromJSONSchema(moderationResultJsonSchema);

const client = new GoogleGenAI({});

const prompt = `
Please moderate the following content and provide a decision.
Content: 'Congratulations! You''ve won a free cruise to the Bahamas. Click here to claim your prize: www.definitely-not-a-scam.com'
`;

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: prompt,
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: moderationResultJsonSchema
  },
});

const result = moderationResultSchema.parse(JSON.parse(interaction.output_text));
console.log(result);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> spamProps = new HashMap<>();
Map<String, Object> reasonProp = new HashMap<>();
reasonProp.put("type", "string");
reasonProp.put("description", "The reason why the content is considered spam.");
spamProps.put("reason", reasonProp);

Map<String, Object> spamTypeProp = new HashMap<>();
spamTypeProp.put("type", "string");
spamTypeProp.put("enum", Arrays.asList("phishing", "scam", "unsolicited promotion", "other"));
spamTypeProp.put("description", "The type of spam.");
spamProps.put("spam_type", spamTypeProp);

Map<String, Object> spamDetailsSchema = new HashMap<>();
spamDetailsSchema.put("type", "object");
spamDetailsSchema.put("title", "SpamDetails");
spamDetailsSchema.put("properties", spamProps);
spamDetailsSchema.put("required", Arrays.asList("reason", "spam_type"));

Map<String, Object> notSpamProps = new HashMap<>();
Map<String, Object> summaryProp = new HashMap<>();
summaryProp.put("type", "string");
summaryProp.put("description", "A brief summary of the content.");
notSpamProps.put("summary", summaryProp);

Map<String, Object> isSafeProp = new HashMap<>();
isSafeProp.put("type", "boolean");
isSafeProp.put("description", "Whether the content is safe for all audiences.");
notSpamProps.put("is_safe", isSafeProp);

Map<String, Object> notSpamDetailsSchema = new HashMap<>();
notSpamDetailsSchema.put("type", "object");
notSpamDetailsSchema.put("title", "NotSpamDetails");
notSpamDetailsSchema.put("properties", notSpamProps);
notSpamDetailsSchema.put("required", Arrays.asList("summary", "is_safe"));

Map<String, Object> decisionProp = new HashMap<>();
decisionProp.put("anyOf", Arrays.asList(spamDetailsSchema, notSpamDetailsSchema));

Map<String, Object> properties = new HashMap<>();
properties.put("decision", decisionProp);

Map<String, Object> moderationResultJsonSchema = new HashMap<>();
moderationResultJsonSchema.put("type", "object");
moderationResultJsonSchema.put("properties", properties);
moderationResultJsonSchema.put("required", Arrays.asList("decision"));

String prompt =
    "Please moderate the following content and provide a decision.\n"
        + "Content: 'Congratulations! You''ve won a free cruise to the Bahamas. Click here to claim your prize: www.definitely-not-a-scam.com'";

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            TextResponseFormat.builder()
                .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
                .schema(moderationResultJsonSchema)
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of(prompt))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    spamDetailsSchema := map[string]any{
        "type":  "object",
        "title": "SpamDetails",
        "properties": map[string]any{
            "reason": map[string]any{
                "type":        "string",
                "description": "The reason why the content is considered spam.",
            },
            "spam_type": map[string]any{
                "type":        "string",
                "enum":        []string{"phishing", "scam", "unsolicited promotion", "other"},
                "description": "The type of spam.",
            },
        },
        "required": []string{"reason", "spam_type"},
    }

    notSpamDetailsSchema := map[string]any{
        "type":  "object",
        "title": "NotSpamDetails",
        "properties": map[string]any{
            "summary": map[string]any{
                "type":        "string",
                "description": "A brief summary of the content.",
            },
            "is_safe": map[string]any{
                "type":        "boolean",
                "description": "Whether the content is safe for all audiences.",
            },
        },
        "required": []string{"summary", "is_safe"},
    }

    moderationResultJsonSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "decision": map[string]any{
                "anyOf": []any{spamDetailsSchema, notSpamDetailsSchema},
            },
        },
        "required": []string{"decision"},
    }

    prompt := "Please moderate the following content and provide a decision.\n" +
        "Content: 'Congratulations! You've won a free cruise to the Bahamas. Click here to claim your prize: www.definitely-not-a-scam.com'"

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.TextResponseFormat{
            MimeType: interactions.TextResponseFormatMimeTypeApplicationJSON.ToPointer(),
            Schema:   moderationResultJsonSchema,
        }),
    )

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model:          interactions.Model("gemini-3.8-flash"),
                Input:          interactions.NewInteractionsInput(prompt),
                ResponseFormat: &format,
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -d '{
      "model": "gemini-3.8-flash",
      "input": "Please moderate the following content and provide a decision.\nContent: '\''Congratulations! You have won a free cruise to the Bahamas. Click here to claim your prize: www.definitely-not-a-scam.com'\''",
      "response_format": {
        "type": "text",
        "mime_type": "application/json",
        "schema": {
          "type": "object",
          "properties": {
            "decision": {
              "anyOf": [
                {
                  "type": "object",
                  "title": "SpamDetails",
                  "description": "Details for content classified as spam.",
                  "properties": {
                    "reason": { "type": "string", "description": "The reason why the content is considered spam." },
                    "spam_type": { "type": "string", "enum": ["phishing", "scam", "unsolicited promotion", "other"], "description": "The type of spam." }
                  },
                  "required": ["reason", "spam_type"]
                },
                {
                  "type": "object",
                  "title": "NotSpamDetails",
                  "description": "Details for content classified as not spam.",
                  "properties": {
                    "summary": { "type": "string", "description": "A brief summary of the content." },
                    "is_safe": { "type": "boolean", "description": "Whether the content is safe for all audiences." }
                  },
                  "required": ["summary", "is_safe"]
                }
              ]
            }
          },
          "required": ["decision"]
        }
      }
      }
    }'
```
{% /tab %}
{% /tabs %}

**Example Response:**

```json
{
  "decision": {
    "reason": "The content is an unsolicited prize notification attempting to trick the user into clicking a suspicious link.",
    "spam_type": "scam"
  }
}
```

### Recursive Structures {% id="recursive" %}

This example illustrates how to define a recursive schema such as an
organization chart.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from pydantic import BaseModel, Field
from typing import List

class Employee(BaseModel):
    """Represents an employee in an organization."""
    name: str
    employee_id: int
    reports: List["Employee"] = Field(
        default_factory=list,
        description="A list of employees reporting to this employee."
    )

client = genai.Client()

prompt = """
Generate an organization chart for a small team.
The manager is Alice, who manages Bob and Charlie. Bob manages David.
"""

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=prompt,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Employee.model_json_schema()
    },
)

employee = Employee.model_validate_json(interaction.output_text)
print(employee)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const employeeJsonSchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    employee_id: { type: "integer" },
    reports: {
      type: "array",
      description: "A list of employees reporting to this employee.",
      items: {
        "$ref": "#"
      }
    }
  },
  required: ["name", "employee_id", "reports"]
};

const employeeSchema = z.fromJSONSchema(employeeJsonSchema);

const client = new GoogleGenAI({});

const prompt = `
Generate an organization chart for a small team.
The manager is Alice, who manages Bob and Charlie. Bob manages David.
`;

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: prompt,
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: employeeJsonSchema
  },
});

const employee = employeeSchema.parse(JSON.parse(interaction.output_text));
console.log(employee);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> properties = new HashMap<>();

Map<String, Object> nameProp = new HashMap<>();
nameProp.put("type", "string");
properties.put("name", nameProp);

Map<String, Object> idProp = new HashMap<>();
idProp.put("type", "integer");
properties.put("employee_id", idProp);

Map<String, Object> reportsProp = new HashMap<>();
reportsProp.put("type", "array");
reportsProp.put("description", "A list of employees reporting to this employee.");
reportsProp.put("items", Collections.singletonMap("$ref", "#"));
properties.put("reports", reportsProp);

Map<String, Object> employeeJsonSchema = new HashMap<>();
employeeJsonSchema.put("type", "object");
employeeJsonSchema.put("properties", properties);
employeeJsonSchema.put("required", Arrays.asList("name", "employee_id", "reports"));

String prompt =
    "Generate an organization chart for a small team.\n"
        + "The manager is Alice, who manages Bob and Charlie. Bob manages David.";

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            TextResponseFormat.builder()
                .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
                .schema(employeeJsonSchema)
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of(prompt))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    employeeJsonSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "name": map[string]any{
                "type": "string",
            },
            "employee_id": map[string]any{
                "type": "integer",
            },
            "reports": map[string]any{
                "type":        "array",
                "description": "A list of employees reporting to this employee.",
                "items": map[string]any{
                    "$ref": "#",
                },
            },
        },
        "required": []string{"name", "employee_id", "reports"},
    }

    prompt := "Generate an organization chart for a small team.\n" +
        "The manager is Alice, who manages Bob and Charlie. Bob manages David."

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.TextResponseFormat{
            MimeType: interactions.TextResponseFormatMimeTypeApplicationJSON.ToPointer(),
            Schema:   employeeJsonSchema,
        }),
    )

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model:          interactions.Model("gemini-3.8-flash"),
                Input:          interactions.NewInteractionsInput(prompt),
                ResponseFormat: &format,
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -d '{
      "model": "gemini-3.8-flash",
      "input": "Generate an organization chart for a small team.\nThe manager is Alice, who manages Bob and Charlie. Bob manages David.",
      "response_format": {
        "type": "text",
        "mime_type": "application/json",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "employee_id": { "type": "integer" },
            "reports": {
              "type": "array",
              "description": "A list of employees reporting to this employee.",
              "items": {
                "$ref": "#"
              }
            }
          },
          "required": ["name", "employee_id", "reports"]
        }
      }
      }
    }'
```
{% /tab %}
{% /tabs %}

**Example Response:**

```json
{
  "name": "Alice",
  "employee_id": 101,
  "reports": [
    {
      "name": "Bob",
      "employee_id": 102,
      "reports": [
        {
          "name": "David",
          "employee_id": 104,
          "reports": []
        }
      ]
    },
    {
      "name": "Charlie",
      "employee_id": 103,
      "reports": []
    }
  ]
}
```

## Streaming results {% id="streaming" %}

You can stream structured outputs, allowing you to start processing the
response as it's being generated. The streamed chunks are valid partial JSON
strings that can be concatenated to form the final JSON object.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from pydantic import BaseModel
from typing import Literal

class Feedback(BaseModel):
    sentiment: Literal["positive", "neutral", "negative"]
    summary: str

client = genai.Client()
prompt = "The new UI is incredibly intuitive. Add a very long summary to test streaming!"

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input=prompt,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Feedback.model_json_schema()
    },
    stream=True
)
for event in stream:
    if event.event_type == "step.delta" and event.delta.text:
        print(event.delta.text, end="")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const feedbackJsonSchema = {
  type: "object",
  properties: {
    sentiment: { type: "string", enum: ["positive", "neutral", "negative"] },
    summary: { type: "string" }
  },
  required: ["sentiment", "summary"]
};

const feedbackSchema = z.fromJSONSchema(feedbackJsonSchema);

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "The new UI is incredibly intuitive. Add a very long summary!",
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: feedbackJsonSchema
  },
  stream: true,
});

for await (const event of stream) {
  if (event.event_type === "step.delta" && event.delta?.type === "text") {
    process.stdout.write(event.delta.text);
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> properties = new HashMap<>();

Map<String, Object> sentimentProp = new HashMap<>();
sentimentProp.put("type", "string");
sentimentProp.put("enum", Arrays.asList("positive", "neutral", "negative"));
properties.put("sentiment", sentimentProp);

Map<String, Object> summaryProp = new HashMap<>();
summaryProp.put("type", "string");
properties.put("summary", summaryProp);

Map<String, Object> feedbackJsonSchema = new HashMap<>();
feedbackJsonSchema.put("type", "object");
feedbackJsonSchema.put("properties", properties);
feedbackJsonSchema.put("required", Arrays.asList("sentiment", "summary"));

String prompt = "The new UI is incredibly intuitive. Add a very long summary to test streaming!";

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            TextResponseFormat.builder()
                .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
                .schema(feedbackJsonSchema)
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of(prompt))
        .responseFormat(format)
        .stream(true)
        .build();

CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));

try (EventStream<InteractionSSEStreamEvent> events = response.events()) {
  for (InteractionSSEStreamEvent streamEvent : events) {
    InteractionSSEEvent event = streamEvent.data().orElse(null);
    if (event instanceof StepDelta) {
      StepDeltaData data = ((StepDelta) event).delta().orElse(null);
      if (data instanceof TextDelta) {
        ((TextDelta) data).text().ifPresent(System.out::print);
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    feedbackJsonSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "sentiment": map[string]any{
                "type": "string",
                "enum": []string{"positive", "neutral", "negative"},
            },
            "summary": map[string]any{
                "type": "string",
            },
        },
        "required": []string{"sentiment", "summary"},
    }

    prompt := "The new UI is incredibly intuitive. Add a very long summary to test streaming!"

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.TextResponseFormat{
            MimeType: interactions.TextResponseFormatMimeTypeApplicationJSON.ToPointer(),
            Schema:   feedbackJsonSchema,
        }),
    )

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model:          interactions.Model("gemini-3.8-flash"),
                Input:          interactions.NewInteractionsInput(prompt),
                ResponseFormat: &format,
                Stream:         genai.Ptr(true),
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }
    defer resp.InteractionSSEStreamEvent.Close()

    for resp.InteractionSSEStreamEvent.Next() {
        event := resp.InteractionSSEStreamEvent.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
    }
}
```
{% /tab %}

{% /tabs %}

## Structured outputs with tools {% id="tools" %}

{% callout type="note" %}
Preview: This feature is available only to Gemini 3 series models.
{% /callout %}

Gemini 3 lets you combine Structured Outputs with built-in tools, including
[Grounding with Google Search](/docs/google-search),
[URL Context](/docs/url-context),
[Code Execution](/docs/code-execution),
[File Search](/docs/file-search#structured-output), and
[Function Calling](/docs/function-calling).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Search for all details for the latest Euro.",
    tools=[{"type": "google_search"}, {"type": "url_context"}],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": MatchResult.model_json_schema()
    },
)

result = MatchResult.model_validate_json(interaction.output_text)
print(result)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const matchJsonSchema = {
  type: "object",
  properties: {
    winner: { type: "string" },
    final_match_score: { type: "string" },
    scorers: { type: "array", items: { type: "string" } }
  },
  required: ["winner", "final_match_score", "scorers"]
};

const matchSchema = z.fromJSONSchema(matchJsonSchema);

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-4-argon",
  input: "Search for all details for the latest Euro.",
  tools: [{type: "google_search"}, {type: "url_context"}],
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: matchJsonSchema
  },
});

const match = matchSchema.parse(JSON.parse(interaction.output_text));
console.log(match);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.interactions.URLContext;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> properties = new HashMap<>();

Map<String, Object> winnerProp = new HashMap<>();
winnerProp.put("type", "string");
winnerProp.put("description", "The name of the winner.");
properties.put("winner", winnerProp);

Map<String, Object> scoreProp = new HashMap<>();
scoreProp.put("type", "string");
scoreProp.put("description", "The final match score.");
properties.put("final_match_score", scoreProp);

Map<String, Object> scorersProp = new HashMap<>();
scorersProp.put("type", "array");
scorersProp.put("description", "The name of the scorer.");
scorersProp.put("items", Collections.singletonMap("type", "string"));
properties.put("scorers", scorersProp);

Map<String, Object> matchJsonSchema = new HashMap<>();
matchJsonSchema.put("type", "object");
matchJsonSchema.put("properties", properties);
matchJsonSchema.put("required", Arrays.asList("winner", "final_match_score", "scorers"));

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            TextResponseFormat.builder()
                .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
                .schema(matchJsonSchema)
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-4-argon"))
        .input(InteractionsInput.of("Search for all details for the latest Euro."))
        .tools(Arrays.asList(GoogleSearch.builder().build(), URLContext.builder().build()))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    matchJsonSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "winner": map[string]any{
                "type":        "string",
                "description": "The name of the winner.",
            },
            "final_match_score": map[string]any{
                "type":        "string",
                "description": "The final match score.",
            },
            "scorers": map[string]any{
                "type":        "array",
                "description": "The name of the scorer.",
                "items": map[string]any{
                    "type": "string",
                },
            },
        },
        "required": []string{"winner", "final_match_score", "scorers"},
    }

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.TextResponseFormat{
            MimeType: interactions.TextResponseFormatMimeTypeApplicationJSON.ToPointer(),
            Schema:   matchJsonSchema,
        }),
    )

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-4-argon"),
                Input: interactions.NewInteractionsInput("Search for all details for the latest Euro."),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleSearch{}),
                    interactions.NewTool(interactions.URLContext{}),
                },
                ResponseFormat: &format,
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-4-argon",
    "input": "Search for all details for the latest Euro.",
    "tools": [{"type": "google_search"}, {"type": "url_context"}],
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
            "winner": {"type": "string"},
            "final_match_score": {"type": "string"},
            "scorers": {"type": "array", "items": {"type": "string"}}
        },
        "required": ["winner", "final_match_score", "scorers"]
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## JSON schema support {% id="json-schema-support" %}

To generate a JSON object, configure `response_format` with an object (or an
array containing an object) of type `text` and set its `mime_type` to
`application/json`. The schema should be provided in the `schema` field.

Gemini's structured output mode supports a subset of the
[JSON Schema][json-schema] specification.

[json-schema]: https://json-schema.org/

The following values of `type` are supported:

* **`string`**: For text.
* **`number`**: For floating-point numbers.
* **`integer`**: For whole numbers.
* **`boolean`**: For true or false values.
* **`object`**: For structured data with key-value pairs.
* **`array`**: For lists of items.
* **`null`**: To allow a property to be null, include `"null"` in the type array
  (e.g., `{"type": ["string", "null"]}`).

These descriptive properties help guide the model:

* **`title`**: A short description of a property.
* **`description`**: A longer and more detailed description of a property.

### Type-specific properties {% id="type-specific-properties" %}

**For `object` values:**

* **`properties`**: An object where each key is a property name and each value
  is a schema for that property.
* **`required`**: An array of strings, listing which properties are mandatory.
* **`additionalProperties`**: Controls whether properties not listed in
  `properties` are allowed. Can be a boolean or a schema.
* **Unsupported counting constraints**: `minProperties` and `maxProperties` are
  not enforced during constrained decoding and are ignored by the server.
  Validate property counts in your application code if needed.

**For `string` values:**

* **`enum`**: Lists a specific set of possible strings for classification tasks.
* **`format`**: Specifies a syntax for the string, such as `date-time`, `date`,
  `time`.
* **Unsupported length constraints**: `minLength` and `maxLength` are not
  enforced during constrained decoding and are ignored by the server.
  Validate string lengths in your application code if needed.

**For `number` and `integer` values:**

* **`enum`**: Lists a specific set of possible numeric values.
* **`minimum`**: The minimum inclusive value.
* **`maximum`**: The maximum inclusive value.

**For `array` values:**

* **`items`**: Defines the schema for all items in the array.
* **`prefixItems`**: Defines a list of schemas for the first N items, allowing
  for tuple-like structures.
* **`minItems`**: The minimum number of items in the array.
* **`maxItems`**: The maximum number of items in the array.
* **Unsupported array constraints**: `uniqueItems`, `contains`, `minContains`,
  and `maxContains` are not enforced during constrained decoding and are ignored
  by the server. Deduplicate items or check array contents in your application
  code if needed.

## Structured outputs versus function calling {% id="vs-function-calling" %}

| Feature | Primary Use Case |
| :--- | :--- |
| **Structured Outputs** | **Formatting the final response.** Use when you want the model's *answer* in a specific format. |
| **Function Calling** | **Taking action during conversation.** Use when the model needs to *ask you* to perform a task before providing a final answer. |

## Best practices {% id="best-practices" %}

* **Clear descriptions:** Use the `description` field to guide the model.
* **Strong typing:** Use specific types (`integer`, `string`, `enum`).
* **Prompt engineering:** Clearly state what you want the model to do.
* **Validation:** While output is syntactically correct JSON, always validate
  values in your application.
* **Error handling:** Implement robust error handling for schema-compliant but
  semantically incorrect outputs.

## Limitations {% id="limitations" %}

* **Schema subset:** Not all JSON Schema features are supported.
* **Schema complexity:** Very large or deeply nested schemas may be rejected.
* **Unenforced constraints:** `minLength`, `maxLength`, `minProperties`,
  `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains`
  (and their snake_case variants) are not enforced by the constrained decoding
  grammar engine. If these keywords are present in your schema (for instance,
  emitted automatically by Pydantic's `Field(min_length=...)` or Zod's
  `.min()`), the API automatically strips and ignores them during request
  normalization rather than returning an error. `minItems` and `maxItems` are
  enforced. To enforce the other constraints, validate the output in your client
  application (e.g., using Pydantic `model_validate_json()` or Zod `.parse()`).

### Simplifying complex schemas {% id="simplifying-complex-schemas" %}

When you request structured output, the API compiles your JSON Schema into a
state machine that constrains token generation. This state machine enforces
limits on total states, branching paths, and nesting depth. If your schema
exceeds these limits, the API rejects the request with a
`400 INVALID_ARGUMENT` error.

To fix schema rejection errors, reduce the structural depth and branching
factor of your schema. You can simplify complex schemas in several ways:

* **Move non-structural rules to descriptions:** Field `description` properties
  and system instructions guide the model without adding states to the output
  grammar. If complex constraints push your schema over the limit, move those
  rules into concise descriptions and validate the response in your application
  code.
* **Flatten nested objects and bound recursion:** Replace deeply nested object
  hierarchies with flatter structures. If you use `$defs` and `$ref` for
  recursive types, make the recursive reference optional or nullable. Avoid
  recursing through required properties or arrays with `minItems` greater than
  zero.
* **Reduce branching from optional fields, enums, and unions:** Optional
  properties, `enum` values, and `anyOf` branches multiply the branching paths
  in the output grammar. Mark properties as `required` where possible and allow
  `null` values when a field can be empty. Trim large `enum` lists and simplify
  `anyOf` unions, or include the constraint in your prompt (for example, with a
  Pydantic schema) as a softer restriction.
* **Shorten property names and drop array or numeric bounds:** Property keys
  consume states proportional to their character length. Array bounds such as
  `minItems` and `maxItems` duplicate the item schema for each counted
  position, and numeric bounds (`minimum` and `maximum`) also increase the
  state space. Use concise property names, remove unused fields, and either
  include bounds in your prompt (for example, with a Pydantic schema) as a
  softer restriction or validate bounds in your application code.

# Function calling with the Gemini API
Source: https://aistudio.google.com/docs/function-calling
Description: Get started using Function Calling with the Gemini API

Function calling lets you connect models to external tools and APIs.
Instead of generating text responses, the model determines when to call specific
functions and provides the necessary parameters to execute real-world actions.
This allows the model to act as a bridge between natural language and real-world
actions and data. Function calling has 3 primary use cases:

- [**Take Actions:**](/docs/function-calling#meeting) Interact with external systems using APIs, such as
    scheduling appointments, creating invoices, sending emails, or controlling
    smart home devices.
- [**Augment Knowledge:**](/docs/function-calling#weather) Access information from external sources like
    databases, APIs, and knowledge bases.
- [**Extend Capabilities:**](/docs/function-calling#chart) Use external tools to perform computations and
    extend the limitations of the model, such as using a calculator or creating
    charts.

You can browse examples of these use cases below:

### Schedule Meeting {% id="meeting" %}

This example shows how to define a function that schedules a meeting with attendees at a specific time, allowing the model to parse user requests and return structured arguments to trigger actions in external systems.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

schedule_meeting_function = {
    "type": "function",
    "name": "schedule_meeting",
    "description": "Schedules a meeting with specified attendees at a given time and date.",
    "parameters": {
        "type": "object",
        "properties": {
            "attendees": {"type": "array", "items": {"type": "string"}},
            "date": {"type": "string", "description": "Date (e.g., '2024-07-29')"},
            "time": {"type": "string", "description": "Time (e.g., '15:00')"},
            "topic": {"type": "string", "description": "The meeting topic."},
        },
        "required": ["attendees", "date", "time", "topic"],
    },
}

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about Q3 planning.",
    tools=[{"type": "function", **schedule_meeting_function}],
)

for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function to call: {step.name}")
        print(f"Arguments: {step.arguments}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: 'gemini-3.8-flash',
  input: 'Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about Q3 planning.',
  tools: [
    {
      type: "function",
      name: "schedule_meeting",
      description: "Schedule a meeting with specified attendees, date, time, and topic.",
      parameters: {
        type: "object",
        properties: {
          attendees: {
            type: "array",
            items: { type: "string" },
            description: "List of attendee names or email addresses",
          },
          date: { type: "string", description: "Date of the meeting (YYYY-MM-DD)" },
          time: { type: "string", description: "Time of the meeting (HH:MM)" },
          topic: { type: "string", description: "Subject or topic of the meeting" },
        },
        required: ["attendees", "date", "time", "topic"],
      },
    },
  ],
});

for (const step of interaction.steps) {
  if (step.type === 'function_call') {
    console.log(`Function to call: ${step.name}`);
    console.log(`Arguments: ${JSON.stringify(step.arguments)}`);
  }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
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.8-flash",
    "input": "Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about Q3 planning.",
    "tools": [{
        "type": "function",
        "name": "schedule_meeting",
        "description": "Schedules a meeting with specified attendees at a given time and date.",
        "parameters": {
          "type": "object",
          "properties": {
            "attendees": {"type": "array", "items": {"type": "string"}},
            "date": {"type": "string"},
            "time": {"type": "string"},
            "topic": {"type": "string"}
          },
          "required": ["attendees", "date", "time", "topic"]
        }
    }]
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> attendeesProp = new HashMap<>();
attendeesProp.put("type", "array");
Map<String, Object> itemsMap = new HashMap<>(); itemsMap.put("type", "string"); attendeesProp.put("items", itemsMap);

Map<String, Object> dateProp = new HashMap<>();
dateProp.put("type", "string");
dateProp.put("description", "Date (e.g., \"2024-07-29\")");

Map<String, Object> timeProp = new HashMap<>();
timeProp.put("type", "string");
timeProp.put("description", "Time (e.g., \"15:00\")");

Map<String, Object> topicProp = new HashMap<>();
topicProp.put("type", "string");
topicProp.put("description", "The meeting topic.");

Map<String, Object> properties = new HashMap<>();
properties.put("attendees", attendeesProp);
properties.put("date", dateProp);
properties.put("time", timeProp);
properties.put("topic", topicProp);

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");
parameters.put("properties", properties);
parameters.put("required", Arrays.asList("attendees", "date", "time", "topic"));

Function scheduleMeetingFunction =
    Function.builder()
        .name("schedule_meeting")
        .description("Schedules a meeting with specified attendees at a given time and date.")
        .parameters(parameters)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.6-flash"))
        .input(InteractionsInput.of("Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about Q3 planning."))
        .tools(Arrays.asList(scheduleMeetingFunction))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep functionCall = (FunctionCallStep) step;
      System.out.println("Function to call: " + functionCall.name().orElse(""));
      System.out.println("Arguments: " + functionCall.arguments().orElse(null));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    scheduleMeetingFunction := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("schedule_meeting"),
        Description: genai.Ptr("Schedules a meeting with specified attendees at a given time and date."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "attendees": map[string]any{
                    "type":  "array",
                    "items": map[string]any{"type": "string"},
                },
                "date": map[string]any{
                    "type":        "string",
                    "description": "Date (e.g., '2024-07-29')",
                },
                "time": map[string]any{
                    "type":        "string",
                    "description": "Time (e.g., '15:00')",
                },
                "topic": map[string]any{
                    "type":        "string",
                    "description": "The meeting topic.",
                },
            },
            "required": []string{"attendees", "date", "time", "topic"},
        },
    })

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about Q3 planning."),
                Tools: []interactions.Tool{scheduleMeetingFunction},
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            fc := step.FunctionCallStep
            fmt.Println("Function to call:", fc.Name)
            fmt.Println("Arguments:", fc.Arguments)
        }
    }
}
```
{% /tab %}
{% /tabs %}
### Get Weather {% id="weather" %}

This example shows how to define a function that retrieves temperature data for a location, enabling the model to call external APIs to answer queries requiring real-time or external information.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

weather_function = {
    "type": "function",
    "name": "get_current_temperature",
    "description": "Gets the current temperature for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city name, e.g. San Francisco",
            },
        },
        "required": ["location"],
    },
}

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What's the temperature in London?",
    tools=[weather_function],
)

for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function to call: {step.name}")
        print(f"Arguments: {step.arguments}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: 'gemini-3.8-flash',
  input: "What's the temperature in London?",
  tools: [
    {
      type: "function",
      name: "get_current_weather",
      description: "Get the current weather for a given location",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string", description: "City and state, e.g. San Francisco, CA" },
          unit: { type: "string", enum: ["celsius", "fahrenheit"] },
        },
        required: ["location"],
      },
    },
  ],
});

for (const step of interaction.steps) {
  if (step.type === 'function_call') {
    console.log(`Function to call: ${step.name}`);
    console.log(`Arguments: ${JSON.stringify(step.arguments)}`);
  }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
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.8-flash",
    "input": "What'\''s the temperature in London?",
    "tools": [{
      "type": "function",
      "name": "get_current_temperature",
      "description": "Gets the current temperature for a given location.",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "The city name"}
        },
        "required": ["location"]
      }
    }]
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> locationProp = new HashMap<>();
locationProp.put("type", "string");
locationProp.put("description", "The city name, e.g. San Francisco");

Map<String, Object> properties = new HashMap<>();
properties.put("location", locationProp);

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");
parameters.put("properties", properties);
parameters.put("required", Arrays.asList("location"));

Function weatherFunction =
    Function.builder()
        .name("get_current_temperature")
        .description("Gets the current temperature for a given location.")
        .parameters(parameters)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.6-flash"))
        .input(InteractionsInput.of("What's the temperature in London?"))
        .tools(Arrays.asList(weatherFunction))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep functionCall = (FunctionCallStep) step;
      System.out.println("Function to call: " + functionCall.name().orElse(""));
      System.out.println("Arguments: " + functionCall.arguments().orElse(null));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    weatherFunction := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_current_temperature"),
        Description: genai.Ptr("Gets the current temperature for a given location."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{
                    "type":        "string",
                    "description": "The city name, e.g. San Francisco",
                },
            },
            "required": []string{"location"},
        },
    })

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("What's the temperature in London?"),
                Tools: []interactions.Tool{weatherFunction},
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            fc := step.FunctionCallStep
            fmt.Println("Function to call:", fc.Name)
            fmt.Println("Arguments:", fc.Arguments)
        }
    }
}
```
{% /tab %}
{% /tabs %}
### Create Chart {% id="chart" %}

This example shows how to define a function that generates a bar chart from structured data, demonstrating how the model can use external tools to perform computations or create visual assets:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

create_chart_function = {
    "type": "function",
    "name": "create_bar_chart",
    "description": "Creates a bar chart given a title, labels, and values.",
    "parameters": {
        "type": "object",
        "properties": {
            "title": {"type": "string", "description": "The title for the chart."},
            "labels": {"type": "array", "items": {"type": "string"}},
            "values": {"type": "array", "items": {"type": "number"}},
        },
        "required": ["title", "labels", "values"],
    },
}

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Create a bar chart titled 'Quarterly Sales' with Q1: 50000, Q2: 75000, Q3: 60000.",
    tools=[create_chart_function],
)

for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function to call: {step.name}")
        print(f"Arguments: {step.arguments}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: 'gemini-3.8-flash',
  input: "Create a bar chart titled 'Quarterly Sales' with Q1: 50000, Q2: 75000, Q3: 60000.",
  tools: [
    {
      type: "function",
      name: "create_chart",
      description: "Create a chart based on provided data",
      parameters: {
        type: "object",
        properties: {
          chart_type: { type: "string", enum: ["bar", "line", "pie"] },
          data: { type: "string", description: "JSON string of chart data points" },
          title: { type: "string", description: "Title of the chart" },
        },
        required: ["chart_type", "data", "title"],
      },
    },
  ],
});

for (const step of interaction.steps) {
  if (step.type === 'function_call') {
    console.log(`${step.name}(${JSON.stringify(step.arguments)})`);
  }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
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.8-flash",
    "input": "Create a bar chart titled '\''Quarterly Sales'\'' with Q1: 50000, Q2: 75000, Q3: 60000.",
    "tools": [{
        "type": "function",
        "name": "create_bar_chart",
        "description": "Creates a bar chart given a title, labels, and values.",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "labels": {"type": "array", "items": {"type": "string"}},
            "values": {"type": "array", "items": {"type": "number"}}
          },
          "required": ["title", "labels", "values"]
        }
    }]
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> properties = new HashMap<>();
Map<String, Object> titleMap = new HashMap<>(); titleMap.put("type", "string"); titleMap.put("description", "The title for the chart."); properties.put("title", titleMap);
Map<String, Object> labelsMap = new HashMap<>(); labelsMap.put("type", "array"); labelsMap.put("items", Collections.singletonMap("type", "string")); properties.put("labels", labelsMap);
Map<String, Object> valuesMap = new HashMap<>(); valuesMap.put("type", "array"); valuesMap.put("items", Collections.singletonMap("type", "number")); properties.put("values", valuesMap);

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");
parameters.put("properties", properties);
parameters.put("required", Arrays.asList("title", "labels", "values"));

Function createChartFunction =
    Function.builder()
        .name("create_bar_chart")
        .description("Creates a bar chart given a title, labels, and values.")
        .parameters(parameters)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.6-flash"))
        .input(InteractionsInput.of("Create a bar chart titled 'Quarterly Sales' with Q1: 50000, Q2: 75000, Q3: 60000."))
        .tools(Arrays.asList(createChartFunction))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep functionCall = (FunctionCallStep) step;
      System.out.println(functionCall.name().orElse("") + "(" + functionCall.arguments().orElse(null) + ")");
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    createChartFunction := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("create_bar_chart"),
        Description: genai.Ptr("Creates a bar chart given a title, labels, and values."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "title": map[string]any{
                    "type":        "string",
                    "description": "The title for the chart.",
                },
                "labels": map[string]any{
                    "type":  "array",
                    "items": map[string]any{"type": "string"},
                },
                "values": map[string]any{
                    "type":  "array",
                    "items": map[string]any{"type": "number"},
                },
            },
            "required": []string{"title", "labels", "values"},
        },
    })

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Create a bar chart titled 'Quarterly Sales' with Q1: 50000, Q2: 75000, Q3: 60000."),
                Tools: []interactions.Tool{createChartFunction},
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            fc := step.FunctionCallStep
            fmt.Println("Function to call:", fc.Name)
            fmt.Println("Arguments:", fc.Arguments)
        }
    }
}
```
{% /tab %}
{% /tabs %}
## How function calling works {% id="how-it-works" %}

![Function calling overview](/googledevai/static/gemini-api/docs/images/function-calling-overview.png)

Function calling involves a structured interaction between your application, the
model, and external functions:

1. **Define Function Declaration:** Define the function's name, parameters, and
    purpose to the model.
2. **Call LLM with function declarations:** Send user prompt along with the
    function declaration(s) to the model.
3. **Execute Function Code (Your Responsibility):** The model *doesn't*
    execute the function itself. Extract the name and args and execute in
    your application.
4. **Create User friendly response:** Send the result back to the model for a
    final, user-friendly response.

This process can be repeated over multiple turns. The model supports calling
multiple functions in a single turn ([parallel function calling](/docs/function-calling#parallel_function_calling)) and in sequence ([compositional function calling](/docs/function-calling#compositional_function_calling)).

### Step 1: Define a function declaration {% id="step-1" %}

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
set_light_values_declaration = {
    "type": "function",
    "name": "set_light_values",
    "description": "Sets the brightness and color temperature of a light.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "integer",
                "description": "Light level from 0 to 100",
            },
            "color_temp": {
                "type": "string",
                "enum": ["daylight", "cool", "warm"],
                "description": "Color temperature",
            },
        },
        "required": ["brightness", "color_temp"],
    },
}

def set_light_values(brightness: int, color_temp: str) -> dict:
    """Set the brightness and color temperature of a room light."""
    return {"brightness": brightness, "colorTemperature": color_temp}
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const setLightValuesTool = {
  type: 'function',
  name: 'set_light_values',
  description: 'Sets the brightness and color temperature of a light.',
  parameters: {
    type: 'object',
    properties: {
      brightness: { type: 'number', description: 'Light level from 0 to 100' },
      color_temp: { type: 'string', enum: ['daylight', 'cool', 'warm'] },
    },
    required: ['brightness', 'color_temp'],
  },
};

function setLightValues(brightness = 0, color_temp = 'daylight') {
  return { brightness: brightness, colorTemperature: color_temp };
}
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
)

func setLightValues(brightness int, colorTemp string) map[string]any {
    return map[string]any{
        "brightness":       brightness,
        "colorTemperature": colorTemp,
    }
}

func main() {
    setLightValuesDeclaration := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("set_light_values"),
        Description: genai.Ptr("Sets the brightness and color temperature of a light."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "brightness": map[string]any{
                    "type":        "integer",
                    "description": "Light level from 0 to 100",
                },
                "color_temp": map[string]any{
                    "type":        "string",
                    "enum":        []string{"daylight", "cool", "warm"},
                    "description": "Color temperature",
                },
            },
            "required": []string{"brightness", "color_temp"},
        },
    })
    _ = setLightValuesDeclaration
}
```
{% /tab %}
{% /tabs %}
### Step 2: Call the model with function declarations {% id="step-2" %}

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Turn the lights down to a romantic level",
    tools=[set_light_values_declaration],
)

fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(fc_step)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: 'gemini-3.8-flash',
  input: 'Turn the lights down to a romantic level',
  tools: [
    {
      type: "function",
      name: "set_light_values",
      description: "Set the brightness and color temperature of a room light.",
      parameters: {
        type: "object",
        properties: {
          brightness: { type: "number", description: "Light level from 0 to 100." },
          color_temp: { type: "string", description: "Color temperature (e.g. daylight, cool_white, warm_white)." },
        },
        required: ["brightness", "color_temp"],
      },
    },
  ],
});

let fcStep;
for (const step of interaction.steps || []) {
  if (step.type === 'function_call') {
    fcStep = step;
    break;
  }
}
console.log(fcStep);
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    setLightValuesDeclaration := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("set_light_values"),
        Description: genai.Ptr("Sets the brightness and color temperature of a light."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "brightness": map[string]any{
                    "type":        "integer",
                    "description": "Light level from 0 to 100",
                },
                "color_temp": map[string]any{
                    "type":        "string",
                    "enum":        []string{"daylight", "cool", "warm"},
                    "description": "Color temperature",
                },
            },
            "required": []string{"brightness", "color_temp"},
        },
    })

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Turn the lights down to a romantic level"),
                Tools: []interactions.Tool{setLightValuesDeclaration},
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    var fcStep *interactions.FunctionCallStep
    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            fcStep = step.FunctionCallStep
            break
        }
    }
    fmt.Println(fcStep)
}
```
{% /tab %}
{% /tabs %}

The model returns a `function_call` step with `type`, `name`, and `arguments`:

```python
type='function_call'
name='set_light_values'
arguments={'color_temp': 'warm', 'brightness': 25}
```

### Step 3: Execute the function {% id="step-3" %}

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
fc_step = next(s for s in interaction.steps if s.type == "function_call")

if fc_step.name == "set_light_values":
    result = set_light_values(**fc_step.arguments)
    print(f"Function execution result: {result}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
function setLightValues(brightness = 0, color_temp = '') {
  return { brightness: brightness, colorTemperature: color_temp };
}

let fcStep;
for (const step of interaction.steps || []) {
  if (step.type === 'function_call') {
    fcStep = step;
    break;
  }
}

let result;
if (fcStep?.name === 'set_light_values') {
  result = setLightValues(fcStep.arguments?.brightness, fcStep.arguments?.color_temp);
  console.log(`Function execution result: ${JSON.stringify(result)}`);
}
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func setLightValues(brightness int, colorTemp string) map[string]any {
    return map[string]any{
        "brightness":       brightness,
        "colorTemperature": colorTemp,
    }
}

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    setLightValuesDeclaration := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("set_light_values"),
        Description: genai.Ptr("Sets the brightness and color temperature of a light."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "brightness": map[string]any{
                    "type":        "integer",
                    "description": "Light level from 0 to 100",
                },
                "color_temp": map[string]any{
                    "type":        "string",
                    "enum":        []string{"daylight", "cool", "warm"},
                    "description": "Color temperature",
                },
            },
            "required": []string{"brightness", "color_temp"},
        },
    })

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Turn the lights down to a romantic level"),
                Tools: []interactions.Tool{setLightValuesDeclaration},
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            fcStep := step.FunctionCallStep
            if fcStep.Name == "set_light_values" {
                brightness := 25
                if b, ok := fcStep.Arguments["brightness"].(float64); ok {
                    brightness = int(b)
                }
                colorTemp := "warm"
                if c, ok := fcStep.Arguments["color_temp"].(string); ok {
                    colorTemp = c
                }
                result := setLightValues(brightness, colorTemp)
                fmt.Println("Function execution result:", result)
            }
        }
    }
}
```
{% /tab %}
{% /tabs %}
### Step 4: Send result back to model {% id="step-4" %}

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
final_interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": json.dumps(result)}],
        }
    ],
    tools=[set_light_values_declaration],
    previous_interaction_id=interaction.id,
)

print(final_interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const finalInteraction = await client.interactions.create({
  model: 'gemini-3.8-flash',
  input: [{
    type: 'function_result',
    name: fcStep.name,
    call_id: fcStep.id,
    result: [{ type: 'text', text: JSON.stringify(result) }]
  }],
  tools: [
    {
      type: "function",
      name: "set_light_values",
      description: "Set the brightness and color temperature of a room light.",
      parameters: {
        type: "object",
        properties: {
          brightness: { type: "number", description: "Light level from 0 to 100." },
          color_temp: { type: "string", description: "Color temperature (e.g. daylight, cool_white, warm_white)." },
        },
        required: ["brightness", "color_temp"],
      },
    },
  ],
  previous_interaction_id: interaction.id,
});

console.log(finalInteraction.output_text);
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    setLightValuesDeclaration := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("set_light_values"),
        Description: genai.Ptr("Sets the brightness and color temperature of a light."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "brightness": map[string]any{
                    "type":        "integer",
                    "description": "Light level from 0 to 100",
                },
                "color_temp": map[string]any{
                    "type":        "string",
                    "enum":        []string{"daylight", "cool", "warm"},
                    "description": "Color temperature",
                },
            },
            "required": []string{"brightness", "color_temp"},
        },
    })

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Turn the lights down to a romantic level"),
                Tools: []interactions.Tool{setLightValuesDeclaration},
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    var fcStep *interactions.FunctionCallStep
    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            fcStep = step.FunctionCallStep
            break
        }
    }

    if fcStep != nil {
        resultJson := `{"brightness": 25, "colorTemperature": "warm"}`
        resultStep := interactions.NewStep(interactions.FunctionResultStep{
            Name:   genai.Ptr(fcStep.Name),
            CallID: fcStep.ID,
            Result: interactions.NewFunctionResultStepResultUnion([]interactions.FunctionResultSubcontent{
                interactions.NewFunctionResultSubcontent(interactions.TextContent{
                    Text: resultJson,
                }),
            }),
        })

        finalResp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
            Body: operations.NewCreateInteractionRequestBody(
                interactions.CreateModelInteraction{
                    Model:                 interactions.Model("gemini-3.8-flash"),
                    PreviousInteractionID: resp.Interaction.ID,
                    Tools:                 []interactions.Tool{setLightValuesDeclaration},
                    Input:                 interactions.NewInteractionsInput([]interactions.Step{resultStep}),
                },
            ),
        })
        if err != nil {
            log.Fatal(err)
        }

        fmt.Println(finalResp.Interaction.GetOutputText())
    }
}
```
{% /tab %}
{% /tabs %}
### Stateless function calling {% id="stateless-function-calling" %}

You can also use function calling in stateless mode by managing the conversation history on the client side and setting `store=false`.

In stateless mode, you must pass the full history of the conversation in the `input` field of each subsequent request. This history must include:
1. The initial `user_input` step.
2. All model-generated steps returned in Turn 1 (including `thought` and `function_call` steps) exactly as received.
3. The `function_result` step containing the output of your executed function.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai
import json

client = genai.Client()

history = [
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "Turn the lights down to a romantic level"}]
    }
]

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    store=False,
    input=history,
    tools=[set_light_values_declaration],
)

for step in interaction.steps:
    history.append(step.model_dump())

fc_step = next(s for s in interaction.steps if s.type == "function_call")
if fc_step.name == "set_light_values":
    result = set_light_values(**fc_step.arguments)

history.append({
    "type": "function_result",
    "name": fc_step.name,
    "call_id": fc_step.id,
    "result": [{"type": "text", "text": json.dumps(result)}],
})

final_interaction = client.interactions.create(
    model="gemini-3.8-flash",
    store=False,
    input=history,
    tools=[set_light_values_declaration],
)

print(final_interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

async function main() {
  const history = [
    {
      type: "user_input",
      content: [{ type: "text", text: "Turn the lights down to a romantic level" }]
    }
  ];

  const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    store: false,
    input: history,
    tools: [setLightValuesTool],
  });

  history.push(...interaction.steps);

  const fcStep = interaction.steps.find(s => s.type === 'function_call');
  let result;
  if (fcStep.name === 'set_light_values') {
    result = setLightValues(fcStep.arguments.brightness, fcStep.arguments.color_temp);
  }

  history.push({
    type: 'function_result',
    name: fcStep.name,
    call_id: fcStep.id,
    result: [{ type: 'text', text: JSON.stringify(result) }]
  });

  const finalInteraction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    store: false,
    input: history,
    tools: [setLightValuesTool],
  });

  console.log(finalInteraction.output_text);
}

await main();
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Turn 1: Send request with tools and store: false
RESPONSE1=$(curl -s -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.8-flash",
    "store": false,
    "input": [
      {
        "type": "user_input",
        "content": "Turn the lights down to a romantic level"
      }
    ],
    "tools": [{
      "type": "function",
      "name": "set_light_values",
      "description": "Sets the brightness and color temperature of a light.",
      "parameters": {
        "type": "object",
        "properties": {
          "brightness": {"type": "integer", "description": "Light level from 0 to 100"},
          "color_temp": {"type": "string", "enum": ["daylight", "cool", "warm"]}
        },
        "required": ["brightness", "color_temp"]
      }
    }]
  }')

# Extract model steps (thought, function_call)
MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')

# Extract function call details to execute
FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')
FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')

# Assume local execution returns: {"brightness": 25, "colorTemperature": "warm"}
RESULT="{\"brightness\": 25, \"colorTemperature\": \"warm\"}"

# Reconstruct history for Turn 2
HISTORY=$(jq -n \
  --argjson first_input '[{"type": "user_input", "content": "Turn the lights down to a romantic level"}]' \
  --argjson model_steps "$MODEL_STEPS" \
  --arg fc_name "$FC_NAME" \
  --arg fc_id "$FC_ID" \
  --arg result "$RESULT" \
  '$first_input + $model_steps + [{"type": "function_result", "name": $fc_name, "call_id": $fc_id, "result": [{"type": "text", "text": $result}]}]')

# Turn 2: Send the full history
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.8-flash\",
    \"store\": false,
    \"input\": $HISTORY,
    \"tools\": [{
      \"type\": \"function\",
      \"name\": \"set_light_values\",
      \"description\": \"Sets the brightness and color temperature of a light.\",
      \"parameters\": {
        \"type\": \"object\",
        \"properties\": {
          \"brightness\": {\"type\": \"integer\"},
          \"color_temp\": {\"type\": \"string\"}
        },
        \"required\": [\"brightness\", \"color_temp\"]
      }
    }]
  }"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    setLightValuesDeclaration := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("set_light_values"),
        Description: genai.Ptr("Sets the brightness and color temperature of a light."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "brightness": map[string]any{
                    "type":        "integer",
                    "description": "Light level from 0 to 100",
                },
                "color_temp": map[string]any{
                    "type":        "string",
                    "enum":        []string{"daylight", "cool", "warm"},
                    "description": "Color temperature",
                },
            },
            "required": []string{"brightness", "color_temp"},
        },
    })

    history := []interactions.Step{
        interactions.NewStep(interactions.UserInputStep{
            Content: []interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Turn the lights down to a romantic level",
                }),
            },
        }),
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Store: genai.Ptr(false),
                Input: interactions.NewInteractionsInput(history),
                Tools: []interactions.Tool{setLightValuesDeclaration},
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    history = append(history, resp.Interaction.Steps...)
    var fcStep *interactions.FunctionCallStep
    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            fcStep = step.FunctionCallStep
            break
        }
    }

    if fcStep != nil {
        resultJson := `{"brightness": 25, "colorTemperature": "warm"}`
        history = append(history, interactions.NewStep(interactions.FunctionResultStep{
            Name:   genai.Ptr(fcStep.Name),
            CallID: fcStep.ID,
            Result: interactions.NewFunctionResultStepResultUnion([]interactions.FunctionResultSubcontent{
                interactions.NewFunctionResultSubcontent(interactions.TextContent{
                    Text: resultJson,
                }),
            }),
        }))

        finalResp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
            Body: operations.NewCreateInteractionRequestBody(
                interactions.CreateModelInteraction{
                    Model: interactions.Model("gemini-3.8-flash"),
                    Store: genai.Ptr(false),
                    Input: interactions.NewInteractionsInput(history),
                    Tools: []interactions.Tool{setLightValuesDeclaration},
                },
            ),
        })
        if err != nil {
            log.Fatal(err)
        }

        fmt.Println(finalResp.Interaction.GetOutputText())
    }
}
```
{% /tab %}
{% /tabs %}
## Function declarations {% id="function-declarations" %}

A function declaration is passed as a tool and includes:

* `type` (string): Must be `"function"` for custom functions.
* `name` (string): Unique function name (use underscores or camelCase).
* `description` (string): Clear explanation of the function's purpose.
* `parameters` (object): Input parameters the function expects.
    * `type` (string): Overall data type, such as `object`.
    * `properties` (object): Individual parameters with type and description.
    * `required` (array): Mandatory parameter names.

## Function calling with thinking models {% id="thinking" %}

Gemini 3 series models use an internal ["thinking"](/docs/thinking) process that improves function calling. The SDKs automatically handle [thought signatures](/docs/thought-signatures) for you.

## Parallel function calling {% id="parallel_function_calling" %}

Call multiple functions at once when they are independent:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
power_disco_ball = {"type": "function", "name": "power_disco_ball", "description": "Powers the disco ball.",
    "parameters": {"type": "object", "properties": {"power": {"type": "boolean"}}, "required": ["power"]}}
start_music = {"type": "function", "name": "start_music", "description": "Play music.",
    "parameters": {"type": "object", "properties": {"energetic": {"type": "boolean"}, "loud": {"type": "boolean"}}, "required": ["energetic", "loud"]}}
dim_lights = {"type": "function", "name": "dim_lights", "description": "Dim the lights.",
    "parameters": {"type": "object", "properties": {"brightness": {"type": "number"}}, "required": ["brightness"]}}

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Turn this place into a party!",
    tools=[power_disco_ball, start_music, dim_lights],
    generation_config={"tool_choice": "any"},
)

for step in interaction.steps:
    if step.type == "function_call":
        args = ", ".join(f"{key}={val}" for key, val in step.arguments.items())
        print(f"{step.name}({args})")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const powerDiscoBall = { type: 'function', name: 'power_disco_ball', description: 'Powers the disco ball.',
  parameters: { type: 'object', properties: { power: { type: 'boolean' } }, required: ['power'] } };
const startMusic = { type: 'function', name: 'start_music', description: 'Play music.',
  parameters: { type: 'object', properties: { energetic: { type: 'boolean' }, loud: { type: 'boolean' } }, required: ['energetic', 'loud'] } };
const dimLights = { type: 'function', name: 'dim_lights', description: 'Dim the lights.',
  parameters: { type: 'object', properties: { brightness: { type: 'number' } }, required: ['brightness'] } };

const interaction = await client.interactions.create({
  model: 'gemini-3.8-flash',
  input: 'Turn this place into a party!',
  tools: [powerDiscoBall, startMusic, dimLights],
  generation_config: { tool_choice: 'any' },
});

for (const step of interaction.steps) {
  if (step.type === 'function_call') {
    console.log(`${step.name}(${JSON.stringify(step.arguments)})`);
  }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
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.8-flash",
    "input": "Turn this place into a party!",
    "tools": [
      {
        "type": "function",
        "name": "power_disco_ball",
        "description": "Powers the disco ball.",
        "parameters": {
          "type": "object",
          "properties": {
            "power": {"type": "boolean"}
          },
          "required": ["power"]
        }
      },
      {
        "type": "function",
        "name": "start_music",
        "description": "Play music.",
        "parameters": {
          "type": "object",
          "properties": {
            "energetic": {"type": "boolean"},
            "loud": {"type": "boolean"}
          },
          "required": ["energetic", "loud"]
        }
      },
      {
        "type": "function",
        "name": "dim_lights",
        "description": "Dim the lights.",
        "parameters": {
          "type": "object",
          "properties": {
            "brightness": {"type": "number"}
          },
          "required": ["brightness"]
        }
      }
    ]
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    powerDiscoBall := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("power_disco_ball"),
        Description: genai.Ptr("Powers the disco ball."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "power": map[string]any{"type": "boolean"},
            },
            "required": []string{"power"},
        },
    })

    startMusic := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("start_music"),
        Description: genai.Ptr("Play music."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "energetic": map[string]any{"type": "boolean"},
                "loud":      map[string]any{"type": "boolean"},
            },
            "required": []string{"energetic", "loud"},
        },
    })

    dimLights := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("dim_lights"),
        Description: genai.Ptr("Dim the lights."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "brightness": map[string]any{"type": "number"},
            },
            "required": []string{"brightness"},
        },
    })

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Turn this place into a party!"),
                Tools: []interactions.Tool{powerDiscoBall, startMusic, dimLights},
                GenerationConfig: &interactions.GenerationConfig{
                    ToolChoice: genai.Ptr(interactions.NewToolChoice(interactions.ToolChoiceTypeAny)),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            fc := step.FunctionCallStep
            fmt.Printf("%s(%v)\n", fc.Name, fc.Arguments)
        }
    }
}
```
{% /tab %}
{% /tabs %}
## Compositional function calling {% id="compositional_function_calling" %}

Chain multiple function calls together for complex requests (e.g., get location
first, then get weather for that location).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
get_weather_forecast_declaration = {
    "type": "function",
    "name": "get_weather_forecast",
    "description": "Gets the current weather temperature for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "The location"},
        },
        "required": ["location"],
    },
}

set_thermostat_temperature_declaration = {
    "type": "function",
    "name": "set_thermostat_temperature",
    "description": "Sets the thermostat to a desired temperature.",
    "parameters": {
        "type": "object",
        "properties": {
            "temperature": {
                "type": "integer",
                "description": "The temperature in Celsius",
            },
        },
        "required": ["temperature"],
    },
}

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise 18°C.",
    tools=[
        get_weather_forecast_declaration,
        set_thermostat_temperature_declaration,
    ],
)

for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function to call: {step.name}")
        print(f"Arguments: {step.arguments}")
    elif hasattr(step, "content") and step.content:
         for part in step.content:
             if hasattr(part, "text"):
                 print(part.text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: 'gemini-3.8-flash',
  input: "If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise 18°C.",
  tools: [
    {
      type: "function",
      name: "get_weather_forecast",
      description: "Get the weather forecast for a given location and number of days.",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string", description: "The city and state, e.g. San Francisco, CA" },
          days: { type: "number", description: "Number of days for the forecast." },
        },
        required: ["location"],
      },
    },
    {
      type: "function",
      name: "set_thermostat_temperature",
      description: "Set the target temperature for the home thermostat.",
      parameters: {
        type: "object",
        properties: {
          temperature: { type: "number", description: "Target temperature in Fahrenheit." },
        },
        required: ["temperature"],
      },
    },
  ],
});

for (const step of interaction.steps) {
  if (step.type === 'function_call') {
    console.log(`Function to call: ${step.name}`);
    console.log(`Arguments: ${JSON.stringify(step.arguments)}`);
  } else if ('content' in step && Array.isArray(step.content)) {
    for (const part of step.content || []) {
      if ('text' in part && part.text) {
        console.log(part.text);
      }
    }
  }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
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.8-flash",
    "input": "If it'\''s warmer than 20°C in London, set the thermostat to 20°C, otherwise 18°C.",
    "tools": [
      {
        "type": "function",
        "name": "get_weather_forecast",
        "description": "Gets the current weather temperature for a given location.",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"}
          },
          "required": ["location"]
        }
      },
      {
        "type": "function",
        "name": "set_thermostat_temperature",
        "description": "Sets the thermostat to a desired temperature.",
        "parameters": {
          "type": "object",
          "properties": {
            "temperature": {"type": "integer"}
          },
          "required": ["temperature"]
        }
      }
    ]
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    getWeatherForecastDeclaration := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_weather_forecast"),
        Description: genai.Ptr("Gets the current weather temperature for a given location."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{
                    "type":        "string",
                    "description": "The location",
                },
            },
            "required": []string{"location"},
        },
    })

    setThermostatTemperatureDeclaration := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("set_thermostat_temperature"),
        Description: genai.Ptr("Sets the thermostat to a desired temperature."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "temperature": map[string]any{
                    "type":        "integer",
                    "description": "The temperature in Celsius",
                },
            },
            "required": []string{"temperature"},
        },
    })

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise 18°C."),
                Tools: []interactions.Tool{getWeatherForecastDeclaration, setThermostatTemperatureDeclaration},
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            fc := step.FunctionCallStep
            fmt.Println("Function to call:", fc.Name)
            fmt.Println("Arguments:", fc.Arguments)
        } else if step.ModelOutputStep != nil {
            for _, part := range step.ModelOutputStep.Content {
                if part.TextContent != nil {
                    fmt.Println(part.TextContent.Text)
                }
            }
        }
    }
}
```
{% /tab %}
{% /tabs %}
## Function calling modes {% id="function_calling_modes" %}

Control how the model uses tools using `tool_choice` in `generation_config`:

* `auto` (Default): Model decides whether to call a function or respond directly.
* `any`: Model is constrained to always predict a function call.
* `none`: Model is prohibited from making function calls.
* `validated`: Model ensures function schema adherence.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
generation_config = {
    "tool_choice": {
        "allowed_tools": {
            "mode": "any",
            "tools": ["get_current_temperature"]
        }
    }
}
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const generation_config = {
  tool_choice: {
    allowed_tools: {
      mode: 'any',
      tools: ['get_current_temperature']
    }
  }
};
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
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.8-flash",
    "input": "What is the temperature in Boston?",
    "tools": [{
      "type": "function",
      "name": "get_current_temperature",
      "description": "Gets the current temperature for a given location.",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string"}
        },
        "required": ["location"]
      }
    }],
    "generation_config": {
      "tool_choice": {
        "allowed_tools": {
          "mode": "any",
          "tools": ["get_current_temperature"]
        }
      }
    }
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
)

func main() {
    generationConfig := interactions.GenerationConfig{
        ToolChoice: genai.Ptr(interactions.NewToolChoice(interactions.ToolChoiceConfig{
            AllowedTools: &interactions.AllowedTools{
                Mode:  interactions.ToolChoiceTypeAny.ToPointer(),
                Tools: []string{"get_current_temperature"},
            },
        })),
    }
    _ = generationConfig
}
```
{% /tab %}
{% /tabs %}
## Multi-tool use {% id="native-tools" %}

You can enable multiple tools, combining built-in tools with function calling in
the same request. Gemini 3 models can combine built-in tools with function
calling out-of-the-box in Interactions. Passing `previous_interaction_id`
automatically circulates the built-in tool context.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai
import json

client = genai.Client()

get_weather = {
    "type": "function",
    "name": "get_weather",
    "description": "Gets the weather for a requested city.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "The city and state, e.g. Utqiaġvik, Alaska",
            },
        },
        "required": ["city"],
    },
}

tools = [
    {"type": "google_search"},
    get_weather
]

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the northernmost city in the United States? What's the weather like there today?",
    tools=tools
)

for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function call: {step.name} (ID: {step.id})")
        result = {"response": "Very cold. 22 degrees Fahrenheit."}
        interaction_2 = client.interactions.create(
            model="gemini-3.8-flash",
            previous_interaction_id=interaction.id,
            tools=tools,
            input=[{
                "type": "function_result",
                "name": step.name,
                "call_id": step.id,
                "result": [{"type": "text", "text": json.dumps(result)}]
            }]
        )

        print(interaction_2.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const weatherTool = {
  type: 'function',
  name: 'get_weather',
  description: 'Gets the weather for a given location.',
  parameters: {
    type: 'object',
    properties: {
      location: {
        type: 'string',
        description: 'The city and state, e.g. San Francisco, CA',
      },
    },
    required: ['location'],
  },
};

const tools = [
  { type: 'google_search' }, // Built-in tool
  weatherTool,
];

const interaction = await client.interactions.create({
  model: 'gemini-3.8-flash',
  input: "What is the northernmost city in the United States? What's the weather like there today?",
  tools: tools,
});

for (const step of interaction.steps) {
  if (step.type === 'function_call') {
    console.log(`Function call: ${step.name} (ID: ${step.id})`);
    const result = { response: 'Very cold. 22 degrees Fahrenheit.' };
    const interaction_2 = await client.interactions.create({
      model: 'gemini-3.8-flash',
      previous_interaction_id: interaction.id,
      tools: tools,
      input: [
        {
          type: 'function_result',
          name: step.name,
          call_id: step.id,
          result: [{ type: 'text', text: JSON.stringify(result) }],
        },
      ],
    });

    console.log(interaction_2.output_text);
  }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Turn 1: Send request with built-in google_search tool and custom weather tool
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.8-flash",
    "input": "What is the northernmost city in the United States? What'\''s the weather like there today?",
    "tools": [
      {"type": "google_search"},
      {
        "type": "function",
        "name": "get_weather",
        "description": "Gets the weather for a given location.",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}
          },
          "required": ["location"]
        }
      }
    ]
  }'

# Turn 2: Provide function result and pass previous_interaction_id
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.8-flash",
    "previous_interaction_id": "INTERACTION_ID",
    "tools": [
      {"type": "google_search"},
      {
        "type": "function",
        "name": "get_weather",
        "description": "Gets the weather for a given location.",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}
          },
          "required": ["location"]
        }
      }
    ],
    "input": [
      {
        "type": "function_result",
        "name": "get_weather",
        "call_id": "call_123",
        "result": [{"type": "text", "text": "{\"response\": \"Very cold. 22 degrees Fahrenheit.\"}"}]
      }
    ]
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    getWeather := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Gets the weather for a requested city."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "city": map[string]any{
                    "type":        "string",
                    "description": "The city and state, e.g. Utqiaġvik, Alaska",
                },
            },
            "required": []string{"city"},
        },
    })

    tools := []interactions.Tool{
        interactions.NewTool(interactions.GoogleSearch{}),
        getWeather,
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("What is the northernmost city in the United States? What's the weather like there today?"),
                Tools: tools,
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            fcStep := step.FunctionCallStep
            fmt.Printf("Function call: %s (ID: %s)\n", fcStep.Name, fcStep.ID)
            resultJson := `{"response": "Very cold. 22 degrees Fahrenheit."}`

            resultStep := interactions.NewStep(interactions.FunctionResultStep{
                Name:   genai.Ptr(fcStep.Name),
                CallID: fcStep.ID,
                Result: interactions.NewFunctionResultStepResultUnion([]interactions.FunctionResultSubcontent{
                    interactions.NewFunctionResultSubcontent(interactions.TextContent{
                        Text: resultJson,
                    }),
                }),
            })

            resp2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
                Body: operations.NewCreateInteractionRequestBody(
                    interactions.CreateModelInteraction{
                        Model:                 interactions.Model("gemini-3.8-flash"),
                        PreviousInteractionID: resp.Interaction.ID,
                        Tools:                 tools,
                        Input:                 interactions.NewInteractionsInput([]interactions.Step{resultStep}),
                    },
                ),
            })
            if err != nil {
                log.Fatal(err)
            }

            fmt.Println(resp2.Interaction.GetOutputText())
        }
    }
}
```
{% /tab %}
{% /tabs %}
## Multimodal function responses {% id="multimodal" %}

For Gemini 3 series models, you can include multimodal content in
the function response parts that you send to the model. The model can process
this multimodal content in its next turn to produce a more informed response.

To include multimodal data in a function response, include it as one or more content blocks in the `result` field of the `function_result` step. Each content block must specify its `type` (e.g., `"text"`, `"image"`).

The following example shows how to send a function response containing image data back to the model in an interaction:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import base64
from google import genai
import requests

client = genai.Client()

tool_call = next(s for s in interaction.steps if s.type == "function_call")

image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content

base64_image_data = base64.b64encode(image_bytes).decode("utf-8")

final_interaction = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": tool_call.name,
            "call_id": tool_call.id,
            "result": [
                {"type": "text", "text": "instrument.jpg"},
                {
                    "type": "image",
                    "mime_type": "image/jpeg",
                    "data": base64_image_data,
                },
            ],
        }
    ],
)

print(final_interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

let toolCall;
for (const s of interaction.steps || []) {
  if (s.type === 'function_call') {
    toolCall = s;
    break;
  }
}

const base64ImageData = "BASE64_IMAGE_DATA";

const finalInteraction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    previous_interaction_id: interaction.id,
    input: [{
        type: 'function_result',
        name: (toolCall && toolCall.type === 'function_call' ? toolCall.name : ''),
        call_id: (toolCall && toolCall.type === 'function_call' ? toolCall.id : ''),
        result: [
            { type: 'text', text: 'instrument.jpg' },
            {
                type: 'image',
                mime_type: 'image/jpeg',
                data: base64ImageData,
            }
        ]
    }]
});

console.log(finalInteraction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
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.8-flash",
    "previous_interaction_id": "INTERACTION_ID",
    "input": [
      {
        "type": "function_result",
        "name": "get_image",
        "call_id": "call_123",
        "result": [
          {"type": "text", "text": "instrument.jpg"},
          {
            "type": "image",
            "mime_type": "image/jpeg",
            "data": "BASE64_IMAGE_DATA"
          }
        ]
      }
    ]
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    getInstrumentImage := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_instrument_image"),
        Description: genai.Ptr("Gets an image of an instrument."),
        Parameters: map[string]any{
            "type": "object",
        },
    })

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Show me the instrument."),
                Tools: []interactions.Tool{getInstrumentImage},
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    var toolCall *interactions.FunctionCallStep
    for _, step := range resp.Interaction.Steps {
        if step.FunctionCallStep != nil {
            toolCall = step.FunctionCallStep
            break
        }
    }

    if toolCall != nil {
        base64ImageData := "BASE64_IMAGE_DATA"

        resultStep := interactions.NewStep(interactions.FunctionResultStep{
            Name:   genai.Ptr(toolCall.Name),
            CallID: toolCall.ID,
            Result: interactions.NewFunctionResultStepResultUnion([]interactions.FunctionResultSubcontent{
                interactions.NewFunctionResultSubcontent(interactions.TextContent{
                    Text: "instrument.jpg",
                }),
                interactions.NewFunctionResultSubcontent(interactions.ImageContent{
                    MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
                    Data:     genai.Ptr(base64ImageData),
                }),
            }),
        })

        finalResp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
            Body: operations.NewCreateInteractionRequestBody(
                interactions.CreateModelInteraction{
                    Model:                 interactions.Model("gemini-3.8-flash"),
                    PreviousInteractionID: resp.Interaction.ID,
                    Input:                 interactions.NewInteractionsInput([]interactions.Step{resultStep}),
                },
            ),
        })
        if err != nil {
            log.Fatal(err)
        }

        fmt.Println(finalResp.Interaction.GetOutputText())
    }
}
```
{% /tab %}
{% /tabs %}
## Function calling with Structured output {% id="structured-output" %}

For Gemini 3 series models, combine function calling with
[structured output](/docs/structured-output) for
consistently formatted responses.

## Remote MCP (Model Context Protocol) {% id="mcp" %}

Interactions API supports connecting to remote MCP servers to give the model access to external tools and services. You provide the server `name` and `url` in the tools configuration.

When using Remote MCP, be aware of the following constraints:

* **Server types**: Remote MCP only works with Streamable HTTP servers. SSE (Server-Sent Events) servers are not supported.
* **Naming**: MCP server names should not include the `-` character. Use `snake_case` server names instead.

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `type` | `string` | Yes | Must be `"mcp_server"`. |
| `name` | `string` | No | A display name for the MCP server. |
| `url` | `string` | No | The full URL for the MCP server endpoint. |
| `headers` | `object` | No | Key-value pairs sent as HTTP headers with every request to the server (for example, authentication tokens). |
| `allowed_tools` | `array` | No | Restrict which tools from the server the agent may call. |

### Example

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Check the weather in San Francisco.",
    tools=[
        {
            "type": "mcp_server",
            "name": "weather",
            "url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
        }
    ]
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Check the weather in San Francisco.',
    tools: [
        {
            type: 'mcp_server',
            name: 'weather',
            url: 'https://gemini-api-demos.uc.r.appspot.com/mcp'
        }
    ]
});
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    "input": "Check the weather in San Francisco.",
    "tools": [
        {
            "type": "mcp_server",
            "name": "weather",
            "url": "https://gemini-api-demos.uc.r.appspot.com/mcp"
        }
    ]
}'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Check the weather in San Francisco."),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.MCPServer{
                        Name: genai.Ptr("weather"),
                        URL:  genai.Ptr("https://gemini-api-demos.uc.r.appspot.com/mcp"),
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = resp
}
```
{% /tab %}
{% /tabs %}
## Stream tool calls {% id="streaming-tool-calls" %}

When using tools with streaming, the model generates function calls as a
sequence of `step.delta` events on the stream. Tool arguments can be streamed
as partial arguments using `arguments`. You must aggregate these deltas to
reconstruct the complete tool calls before executing them.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import json
from google import genai

client = genai.Client()

weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Gets the weather for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "The city and state"}
        },
        "required": ["location"]
    }
}

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the weather in Paris?",
    tools=[weather_tool],
    stream=True
)

current_calls = {}
tool_calls = []

for event in stream:
    if event.event_type == "step.start":
        if event.step.type == "function_call":
            current_calls[event.index] = {
                "id": event.step.id,
                "name": event.step.name,
                "arguments": ""
            }
            if hasattr(event.step, "arguments") and event.step.arguments:
                if isinstance(event.step.arguments, dict):
                    current_calls[event.index]["arguments"] = json.dumps(event.step.arguments)
                else:
                    current_calls[event.index]["arguments"] = event.step.arguments
    elif event.event_type == "step.delta":
        if event.delta.type == "arguments":
            if event.index in current_calls:
                current_calls[event.index]["arguments"] += event.delta.partial_arguments
        elif event.delta.type == "text":
            print(event.delta.text, end="", flush=True)

    elif event.event_type == "interaction.completed":
        for index, call in current_calls.items():
            args = call["arguments"]
            if args:
                args = json.loads(args)
            else:
                args = {}

            tool_calls.append({
                "type": "function_call",
                "id": call["id"],
                "name": call["name"],
                "arguments": args
            })

        print(f"\nFinal tool calls ready to execute:")
        print(json.dumps(tool_calls, indent=2))
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'What is the weather in Paris?',
    tools: [
        {
            type: 'function',
            name: 'get_weather',
            description: 'Gets the weather for a given location.',
            parameters: {
                type: 'object',
                properties: {
                    location: { type: 'string', description: 'The city and state' }
                },
                required: ['location']
            }
        }
    ],
    stream: true,
});

const currentCalls = [];
let toolCalls = [];

for await (const event of stream) {
    const evType = event.event_type;
    if (evType === 'step.start') {
        if (event.step.type === 'function_call') {
            currentCalls[event.index] = {
                id: event.step.id,
                name: event.step.name,
                arguments: ''
            };
            if (event.step.arguments) {
                if (typeof event.step.arguments === 'object') {
                    currentCalls[event.index].arguments = JSON.stringify(event.step.arguments);
                } else {
                    currentCalls[event.index].arguments = event.step.arguments;
                }
            }
        }
    } else if (evType === 'step.delta') {
        if (event.delta.type === 'arguments_delta') {
            if (currentCalls[event.index]) {
                currentCalls[event.index].arguments += event.delta.arguments ?? '';
            }
        } else if (event.delta.type === 'text') {
            process.stdout.write(event.delta.text ?? '');
        }
    } else if (evType === 'step.stop') {
        toolCalls = currentCalls.map((call) => ({
            type: 'function_call',
            id: call.id,
            name: call.name,
            arguments: call.arguments ? JSON.parse(call.arguments) : {}
        }));
        console.log('\nFinal tool calls ready to execute:');
        console.log(JSON.stringify(toolCalls, null, 2));
    }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    "input": "What is the weather in Paris?",
    "tools": [{
        "type": "function",
        "name": "get_weather",
        "description": "Gets the weather for a given location.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "The city and state"}
            },
            "required": ["location"]
        }
    }],
    "stream": true
}'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();
Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function function = Function.builder()
    .name("custom_function")
    .description("A custom function.")
    .parameters(parameters)
    .build();

CreateModelInteraction params = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Call the function."))
    .tools(Arrays.asList(function))
    .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof FunctionCallStep) {
      FunctionCallStep fc = (FunctionCallStep) step;
      System.out.println("Function: " + fc.name().orElse(""));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "strings"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

type callState struct {
    id        string
    name      string
    arguments *strings.Builder
}

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    weatherTool := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Gets the weather for a given location."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{
                    "type":        "string",
                    "description": "The city and state",
                },
            },
            "required": []string{"location"},
        },
    })

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model:  interactions.Model("gemini-3.8-flash"),
                Input:  interactions.NewInteractionsInput("What is the weather in Paris?"),
                Tools:  []interactions.Tool{weatherTool},
                Stream: genai.Ptr(true),
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }
    defer resp.InteractionSSEStreamEvent.Close()

    currentCalls := make(map[int]*callState)
    var toolCalls []map[string]any

    for resp.InteractionSSEStreamEvent.Next() {
        event := resp.InteractionSSEStreamEvent.Value()
        if stepStart := event.GetDataStepStart(); stepStart != nil {
            if fcStep := stepStart.GetStepFunctionCall(); fcStep != nil {
                idx := stepStart.Index
                builder := &strings.Builder{}
                if len(fcStep.Arguments) > 0 {
                    builder.WriteString(fmt.Sprint(fcStep.Arguments))
                }
                currentCalls[idx] = &callState{
                    id:        fcStep.ID,
                    name:      fcStep.Name,
                    arguments: builder,
                }
            }
        } else if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            idx := stepDelta.Index
            if argsDelta := stepDelta.GetDeltaArgumentsDelta(); argsDelta != nil {
                if argsDelta.Arguments != nil {
                    if call, ok := currentCalls[idx]; ok {
                        call.arguments.WriteString(*argsDelta.Arguments)
                    }
                }
            } else if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        } else if completed := event.GetDataInteractionCompleted(); completed != nil {
            for _, call := range currentCalls {
                toolCalls = append(toolCalls, map[string]any{
                    "type":      "function_call",
                    "id":        call.id,
                    "name":      call.name,
                    "arguments": call.arguments.String(),
                })
            }
            fmt.Println("\nFinal tool calls ready to execute:")
            fmt.Println(toolCalls)
        }
    }
}
```
{% /tab %}
{% /tabs %}
## Best practices {% id="best-practices" %}

* **Function and Parameter Descriptions:** Be clear and specific.
* **Naming:** Use descriptive names without spaces or special characters.
* **Strong Typing:** Use specific types (integer, string, enum).
* **Tool Selection:** Keep active set to 10-20 tools maximum.
* **Prompt Engineering:** Provide context and instructions.
* **Validation:** Validate function calls before executing.
* **Error Handling:** Implement robust error handling.
* **Security:** Use appropriate authentication for external APIs.

## Workarounds for pre-tool text requirements {% id="workarounds-for-pre-tool-text-requirements" %}

**Issue:** If your prompt requires the model to output structured text (XML, YAML, JSON, etc.) (e.g., `<UPDATE>...</UPDATE>`) immediately before making a tool call, the tool call may occasionally fail with `Malformed_Function_Call`.

**Solutions:** The following workarounds resolve this issue:

* **PREFERRED:** Instruct the model to put its pre-tool notes inside a dedicated `update()` function call instead of raw text (details below).
* Instruct the model to write notes as Markdown headers (`# UPDATE`, `## PLAN`) instead of structured text.
* Do not require the model to output text before tool calls.

### Preferred workaround: Wrap working notes in a dedicated function call {% id="preferred-workaround" %}

Instead of the original instruction:

```html
Before calling a tool, in every response you MUST first output a single `<UPDATE>` part as specified, don't skip this part or any of required sub-tags within `<UPDATE>`.
```

Use this updated instruction:

```html
Before calling any other tool, in every response you MUST first call `update` with all required parameters (previous_step, plan, next_step, external).
```

And update all references to the old `<UPDATE>` XML format in the customer request. Then add the corresponding function declaration for the update function:

```json
{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}
```

Then the model will make two calls in the same step: the `update()` call that replaces the structured XML, and the actual function call it wants to make.

## Notes and limitations {% id="limitations" %}

* Only a [subset of the OpenAPI schema](https://ai.google.dev/api/rest/v1beta/cachedContents#FunctionDeclaration) is supported.
* For `any` mode, very large or deeply nested schemas may be rejected.
* Supported parameter types in Python are limited.

### Simplifying complex function schemas {% id="simplifying-complex-schemas" %}

When you use `any` mode or define complex parameter schemas, the API compiles
your function declarations into a state machine that constrains token
generation. This state machine enforces limits on total states, branching
paths, and nesting depth. If the combined complexity of your tools exceeds
these limits, the API rejects the request with a `400 INVALID_ARGUMENT` error.

To fix schema rejection errors, reduce the structural depth and branching
factor of your declarations. You can simplify complex function schemas in
several ways:

* **Split large tool sets and move rules to descriptions:** Constrained
  decoding evaluates all declared tools together. Limit the number of functions
  in a single request and split monolithic functions into smaller, focused
  tools. Move complex formatting rules into field `description` properties or
  system instructions, which guide the model without expanding the grammar.
* **Flatten nested objects and bound recursion:** Replace deeply nested object
  hierarchies with flatter structures. If you use `$defs` and `$ref` for
  recursive types, make the recursive reference optional or nullable. Avoid
  recursing through required properties or arrays with `minItems` greater than
  zero.
* **Reduce branching from optional fields, enums, and unions:** Optional
  properties, `enum` values, and `anyOf` branches multiply the branching paths
  in the output grammar. Mark properties as `required` where possible and allow
  `null` values when a field can be empty. Trim large `enum` lists and simplify
  `anyOf` unions, or include the constraint in your prompt (for example, with a
  Pydantic schema) as a softer restriction.
* **Shorten property names and drop array bounds:** Property keys consume
  states proportional to their character length. Array bounds such as
  `minItems` and `maxItems` also duplicate the item schema for each counted
  position. Use concise property names, remove unused fields, and either
  include array bounds in your prompt (for example, with a Pydantic schema) as
  a softer restriction or check array lengths in your application code.

# Long context
Source: https://aistudio.google.com/docs/long-context
Description: Learn about how to get started building with long context (1 million context window) on Gemini.

Many Gemini models come with large context windows of 1 million or more tokens.
Historically, large language models (LLMs) were significantly limited by
the amount of text (or tokens) that could be passed to the model at one time.
The Gemini long context window unlocks many new use cases and developer
paradigms.

The code you already use for cases like [text
generation](/docs/text-generation) or [multimodal
inputs](/docs/image-understanding) will work without any changes with long
context.

This document gives you an overview of what you can achieve using models with
context windows of 1M and more tokens. The page gives a brief overview of
a context window, and explores how developers should think about long context,
various real world use cases for long context, and ways to optimize the usage
of long context.

For the context window sizes of specific models, see the
[Models](/docs/models) page.

## What is a context window? {% id="what-is-context-window" %}

The basic way you use the Gemini models is by passing information (context)
to the model, which will subsequently generate a response. An analogy for the
context window is short term memory. There is a limited amount of information
that can be stored in someone's short term memory, and the same is true for
generative models.

In Gemini 4 (`gemini-4-argon`), the 1M-token context window is **shared across input, thinking, and output tokens**, and the model can generate up to 1M output tokens using [long decode](/docs/long-decode). If your input tokens plus `max_output_tokens` exceed 1,048,576 tokens, the API automatically caps the output limit to the remaining space in the context window (`1,048,576` minus your input tokens). Earlier Gemini 3 and 2.5 models use separate 1M input and 64K output budgets.

You can read more about how models work in our [generative models
guide](/docs/prompting-strategies).

## Getting started with long context {% id="getting-started-with-long-context" %}

Earlier versions of generative models were only able to process 8,000
tokens at a time. Newer models pushed this further by accepting 32,000 or even
128,000 tokens. Gemini is the first model capable of accepting 1 million tokens.

In practice, 1 million tokens would look like:

- 50,000 lines of code (with the standard 80 characters per line)
- All the text messages you have sent in the last 5 years
- 8 average length English novels
- Transcripts of over 200 average length podcast episodes

The more limited context windows common in many other models often require
strategies like arbitrarily dropping old messages, summarizing content, using
RAG with vector databases, or filtering prompts to save tokens.

While these techniques remain valuable in specific scenarios, Gemini's extensive
context window invites a more direct approach: providing all relevant
information upfront. Because Gemini models were purpose-built with massive
context capabilities, they demonstrate powerful in-context learning. For
example, using only in-context instructional materials (a 500-page reference
grammar, a dictionary, and ≈400 parallel sentences), Gemini
[learned to translate](https://storage.googleapis.com/deepmind-media/gemini/gemini_v1_5_report.pdf)
from English to Kalamang—a Papuan language with
fewer than 200 speakers—with quality similar to a human learner using the same
materials. This illustrates the paradigm shift enabled by Gemini's long context,
empowering new possibilities through robust in-context learning.

## Long context use cases {% id="long-context-use-cases" %}

While the standard use case for most generative models is still text input, the
Gemini model family enables a new paradigm of multimodal use cases. These
models can natively understand text, video, audio, and images. They are
accompanied by the [Gemini API that takes in multimodal file
types](/docs/files#prompt-guide) for
convenience.

### Long form text {% id="long-form-text" %}

Text has proved to be the layer of intelligence underpinning much of the
momentum around LLMs. As mentioned earlier, much of the practical limitation of
LLMs was because of not having a large enough context window to do certain
tasks. This led to the rapid adoption of retrieval augmented generation (RAG)
and other techniques which dynamically provide the model with relevant
contextual information. Now, with larger and larger context windows, there are
new techniques becoming available which unlock new use cases.

Some emerging and standard use cases for text based long context include:

- Summarizing large corpuses of text
    - Previous summarization options with smaller context models would require
        a sliding window or another technique to keep state of previous sections
        as new tokens are passed to the model

- Question and answering
    - Historically this was only possible with RAG given the limited amount of
        context and models' factual recall being low

- Agentic workflows
    - Text is the underpinning of how agents keep state of what they have done
        and what they need to do; not having enough information about the world
        and the agent's goal is a limitation on the reliability of agents

[Many-shot in-context learning](https://arxiv.org/pdf/2404.11018) is one of the
most unique capabilities unlocked by long context models. Research has shown
that taking the common "single shot" or "multi-shot" example paradigm, where the
model is presented with one or a few examples of a task, and scaling that up to
hundreds, thousands, or even hundreds of thousands of examples, can lead to
novel model capabilities. This many-shot approach has also been shown to perform
similarly to models which were fine-tuned for a specific task. For use cases
where a Gemini model's performance is not yet sufficient for a production
rollout, you can try the many-shot approach. As you might explore later in the
long context optimization section, context caching makes this type of high input
token workload much more economically feasible and even lower latency in some
cases.

### Long form video {% id="long-form-video" %}

Video content's utility has long been constrained by the lack of accessibility
of the medium itself. It was hard to skim the content, transcripts often failed
to capture the nuance of a video, and most tools don't process image, text, and
audio together. With Gemini, the long-context text capabilities translate to
the ability to reason and answer questions about multimodal inputs with
sustained performance.

Some emerging and standard use cases for video long context include:

- Video question and answering
- Video memory, as shown with [Google's Project Astra](https://deepmind.google/technologies/gemini/project-astra/)
- Video captioning
- Video recommendation systems, by enriching existing metadata with new
    multimodal understanding

- Video customization, by looking at a corpus of data and associated video
    metadata and then removing parts of videos that are not relevant to the
    viewer

- Video content moderation
- Real-time video processing

When working with videos, it is important to consider how the [videos are
processed into tokens](/docs/tokens#video), which affects
billing and usage limits. You can learn more about prompting with video files in
the [Prompting
guide](/docs/files#prompt-guide).

### Long form audio {% id="long-form-audio" %}

The Gemini models were the first natively multimodal large language models
that could understand audio. Historically, the typical developer workflow would
involve stringing together multiple domain specific models, like a
speech-to-text model and a text-to-text model, in order to process audio. This
led to additional latency required by performing multiple round-trip requests
and decreased performance usually attributed to disconnected architectures of
the multiple model setup.

Some emerging and standard use cases for audio context include:

- Real-time transcription and translation
- Podcast / video question and answering
- Meeting transcription and summarization
- Voice assistants

You can learn more about prompting with audio files in the [Prompting
guide](/docs/files#prompt-guide).

## Long context optimizations {% id="long-context-optimizations" %}

The primary optimization when working with long context and the Gemini
models is to use [context
caching](/docs/caching). Beyond the previous
impossibility of processing lots of tokens in a single request, the other main
constraint was the cost. If you have a "chat with your data" app where a user
uploads 10 PDFs, a video, and some work documents, you would historically have
to work with a more complex retrieval augmented generation (RAG) tool /
framework in order to process these requests and pay a significant amount for
tokens moved into the context window. Now, you can cache the files the user
uploads and pay to store them on a per hour basis. The input / output cost per
request with Gemini Flash for example is ~4x less than the standard
input / output cost, so if
the user chats with their data enough, it becomes a huge cost saving for you as
the developer.

## Long context limitations {% id="long-context-limitations" %}

In various sections of this guide, we talked about how Gemini models achieve
high performance across various needle-in-a-haystack retrieval evals. These
tests consider the most basic setup, where you have a single needle you are
looking for. In cases where you might have multiple "needles" or specific pieces
of information you are looking for, the model does not perform with the same
accuracy. Performance can vary to a wide degree depending on the context. This
is important to consider as there is an inherent tradeoff between getting the
right information retrieved and cost. You can get ~99% on a single query, but
you have to pay the input token cost every time you send that query. So for 100
pieces of information to be retrieved, if you needed 99% performance, you would
likely need to send 100 requests. This is a good example of where context
caching can significantly reduce the cost associated with using Gemini models
while keeping the performance high.

## FAQs {% id="faqs" %}

### Where is the best place to put my query in the context window? {% id="where-is-the-best-place-to-put-my-query-in-the-context-window" %}

In most cases, especially if the total context is long, the model's
performance will be better if you put your query / question at the end of the
prompt (after all the other context).

### Do I lose model performance when I add more tokens to a query? {% id="do-i-lose-model-performance-when-i-add-more-tokens-to-a-query" %}

Generally, if you don't need tokens to be passed to the model, it is best to
avoid passing them. However, if you have a large chunk of tokens with some
information and want to ask questions about that information, the model is
highly capable of extracting that information (up to 99% accuracy in many
cases).

### How can I lower my cost with long-context queries? {% id="how-can-i-lower-my-cost-with-long-context-queries" %}

If you have a similar set of tokens / context that you want to re-use many
times, [context caching](/docs/caching) can help reduce the costs
associated with asking questions about that information.

### Does the context length affect the model latency? {% id="does-the-context-length-affect-the-model-latency" %}

There is some fixed amount of latency in any given request, regardless of the
size, but generally longer queries will have higher latency (time to first
token).

# Long decode
Source: https://aistudio.google.com/docs/long-decode
Description: Use long decode with Gemini 4 Argon on the Interactions API to generate past 64K tokens up to the 1M-token context window with background execution or client-side continuation.

By default, Gemini 4 Argon generates up to 64K tokens (65,536) of thinking and output per response. Long decode lets you raise `max_output_tokens` past 64K for hard reasoning, math, and coding tasks, up to the unified 1M-token context window (1,048,576 tokens shared across input, thinking, and output). On the Interactions API, you can run long decode with [background execution](/docs/background-execution) so our servers run every hop for you, or in the foreground with [client-side continuation](/docs/long-decode#client-side-continuation).

## How long decode works {% id="how-long-decode-works" %}

Generating hundreds of thousands of tokens can take longer than a single HTTP request can stay open, so long decode splits generation into sequential hops that continue from where the previous hop stopped: up to 64K tokens (65,536) per background or streaming hop, or up to 32K tokens (32,768) per non-streaming hop.

When you set `background: true` and `max_output_tokens` greater than 65,536 on the Interactions API:

1. The request runs asynchronously and returns an interaction with `status="in_progress"`.
2. If the response reaches 64K tokens without finishing, the server starts a continuation hop with the tokens generated so far.
3. This repeats until the model finishes or reaches `max_output_tokens`.
4. When you poll the interaction, you get the combined thinking and output from all hops in a single interaction.

To run continuation hops from your client instead, see [Choose how to run long decode](/docs/long-decode#choose-how-to-run-long-decode).

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete, rigorous proof of the prime number theorem.",
    background=True,
    generation_config={
        "max_output_tokens": 262144,
        "thinking_level": "high",
    },
)

while interaction.status in ("in_progress", "queued"):
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

# Each hop adds a model_output step, so join the text of all of them.
text = "".join(
    content.text
    for step in interaction.steps
    if step.type == "model_output"
    for content in step.content
    if content.type == "text"
)
print(text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
  model: "gemini-4-argon",
  input: "Write a complete, rigorous proof of the prime number theorem.",
  background: true,
  generation_config: {
    max_output_tokens: 262144,
    thinking_level: "high",
  },
});

while (interaction.status === "in_progress" || interaction.status === "queued") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await client.interactions.get(interaction.id);
}

// Each hop adds a model_output step, so join the text of all of them.
const text = interaction.steps
  .filter((step) => step.type === "model_output")
  .flatMap((step) => step.content ?? [])
  .filter((content) => content.type === "text")
  .map((content) => content.text)
  .join("");
console.log(text);
console.log("Status:", interaction.status);
console.log("Usage:", interaction.usage);
```
{% /tab %}
{% tab label="REST" %}
```bash
# 1. Create the background interaction. It returns an ID right away.
ID=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-argon",
    "input": "Write a complete, rigorous proof of the prime number theorem.",
    "background": true,
    "generation_config": {"max_output_tokens": 262144, "thinking_level": "high"}
  }' | jq -r '.id')

# 2. Poll until the status is no longer in_progress or queued.
#    The REST response has no output_text field, so join the text of every model_output step.
while true; do
  RESP=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$ID" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status')
  if [[ "$STATUS" != "in_progress" && "$STATUS" != "queued" ]]; then
    echo "$RESP" | jq -r '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
    echo "$RESP" | jq '{status, usage}'
    break
  fi
  sleep 5
done
```
{% /tab %}
{% /tabs %}

## Output limits {% id="output-limits" %}

Streaming and non-streaming interactions default to a 64K output token limit, so responses up to 64K tokens need no code changes. To generate past 64K tokens, raise `max_output_tokens` and use background execution or client-side continuation.

| How you create the interaction | Output limit |
| :--- | :--- |
| `background: false`, `max_output_tokens` not set | 65,536 tokens |
| `background: false`, `max_output_tokens` greater than 65,536, `automatic_continuation: true` (SDK default) | Your `max_output_tokens`, up to 1,048,576 minus your input |
| `background: false`, `max_output_tokens` greater than 65,536, `automatic_continuation: false` or REST | 65,536 tokens per streaming hop or 32,768 per non-streaming hop. Loop with `continuation_token` to generate up to your `max_output_tokens`. |
| `background: true`, `max_output_tokens` not set | 65,536 tokens |
| `background: true`, `max_output_tokens` greater than 65,536 | Your `max_output_tokens`, up to 1,048,576 minus your input |

{% callout type="warning" %}
Always set `max_output_tokens` greater than 65,536 for long decode. Also check the value in your agent framework or evaluation tool. A low value, such as 8,192, stops the model before it finishes thinking.
{% /callout %}

## When to use long decode {% id="when-to-use-long-decode" %}

Most requests finish within 64K tokens. Use long decode only when one response needs more thinking and output than that.

| Workload | Use long decode? | Why |
| :--- | :--- | :--- |
| Hard math, science, research, and formal proofs | Yes | The model can spend more than 64K tokens to explore and check its reasoning. |
| The hardest coding and agentic tasks | Yes | Some tasks need more than 64K tokens of thinking and code in one response. Most coding and agentic tasks finish under 64K. |
| Evaluation tools that stop at the output limit | Yes | Long decode prevents cut-off answers when the model spends a whole 64K response on thinking. |
| Chat, Q&A, summarization, classification, and extraction | No | These tasks finish well under 32K tokens. |
| Requests for a fixed length, such as "write a 700,000-word book" | No | The model doesn't follow length targets. |
| Agents that call tools in many short turns | No | Each turn is short. Large outputs on each turn fill the shared context window fast. |
| Prompts near the input limit | No | Output can use only 1,048,576 tokens minus your input. |
| Latency-sensitive requests | No | Long decode can run for several minutes. |

Setting a high `max_output_tokens` gives the model room to think longer on hard problems, but the model still decides how much to write. To control how much reasoning effort the model uses, set [`thinking_level`](/docs/thinking).

## Choose how to run long decode {% id="choose-how-to-run-long-decode" %}

Background execution is the easiest way to run long decode on the Interactions API. Our servers run every hop, so a dropped client connection won't interrupt generation. Client-side continuation, where the Google GenAI SDK or your own code starts each hop, is also available on the Interactions API for foreground calls, stateless requests, or managing your own retry resilience.

| | Background execution (Interactions API) | Client-side continuation (Interactions API) |
| :--- | :--- | :--- |
| **Who starts each hop** | Our servers | The Google GenAI SDK (by default), or your own code |
| **Tokens per request** | Your `max_output_tokens`, in one interaction (up to 64K per internal hop) | 64K per stream, 32K per non-streaming request |
| **Run time** | Up to 24 hours | 20 minutes per streaming hop, 10 minutes per non-streaming hop |
| **Storage** | Requires `store: true` | Stored by default (`store: true`), or stateless with `store: false` |
| **Best for** | The easiest way to run long decode | Foreground calls, stateless apps, or finer-grained control over retries, so you can build your own backoff, error handling, and resilience |

If you use the GenerateContent API instead, see [long decode with the GenerateContent API](/docs/long-decode?generate-content=true).

## Client-side continuation {% id="client-side-continuation" %}

The following sections apply when `background: false` (the default). Your client drives each continuation hop instead of our servers, either automatically with the Google GenAI SDK or with your own loop.

### Automatic continuation with the SDK {% id="automatic-continuation" %}

{% callout type="note" %}
Client-side continuation requires Google GenAI SDK version 2.34.0+ for Python, 2.32.0+ for JavaScript, 1.77.0+ for Go, 1.80.0+ for Java, or 1.28.0+ for .NET.
{% /callout %}

When `max_output_tokens` exceeds the single-hop limit, the Google GenAI SDK runs the continuation hops and returns one combined interaction. For REST or custom loop control, see [Client-side continuation with your own loop](/docs/long-decode#client-side-loop).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete, rigorous proof of the prime number theorem.",
    generation_config={
        "max_output_tokens": 262144,
        "thinking_level": "high",
    },
)

print(interaction.output_text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-4-argon",
  input: "Write a complete, rigorous proof of the prime number theorem.",
  generation_config: {
    max_output_tokens: 262144,
    thinking_level: "high",
  },
});

console.log(interaction.output_text);
console.log("Status:", interaction.status);
console.log("Usage:", interaction.usage);
```
{% /tab %}
{% /tabs %}

Keep these SDK behaviors in mind:

* **Save the merged response:** `interactions.create` merges text, steps, and usage across all hops, using the final hop's `id`. Because each hop is stored separately, `interactions.get` returns only the last hop's output, so save the response from `create`. Passing that `id` as `previous_interaction_id` on the next turn keeps the full history.
* **Timeouts:** Client `http_options` sets the HTTP timeout for each hop. Passing `timeout` to `interactions.create` caps total time across all hops.
* **Interrupted runs:** If a hop fails after earlier progress, the SDK raises `ContinuationInterruptedError`. For non-streaming calls, `partial_interaction` holds the merged output from completed hops. To resume, pass the error's interaction ID and `continuation_token` to `interactions.create` (or resend `input` when `store` is `false`).

### Client-side continuation with your own loop {% id="client-side-loop" %}

To call REST directly or manage retries, backoff, and logging between hops yourself, run the continuation loop in your code (in the SDK, disable `automatic_continuation`). Keep the same model, tools, system instruction, and generation config on each hop, and resend the prompt instead of the previous interaction ID if storage is disabled.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete, rigorous proof of the prime number theorem.",
    automatic_continuation=False,
    generation_config={
        "max_output_tokens": 262144,
        "thinking_level": "high",
    },
)
full_text = interaction.output_text or ""

while interaction.status == "requires_continuation":
    interaction = client.interactions.create(
        model="gemini-4-argon",
        previous_interaction_id=interaction.id,
        continuation_token=interaction.continuation_token,
        automatic_continuation=False,
        generation_config={
            "max_output_tokens": 262144,
            "thinking_level": "high",
        },
    )
    full_text += interaction.output_text or ""

print(full_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
  model: "gemini-4-argon",
  input: "Write a complete, rigorous proof of the prime number theorem.",
  automatic_continuation: false,
  generation_config: {
    max_output_tokens: 262144,
    thinking_level: "high",
  },
});
let fullText = interaction.output_text ?? "";

while (interaction.status === "requires_continuation") {
  interaction = await client.interactions.create({
    model: "gemini-4-argon",
    previous_interaction_id: interaction.id,
    continuation_token: interaction.continuation_token,
    automatic_continuation: false,
    generation_config: {
      max_output_tokens: 262144,
      thinking_level: "high",
    },
  });
  fullText += interaction.output_text ?? "";
}

console.log(fullText);
```
{% /tab %}
{% tab label="REST" %}
```bash
RESP=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-argon",
    "input": "Write a complete, rigorous proof of the prime number theorem.",
    "generation_config": {"max_output_tokens": 262144, "thinking_level": "high"}
  }')

while [[ "$(echo "$RESP" | jq -r '.status')" == "requires_continuation" ]]; do
  echo "$RESP" | jq -rj '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
  PREV_ID=$(echo "$RESP" | jq -r '.id')
  TOKEN=$(echo "$RESP" | jq -r '.continuation_token')
  RESP=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"model\": \"gemini-4-argon\",
      \"previous_interaction_id\": \"$PREV_ID\",
      \"continuation_token\": \"$TOKEN\",
      \"generation_config\": {\"max_output_tokens\": 262144, \"thinking_level\": \"high\"}
    }")
done

echo "$RESP" | jq -r '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
```
{% /tab %}
{% /tabs %}

## Stream long decode {% id="streaming" %}

To stream outputs and thought summaries as they arrive, add `stream: true` and `thinking_summaries: "auto"`. Long streams can drop, so your client must reconnect. Follow the reconnect pattern in the [background execution guide](/docs/background-execution). Long decode adds these rules:

* **Save the interaction ID:** Read it from the `interaction.created` event.
* **Save every `event_id`:** An `event_id` can arrive on `interaction.status_update` events, not only on text deltas.
* **Reconnect with `last_event_id`:** Call `interactions.get` with `stream: true` and the last `event_id`. The stream continues after that event.
* **Read to the end:** After you reconnect, read the stream to the end before you check the status. The server replays missed events, even after the interaction completes.
* **Set long timeouts:** Set HTTP read timeouts to 15 to 20 minutes per stream.
* **Expect output in 5K-token chunks:** After the first 32K tokens, the stream sends output in chunks of about 5,000 tokens at each checkpoint. Pauses between chunks are normal. The interaction isn't stuck, so keep the connection open.

For foreground streams with the Google GenAI SDK, the SDK chains continuation hops into a single stream:

* **Keep reading across hops:** Each hop is its own interaction and emits `interaction.created` and `interaction.completed` events. Don't reset your stream parser on `interaction.created`, and don't stop on `interaction.completed` while status is `requires_continuation`. Save the final hop's ID if you continue the conversation.
* **Handle mid-hop disconnects:** If a connection drops at a checkpoint before new deltas arrive, the SDK reconnects for you. If the stream already yielded deltas after the latest checkpoint, the SDK raises `ContinuationInterruptedError` to avoid duplicate output.

## Interaction status {% id="background-status" %}

A background interaction can run for up to 24 hours. Once the status is no longer `in_progress` or `queued`, handle the interaction status using this table:

| Status | Meaning | What to do |
| :--- | :--- | :--- |
| `completed` | The model finished. | Join the `model_output` steps in `steps` and read `usage`. To continue the conversation, pass this interaction's `id` as `previous_interaction_id`. |
| `requires_continuation` | A foreground hop reached its single-request cap (32K non-streaming or 64K streaming) with token budget left. | The Google GenAI SDK continues this for you by default. In REST, send the next hop with `previous_interaction_id` and `continuation_token`. |
| `requires_action` | The model asked for a tool call. | Run the tool. Then send the result with this interaction's `id`. |
| `incomplete` | The model used all of `max_output_tokens`. Text can be empty if the model was still thinking. | Resume with `previous_interaction_id`, `continuation_token`, and a higher `max_output_tokens`, or send the request again with a higher `max_output_tokens`. |
| `failed` | The server couldn't finish, or the interaction ran longer than 24 hours. | Retry the request. If it fails again, share the interaction `id` with support. |
| `cancelled` | You cancelled the interaction. | Read `usage` to see the billed tokens. |

To stop a running interaction, call `client.interactions.cancel(id=interaction.id)` in Python, `client.interactions.cancel(interaction.id)` in JavaScript, or `POST /v1beta/interactions/{id}/cancel` in REST.

## Set `max_output_tokens` {% id="set-max-output-tokens" %}

`max_output_tokens` sets the combined limit for thinking and output across the interaction. Lowering it doesn't make the model think more concisely, and instead cuts the response off sooner.

| Your workload | Recommended `max_output_tokens` |
| :--- | :--- |
| Existing apps with a limit lower than 32K | Raise to 32,768. Background execution isn't needed. |
| Long coding and agentic tasks | Start at 65,536 (the default). Background execution isn't needed. |
| Complex reasoning, hard math, science, and proofs | Set `background: true` (or use client-side continuation) and start at 262,144, up to 1,048,576 minus your input tokens. |

To use fewer tokens, lower `thinking_level`. Use `high` for the hardest reasoning tasks. Use `medium` (the default) for most coding and agentic work.

## Count tokens {% id="count-tokens" %}

`interaction.usage` reports the totals across all hops. Read these fields: `total_input_tokens`, `total_cached_tokens`, `total_output_tokens`, `total_thought_tokens`, and `total_tokens`.

`total_input_tokens` adds up the input tokens of every hop. Each hop sends your prompt plus everything generated so far back to the model as input, so the same tokens are counted again in every later hop. For example, a 1,000-token prompt that produces 200,000 tokens of thinking and output takes four 64K hops (or seven 32K non-streaming hops):

| Hop | Input sent to the model | Input tokens |
| :--- | :--- | ---: |
| 1 | Prompt | 1,000 |
| 2 | Prompt + hop 1 | 66,536 |
| 3 | Prompt + hops 1 and 2 | 132,072 |
| 4 | Prompt + hops 1 to 3 | 197,608 |
| **Total** | | **397,216** |

`total_input_tokens` reports about 397,000 tokens (with repeated hop inputs automatically discounted 95% by implicit caching), even though the actual context size is only about 201,000 tokens: the 1,000-token prompt plus 200,000 tokens of thinking and output.

{% callout type="warning" %}
`total_input_tokens` is the sum of every hop's input, not the size of your context. Don't use it to decide when to summarize or trim your conversation history (context compaction). To estimate the context size, add your prompt size (or `usage.initial_input_tokens` on non-streaming SDK responses) to `total_output_tokens` and `total_thought_tokens`.
{% /callout %}

During a stream, `interaction.status_update` and `interaction.completed` events include `usage` (cumulative for that hop, or for the full interaction in background mode). Within a background stream or a single foreground hop, read the latest `usage` value instead of adding them together. In a foreground stream, each hop is a separate interaction, so sum the final `usage` of each hop.

## Understand billing {% id="understand-billing" %}

You pay for every token in every hop, including hops that contain only thinking.

* **Cache discount:** Implicit caching discounts the repeated input in each hop by 95%. Cached input costs $0.10 per 1M tokens instead of $2.00 during the introductory period.
* **Cancelled and failed interactions:** You pay for all work completed before the interaction ends.

## Troubleshooting {% id="troubleshooting" %}

| Symptom | Cause and fix |
| :--- | :--- |
| Output stops at 64K | Set `max_output_tokens` greater than 65,536, and use background execution or upgrade the Google GenAI SDK. |
| Output stops with status `requires_continuation` | The hop reached its single-request cap with budget left. Upgrade the SDK, enable `automatic_continuation`, or add a continuation loop. |
| 400: "store=true is required for background interactions" | Background execution needs `store: true`. |
| Status `incomplete` with empty text | The model used all tokens on thinking. Raise `max_output_tokens` or lower `thinking_level`. |
| Context compaction starts too early | Your agent framework or evaluation tool reads `total_input_tokens`. See [Count tokens](/docs/long-decode#count-tokens). |

## Limitations {% id="limitations" %}

* **Earlier SDKs:** Versions earlier than Python 2.34.0, JavaScript 2.32.0, Go 1.77.0, Java 1.80.0, and .NET 1.28.0 don't continue foreground interactions.
* **No length targets:** The model doesn't follow token-length or word-count targets.

## Next steps {% id="next-steps" %}

* [What's new in Gemini 4 Argon](/docs/latest-model)
* [Background execution](/docs/background-execution)
* [Thinking](/docs/thinking)
* [Long decode with the GenerateContent API](/docs/long-decode?generate-content=true)

# Agents overview
Source: https://aistudio.google.com/docs/agents
Description: Build agents that reason, write code, manage files, and browse the web with the Gemini API.

Managed agents on the Gemini API give you a configurable agent
harness. A single API call provisions a Linux sandbox where the agent reasons,
executes code, manages files, and browses the web autonomously.

{% card-grid %}
{% card
  href="/docs/managed-agents-quickstart"
  icon="rocket_launch"
  title="Quickstart"
  description="Make your first agent call, stream responses, and build a custom
    agent."
/%}
{% card
  href="/docs/antigravity-agent"
  icon="smart_toy"
  title="Antigravity Agent"
  description="Capabilities, tools, multimodal input, and pricing for the
    default agent."
/%}
{% card
  href="/docs/aistudio-agents"
  icon="experiment"
  title="Agents in AI Studio"
  description="Visual playground for prototyping agents without writing code."
/%}
{% /card-grid %}

## Available managed agents {% id="managed-agents" %}

* **[Antigravity agent](/docs/antigravity-agent)**: General-purpose
    managed agent built with Gemini 3.8 Flash. Runs code, manages files, and
    searches the web inside a secure Linux sandbox hosted by Google. You can
    extend it with your own instructions, skills, and data to
    [build a custom agent](/docs/custom-agents).

* **[Deep Research](/docs/deep-research)**: Autonomous research agent
    that plans, executes, and synthesizes multi-step research tasks for use
    cases like market analysis, due diligence, and literature reviews.

## Security and best practices {% id="security-best-practices" %}

{% callout type="note" %}
Note: Managed agents are in **Public Preview**. Review the agent's actions and
outputs before relying on them in sensitive workflows.
{% /callout %}

Every agent runs in a sandboxed environment that is isolated at the OS level.
The sandbox has unrestricted outbound network access by default. You can
restrict or disable network access using an allowlist.

### Network access {% id="network-access" %}

By default, environments have unrestricted outbound network access. Use a
`network` allowlist to restrict outbound traffic to specific domains or
wildcard patterns. For configuration details, see
[Network Allow List](/docs/aistudio-agents#network-allow-list) (AI
Studio) or [Network rules](/docs/custom-agents#with-network-rules)
(API).

### External tools and APIs {% id="external-tools-and-apis" %}

You can connect external tools and APIs to extend the agent. Only use tools
from trusted sources and scope permissions to the minimum required. Store
secrets as managed credentials and reference them by ID, so the egress proxy
injects them at request time and they are never exposed inside the sandbox. The agent may use any credential it has access to,
so only provide credentials whose full scope you are willing to grant.

* Use least-privilege service accounts or API keys.
* Prefer short-lived tokens over long-lived keys.
* Only provide credentials whose full scope you are willing to grant.
* Rotate credentials on a regular schedule.

For the credential types and management operations, see
[Credentials](/docs/agent-credentials). You can also set headers inline on an
allowlist rule, see [Network
configuration](/docs/agent-environment#network-configuration).

### Human oversight {% id="human-oversight" %}

Always verify outputs (generated code, data transformations, configuration
changes) before deploying them, especially for tasks that modify data or
interact with external systems.

## Pricing {% id="pricing" %}

Managed agents use a [pay-as-you-go model](/docs/pricing#pricing-for-agents) based on Gemini model tokens and tool usage. A single interaction can trigger multiple reasoning loops, typically consuming 100k to 3M tokens. Environment compute is **not billed** during the preview. See [estimated costs](/docs/antigravity-agent#availability-and-pricing) for per-task breakdowns.

## Limits {% id="limits" %}

| Limit | Description |
| :--- | :--- |
| **Environment Lifetime** | Environments are permanently deleted after 7 days of inactivity. |
| **VM Spin-down** | VMs shut down after a brief period of inactivity to conserve resources. The next request restores the state (with a cold start). |
| **Pre-installed Software** | Ubuntu-based environment with Python 3.12 and Node.js 22. For more information on the environment's base image, see [Pre-installed software](/docs/agent-environment#pre-installed-software). |
| **Max agents** | You can have up to 1,000 managed agents. |

## Agent frameworks {% id="agent-frameworks" %}

You can also build agents with Gemini using these frameworks and SDKs:

* [**LangChain / LangGraph**](/docs/langgraph-example): Build
    stateful, complex application flows and multi-agent systems using graph
    structures.

* [**LlamaIndex**](/docs/llama-index): Connect Gemini agents to
    your private data for RAG-enhanced workflows.

* [**CrewAI**](/docs/crewai-example): Orchestrate collaborative,
    role-playing autonomous AI agents.

* [**Vercel AI SDK**](/docs/vercel-ai-sdk-example): Build
    AI-powered user interfaces and agents in JavaScript/TypeScript.

* [**Google ADK**](https://google.github.io/adk-docs/get-started/python/): An
    open-source framework for building and orchestrating interoperable AI
    agents.

* [**Antigravity SDK**](https://antigravity.google/product/antigravity-sdk): Build
    autonomous AI agents using the same tools, agent loop, and context
    management that power Google Antigravity, programmable in Python.

# Managed agents quickstart
Source: https://aistudio.google.com/docs/managed-agents-quickstart
Description: Quickstart guide for making your first call to the manage agents API.

This guide walks you through creating and using Managed Agents on the Gemini
API, using the [Antigravity agent](/docs/antigravity-agent). You'll make
your first agent call, continue a multi-turn conversation, stream the response,
download files from the sandbox, and work with the Antigravity managed agent.

## Run your first agent interaction {% id="run-your-first-agent-interaction" %}

A single call to the [Interactions API](/docs) provisions a Linux sandbox, runs
the agent loop, and returns the result. You'll define three parameters:

* Pass in the `agent` as `"antigravity-preview-09-2026"`, which is the current
  version of our predefined and general purpose managed agent.
* Define `environment="remote"`, to provision a new, fresh sandbox environment.
* Create an input, defining what you want the agent to do.

{% tabs %}
{% tab label="Python" %}
```py
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment="remote",
)

# Print the agent's final output
print(f"Interaction ID: {interaction.id}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output: {interaction.output_text}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment: "remote",
});

console.log(`Interaction ID: ${interaction.id}`);
console.log(`Environment ID: ${interaction.environment_id}`);

console.log(`Output: ${interaction.output_text}`);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

// Print the agent's final output
System.out.println("Interaction ID: " + interaction.id().orElse(""));
System.out.println("Environment ID: " + interaction.environmentId().orElse(""));
System.out.println("Output: " + interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    interaction := res.Interaction
    // Print the agent's final output
    fmt.Printf("Interaction ID: %s\n", *interaction.ID)
    fmt.Printf("Environment ID: %s\n", *interaction.EnvironmentID)
    fmt.Printf("Output: %s\n", *interaction.OutputText)
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": [{"type": "text", "text": "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents."}],
    "environment": {"type": "remote"}
}'
```
{% /tab %}
{% /tabs %}

The response returns an `Interaction` object. Store `interaction.id` and
`interaction.environment_id` to continue the conversation in the same sandbox.
Use `interaction.output_text` to access the agent's final response.
`interaction.steps` lists each step the agent took (reasoning, tool calls, code
execution).

## Continue the conversation (multi-turn) {% id="continue-conversation" %}

The API tracks two independent state dimensions:

- **Conversation context:** chat history, reasoning trace, tool use, using `previous_interaction_id`.
- [**Environment state:**](/docs/agent-environment) files, installed packages and sandbox state, using `environment`.

Pass both in their respective place to resume:

{% tabs %}
{% tab label="Python" %}
```py
interaction_2 = client.interactions.create(
    agent="antigravity-preview-09-2026",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    input="Now plot the Fibonacci sequence as a line chart and save it as chart.png.",
)

print(interaction_2.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction2 = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    previous_interaction_id: interaction.id,
    environment: interaction.environment_id,
    input: "Now plot the Fibonacci sequence as a line chart and save it as chart.png.",
}, { timeout: 300_000 });

console.log(interaction2.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();
String interactionId = "INTERACTION_ID";
String environmentId = "ENVIRONMENT_ID";

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .previousInteractionId(interactionId)
    .environment(CreateAgentInteractionEnvironment.of(environmentId))
    .input(InteractionsInput.of("Now plot the Fibonacci sequence as a line chart and save it as chart.png."))
    .build();

Interaction interaction2 = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction2.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    interactionID := "INTERACTION_ID"
    environmentID := "ENVIRONMENT_ID"

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:                 interactions.AgentOption("antigravity-preview-09-2026"),
            PreviousInteractionID: genai.Ptr(interactionID),
            Environment:           genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(environmentID)),
            Input:                 interactions.NewInteractionsInput("Now plot the Fibonacci sequence as a line chart and save it as chart.png."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "previous_interaction_id": "interaction_id_from_step_1",
    "environment": "environment_id_from_step_1",
    "input": [{"type": "text", "text": "Now plot the Fibonacci sequence as a line chart and save it as chart.png."}]
}'
```
{% /tab %}
{% /tabs %}

Files from turn 1 (`fibonacci.txt`) persist in turn 2. The agent also retains
conversation context.

You can mix and match these independently:

- **Clear conversation, keep files:** Omit `previous_interaction_id`, only pass the environment ID using `environment` for a fresh conversation in the same workspace.
- **Keep conversation, new workspace:** Pass `previous_interaction_id`, set `environment="remote"` for a fresh sandbox.

### Automatic context compaction {% id="automatic-context-compaction" %}

In long-running, multi-turn conversations, the raw history of reasoning steps,
tool calls, and large file contents can quickly grow and consume significant
context space. To prevent token limit errors and maintain the agent's focus
(preventing "context rot"), the Managed Agents API features a native context
compaction step at around 135k tokens. This happens automatically.

## Stream the response {% id="stream-response" %}

For long-running tasks, you can stream the response to see the agent work in
real time:

{% tabs %}
{% tab label="Python" %}
```py
from google import genai

client = genai.Client()

stream = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Read Hacker News, summarize the top 5 stories, and save the results as a PDF.",
    environment="remote",
    stream=True,
)

for event in stream:
    print(event)
    if event.event_type == "step.stop" and event.usage:
        print(event.usage)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Read Hacker News, summarize the top 5 stories, and save the results as a PDF.",
    environment: "remote",
    stream: true,
});

for await (const event of stream) {
    console.log(event);
    if (event.event_type === "step.stop" && event.usage) {
        console.log(event.usage);
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.StepStop;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.utils.EventStream;

Client client = new Client();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Read Hacker News, summarize the top 5 stories, and save the results as a PDF."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .stream(true)
    .build();

try (EventStream<InteractionSSEStreamEvent> stream =
    client.interactions.create(CreateInteractionRequestBody.of(params)).events()) {
  for (InteractionSSEStreamEvent event : stream) {
    System.out.println(event);
    if (event.data().isPresent() && event.data().get() instanceof StepStop stepStop) {
      stepStop.usage().ifPresent(System.out::println);
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Read Hacker News, summarize the top 5 stories, and save the results as a PDF."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
            Stream:      genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        fmt.Printf("%+v\n", event)
        if stepStop := event.GetDataStepStop(); stepStop != nil && stepStop.Usage != nil {
            fmt.Printf("%+v\n", stepStop.Usage)
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -N -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Read Hacker News, summarize the top 5 stories, and save the results as a PDF.",
    "environment": "remote",
    "stream": true
}'
```
{% /tab %}
{% /tabs %}

Streaming returns step deltas with incremental updates. When a step completes,
the `step.stop` event includes accumulated usage stats. Learn more in the
[Streaming guide](/docs/streaming).

## Download files from the environment {% id="download-files" %}

When the agent creates files inside the sandbox. Download them using the Files
API with a direct HTTP request (no SDK method yet):

{% tabs %}
{% tab label="Python" %}
```py
import os
import requests
import tarfile

env_id = interaction.environment_id
api_key = os.environ["GEMINI_API_KEY"]

response = requests.get(
    f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download",
    params={"alt": "media"},
    headers={"x-goog-api-key": api_key},
    allow_redirects=True,
)

with open("snapshot.tar", "wb") as f:
    f.write(response.content)

with tarfile.open("snapshot.tar") as tar:
    tar.extractall(path="extracted_snapshot")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import fs from "fs";
import { execSync } from "child_process";

const envId = interaction.environment_id;
const apiKey = process.env.GEMINI_API_KEY || "";

const url = `https://generativelanguage.googleapis.com/v1beta/files/environment-${envId}:download?alt=media`;
const response = await fetch(url, {
    headers: {
        "x-goog-api-key": apiKey,
    },
});

if (!response.ok) {
    throw new Error(`Failed to download file: ${response.statusText}`);
}

const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync("snapshot.tar", buffer);

if (!fs.existsSync("extracted_snapshot")) {
    fs.mkdirSync("extracted_snapshot");
}
execSync("tar -xf snapshot.tar -C extracted_snapshot");

console.log(fs.readdirSync("extracted_snapshot"));
```
{% /tab %}
{% tab label="Java" %}
```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Paths;

String envId = "ENVIRONMENT_ID";
String apiKey = System.getenv("GEMINI_API_KEY");

HttpClient httpClient = HttpClient.newBuilder()
    .followRedirects(HttpClient.Redirect.NORMAL)
    .build();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://generativelanguage.googleapis.com/v1beta/files/environment-" + envId + ":download?alt=media"))
    .header("x-goog-api-key", apiKey)
    .GET()
    .build();

HttpResponse<byte[]> response = httpClient.send(request, HttpResponse.BodyHandlers.ofByteArray());
Files.write(Paths.get("snapshot.tar"), response.body());
System.out.println("Saved snapshot to snapshot.tar");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "io"
    "log"
    "net/http"
    "os"
)

func main() {
    ctx := context.Background()
    envID := "ENVIRONMENT_ID"
    apiKey := os.Getenv("GEMINI_API_KEY")

    url := fmt.Sprintf("https://generativelanguage.googleapis.com/v1beta/files/environment-%s:download?alt=media", envID)
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("x-goog-api-key", apiKey)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    data, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    if err := os.WriteFile("snapshot.tar", data, 0644); err != nil {
        log.Fatal(err)
    }
    fmt.Println("Saved snapshot to snapshot.tar")
}
```
{% /tab %}

{% tab label="REST" %}
```shell
ENV_ID="your_environment_id_here"

curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/files/environment-$ENV_ID:download?alt=media" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-o snapshot.tar

mkdir -p extracted_snapshot
tar -xf snapshot.tar -C extracted_snapshot
```
{% /tab %}
{% /tabs %}

## Save a managed agent {% id="save-managed-agent" %}

In the previous steps, we used the default Antigravity agent and customized it
inline. Once you have iterated on your configuration (instructions, skills,
model selection, and environment), you can save it as a reusable managed agent.
This allows you to invoke it by ID without repeating the configuration.

When you save an agent, notice the architectural symmetry with inline
interactions: you specify `base_agent: "antigravity-preview-09-2026"` and can
pass an `agent_config` with your chosen `model` just as you would on
`interactions.create`. You also define a `base_environment` (either from sources
or by forking an existing environment). The agent will use this environment and
model configuration for every new interaction.

**From sources:** Define sources inline, or from other sources such as GitHub
or Cloud Storage.

{% tabs %}
{% tab label="Python" %}
```py
agent = client.agents.create(
    id="fibonacci-analyst",
    base_agent="antigravity-preview-09-2026",
    agent_config={
        "type": "antigravity",
        "model": "gemini-3.8-flash",
    },
    system_instruction="You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always include a chart and a summary table in your reports.",
            },
            {
                "type": "repository",
                "source": "https://github.com/your-org/skills",
                "target": ".agents/skills"
            }
        ],
    },
)

print(f"Saved agent: {agent.id}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const agent = await client.agents.create({
    id: "fibonacci-analyst",
    base_agent: "antigravity-preview-09-2026",
    agent_config: {
        type: "antigravity",
        model: "gemini-3.8-flash",
    },
    system_instruction: "You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/AGENTS.md",
                content: "Always include a chart and a summary table in your reports.",
            },
            {
                type: "repository",
                source: "https://github.com/your-org/skills",
                target: ".agents/skills"
            }
        ],
    },
});

console.log(`Saved agent: ${agent.id}`);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.gaos.models.agents.AgentConfig;
import com.google.genai.gaos.models.agents.BaseEnvironment;
import com.google.genai.gaos.models.interactions.AntigravityAgentConfig;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import java.util.List;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/AGENTS.md")
            .content("Always include a chart and a summary table in your reports.")
            .build(),
        Source.builder()
            .type(SourceType.REPOSITORY)
            .source("https://github.com/your-org/skills")
            .target(".agents/skills")
            .build()
    ))
    .build();

Agent agentParams = Agent.builder()
    .id("fibonacci-analyst")
    .baseAgent("antigravity-preview-09-2026")
    .agentConfig(AgentConfig.of(
        AntigravityAgentConfig.builder()
            .model("gemini-3.8-flash")
            .build()
    ))
    .systemInstruction("You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.")
    .baseEnvironment(BaseEnvironment.of(env))
    .build();

Agent agent = client.agents.create(agentParams).agent().get();
System.out.println("Saved agent: " + agent.id().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/agents"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/AGENTS.md"),
                Content: genai.Ptr("Always include a chart and a summary table in your reports."),
            },
            {
                Type:   interactions.SourceTypeRepository.ToPointer(),
                Source: genai.Ptr("https://github.com/your-org/skills"),
                Target: genai.Ptr(".agents/skills"),
            },
        },
    }

    res, err := client.Agents.Create(ctx, operations.CreateAgentRequest{
        Body: agents.Agent{
            ID:        genai.Ptr("fibonacci-analyst"),
            BaseAgent: genai.Ptr("antigravity-preview-09-2026"),
            AgentConfig: genai.Ptr(agents.NewAgentConfig(interactions.AntigravityAgentConfig{
                Model: genai.Ptr("gemini-3.8-flash"),
            })),
            SystemInstruction: genai.Ptr("You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports."),
            BaseEnvironment:   genai.Ptr(agents.NewBaseEnvironment(env)),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Saved agent: %s\n", *res.Agent.ID)
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "fibonacci-analyst",
    "base_agent": "antigravity-preview-09-2026",
    "agent_config": {
        "type": "antigravity",
        "model": "gemini-3.8-flash"
    },
    "system_instruction": "You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.",
    "base_environment": {
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always include a chart and a summary table in your reports."
            },
            {
                "type": "repository",
                "source": "https://github.com/your-org/skills",
                "target": ".agents/skills"
            }
        ]
    }
}'
```
{% /tab %}
{% /tabs %}

## Invoke the managed agent {% id="invoke-managed-agent" %}

Once you've saved a managed agent, you can invoke it by ID. Each invocation
forks the base environment, so every run starts clean:

{% tabs %}
{% tab label="Python" %}
```py
result = client.interactions.create(
    agent="fibonacci-analyst",
    input="Generate the first 50 prime numbers, plot their distribution, and save a PDF report.",
    environment="remote",
)

print(result.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const result = await client.interactions.create({
    agent: "fibonacci-analyst",
    input: "Generate the first 50 prime numbers, plot their distribution, and save a PDF report.",
    environment: "remote",
}, {
    timeout: 300_000,
});

console.log(result.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("fibonacci-analyst"))
    .input(InteractionsInput.of("Generate the first 50 prime numbers, plot their distribution, and save a PDF report."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();

Interaction result = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(result.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("fibonacci-analyst"),
            Input:       interactions.NewInteractionsInput("Generate the first 50 prime numbers, plot their distribution, and save a PDF report."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20" \
-d '{
    "agent": "fibonacci-analyst",
    "environment": "remote",
    "input": "Generate the first 50 prime numbers, plot their distribution, and save a PDF report."
}'
```
{% /tab %}
{% /tabs %}

## What's next {% id="whats-next" %}

- [Antigravity Agent](/docs/antigravity-agent): capabilities, supported tools, multimodal input, pricing, and limitations.
- [Building Managed Agents](/docs/custom-agents): extend Antigravity with your own instructions, skills, and data.
- [Environments](/docs/agent-environment): sources, networking, lifecycle, resource limits.
- [Interactions API](/docs/interactions-overview): the underlying API for models and agents.

# Antigravity agent
Source: https://aistudio.google.com/docs/antigravity-agent
Description: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

The Antigravity agent is a general-purpose managed agent on the Gemini API. A single API call gives you an agent that reasons, executes code, manages files, and browses the web inside your own secure Linux sandbox, hosted by Google.

It is built with Gemini 3.8 Flash and uses the same harness as the Antigravity IDE. You can configure the underlying Gemini model using `agent_config`. Available through the [Interactions API](/docs/interactions-overview) and [Google AI Studio](https://aistudio.google.com).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```py
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Read Hacker News, summarize the top 10 stories, and save the results as a PDF.",
    environment="remote",
)

print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Read Hacker News, summarize the top 10 stories, and save the results as a PDF.",
    environment: "remote",
}, { timeout: 300000 });

console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Read Hacker News, summarize the top 10 stories, and save the results as a PDF.",
    "environment": "remote"
}'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Read Hacker News, summarize the top 10 stories, and save the results as a PDF."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Read Hacker News, summarize the top 10 stories, and save the results as a PDF."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
## Capabilities {% id="capabilities" %}

Each call can provision a Linux sandbox and starts a tool-use loop. The agent plans, acts, observes results, and repeats until the task is done.

- **Code execution:** Run Bash, Python, and Node.js commands. Install packages, run tests, build apps.
- **File management:** Read, write, edit, search, and list files in the sandbox. Files persist across interactions.
- **Web access:** Google Search and URL fetching for data.
- **Context compaction:** Automatic context compaction (triggered at ~135k tokens) to support long-running, multi-turn sessions without losing context or hitting token limits.

See the [Quickstart](/docs/managed-agents-quickstart) for multi-turn usage and streaming.

## Supported tools {% id="supported-tools" %}

By default, the agent has access to `code_execution`, `google_search`, and `url_context`. Filesystem tools are enabled automatically when you specify the `environment` parameter. You can also define **custom functions** to connect the agent to your own APIs and tools. You only need to specify the `tools` parameter when customizing or restricting the default set, or when adding custom functions.

| Tool | Type value | Description |
| :---- | :---- | :---- |
| Code Execution | `code_execution` | Run shell commands (bash, Python, Node) with stdout/stderr capture. |
| Google Search | `google_search` | Search the public web. |
| URL Context | `url_context` | Fetch and read web pages. |
| Filesystem | *(enabled via `environment`)* | Read, write, edit, search, and list files in the sandbox. The system enables these tools automatically when you set the `environment`. |
| Custom Functions | `function` | Define custom functions that the agent can request to execute. See [Function calling](/docs/antigravity-agent#function-calling). |
| Remote MCP Server | `mcp_server` | Register external Model Context Protocol (MCP) servers as tools. See [MCP servers](/docs/antigravity-agent#mcp-servers). |

You can intercept and validate `code_execution` and `filesystem` tool execution right inside the remote sandbox using synchronous [Hooks](/docs/agent-hooks).

To limit the agent to specific tools, pass only the ones you need:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```py
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Search for the latest AI research papers on reasoning and summarize them.",
    environment="remote",
    tools=[
        {"type": "google_search"},
        {"type": "url_context"},
    ],
)

print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Search for the latest AI research papers on reasoning and summarize them.",
    environment: "remote",
    tools: [
        { type: "google_search" },
        { type: "url_context" },
    ],
}, { timeout: 300000 });

console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Search for the latest AI research papers on reasoning and summarize them.",
    "environment": "remote",
    "tools": [
        {"type": "google_search"},
        {"type": "url_context"}
    ]
}'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.URLContext;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Search for the latest AI research papers on reasoning and summarize them."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .tools(List.of(
        GoogleSearch.builder().build(),
        URLContext.builder().build()
    ))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Search for the latest AI research papers on reasoning and summarize them."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.GoogleSearch{}),
                interactions.NewTool(interactions.URLContext{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
## Multimodal Input {% id="multimodal-input" %}

The Antigravity agent supports multimodal inputs. Currently, only `text` and `image` inputs are supported. Images must be supplied as inline base64-encoded strings (`data`).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```py
import base64
from google import genai

client = genai.Client()

with open("path/to/chart.png", "rb") as f:
    image_bytes = f.read()

interaction_inline = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input=[
        {"type": "text", "text": "Analyze this chart and summarize the trends."},
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode("utf-8"),
            "mime_type": "image/png",
        },
    ],
    environment="remote",
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript

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

import * as fs from "node:fs";

const client = new GoogleGenAI({});
const base64Image = fs.readFileSync("path/to/chart.png", { encoding: "base64" });

const interactionInline = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: [
        { type: "text", text: "Analyze this chart and summarize the trends." },
        {
            type: "image",
            data: base64Image,
            mime_type: "image/png",
        },
    ],
    environment: "remote",
}, { timeout: 300000 });
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
BASE64_IMAGE=$(base64 -w0 /path/to/chart.png)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d "{
    \"agent\": \"antigravity-preview-09-2026\",
    \"input\": [
        {\"type\": \"text\", \"text\": \"Analyze this chart and summarize the trends.\"},
        {
            \"type\": \"image\",
            \"mime_type\": \"image/png\",
            \"data\": \"$BASE64_IMAGE\"
        }
    ],
    \"environment\": \"remote\"
}"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("path/to/chart.png"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.ofContent(List.of(
        TextContent.builder().text("Analyze this chart and summarize the trends.").build(),
        ImageContent.builder()
            .data(base64Image)
            .mimeType(ImageContentMimeType.IMAGE_PNG)
            .build()
    )))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();

Interaction interactionInline = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interactionInline.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("path/to/chart.png")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("antigravity-preview-09-2026"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Analyze this chart and summarize the trends.",
                }),
                interactions.NewContent(interactions.ImageContent{
                    Data:     genai.Ptr(base64Image),
                    MimeType: interactions.ImageContentMimeTypeImagePng.ToPointer(),
                }),
            }),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
## Function calling {% id="function-calling" %}

Function calling allows you to connect the Antigravity agent to external APIs and databases by defining custom tools the agent can invoke. For general concepts, see [Function calling with the Gemini API](/docs/function-calling).

The following example demonstrates a 2-turn interaction. The agent first requests a custom `get_weather` function call, and the client executes it and returns the result in the second turn.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

# 1. Define the custom function
get_weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Gets the current weather for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and country, e.g. San Francisco, USA",
            }
        },
        "required": ["location"],
    },
}

# 2. Call the agent with the custom tool (Turn 1)
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="What is the weather in Tokyo?",
    environment="remote",
    tools=[
        {"type": "code_execution"},  # Enable default code execution
        get_weather_tool,            # Add custom function
    ],
)

# Check if the agent requested a function call
if interaction.status == "requires_action":
    # Find function calls that do not have a matching function result.
    # Filesystem tools (like write_to_file) are also represented as function calls
    # but are executed automatically by the environment.
    executed_calls = {step.call_id for step in interaction.steps if step.type == "function_result"}
    pending_calls = [step for step in interaction.steps if step.type == "function_call" and step.id not in executed_calls]

    if pending_calls:
        fc_step = pending_calls[0]
        print(f"Function to call: {fc_step.name} (ID: {fc_step.id})")
        print(f"Arguments: {fc_step.arguments}")

        # 3. Execute the function locally (simulated get_weather()) and send the result back (Turn 2)
        function_result = {
            "temperature": 23,
            "unit": "celsius"
        }

        final_interaction = client.interactions.create(
            agent="antigravity-preview-09-2026",
            previous_interaction_id=interaction.id,  # Reference the interaction ID
            environment=interaction.environment_id,
            input=[
                {
                    "type": "function_result",
                    "name": fc_step.name,
                    "call_id": fc_step.id,
                    "result": function_result,
                }
            ],
        )

        print(final_interaction.output_text)
        # Output: The current weather in Tokyo, Japan is 23°C (Celsius).
    else:
        print("No pending function calls.")
else:
    print(f"Interaction completed with status: {interaction.status}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

// 1. Call the agent with the custom tool (Turn 1)
const interaction = await client.interactions.create({
  agent: "antigravity-preview-09-2026",
  input: "What is the weather in Tokyo?",
  environment: "remote",
  tools: [
    { type: "code_execution" },
    {
      type: "function",
      name: "get_weather",
      description: "Gets the current weather for a given location.",
      parameters: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "The city and country, e.g. San Francisco, USA",
          },
        },
        required: ["location"],
      },
    },
  ],
}, { timeout: 300000 });

if (interaction.status === "requires_action") {
  // Find function calls that do not have a matching function result.
  // Filesystem tools (like write_to_file) are also represented as function calls
  // but are executed automatically by the environment.
  const executedCalls = new Set(
    (interaction.steps || [])
      .filter(s => s.type === "function_result")
      .map(s => s.call_id)
  );
  const pendingCalls = (interaction.steps || []).filter(
    s => s.type === "function_call" && !executedCalls.has(s.id)
  );

  if (pendingCalls.length > 0) {
    const fcStep = pendingCalls[0];
    if (fcStep.type === "function_call") {
      console.log(`Function to call: ${fcStep.name} (ID: ${fcStep.id})`);

      // Execute the function locally (simulated get_weather()) and send the result back (Turn 2)
      const functionResult = {
        temperature: 23,
        unit: "celsius"
      };

      const finalInteraction = await client.interactions.create({
        agent: "antigravity-preview-09-2026",
        previous_interaction_id: interaction.id, // Reference the interaction ID
        environment: interaction.environment_id,
        input: [
          {
            type: "function_result",
            name: fcStep.name,
            call_id: fcStep.id,
            result: functionResult,
          }
        ],
      }, { timeout: 300000 });

      console.log(finalInteraction.output_text);
    }
  } else {
    console.log("No pending function calls.");
  }
} else {
  console.log(`Interaction completed with status: ${interaction.status}`);
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# 1. Turn 1: Request function call
RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": "What is the weather in Tokyo?",
      "environment": "remote",
      "tools": [
          {"type": "code_execution"},
          {
              "type": "function",
              "name": "get_weather",
              "description": "Gets the current weather for a given location.",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "location": {"type": "string"}
                  },
                  "required": ["location"]
              }
          }
      ]
  }')

# Extract interaction ID, environment ID, and call ID (requires jq)
INTERACTION_ID=$(echo $RESPONSE | jq -r '.id')
ENVIRONMENT_ID=$(echo $RESPONSE | jq -r '.environment_id')
CALL_ID=$(echo $RESPONSE | jq -r '.steps[] | select(.type=="function_call") | .id')

# 2. Turn 2: Send function result back using variables
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d "{
      \"agent\": \"antigravity-preview-09-2026\",
      \"previous_interaction_id\": \"$INTERACTION_ID\",
      \"environment\": \"$ENVIRONMENT_ID\",
      \"input\": [
          {
              \"type\": \"function_result\",
              \"name\": \"get_weather\",
              \"call_id\": \"$CALL_ID\",
              \"result\": {
                  \"temperature\": 23,
                  \"unit\": \"celsius\"
              }
          }
      ]
  }"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.FunctionResultStep;
import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;

Client client = new Client();

// 1. Define the custom function
Function getWeatherTool = Function.builder()
    .name("get_weather")
    .description("Gets the current weather for a given location.")
    .parameters(Map.of(
        "type", "object",
        "properties", Map.of(
            "location", Map.of(
                "type", "string",
                "description", "The city and country, e.g. San Francisco, USA"
            )
        ),
        "required", List.of("location")
    ))
    .build();

// 2. Call the agent with the custom tool (Turn 1)
CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("What is the weather in Tokyo?"))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .tools(List.of(
        CodeExecution.builder().build(), // Enable default code execution
        getWeatherTool                   // Add custom function
    ))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

// Check if the agent requested a function call
if (interaction.status().orElse(null) == InteractionStatus.REQUIRES_ACTION) {
    // Find function calls that do not have a matching function result.
    List<Step> steps = interaction.steps().orElse(List.of());
    Set<String> executedCalls = steps.stream()
        .filter(step -> step instanceof FunctionResultStep)
        .map(step -> ((FunctionResultStep) step).callId().orElse(""))
        .collect(Collectors.toSet());

    List<FunctionCallStep> pendingCalls = steps.stream()
        .filter(step -> step instanceof FunctionCallStep)
        .map(step -> (FunctionCallStep) step)
        .filter(fc -> !executedCalls.contains(fc.id().orElse("")))
        .collect(Collectors.toList());

    if (!pendingCalls.isEmpty()) {
        FunctionCallStep fcStep = pendingCalls.get(0);
        System.out.println("Function to call: " + fcStep.name().orElse("") + " (ID: " + fcStep.id().orElse("") + ")");
        System.out.println("Arguments: " + fcStep.arguments().orElse(Map.of()));

        // 3. Execute the function locally (simulated get_weather()) and send the result back (Turn 2)
        FunctionResultStep resultStep = FunctionResultStep.builder()
            .name(fcStep.name().orElse(""))
            .callId(fcStep.id().orElse(""))
            .result(FunctionResultStepResultUnion.of("{\"temperature\": 23, \"unit\": \"celsius\"}"))
            .build();

        CreateAgentInteraction followupParams = CreateAgentInteraction.builder()
            .agent(AgentOption.of("antigravity-preview-09-2026"))
            .previousInteractionId(interaction.id().orElse(""))
            .environment(CreateAgentInteractionEnvironment.of(interaction.environmentId().orElse("")))
            .input(InteractionsInput.ofStep(List.of(resultStep)))
            .build();

        Interaction finalInteraction = client.interactions.create(CreateInteractionRequestBody.of(followupParams)).interaction().get();
        System.out.println(finalInteraction.outputText().orElse(""));
        // Output: The current weather in Tokyo, Japan is 23°C (Celsius).
    } else {
        System.out.println("No pending function calls.");
    }
} else {
    System.out.println("Interaction completed with status: " + interaction.status().orElse(null));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. Define the custom function
    getWeatherTool := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Gets the current weather for a given location."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{
                    "type":        "string",
                    "description": "The city and country, e.g. San Francisco, USA",
                },
            },
            "required": []string{"location"},
        },
    })

    // 2. Call the agent with the custom tool (Turn 1)
    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("What is the weather in Tokyo?"),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.CodeExecution{}), // Enable default code execution
                getWeatherTool, // Add custom function
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    interaction := res.Interaction

    // Check if the agent requested a function call
    if interaction.Status == interactions.InteractionStatusRequiresAction {
        executedCalls := make(map[string]bool)
        for _, step := range interaction.Steps {
            if fr := step.FunctionResultStep; fr != nil {
                executedCalls[fr.CallID] = true
            }
        }

        var pendingCalls []*interactions.FunctionCallStep
        for _, step := range interaction.Steps {
            if fc := step.FunctionCallStep; fc != nil && !executedCalls[fc.ID] {
                pendingCalls = append(pendingCalls, fc)
            }
        }

        if len(pendingCalls) > 0 {
            fcStep := pendingCalls[0]
            fmt.Printf("Function to call: %s (ID: %s)\n", fcStep.Name, fcStep.ID)
            fmt.Printf("Arguments: %v\n", fcStep.Arguments)

            // 3. Execute the function locally (simulated get_weather()) and send the result back (Turn 2)
            resultStep := interactions.FunctionResultStep{
                Name:   genai.Ptr(fcStep.Name),
                CallID: fcStep.ID,
                Result: interactions.NewFunctionResultStepResultUnion(`{"temperature": 23, "unit": "celsius"}`),
            }

            followupRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
                Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
                    Agent:                 interactions.AgentOption("antigravity-preview-09-2026"),
                    PreviousInteractionID: interaction.ID,
                    Environment:           genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(*interaction.EnvironmentID)),
                    Input: interactions.NewInteractionsInput([]interactions.Step{
                        interactions.NewStep(resultStep),
                    }),
                }),
            })
            if err != nil {
                log.Fatal(err)
            }
            if followupRes.Interaction.OutputText != nil {
                fmt.Println(*followupRes.Interaction.OutputText)
            }
        } else {
            fmt.Println("No pending function calls.")
        }
    } else {
        fmt.Printf("Interaction completed with status: %s\n", interaction.Status)
    }
}
```
{% /tab %}
{% /tabs %}
## MCP servers {% id="mcp-servers" %}

You can connect the Antigravity agent to external tools by registering remote Model Context Protocol (MCP) servers. The agent supports remote MCP servers over streamable HTTP.

When registering an MCP server, you must specify the following fields in the `tools` array:

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `type` | string | Yes | Must be `"mcp_server"`. |
| `name` | string | Yes | A unique identifier for the server. Must be strictly lowercase and alphanumeric (matching `^[a-z0-9_-]+$`). |
| `url` | string | Yes | The endpoint URL of the remote MCP server. |
| `headers` | object | No | Custom headers (e.g., authentication) sent with requests. |
| `allowed_tools` | array | No | List of tool names allowed to be executed. If omitted, all tools are allowed. |

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```py
from google import genai

client = genai.Client()

# Register a remote HTTP MCP server
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="What is the weather in Tokyo?",
    environment="remote",
    tools=[{
        "type": "mcp_server",
        "name": "weather", # Must be lowercase
        "url": "https://gemini-api-demos.uc.r.appspot.com/mcp"
    }]
)

print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "What is the weather in Tokyo?",
    environment: "remote",
    tools: [{
        type: "mcp_server",
        name: "weather", // Must be lowercase
        url: "https://gemini-api-demos.uc.r.appspot.com/mcp"
    }]
}, { timeout: 300000 });

console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": "What is the weather in Tokyo?",
      "environment": "remote",
      "tools": [{
          "type": "mcp_server",
          "name": "weather",
          "url": "https://gemini-api-demos.uc.r.appspot.com/mcp"
      }]
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.MCPServer;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

// Register a remote HTTP MCP server
CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("What is the weather in Tokyo?"))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .tools(List.of(
        MCPServer.builder()
            .name("weather") // Must be lowercase
            .url("https://gemini-api-demos.uc.r.appspot.com/mcp")
            .build()
    ))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Register a remote HTTP MCP server
    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("What is the weather in Tokyo?"),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.MCPServer{
                    Name: genai.Ptr("weather"), // Must be lowercase
                    URL:  genai.Ptr("https://gemini-api-demos.uc.r.appspot.com/mcp"),
                }),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
## Model selection {% id="model-selection" %}

For `antigravity-preview-09-2026`, the default model is **Gemini 3.8 Flash** (`gemini-3.8-flash`). If you omit `agent_config`, the agent defaults to `gemini-3.8-flash`.

You can configure the underlying Gemini model using `agent_config` to optimize for speed, cost, or reasoning capability. For example, set `model` to **Gemini 4 Argon** (`gemini-4-argon`) for complex software engineering and reasoning tasks:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Summarize the key differences between functional and object-oriented programming.",
    environment="remote",
    agent_config={
        "type": "antigravity",
        "model": "gemini-4-argon",
    },
)

print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Summarize the key differences between functional and object-oriented programming.",
    environment: "remote",
    agent_config: {
        type: "antigravity",
        model: "gemini-4-argon",
    },
}, { timeout: 300000 });

console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": "Summarize the key differences between functional and object-oriented programming.",
      "environment": "remote",
      "agent_config": {
          "type": "antigravity",
          "model": "gemini-4-argon"
      }
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.AntigravityAgentConfig;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Summarize the key differences between functional and object-oriented programming."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .agentConfig(
        AntigravityAgentConfig.builder()
            .model("gemini-4-argon")
            .build()
    )
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Summarize the key differences between functional and object-oriented programming."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
            AgentConfig: genai.Ptr(interactions.NewCreateAgentInteractionAgentConfig(interactions.AntigravityAgentConfig{
                Model: genai.Ptr("gemini-4-argon"),
            })),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

The supported values for `agent_config.model` are:

| Model | Value in `agent_config.model` | Description |
| :---- | :---- | :---- |
| **Gemini 3.8 Flash** (default) | `gemini-3.8-flash` | Default balanced model for reasoning, coding, and tool use. |
| **Gemini 4 Argon** | `gemini-4-argon` | Frontier reasoning model for complex software engineering, deep problem solving, and long-horizon agentic tasks. |
| **Gemini 3.6 Flash** | `gemini-3.6-flash` | Balanced Flash model for general agentic workflows. |
| **Gemini 3.5 Flash-Lite** | `gemini-3.5-flash-lite` | Lightweight model optimized for low latency and cost-sensitive tasks. |

When creating a managed agent with `agents.create`, you configure the model in the exact same way by passing `base_agent` and `agent_config`. Notice that you cannot override the model at interaction time for a managed agent created with `agents.create`. The model is locked to what was set when the agent was created. This ensures predictable tool calling behavior, consistent debugging, and adherence to security boundaries.

## Customizing the agent {% id="customizing-the-agent" %}

You can extend the Antigravity agent by customizing its instructions, tools, and environment. The agent supports a filesystem-native approach to customization: you can mount files like `AGENTS.md` for instructions and skills under `.agents/skills/` directly into the sandbox, or pass configuration inline at interaction time. You can iterate on your configuration inline and then save it as a managed agent when you are ready.

For full details on how to build custom agents, see [Building Managed Agents](/docs/custom-agents).

## Background execution {% id="background-execution" %}

Agent tasks that involve multi-step reasoning, code execution, or file operations can take minutes to complete. Use `background=True` to run the interaction asynchronously. The API returns immediately with an interaction ID that you poll until the status is `completed` or `failed`.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai

client = genai.Client()

# 1. Start the interaction in the background
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Run a complex analysis on the repository.",
    environment="remote",
    background=True,
)

print(f"Interaction started in background: {interaction.id}")

# 2. Poll for completion
while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

if interaction.status == "completed":
    print(interaction.output_text)
else:
    print(f"Finished with status: {interaction.status}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Run a complex analysis on the repository.",
    environment: "remote",
    background: true,
});

console.log(`Interaction started in background: ${interaction.id}`);

let result = interaction;
while (result.status === "in_progress") {
    await new Promise(resolve => setTimeout(resolve, 5000));
    result = await client.interactions.get(interaction.id);
}

if (result.status === "completed") {
    console.log(result.output_text);
} else {
    console.log(`Finished with status: ${result.status}`);
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# 1. Start the interaction in the background
RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": "Run a complex analysis on the repository.",
      "environment": "remote",
      "background": true
  }')

INTERACTION_ID=$(echo $RESPONSE | jq -r '.id')

# 2. Poll for results (repeat until status is "completed")
curl -s -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;

Client client = new Client();

// 1. Start the interaction in the background
CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Run a complex analysis on the repository."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .background(true)
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Interaction started in background: " + interaction.id().orElse(""));

// 2. Poll for completion
while (interaction.status().orElse(null) == InteractionStatus.IN_PROGRESS) {
    Thread.sleep(5000);
    interaction = client.interactions.get(new GetInteractionByIdRequest(interaction.id().orElse(""))).interaction().get();
}

if (interaction.status().orElse(null) == InteractionStatus.COMPLETED) {
    System.out.println(interaction.outputText().orElse(""));
} else {
    System.out.println("Finished with status: " + interaction.status().orElse(null));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. Start the interaction in the background
    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Run a complex analysis on the repository."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
            Background:  genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    interaction := res.Interaction
    fmt.Printf("Interaction started in background: %s\n", *interaction.ID)

    // 2. Poll for completion
    for interaction.Status == interactions.InteractionStatusInProgress {
        time.Sleep(5 * time.Second)
        getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        interaction = getRes.Interaction
    }

    if interaction.Status == interactions.InteractionStatusCompleted {
        if interaction.OutputText != nil {
            fmt.Println(*interaction.OutputText)
        }
    } else {
        fmt.Printf("Finished with status: %s\n", interaction.Status)
    }
}
```
{% /tab %}
{% /tabs %}

Background execution requires `store=True`, which is the default. For real-time progress updates during background execution, see [Streaming background interactions](/docs/background-execution#streaming-pattern).

You can cancel a running background interaction using the `cancel` method.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
client.interactions.cancel(id="INTERACTION_ID")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
await client.interactions.cancel("INTERACTION_ID");
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID:cancel" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;

Client client = new Client();
client.interactions.cancel("INTERACTION_ID");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Interactions.Cancel(ctx, operations.CancelInteractionByIDRequest{
        ID: "INTERACTION_ID",
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}
{% /tabs %}

<a id="multi-turn-background"></a>**Multi-turn with background execution**

When a background interaction involves stateful tools (like code execution in a sandbox), use the `environment_id` from the completed interaction to continue in the same environment. This ensures the agent picks up where it left off with all files and state intact.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from google import genai

client = genai.Client()

# First turn: run a task in the background
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Clone https://github.com/google/generative-ai-python and run its tests.",
    environment="remote",
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

# Second turn: continue in the same environment
followup = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Fix any failing tests and re-run them.",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    background=True,
)

while followup.status == "in_progress":
    time.sleep(5)
    followup = client.interactions.get(id=followup.id)

print(followup.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

// First turn: run a task in the background
let interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Clone https://github.com/google/generative-ai-python and run its tests.",
    environment: "remote",
    background: true,
});

while (interaction.status === "in_progress") {
    await new Promise(resolve => setTimeout(resolve, 5000));
    interaction = await client.interactions.get(interaction.id);
}

// Second turn: continue in the same environment
let followup = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Fix any failing tests and re-run them.",
    previous_interaction_id: interaction.id,
    environment: interaction.environment_id,
    background: true,
});

while (followup.status === "in_progress") {
    await new Promise(resolve => setTimeout(resolve, 5000));
    followup = await client.interactions.get(followup.id);
}

console.log(followup.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# 1. Start first interaction in the background
RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": "Clone https://github.com/google/generative-ai-python and run its tests.",
      "environment": "remote",
      "background": true
  }')

INTERACTION_ID=$(echo $RESPONSE | jq -r '.id')

# 2. Poll until completed (repeat until status is "completed")
RESULT=$(curl -s -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY")

ENVIRONMENT_ID=$(echo $RESULT | jq -r '.environment_id')

# 3. Continue in the same environment
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d "{
      \"agent\": \"antigravity-preview-09-2026\",
      \"input\": \"Fix any failing tests and re-run them.\",
      \"previous_interaction_id\": \"$INTERACTION_ID\",
      \"environment\": \"$ENVIRONMENT_ID\",
      \"background\": true
  }"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;

Client client = new Client();

// First turn: run a task in the background
CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Clone https://github.com/google/generative-ai-python and run its tests."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .background(true)
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

while (interaction.status().orElse(null) == InteractionStatus.IN_PROGRESS) {
    Thread.sleep(5000);
    interaction = client.interactions.get(new GetInteractionByIdRequest(interaction.id().orElse(""))).interaction().get();
}

// Second turn: continue in the same environment
CreateAgentInteraction followupParams = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Fix any failing tests and re-run them."))
    .previousInteractionId(interaction.id().orElse(""))
    .environment(CreateAgentInteractionEnvironment.of(interaction.environmentId().orElse("")))
    .background(true)
    .build();

Interaction followup = client.interactions.create(CreateInteractionRequestBody.of(followupParams)).interaction().get();

while (followup.status().orElse(null) == InteractionStatus.IN_PROGRESS) {
    Thread.sleep(5000);
    followup = client.interactions.get(new GetInteractionByIdRequest(followup.id().orElse(""))).interaction().get();
}

System.out.println(followup.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // First turn: run a task in the background
    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Clone https://github.com/google/generative-ai-python and run its tests."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
            Background:  genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    interaction := res.Interaction
    for interaction.Status == interactions.InteractionStatusInProgress {
        time.Sleep(5 * time.Second)
        getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        interaction = getRes.Interaction
    }

    // Second turn: continue in the same environment
    followupRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:                 interactions.AgentOption("antigravity-preview-09-2026"),
            Input:                 interactions.NewInteractionsInput("Fix any failing tests and re-run them."),
            PreviousInteractionID: interaction.ID,
            Environment:           genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(*interaction.EnvironmentID)),
            Background:            genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    followup := followupRes.Interaction
    for followup.Status == interactions.InteractionStatusInProgress {
        time.Sleep(5 * time.Second)
        getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *followup.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        followup = getRes.Interaction
    }

    if followup.OutputText != nil {
        fmt.Println(*followup.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
## Environments {% id="environments" %}

Each call creates or reuses a Linux sandbox. The `environment` parameter takes three forms:

| Form | Description |
| :---- | :---- |
| `"remote"` | Provision a fresh sandbox with default settings. |
| `"env_abc123"` | Reuse an existing environment by ID, preserving all files and state. |
| `{...}` | Full `EnvironmentConfig` with custom sources and network rules. |

See [Environments](/docs/agent-environment) for details on sources (Git, GCS, inline), networking, lifecycle, and resource limits.

## Triggers {% id="triggers" %}

Triggers let you schedule an agent to run automatically on a cron schedule. A trigger binds an agent, environment, prompt, and schedule into a persistent resource that fires without manual intervention. Each execution reuses the same environment, so files created in one run persist and are visible to the next.

### Create a trigger

Create a trigger by specifying a cron schedule, time zone, and the interaction configuration. The trigger starts in `active` status and will fire on the next matching cron time. Save the returned `id` to manage the trigger in subsequent calls.

Because a trigger runs unattended on a schedule, reference a stored [credential](/docs/agent-credentials) rather than an inline token. The egress proxy resolves it on every run, and you rotate the secret without touching the trigger. Inline `transform` rules work here too, they just need you to update the trigger whenever the value changes.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

trigger = client.triggers.create(
    schedule="0 9 * * *",
    time_zone="America/Argentina/Buenos_Aires",
    display_name="issue-solver",
    interaction={
        "agent": "antigravity-preview-09-2026",
        "input": "Review open PRs in my-org/my-app for new comments and address feedback. Close issues whose PRs were merged. Then check for new issues labeled 'accepted', skip any already tracked in /workspace/solved-issues/, fix the rest, and open a PR for each. Save reports to /workspace/solved-issues/.",
        "environment": {
            "type": "remote",
            "network": {
                "allowlist": [
                    {
                        "domain": "api.github.com",
                        "credential": "github-production",
                    },
                    {"domain": "github.com"},
                ]
            },
        },
    },
)

print(f"Trigger created: {trigger.id}")
print(f"Next run: {trigger.next_run_time}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const trigger = await client.triggers.create({
    schedule: "0 9 * * *",
    time_zone: "America/Argentina/Buenos_Aires",
    display_name: "issue-solver",
    interaction: {
        agent: "antigravity-preview-09-2026",
        input: [{
            type: "text",
            text: "Review open PRs in my-org/my-app for new comments and address feedback. Close issues whose PRs were merged. Then check for new issues labeled 'accepted', skip any already tracked in /workspace/solved-issues/, fix the rest, and open a PR for each. Save reports to /workspace/solved-issues/.",
        }],
        environment: {
            type: "remote",
            network: {
                allowlist: [
                    {
                        domain: "api.github.com",
                        credential: "github-production",
                    },
                    { domain: "github.com" },
                ],
            },
        },
    },
});

console.log(`Trigger created: ${trigger.id}`);
console.log(`Next run: ${trigger.next_run_time}`);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/triggers" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "schedule": "0 9 * * *",
      "time_zone": "America/Argentina/Buenos_Aires",
      "display_name": "issue-solver",
      "interaction": {
          "agent": "antigravity-preview-09-2026",
          "input": [{"type": "text", "text": "Review open PRs in my-org/my-app for new comments and address feedback. Close issues whose PRs were merged. Then check for new issues labeled accepted, skip any already tracked in /workspace/solved-issues/, fix the rest, and open a PR for each. Save reports to /workspace/solved-issues/."}],
          "environment": {
              "type": "remote",
              "network": {
                  "allowlist": [
                      {
                          "domain": "api.github.com",
                          "credential": "github-production"
                      },
                      {"domain": "github.com"}
                  ]
              }
          }
      }
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.gaos.GenAI;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.shared.Security;
import com.google.genai.gaos.models.triggers.Trigger;
import com.google.genai.gaos.models.triggers.TriggerCreateParams;
import java.util.List;
import java.util.Map;

GenAI client = GenAI.builder()
    .security(Security.builder().apiKey(System.getenv("GEMINI_API_KEY")).build())
    .build();

Environment env = Environment.builder()
    .network(Network.of(
        EnvironmentNetworkEgressAllowlist.builder()
            .allowlist(Allowlist.of(List.of(
                AllowlistEntry.builder()
                    .domain("api.github.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
                    )))
                    .build(),
                AllowlistEntry.builder()
                    .domain("github.com")
                    .build()
            )))
            .build()
    ))
    .build();

CreateAgentInteraction interactionTemplate = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Review open PRs in my-org/my-app for new comments and address feedback. Close issues whose PRs were merged. Then check for new issues labeled 'accepted', skip any already tracked in /workspace/solved-issues/, fix the rest, and open a PR for each. Save reports to /workspace/solved-issues/."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

TriggerCreateParams params = TriggerCreateParams.builder()
    .schedule("0 9 * * *")
    .timeZone("America/Argentina/Buenos_Aires")
    .displayName("issue-solver")
    .interaction(interactionTemplate)
    .build();

Trigger trigger = client.triggers().create(params).trigger().get();
System.out.println("Trigger created: " + trigger.id().orElse(""));
System.out.println("Next run: " + trigger.nextRunTime().orElse(null));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    interactionssdk "google.golang.org/genai/interactions"
    "google.golang.org/genai/interactions/models/components"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
    "google.golang.org/genai/interactions/models/triggers"
)

func main() {
    ctx := context.Background()
    sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
        APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
    }))

    env := interactions.Environment{
        Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
            Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                {
                    Domain: "api.github.com",
                    Transform: genai.Ptr(interactions.NewTransform(map[string]string{
                        "Authorization": "Bearer ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                    })),
                },
                {
                    Domain: "github.com",
                },
            })),
        })),
    }

    interactionTemplate := interactions.CreateAgentInteraction{
        Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
        Input:       interactions.NewInteractionsInput("Review open PRs in my-org/my-app for new comments and address feedback. Close issues whose PRs were merged. Then check for new issues labeled 'accepted', skip any already tracked in /workspace/solved-issues/, fix the rest, and open a PR for each. Save reports to /workspace/solved-issues/."),
        Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
    }

    res, err := sdk.Triggers.Create(ctx, operations.CreateTriggerRequest{
        Body: triggers.TriggerCreateParams{
            Schedule:    "0 9 * * *",
            TimeZone:    "America/Argentina/Buenos_Aires",
            DisplayName: genai.Ptr("issue-solver"),
            Interaction: interactionTemplate,
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    trigger := res.Trigger
    fmt.Printf("Trigger created: %s\n", trigger.ID)
    fmt.Printf("Next run: %v\n", trigger.NextRunTime)
}
```
{% /tab %}
{% /tabs %}

The `CreateTrigger` request accepts the following fields:

| Field | Type | Required | Description |
| :---- | :---- | :---- | :---- |
| `schedule` | string | Yes | Cron expression (e.g., `0 * * * *` for hourly, `0 9 * * 1-5` for weekday mornings). |
| `time_zone` | string | Yes | IANA time zone (e.g., `UTC`, `America/Argentina/Buenos_Aires`). |
| `display_name` | string | No | Human-readable name for the trigger. |
| `max_consecutive_failures` | integer | No | Max failures before the trigger is automatically paused. Default: 5. |
| `execution_timeout_seconds` | integer | No | Timeout per execution in seconds. Default: 600. |
| `interaction` | object | Yes | A `CreateInteractionRequest` defining the agent, input, tools, and environment. |

The response includes the following key fields:

| Field | Type | Description |
| :---- | :---- | :---- |
| `id` | string | Unique identifier for the trigger. Use this in all subsequent operations. |
| `status` | string | Current state: `active`, `paused`, or `disabled`. |
| `next_run_time` | string | ISO 8601 timestamp of the next scheduled execution. |
| `consecutive_failure_count` | integer | Number of consecutive failed executions since the last success. |

### List triggers

Retrieve all triggers associated with your project.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
triggers = client.triggers.list()
for trigger in triggers.triggers:
    print(f"{trigger.id}: {trigger.display_name} ({trigger.status})")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const triggers = await client.triggers.list();
for (const trigger of triggers.triggers) {
    console.log(`${trigger.id}: ${trigger.display_name} (${trigger.status})`);
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X GET "https://generativelanguage.googleapis.com/v1beta/triggers" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.gaos.GenAI;
import com.google.genai.gaos.models.shared.Security;
import com.google.genai.gaos.models.triggers.Trigger;
import java.util.List;

GenAI client = GenAI.builder()
    .security(Security.builder().apiKey(System.getenv("GEMINI_API_KEY")).build())
    .build();

List<Trigger> triggers = client.triggers().listDirect().listTriggersResponse().get().triggers().orElse(List.of());
for (Trigger trigger : triggers) {
    System.out.println(trigger.id().orElse("") + ": " + trigger.displayName().orElse("") + " (" + trigger.status().orElse(null) + ")");
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    interactionssdk "google.golang.org/genai/interactions"
    "google.golang.org/genai/interactions/models/components"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
        APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
    }))

    res, err := sdk.Triggers.List(ctx, operations.ListTriggersRequest{})
    if err != nil {
        log.Fatal(err)
    }

    if res.ListTriggersResponse != nil {
        for _, trigger := range res.ListTriggersResponse.Triggers {
            fmt.Printf("%s: %s (%v)\n", trigger.ID, *trigger.GetDisplayName(), trigger.Status)
        }
    }
}
```
{% /tab %}
{% /tabs %}
### Get a trigger

Fetch the full configuration and current state of a single trigger.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
trigger = client.triggers.get(id="TRIGGER_ID")
print(f"Schedule: {trigger.schedule}")
print(f"Next run: {trigger.next_run_time}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const trigger = await client.triggers.get("TRIGGER_ID");
console.log(`Schedule: ${trigger.schedule}`);
console.log(`Next run: ${trigger.next_run_time}`);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X GET "https://generativelanguage.googleapis.com/v1beta/triggers/TRIGGER_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.gaos.GenAI;
import com.google.genai.gaos.models.shared.Security;
import com.google.genai.gaos.models.triggers.Trigger;

GenAI client = GenAI.builder()
    .security(Security.builder().apiKey(System.getenv("GEMINI_API_KEY")).build())
    .build();

Trigger trigger = client.triggers().get("TRIGGER_ID").trigger().get();
System.out.println("Schedule: " + trigger.schedule().orElse(""));
System.out.println("Next run: " + trigger.nextRunTime().orElse(null));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    interactionssdk "google.golang.org/genai/interactions"
    "google.golang.org/genai/interactions/models/components"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
        APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
    }))

    res, err := sdk.Triggers.Get(ctx, operations.GetTriggerRequest{
        ID: "TRIGGER_ID",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Schedule: %s\n", res.Trigger.Schedule)
    fmt.Printf("Next run: %v\n", res.Trigger.NextRunTime)
}
```
{% /tab %}
{% /tabs %}
### Pause and resume

You can pause a trigger to stop scheduled executions, and resume it to reactivate the schedule. Pausing does not affect manual executions.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Pause
client.triggers.update(id="TRIGGER_ID", status="paused")

# Resume
client.triggers.update(id="TRIGGER_ID", status="active")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
// Pause
await client.triggers.update("TRIGGER_ID", { status: "paused" });

// Resume
await client.triggers.update("TRIGGER_ID", { status: "active" });
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
# Pause
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/triggers/TRIGGER_ID" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{"status": "paused"}'

# Resume
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/triggers/TRIGGER_ID" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{"status": "active"}'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.gaos.GenAI;
import com.google.genai.gaos.models.shared.Security;
import com.google.genai.gaos.models.triggers.TriggerUpdate;
import com.google.genai.gaos.models.triggers.TriggerUpdateStatus;

GenAI client = GenAI.builder()
    .security(Security.builder().apiKey(System.getenv("GEMINI_API_KEY")).build())
    .build();

// Pause
client.triggers().update("TRIGGER_ID", TriggerUpdate.builder().status(TriggerUpdateStatus.PAUSED).build());

// Resume
client.triggers().update("TRIGGER_ID", TriggerUpdate.builder().status(TriggerUpdateStatus.ACTIVE).build());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"
    "os"

    "google.golang.org/genai"
    interactionssdk "google.golang.org/genai/interactions"
    "google.golang.org/genai/interactions/models/components"
    "google.golang.org/genai/interactions/models/operations"
    "google.golang.org/genai/interactions/models/triggers"
)

func main() {
    ctx := context.Background()
    sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
        APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
    }))

    // Pause
    _, err := sdk.Triggers.Update(ctx, operations.UpdateTriggerRequest{
        ID: "TRIGGER_ID",
        Body: triggers.TriggerUpdate{
            Status: triggers.TriggerUpdateStatusPaused.ToPointer(),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // Resume
    _, err = sdk.Triggers.Update(ctx, operations.UpdateTriggerRequest{
        ID: "TRIGGER_ID",
        Body: triggers.TriggerUpdate{
            Status: triggers.TriggerUpdateStatusActive.ToPointer(),
        },
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}
{% /tabs %}
### Delete a trigger

Permanently remove a trigger. Past execution history is not deleted.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
client.triggers.delete(id="TRIGGER_ID")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
await client.triggers.delete("TRIGGER_ID");
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/triggers/TRIGGER_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.gaos.GenAI;
import com.google.genai.gaos.models.shared.Security;

GenAI client = GenAI.builder()
    .security(Security.builder().apiKey(System.getenv("GEMINI_API_KEY")).build())
    .build();

client.triggers().delete("TRIGGER_ID");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"
    "os"

    "google.golang.org/genai"
    interactionssdk "google.golang.org/genai/interactions"
    "google.golang.org/genai/interactions/models/components"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
        APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
    }))

    _, err := sdk.Triggers.Delete(ctx, operations.DeleteTriggerRequest{
        ID: "TRIGGER_ID",
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}
{% /tabs %}
### Run a trigger immediately

Fire a trigger on demand without waiting for the next scheduled time. This works even if the trigger is paused.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
client.triggers.run(trigger_id="TRIGGER_ID")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
await client.triggers.run("TRIGGER_ID");
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/triggers/TRIGGER_ID/executions" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.gaos.GenAI;
import com.google.genai.gaos.models.shared.Security;

GenAI client = GenAI.builder()
    .security(Security.builder().apiKey(System.getenv("GEMINI_API_KEY")).build())
    .build();

client.triggers().run("TRIGGER_ID");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"
    "os"

    "google.golang.org/genai"
    interactionssdk "google.golang.org/genai/interactions"
    "google.golang.org/genai/interactions/models/components"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
        APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
    }))

    _, err := sdk.Triggers.Run(ctx, operations.RunTriggerRequest{
        TriggerID: "TRIGGER_ID",
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}
{% /tabs %}
### List executions

View the execution history for a trigger. Each execution includes a `status`, timestamps, an `interaction_id` you can use to fetch the full interaction output, and an `environment_id` confirming that all runs share the same sandbox.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
executions = client.triggers.list_executions(trigger_id="TRIGGER_ID")
for ex in executions.trigger_executions:
    print(f"{ex.id}: {ex.status} ({ex.start_time} - {ex.end_time})")

# Fetch the full interaction for an execution
interaction = client.interactions.get(id=ex.interaction_id)
print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const executions = await client.triggers.listExecutions("TRIGGER_ID");
for (const ex of executions.trigger_executions) {
    console.log(`${ex.id}: ${ex.status} (${ex.start_time} - ${ex.end_time})`);
}

// Fetch the full interaction for an execution
const interaction = await client.interactions.get(ex.interaction_id);
console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X GET "https://generativelanguage.googleapis.com/v1beta/triggers/TRIGGER_ID/executions" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.gaos.GenAI;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import com.google.genai.gaos.models.shared.Security;
import com.google.genai.gaos.models.triggers.TriggerExecution;
import java.util.List;

GenAI client = GenAI.builder()
    .security(Security.builder().apiKey(System.getenv("GEMINI_API_KEY")).build())
    .build();

List<TriggerExecution> executions = client.triggers().listExecutions("TRIGGER_ID")
    .listTriggerExecutionsResponse().get()
    .triggerExecutions().orElse(List.of());

for (TriggerExecution ex : executions) {
    System.out.println(ex.id().orElse("") + ": " + ex.status().orElse(null)
        + " (" + ex.startTime().orElse(null) + " - " + ex.endTime().orElse(null) + ")");

    // Fetch the full interaction for an execution
    if (ex.interactionId().isPresent()) {
        Interaction interaction = client.interactions().get(new GetInteractionByIdRequest(ex.interactionId().get())).interaction().get();
        System.out.println(interaction.outputText().orElse(""));
    }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    interactionssdk "google.golang.org/genai/interactions"
    "google.golang.org/genai/interactions/models/components"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
        APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
    }))

    res, err := sdk.Triggers.ListExecutions(ctx, operations.ListTriggerExecutionsRequest{
        TriggerID: "TRIGGER_ID",
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.ListTriggerExecutionsResponse != nil {
        for _, ex := range res.ListTriggerExecutionsResponse.TriggerExecutions {
            fmt.Printf("%s: %v (%v - %v)\n", ex.ID, ex.Status, ex.StartTime, ex.EndTime)

            // Fetch the full interaction for an execution
            if ex.InteractionID != nil {
                intRes, err := sdk.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
                    ID: *ex.InteractionID,
                })
                if err != nil {
                    log.Fatal(err)
                }
                if intRes.Interaction.OutputText != nil {
                    fmt.Println(*intRes.Interaction.OutputText)
                }
            }
        }
    }
}
```
{% /tab %}
{% /tabs %}
## Availability and pricing {% id="availability-and-pricing" %}

Antigravity agent is available in preview through the
[Interactions API](/docs/interactions-overview) in Google AI Studio
and the Gemini API for both free tier and paid tier projects.

Pricing follows a [pay-as-you-go model](/docs/pricing#pricing-for-agents)
based on the underlying Gemini model tokens and the tools the agent uses. Unlike a
standard chat request that produces a single output, an Antigravity interaction is an
agentic workflow. A single request triggers an autonomous loop of reasoning, tool
execution, code running, and file management. Free tier projects include a free rate limit
and usage quota.

Antigravity interactions run multi-turn autonomous loops and can consume
significant tokens. Set [budget controls](/docs/antigravity-agent#budget-controls) on your request to
limit token usage. You can also monitor progress in real time with
[SSE streaming](/docs/streaming), or cancel running requests.

### Budget controls {% id="budget-controls" %}

In addition to [model selection](/docs/antigravity-agent#model-selection), set `max_total_tokens` inside `agent_config` (with `"type": "antigravity"`) to limit
the total number of tokens (input + output + thinking) an interaction can consume.
Cached tokens do not count toward this limit. When the agent reaches the limit, the
interaction stops and returns with `status: "incomplete"`. The limit is best-effort:
actual usage may slightly exceed it depending on when the agent checks the budget
between steps.

Set the budget on the interaction request in `agent_config` alongside `agent` and `input`.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Analyze the dataset in /workspace/data.csv and generate a summary report.",
    agent_config={
        "type": "antigravity",
        "max_total_tokens": 50000
    },
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": "/workspace/data.csv",
                "content": "id,name,value\n1,alpha,100\n2,beta,200\n",
            }
        ],
    }
)
print(f"Status: {interaction.status}")  # "incomplete" if budget was hit
print(f"Tokens used: {interaction.usage.total_tokens}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Analyze the dataset in /workspace/data.csv and generate a summary report.",
    agent_config: {
        type: "antigravity",
        max_total_tokens: "50000"
    },
    environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: "/workspace/data.csv",
                content: "id,name,value\n1,alpha,100\n2,beta,200\n",
            },
        ],
    },
});
console.log(`Status: ${interaction.status}`);
console.log(`Tokens used: ${interaction.usage?.total_tokens}`);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Analyze the dataset in /workspace/data.csv and generate a summary report.",
    "agent_config": {
      "type": "antigravity",
      "max_total_tokens": 50000
    },
    "environment": {
      "type": "remote",
      "sources": [
        {
          "type": "inline",
          "target": "/workspace/data.csv",
          "content": "id,name,value\n1,alpha,100\n2,beta,200\n"
        }
      ]
    }
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.AntigravityAgentConfig;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.INLINE)
            .target("/workspace/data.csv")
            .content("id,name,value\n1,alpha,100\n2,beta,200\n")
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Analyze the dataset in /workspace/data.csv and generate a summary report."))
    .agentConfig(
        AntigravityAgentConfig.builder()
            .maxTotalTokens("50000")
            .build()
    )
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Status: " + interaction.status().orElse(null)); // "incomplete" if budget was hit
interaction.usage().ifPresent(usage -> System.out.println("Tokens used: " + usage.totalTokens().orElse(0)));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr("/workspace/data.csv"),
                Content: genai.Ptr("id,name,value\n1,alpha,100\n2,beta,200\n"),
            },
        },
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("antigravity-preview-09-2026"),
            Input: interactions.NewInteractionsInput("Analyze the dataset in /workspace/data.csv and generate a summary report."),
            AgentConfig: genai.Ptr(interactions.NewCreateAgentInteractionAgentConfig(interactions.AntigravityAgentConfig{
                MaxTotalTokens: genai.Ptr(int64(50000)),
            })),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    interaction := res.Interaction
    fmt.Printf("Status: %s\n", interaction.Status) // "incomplete" if budget was hit
    if interaction.Usage != nil && interaction.Usage.TotalTokens != nil {
        fmt.Printf("Tokens used: %d\n", *interaction.Usage.TotalTokens)
    }
}
```
{% /tab %}
{% /tabs %}
#### Continuing an incomplete interaction {% id="continuing-incomplete-interaction" %}

When an interaction returns `status: "incomplete"`, the agent's work and context
are preserved. Send a new interaction referencing the original interaction `id` and
`environment_id` to pick up where it left off. The new interaction gets its own
`max_total_tokens` budget.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Continue from where the agent stopped
continuation = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="continue",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    agent_config={
        "type": "antigravity",
        "max_total_tokens": 50000
    }
)
print(f"Status: {continuation.status}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const continuation = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "continue",
    previous_interaction_id: interaction.id,
    environment: interaction.environment_id,
    agent_config: {
        type: "antigravity",
        max_total_tokens: "50000"
    }
});
console.log(`Status: ${continuation.status}`);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "agent": "antigravity-preview-09-2026",
    "input": "continue",
    "previous_interaction_id": "INTERACTION_ID",
    "environment": "ENVIRONMENT_ID",
    "agent_config": {
      "type": "antigravity",
      "max_total_tokens": 50000
    }
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.AntigravityAgentConfig;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();
String interactionId = "INTERACTION_ID";
String environmentId = "ENVIRONMENT_ID";

// Continue from where the agent stopped
CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("continue"))
    .previousInteractionId(interactionId)
    .environment(CreateAgentInteractionEnvironment.of(environmentId))
    .agentConfig(
        AntigravityAgentConfig.builder()
            .maxTotalTokens("50000")
            .build()
    )
    .build();

Interaction continuation = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Status: " + continuation.status().orElse(null));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    interactionID := "INTERACTION_ID"
    environmentID := "ENVIRONMENT_ID"

    // Continue from where the agent stopped
    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:                 interactions.AgentOption("antigravity-preview-09-2026"),
            Input:                 interactions.NewInteractionsInput("continue"),
            PreviousInteractionID: genai.Ptr(interactionID),
            Environment:           genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(environmentID)),
            AgentConfig: genai.Ptr(interactions.NewCreateAgentInteractionAgentConfig(interactions.AntigravityAgentConfig{
                MaxTotalTokens: genai.Ptr(int64(50000)),
            })),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Status: %s\n", res.Interaction.Status)
}
```
{% /tab %}
{% /tabs %}
### Estimated costs

Costs vary based on task complexity. The agent autonomously determines how many tool calls, code executions, and file operations are needed. The following estimates are based on runs.

| Task category | Input tokens | Output tokens | Typical cost |
| :---- | :---- | :---- | :---- |
| **Research & information synthesis** | 100k–500k | 10k–40k | $0.30–$1.00 |
| **Document & content generation** | 100k–500k | 15k–50k | $0.30–$1.30 |
| **Process & system design** | 100k–400k | 10k–30k | $0.25–$0.80 |
| **Data processing & analysis** | 300k–3M | 30k–150k | $0.70–$3.25 |

50–70% of input tokens are typically cached. Complex agentic workflows with many tool calls can accumulate 3–5 million tokens in a single interaction, with costs up to \~$5.

**Environment compute** (CPU, memory, sandbox execution) is **not billed** during the preview period.

## Limitations {% id="limitations" %}

- **Preview status:** The Antigravity agent and the Interactions API. Features and schemas may change.
- **Unsupported generation config:** The following parameters are not supported and return a 400 error: `temperature`, `top_p`, `top_k`, `stop_sequences`, `max_output_tokens`.
- **Structured output:** The Antigravity agent does not support structured outputs.
- **Unavailable tools:** `file_search`, `computer_use`, and `google_maps` are not yet supported.
- **Remote MCP limitations:** Server-Sent Events (SSE) transport is not supported (use Streamable HTTP). Additionally, the server `name` must be strictly lowercase and alphanumeric (using uppercase letters triggers a generic `400 Bad Request` error).
- **Filesystem tool:** There is no filesystem tool at the moment. It is part of the `environment`.
- **Store requirement:** Agent execution using `background=True` requires `store=True`.
- **Stateful only function calling:** Function calling is only supported in stateful mode. You must use `previous_interaction_id` to continue the turn; reconstructing history manually (stateless mode) is not supported.
- **Unsupported multimodal types.** Audio, video, and document inputs are not supported at the moment. Only text and image are allowed.

## What's next {% id="whats-next" %}
- [Quickstart](/docs/managed-agents-quickstart): multi-turn conversations and streaming.
- [Building Custom Agents](/docs/custom-agents): custom instructions, skills, and saving agents.
- [Environments](/docs/agent-environment): sandbox configuration, sources, networking.
- [Hooks](/docs/agent-hooks): enforce security gates and side-effect validation inside the sandbox.
- [Deep Research agent](/docs/deep-research): long-form research tasks.
- [Interactions API](/docs/interactions-overview): the underlying API.

# Building managed agents
Source: https://aistudio.google.com/docs/custom-agents
Description: How to create and use custom agents with managed agents in the Gemini API.

Managed agents on the Gemini API let you extend the Antigravity agent with your own instructions, skills, and data. You can [customize the agent inline](/docs/custom-agents#customize-inline) at interaction time, or [save the configuration](/docs/custom-agents#save-agent) as a managed agent you invoke by ID.

## Customize the Antigravity agent {% id="customize-inline" %}

The fastest way to build a custom agent is to pass your configuration inline while creating a new interaction with no registration step required. You can extend the agent in several key ways:

* **[Model selection](/docs/antigravity-agent#model-selection)**: Choose the underlying Gemini model via `agent_config` (defaults to **Gemini 3.8 Flash**).
* **System instructions**: Pass inline text via `system_instruction` to shape behavior.
* **Tools**: Override default tools (Code Execution, Search, URL Context), register remote MCP servers, or define custom functions (Function Calling).
* **Files and skills**: Mount files like `AGENTS.md` and `SKILL.md` into the environment.

Here is an example of passing all three inline:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Analyze the Q1 revenue data and create a slide deck.",
    system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always use matplotlib for charts. Include a summary table in every report.",
            },
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",
            },
        ],
    },
)

print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Analyze the Q1 revenue data and create a slide deck.",
    system_instruction: "You are a data analyst. Always include visualizations and export results as PDF.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/AGENTS.md",
                content: "Always use matplotlib for charts. Include a summary table in every report.",
            },
            {
                type: "inline",
                target: ".agents/skills/slide-maker/SKILL.md",
                content: "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",
            },
        ],
    },
}, { timeout: 300000 });

console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Analyze the Q1 revenue data and create a slide deck.",
    "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always use matplotlib for charts. Include a summary table in every report."
            },
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results."
            }
        ]
    }
}'
```

Everything is defined at interaction time. No need to register anything first. The Antigravity agent harness provides the runtime (code execution, file management, web access) and your configuration layers on top.

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/AGENTS.md")
            .content("Always use matplotlib for charts. Include a summary table in every report.")
            .build(),
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/skills/slide-maker/SKILL.md")
            .content("---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.")
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Analyze the Q1 revenue data and create a slide deck."))
    .systemInstruction("You are a data analyst. Always include visualizations and export results as PDF.")
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/AGENTS.md"),
                Content: genai.Ptr("Always use matplotlib for charts. Include a summary table in every report."),
            },
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/skills/slide-maker/SKILL.md"),
                Content: genai.Ptr("---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results."),
            },
        },
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:             interactions.AgentOption("antigravity-preview-09-2026"),
            Input:             interactions.NewInteractionsInput("Analyze the Q1 revenue data and create a slide deck."),
            SystemInstruction: genai.Ptr("You are a data analyst. Always include visualizations and export results as PDF."),
            Environment:       genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
### Tools and system instructions

You can customize the agent's behavior and capabilities for a specific interaction using the `system_instruction` and `tools` parameters.

- **System instructions**: Use the `system_instruction` parameter to pass inline text that shapes the agent's behavior. This is ideal for quick tweaks you want to change per call. The `system_instruction` and `AGENTS.md` are additive; both apply when present.
- **Tools**: By default, the Antigravity agent has access to `code_execution`, `google_search`, and `url_context`. You can override this list by passing the `tools` parameter at interaction time. You can also register [remote MCP servers](/docs/antigravity-agent#mcp-servers) or define [custom functions (function calling)](/docs/antigravity-agent#function-calling) to connect the agent to your own APIs and databases. For full details on available tools, see [Antigravity Agent: Supported tools](/docs/antigravity-agent#supported-tools).

### File-based customization

#### Agent directory structure

While you can pass configuration inline, we recommend organizing your agent's files in a structured directory. This makes it easier to manage, version control, and mount into the agent's environment.

{% callout type="note" %}
You can also use the open-source [Gemini API CLI](/docs/cli) to create and run custom agents or connect local sandbox environments directly from your terminal.
{% /callout %}

A typical agent project directory looks like this:

```text
my-agent/
├── AGENTS.md        # Instructions on how the agent should operate
├── skills/          # Custom skills (subfolders and SKILL.md files)
│   └── slide-maker/
│       └── SKILL.md
└── workspace/       # Initial data files and knowledge
```

The Antigravity runtime scans `.agents/` (and the root of the environment) for these files.

#### AGENTS.md

The agent automatically loads `.agents/AGENTS.md` (or `/.agents/AGENTS.md`) from the environment as system instructions on startup. Use `AGENTS.md` for long-form persona definitions, detailed guidelines, and instructions you want to version control alongside your code.

Mount an `AGENTS.md` using an inline source:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Analyze the Q1 revenue data and create a report.",
    system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always use matplotlib for charts. Include a summary table in every report.",
            },
        ],
    },
)

print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Analyze the Q1 revenue data and create a report.",
    system_instruction: "You are a data analyst. Always include visualizations and export results as PDF.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/AGENTS.md",
                content: "Always use matplotlib for charts. Include a summary table in every report.",
            },
        ],
    },
}, { timeout: 300000 });

console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": "Analyze the Q1 revenue data and create a report.",
      "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",
      "environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "inline",
                  "target": ".agents/AGENTS.md",
                  "content": "Always use matplotlib for charts. Include a summary table in every report."
              }
          ]
      }
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/AGENTS.md")
            .content("Always use matplotlib for charts. Include a summary table in every report.")
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Analyze the Q1 revenue data and create a report."))
    .systemInstruction("You are a data analyst. Always include visualizations and export results as PDF.")
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/AGENTS.md"),
                Content: genai.Ptr("Always use matplotlib for charts. Include a summary table in every report."),
            },
        },
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:             interactions.AgentOption("antigravity-preview-09-2026"),
            Input:             interactions.NewInteractionsInput("Analyze the Q1 revenue data and create a report."),
            SystemInstruction: genai.Ptr("You are a data analyst. Always include visualizations and export results as PDF."),
            Environment:       genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
#### Skills: SKILL.md

Skills are files that extend the agent's capabilities. Place them under `.agents/skills/<skill-name>/SKILL.md` and the harness auto-discovers and registers them.

```text
.agents/
├── AGENTS.md
└── skills/
    └── slide-maker/
        └── SKILL.md
```

Mount a skill using an inline source:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Create a presentation about our Q1 results.",
    system_instruction="You create presentations from data.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",
            },
        ],
    },
)

print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Create a presentation about our Q1 results.",
    system_instruction: "You create presentations from data.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/skills/slide-maker/SKILL.md",
                content: "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",
            },
        ],
    },
}, { timeout: 300000 });

console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": "Create a presentation about our Q1 results.",
      "system_instruction": "You create presentations from data.",
      "environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "inline",
                  "target": ".agents/skills/slide-maker/SKILL.md",
                  "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html"
              }
          ]
      }
  }'
```

Skills loaded from `.agents/skills/` and `/.agents/skills/` are both discovered automatically.

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/skills/slide-maker/SKILL.md")
            .content("---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html")
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Create a presentation about our Q1 results."))
    .systemInstruction("You create presentations from data.")
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/skills/slide-maker/SKILL.md"),
                Content: genai.Ptr("---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html"),
            },
        },
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:             interactions.AgentOption("antigravity-preview-09-2026"),
            Input:             interactions.NewInteractionsInput("Create a presentation about our Q1 results."),
            SystemInstruction: genai.Ptr("You create presentations from data."),
            Environment:       genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
## Create a managed agent {% id="save-agent" %}

Once you've iterated on your configuration, you can create it as a managed agent with `agents.create`. This lets you invoke the agent by ID without repeating the configuration each time.

The `id` you specify when creating a managed agent must be unique to your project and must not start with reserved prefixes (e.g., `google-`, `gemini-`). See [Agent ID restrictions](/docs/custom-agents#agent-id-restrictions) for the full list of restricted prefixes.

### From sources

Specify `base_agent`, `id`, `agent_config`, `system_instruction` and `base_environment` with sources. The platform provisions a fresh sandbox with your files on every invocation. See [Environments](/docs/agent-environment) for available source types (Git, GCS, inline).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

agent = client.agents.create(
    id="data-analyst",
    base_agent="antigravity-preview-09-2026",
    agent_config={
        "type": "antigravity",
        "model": "gemini-3.8-flash",
    },
    system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always use matplotlib for charts. Include a summary table in every report.",
            },
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",
            },
            {
                "type": "repository",
                "source": "https://github.com/my-org/analysis-templates",
                "target": "/workspace/templates",
            },
        ],
    },
)

print(f"Created agent: {agent.id}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "data-analyst",
    base_agent: "antigravity-preview-09-2026",
    agent_config: {
        type: "antigravity",
        model: "gemini-3.8-flash",
    },
    system_instruction: "You are a data analyst. Always include visualizations and export results as PDF.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/AGENTS.md",
                content: "Always use matplotlib for charts. Include a summary table in every report.",
            },
            {
                type: "inline",
                target: ".agents/skills/slide-maker/SKILL.md",
                content: "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",
            },
            {
                type: "repository",
                source: "https://github.com/my-org/analysis-templates",
                target: "/workspace/templates",
            },
        ],
    },
});

console.log(`Created agent: ${agent.id}`);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "data-analyst",
    "base_agent": "antigravity-preview-09-2026",
    "agent_config": {
        "type": "antigravity",
        "model": "gemini-3.8-flash"
    },
    "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",
    "base_environment": {
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always use matplotlib for charts. Include a summary table in every report."
            },
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results."
            },
            {
                "type": "repository",
                "source": "https://github.com/my-org/analysis-templates",
                "target": "/workspace/templates"
            }
        ]
    }
}'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.gaos.models.agents.AgentConfig;
import com.google.genai.gaos.models.agents.BaseEnvironment;
import com.google.genai.gaos.models.interactions.AntigravityAgentConfig;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import java.util.List;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/AGENTS.md")
            .content("Always use matplotlib for charts. Include a summary table in every report.")
            .build(),
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/skills/slide-maker/SKILL.md")
            .content("---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.")
            .build(),
        Source.builder()
            .type(SourceType.REPOSITORY)
            .source("https://github.com/my-org/analysis-templates")
            .target("/workspace/templates")
            .build()
    ))
    .build();

Agent agentParams = Agent.builder()
    .id("data-analyst")
    .baseAgent("antigravity-preview-09-2026")
    .agentConfig(AgentConfig.of(
        AntigravityAgentConfig.builder()
            .model("gemini-3.8-flash")
            .build()
    ))
    .systemInstruction("You are a data analyst. Always include visualizations and export results as PDF.")
    .baseEnvironment(BaseEnvironment.of(env))
    .build();

Agent agent = client.agents.create(agentParams).agent().get();
System.out.println("Created agent: " + agent.id().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/agents"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/AGENTS.md"),
                Content: genai.Ptr("Always use matplotlib for charts. Include a summary table in every report."),
            },
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/skills/slide-maker/SKILL.md"),
                Content: genai.Ptr("---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results."),
            },
            {
                Type:   interactions.SourceTypeRepository.ToPointer(),
                Source: genai.Ptr("https://github.com/my-org/analysis-templates"),
                Target: genai.Ptr("/workspace/templates"),
            },
        },
    }

    res, err := client.Agents.Create(ctx, operations.CreateAgentRequest{
        Body: agents.Agent{
            ID:        genai.Ptr("data-analyst"),
            BaseAgent: genai.Ptr("antigravity-preview-09-2026"),
            AgentConfig: genai.Ptr(agents.NewAgentConfig(interactions.AntigravityAgentConfig{
                Model: genai.Ptr("gemini-3.8-flash"),
            })),
            SystemInstruction: genai.Ptr("You are a data analyst. Always include visualizations and export results as PDF."),
            BaseEnvironment:   genai.Ptr(agents.NewBaseEnvironment(env)),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created agent: %s\n", *res.Agent.ID)
}
```
{% /tab %}
{% /tabs %}
### From an existing environment (fork)

Iterate with the base Antigravity agent until the environment is right (packages installed, files in place), then fork it into a managed agent.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

# Step 1: set up the environment interactively
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",
    environment="remote",
)

# Step 2: fork that environment into a managed agent

agent = client.agents.create(
    id="my-data-analyst",
    base_agent="antigravity-preview-09-2026",
    system_instruction="You are a data analyst. Use the template at /workspace/template.py for all reports.",
    base_environment=interaction.environment_id,
)

print(f"Forked agent successfully: {agent.id}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",
    environment: "remote",
}, { timeout: 300000 });

const agent = await client.agents.create({
    id: "my-data-analyst",
    base_agent: "antigravity-preview-09-2026",
    system_instruction: "You are a data analyst. Use the template at /workspace/template.py for all reports.",
    base_environment: interaction.environment_id,
});

console.log(`Forked agent successfully: ${agent.id}`);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": "Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",
      "environment": "remote"
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.gaos.models.agents.BaseEnvironment;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// Step 1: set up the environment interactively
CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

// Step 2: fork that environment into a managed agent
Agent agentParams = Agent.builder()
    .id("my-data-analyst")
    .baseAgent("antigravity-preview-09-2026")
    .systemInstruction("You are a data analyst. Use the template at /workspace/template.py for all reports.")
    .baseEnvironment(BaseEnvironment.of(interaction.environmentId().orElse("")))
    .build();

Agent agent = client.agents.create(agentParams).agent().get();
System.out.println("Forked agent successfully: " + agent.id().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/agents"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Step 1: set up the environment interactively
    intRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    interaction := intRes.Interaction

    // Step 2: fork that environment into a managed agent
    agentRes, err := client.Agents.Create(ctx, operations.CreateAgentRequest{
        Body: agents.Agent{
            ID:                genai.Ptr("my-data-analyst"),
            BaseAgent:         genai.Ptr("antigravity-preview-09-2026"),
            SystemInstruction: genai.Ptr("You are a data analyst. Use the template at /workspace/template.py for all reports."),
            BaseEnvironment:   genai.Ptr(agents.NewBaseEnvironment(*interaction.EnvironmentID)),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Forked agent successfully: %s\n", *agentRes.Agent.ID)
}
```
{% /tab %}
{% /tabs %}
### With network rules {% id="with-network-rules" %}

You can lock down outbound access or inject credentials when saving a managed agent. For the full allowlist schema, credential patterns, and wildcards, see [Environments: Network configuration](/docs/agent-environment#network-configuration).

Reference a stored [credential](/docs/agent-credentials) by ID on an allowlist rule (`"credential": "github-production"`) and the egress proxy injects the secret at request time, so it never lands in your agent definition. This example sets the header inline with `transform` instead. The proxy applies both forms the same way, a credential additionally lets you reuse the secret across agents and rotate it in one place.

The following example creates an `issue-resolver` agent that can only access GitHub and PyPI, with credentials injected for GitHub:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-09-2026",
    system_instruction="You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

print(f"Created issue-resolver agent successfully: {agent.id}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "issue-resolver",
    base_agent: "antigravity-preview-09-2026",
    system_instruction: "You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/my-org/backend",
                target: "/workspace/repo",
            }
        ],
        network: {
            allowlist: [
                {
                    domain: "api.github.com",
                    transform: {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    },
                },
                { domain: "pypi.org" },
            ]
        }
    },
});

console.log(`Created issue-resolver agent successfully: ${agent.id}`);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "id": "issue-resolver",
      "base_agent": "antigravity-preview-09-2026",
      "system_instruction": "You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "repository",
                  "source": "https://github.com/my-org/backend",
                  "target": "/workspace/repo"
              }
          ],
          "network": {
              "allowlist": [
                  {
                      "domain": "api.github.com",
                      "transform": {
                          "Authorization": "Basic YOUR_BASE64_TOKEN"
                      }
                  },
                  {"domain": "pypi.org"}
              ]
          }
      }
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.gaos.models.agents.BaseEnvironment;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.interactions.Transform;
import java.util.List;
import java.util.Map;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.REPOSITORY)
            .source("https://github.com/my-org/backend")
            .target("/workspace/repo")
            .build()
    ))
    .network(Network.of(
        EnvironmentNetworkEgressAllowlist.builder()
            .allowlist(Allowlist.of(List.of(
                AllowlistEntry.builder()
                    .domain("api.github.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Basic YOUR_BASE64_TOKEN"
                    )))
                    .build(),
                AllowlistEntry.builder().domain("pypi.org").build()
            )))
            .build()
    ))
    .build();

Agent agentParams = Agent.builder()
    .id("issue-resolver")
    .baseAgent("antigravity-preview-09-2026")
    .systemInstruction("You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.")
    .baseEnvironment(BaseEnvironment.of(env))
    .build();

Agent agent = client.agents.create(agentParams).agent().get();
System.out.println("Created issue-resolver agent successfully: " + agent.id().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/agents"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:   interactions.SourceTypeRepository.ToPointer(),
                Source: genai.Ptr("https://github.com/my-org/backend"),
                Target: genai.Ptr("/workspace/repo"),
            },
        },
        Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
            Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                {
                    Domain: "api.github.com",
                    Transform: genai.Ptr(interactions.NewTransform(map[string]string{
                        "Authorization": "Basic YOUR_BASE64_TOKEN",
                    })),
                },
                {
                    Domain: "pypi.org",
                },
            })),
        })),
    }

    res, err := client.Agents.Create(ctx, operations.CreateAgentRequest{
        Body: agents.Agent{
            ID:                genai.Ptr("issue-resolver"),
            BaseAgent:         genai.Ptr("antigravity-preview-09-2026"),
            SystemInstruction: genai.Ptr("You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR."),
            BaseEnvironment:   genai.Ptr(agents.NewBaseEnvironment(env)),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created issue-resolver agent successfully: %s\n", *res.Agent.ID)
}
```
{% /tab %}
{% /tabs %}
## Invoke the agent

Call your managed agent with your agent ID by creating a new interaction. Each invocation forks the base environment, so every run starts clean.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",
    environment="remote",
)

print(result.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const result = await client.interactions.create({
    agent: "data-analyst",
    input: "Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",
    environment: "remote",
}, { timeout: 300000 });

console.log(result.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "data-analyst",
      "input": "Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",
      "environment": "remote"
  }'
```

For multi-turn conversations and streaming, see the [Quickstart](/docs/managed-agents-quickstart). The same `previous_interaction_id` and `environment` patterns apply to managed agents.

Managed agents also support background execution and cancellation. For details and code examples, see [Antigravity Agent: Background execution](/docs/antigravity-agent#background-execution).

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("data-analyst"))
    .input(InteractionsInput.of("Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();

Interaction result = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(result.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("data-analyst"),
            Input:       interactions.NewInteractionsInput("Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
## Overriding configuration at invocation

You can override the agent's default `system_instruction`, `tools`, and
`environment` network configuration when creating an interaction. This
lets you modify the agent's behavior, capabilities, or credentials for a
specific run without changing the stored agent definition.

### Override system instruction and tools

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",
    system_instruction="You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",
    tools=[{"type": "code_execution"}], # Override to only use code execution
    environment="remote",
)
print(result.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const result = await client.interactions.create({
    agent: "data-analyst",
    input: "Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",
    system_instruction: "You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",
    tools: [{ type: "code_execution" }], // Override to only use code execution
    environment: "remote",
}, { timeout: 300000 });

console.log(result.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "data-analyst",
      "input": "Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",
      "system_instruction": "You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",
      "tools": [{"type": "code_execution"}],
      "environment": "remote"
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("data-analyst"))
    .input(InteractionsInput.of("Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table."))
    .systemInstruction("You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.")
    .tools(List.of(CodeExecution.builder().build())) // Override to only use code execution
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();

Interaction result = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(result.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:             interactions.AgentOption("data-analyst"),
            Input:             interactions.NewInteractionsInput("Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table."),
            SystemInstruction: genai.Ptr("You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides."),
            Tools:             []interactions.Tool{interactions.NewTool(interactions.CodeExecution{})}, // Override to only use code execution
            Environment:       genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

### Override network configuration (refresh credentials) {% id="override-network" %}

If your managed agent has network credentials baked into its `base_environment`,
you can override them at invocation time to refresh expired tokens or rotate API
keys. Pass an `environment` object with a new `network` configuration. The new
network rules fully replace the previous ones for that interaction. The base
environment's sources (files, repositories) are preserved.

If the `base_environment` references a stored
[credential](/docs/agent-credentials) instead of an inline token, you don't need
to override anything. Rotate the credential with a `PATCH` and every agent
referencing it picks up the new secret on the next run.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Invoke the agent with a fresh token, overriding the base_environment credentials
result = client.interactions.create(
    agent="issue-resolver",
    input="Fix issue #42 and open a PR.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_REFRESHED_TOKEN"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

print(result.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
// Invoke the agent with a fresh token, overriding the base_environment credentials
const result = await client.interactions.create({
    agent: "issue-resolver",
    input: "Fix issue #42 and open a PR.",
    environment: {
        type: "remote",
        network: {
            allowlist: [
                {
                    domain: "api.github.com",
                    transform: {
                        "Authorization": "Bearer ghp_REFRESHED_TOKEN"
                    },
                },
                { domain: "pypi.org" },
            ]
        },
    },
}, { timeout: 300000 });

console.log(result.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "issue-resolver",
      "input": "Fix issue #42 and open a PR.",
      "environment": {
          "type": "remote",
          "network": {
              "allowlist": [
                  {
                      "domain": "api.github.com",
                      "transform": {
                          "Authorization": "Bearer ghp_REFRESHED_TOKEN"
                      }
                  },
                  {"domain": "pypi.org"}
              ]
          }
      }
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;

Client client = new Client();

// Invoke the agent with a fresh token, overriding the base_environment credentials
Environment env = Environment.builder()
    .network(Network.of(
        EnvironmentNetworkEgressAllowlist.builder()
            .allowlist(Allowlist.of(List.of(
                AllowlistEntry.builder()
                    .domain("api.github.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer ghp_REFRESHED_TOKEN"
                    )))
                    .build(),
                AllowlistEntry.builder().domain("pypi.org").build()
            )))
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("issue-resolver"))
    .input(InteractionsInput.of("Fix issue #42 and open a PR."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction result = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(result.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Invoke the agent with a fresh token, overriding the base_environment credentials
    env := interactions.Environment{
        Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
            Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                {
                    Domain: "api.github.com",
                    Transform: genai.Ptr(interactions.NewTransform(map[string]string{
                        "Authorization": "Bearer ghp_REFRESHED_TOKEN",
                    })),
                },
                {
                    Domain: "pypi.org",
                },
            })),
        })),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("issue-resolver"),
            Input:       interactions.NewInteractionsInput("Fix issue #42 and open a PR."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
## Manage agents

You can list, get, and delete agents.

### List agents

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
agents = client.agents.list()
for a in agents.agents:
    print(f"{a.id}: {a.description}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const agents = await client.agents.list();
if (agents.agents) {
    for (const a of agents.agents) {
        console.log(`${a.id}: ${a.description}`);
    }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X GET "https://generativelanguage.googleapis.com/v1beta/agents" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.agents.Agent;
import java.util.List;

Client client = new Client();

List<Agent> agents = client.agents.listDirect().agentListResponse().get().agents().orElse(List.of());
for (Agent a : agents) {
    System.out.println(a.id().orElse("") + ": " + a.description().orElse(""));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Agents.List(ctx, operations.ListAgentsRequest{})
    if err != nil {
        log.Fatal(err)
    }

    if res.AgentListResponse != nil {
        for _, a := range res.AgentListResponse.Agents {
            fmt.Printf("%s: %v\n", *a.ID, a.Description)
        }
    }
}
```
{% /tab %}
{% /tabs %}
### Get an agent

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
agent = client.agents.get(id="data-analyst")
print(agent)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const agent = await client.agents.get("data-analyst");
console.log(agent);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X GET "https://generativelanguage.googleapis.com/v1beta/agents/data-analyst" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.agents.Agent;

Client client = new Client();

Agent agent = client.agents.get("data-analyst").agent().get();
System.out.println(agent);
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Agents.Get(ctx, operations.GetAgentRequest{
        ID: "data-analyst",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("%+v\n", res.Agent)
}
```
{% /tab %}
{% /tabs %}
### Delete an agent

Deleting removes the configuration. Existing environments and interactions created by the agent are not affected.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
client.agents.delete(id="data-analyst")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
await client.agents.delete("data-analyst");
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/agents/data-analyst" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;

Client client = new Client();

client.agents.delete("data-analyst");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Agents.Delete(ctx, operations.DeleteAgentRequest{
        ID: "data-analyst",
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}
{% /tabs %}
## Agent definition reference

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `id` | string | Yes | Unique agent identifier within the Google Cloud project. Used to invoke the agent. Must not use reserved prefixes. See [Agent ID restrictions](/docs/custom-agents#agent-id-restrictions). |
| `description` | string | No | Human-readable description of the agent. |
| `base_agent` | string | Yes | Base agent ID (e.g., `antigravity-preview-09-2026`). |
| `agent_config` | object | No | Configuration for the base agent, including model selection (`{"type": "antigravity", "model": "gemini-3.8-flash"}`). Defaults to `gemini-3.8-flash` if omitted. Cannot be overridden at interaction time for named agents. |
| `system_instruction` | string | No | System prompt defining behavior and persona. |
| `tools` | array | No | Tools the agent can use. If omitted, defaults to `code_execution`, `google_search`, and `url_context`. Supported tools include `code_execution`, `google_search`, `url_context`, `mcp_server`, and custom `function` definitions. |
| `base_environment` | string or object | No | `"remote"`, an `environment_id`, or a config object with `sources` and `network`. See Environments. |

### Agent ID restrictions {% id="agent-id-restrictions" %}

When creating a managed agent, the `id` you specify must follow these rules:

* It must be unique to your Google Cloud project.
* It must **not** start with any of the following reserved prefixes (case-insensitive), otherwise creation will fail:
    * `antigravity-`
    * `veo-`
    * `omni-`
    * `lyria-`
    * `imagen-`
    * `gemma-`
    * `gemini-`
    * `google-`
    * `youtube-`
    * `android-`
    * `chrome-`
    * `pixel-`
    * `waze-`
    * `fitbit-`
    * `nest-`
    * `kaggle-`

## Iteration workflow {% id="iteration-workflow" %}

1. **Prototype** with the base Antigravity agent. Pass system instruction and environment sources inline. Test instructions, skills, and environment setup interactively.
2. **Stabilize** the environment. Install packages, mount sources, verify everything works.
3. **Persist** as a managed agent by creating a new agent, either from sources or by forking the environment.
4. **Update** the agent definition. Change system instruction, swap skills, or add sources. The next invocation picks up the new configuration.

## Limitations {% id="limitations" %}

* **Preview status**: Managed agents are in preview. Features and schemas may change.
*   **Base agent and models**: Only `antigravity-preview-09-2026` is supported
    as `base_agent`. Supported model options in `agent_config` are
    `gemini-3.8-flash` (default), `gemini-3.6-flash`, and
    `gemini-3.5-flash-lite`. For named agents, the model cannot be overridden at
    interaction time.
* **No versioning**: Agent versioning and rollback are not yet available.
* **No subagent nesting**: Subagent delegation is not yet supported.
* You can have up to 1000 managed agents.

## What's next {% id="whats-next" %}
* [Agents Overview](/docs/agents): Learn about the core concepts of managed agents.
* [Quickstart](/docs/managed-agents-quickstart): Start building with multi-turn conversations and streaming.
* [Antigravity Agent](/docs/antigravity-agent): Explore capabilities, tools, and pricing for the default agent.
* [Agent Environments](/docs/agent-environment): Configure sandboxes, sources, and networking.
* [Managed Agents API on Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents): For creating agents with built-in organizational governance.

# Environments in managed agents
Source: https://aistudio.google.com/docs/agent-environment
Description: Learn how to provision, configure, and manage remote sandbox environments in Gemini Managed Agents.

Environments are managed Linux sandboxes that give agents an isolated place to
execute code and persist files. They are decoupled from interaction context, so you can reuse the same environment across multiple interactions or start fresh at any time.

The following example demonstrates how to create an interaction with a fresh
remote environment and retrieve its ID:

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Install pandas and matplotlib, verify the imports, and print the versions.",
    environment="remote",
)

print(f"Environment ID: {interaction.environment_id}")
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Install pandas and matplotlib, verify the imports, and print the versions.",
    environment: "remote",
});

console.log(`Environment ID: ${interaction.environment_id}`);
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Install pandas and matplotlib, verify the imports, and print the versions.",
    "environment": "remote"
}'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Install pandas and matplotlib, verify the imports, and print the versions."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Environment ID: " + interaction.environmentId().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Install pandas and matplotlib, verify the imports, and print the versions."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.EnvironmentID != nil {
        fmt.Printf("Environment ID: %s\n", *res.Interaction.EnvironmentID)
    }
}
```
{% /tab %}
{% /tabs %}

## The `environment` parameter {% id="the-environment-parameter" %}

The `environment` parameter accepts three forms:

| Form | Example | When to use |
| :---- | :---- | :---- |
| `"remote"` | `environment="remote"` | Provision a fresh sandbox. |
| Environment ID | `environment="env_abc123"` | Reuse an existing sandbox with all its files and packages. |
| Config object | `environment={...}` | Provision a new sandbox with sources, network rules, environment variables, or a combination. |

The following examples demonstrate the three ways of using the `environment`
parameter.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

# Fresh sandbox
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Write a hello world script.",
    environment="remote",
)

# Reuse an existing sandbox
interaction_2 = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Modify the script to accept a name argument.",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
)

# New sandbox with sources
interaction_3 = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="List all files and summarize the project.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/octocat/Spoon-Knife",
                "target": "/workspace/spoon-knife",
            }
        ],
    },
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

// Fresh sandbox
const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Write a hello world script.",
    environment: "remote",
});

// Reuse an existing sandbox
const interaction2 = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Modify the script to accept a name argument.",
    environment: interaction.environment_id,
    previous_interaction_id: interaction.id,
});

// New sandbox with sources
const interaction3 = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "List all files and summarize the project.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/octocat/Spoon-Knife",
                target: "/workspace/spoon-knife",
            },
        ],
    },
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
# Fresh sandbox
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": [{"type": "text", "text": "Write a hello world script."}],
    "environment": "remote"
}'

# Reuse an existing sandbox (replace $ENV_ID and $INTERACTION_ID with values from the previous response)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d "{
    \"agent\": \"antigravity-preview-09-2026\",
    \"input\": [{\"type\": \"text\", \"text\": \"Modify the script to accept a name argument.\"}],
    \"environment\": \"$ENV_ID\",
    \"previous_interaction_id\": \"$INTERACTION_ID\"
}"

# New sandbox with sources
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": [{"type": "text", "text": "List all files and summarize the project."}],
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/octocat/Spoon-Knife",
                "target": "/workspace/spoon-knife"
            }
        ]
    }
}'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

// Fresh sandbox
CreateAgentInteraction params1 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Write a hello world script."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();
Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();

// Reuse an existing sandbox
CreateAgentInteraction params2 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Modify the script to accept a name argument."))
    .environment(CreateAgentInteractionEnvironment.of(interaction.environmentId().orElse("")))
    .previousInteractionId(interaction.id().orElse(""))
    .build();
Interaction interaction2 = client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();

// New sandbox with sources
Environment env3 = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.REPOSITORY)
            .source("https://github.com/octocat/Spoon-Knife")
            .target("/workspace/spoon-knife")
            .build()
    ))
    .build();

CreateAgentInteraction params3 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("List all files and summarize the project."))
    .environment(CreateAgentInteractionEnvironment.of(env3))
    .build();
Interaction interaction3 = client.interactions.create(CreateInteractionRequestBody.of(params3)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Fresh sandbox
    res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Write a hello world script."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    interaction := res1.Interaction

    // Reuse an existing sandbox
    res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:                 interactions.AgentOption("antigravity-preview-09-2026"),
            Input:                 interactions.NewInteractionsInput("Modify the script to accept a name argument."),
            Environment:           genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(*interaction.EnvironmentID)),
            PreviousInteractionID: interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res2

    // New sandbox with sources
    env3 := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:   interactions.SourceTypeRepository.ToPointer(),
                Source: genai.Ptr("https://github.com/octocat/Spoon-Knife"),
                Target: genai.Ptr("/workspace/spoon-knife"),
            },
        },
    }

    res3, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("List all files and summarize the project."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env3)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res3

    if interaction.OutputText != nil {
        fmt.Println(*interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

## Configure an environment {% id="configure-an-environment" %}

One way to set up an environment is to tell the agent what you need installed.
It handles dependency resolution and troubleshooting. Once the environment is
ready, save the `environment_id` and reuse it.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions.",
    environment="remote",
)

# Reuse the configured environment
interaction_2 = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Clone https://github.com/octocat/Spoon-Knife into /workspace/tools. Run the test suite and fix any missing dependencies.",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
)

# Reuse the configured environment
interaction_3 = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Using the tools in /workspace/tools, list the files.",
    environment=interaction.environment_id,
    previous_interaction_id=interaction_2.id,
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions.",
    environment: "remote",
});

const interaction2 = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Clone https://github.com/octocat/Spoon-Knife into /workspace/tools. Run the test suite and fix any missing dependencies.",
    environment: interaction.environment_id,
    previous_interaction_id: interaction.id,
});

const interaction3 = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Using the tools in /workspace/tools, list the files.",
    environment: interaction.environment_id,
    previous_interaction_id: interaction2.id,
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
# Create interaction
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions.",
    "environment": "remote"
}'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params1 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();
Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();

// Reuse the configured environment
CreateAgentInteraction params2 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Clone https://github.com/octocat/Spoon-Knife into /workspace/tools. Run the test suite and fix any missing dependencies."))
    .environment(CreateAgentInteractionEnvironment.of(interaction.environmentId().orElse("")))
    .previousInteractionId(interaction.id().orElse(""))
    .build();
Interaction interaction2 = client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();

// Reuse the configured environment
CreateAgentInteraction params3 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Using the tools in /workspace/tools, list the files."))
    .environment(CreateAgentInteractionEnvironment.of(interaction.environmentId().orElse("")))
    .previousInteractionId(interaction2.id().orElse(""))
    .build();
Interaction interaction3 = client.interactions.create(CreateInteractionRequestBody.of(params3)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    interaction := res1.Interaction

    // Reuse the configured environment
    res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:                 interactions.AgentOption("antigravity-preview-09-2026"),
            Input:                 interactions.NewInteractionsInput("Clone https://github.com/octocat/Spoon-Knife into /workspace/tools. Run the test suite and fix any missing dependencies."),
            Environment:           genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(*interaction.EnvironmentID)),
            PreviousInteractionID: interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    interaction2 := res2.Interaction

    // Reuse the configured environment
    res3, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:                 interactions.AgentOption("antigravity-preview-09-2026"),
            Input:                 interactions.NewInteractionsInput("Using the tools in /workspace/tools, list the files."),
            Environment:           genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(*interaction.EnvironmentID)),
            PreviousInteractionID: interaction2.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res3

    if interaction.OutputText != nil {
        fmt.Println(*interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

### Mount from a source {% id="mount-from-a-source" %}

If you know exactly what files the agent needs, mount them in a single call
instead of iterating. The `environment` config object accepts a `sources` array
with three types:

| Source type | `type` value | Description | Limit |
| :---- | :---- | :---- | :---- |
| Git repository | `repository` | Clones a repository from a URL into the sandbox at `target`. | 500 MB |
| Cloud Storage | `gcs` | Copies a file or directory from Cloud Storage into the sandbox at `target`. | 2 GB |
| Inline content | `inline` | Writes raw text content to a file in the sandbox at `target`. | 1 MB per file, 2 MB total |

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="List all files under /workspace and describe what you find.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/octocat/Spoon-Knife",
                "target": "/workspace/spoon-knife",
            },
            {
                "type": "gcs",
                "source": "gs://cloud-samples-data/bigquery/us-states/",
                "target": "/workspace/gcs-data",
            },
            {
                "type": "inline",
                "content": "# Project Notes\n\n- Analyze state population data\n- Create visualizations\n",
                "target": "/workspace/notes/readme.md",
            },
        ],
    },
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "List all files under /workspace and describe what you find.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/octocat/Spoon-Knife",
                target: "/workspace/spoon-knife",
            },
            {
                type: "gcs",
                source: "gs://cloud-samples-data/bigquery/us-states/",
                target: "/workspace/gcs-data",
            },
            {
                type: "inline",
                content: "# Project Notes\n\n- Analyze state population data\n- Create visualizations\n",
                target: "/workspace/notes/readme.md",
            },
        ],
    },
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
# Create interaction with sources
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "List all files under /workspace and describe what you find.",
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/octocat/Spoon-Knife",
                "target": "/workspace/spoon-knife"
            },
            {
                "type": "gcs",
                "source": "gs://cloud-samples-data/bigquery/us-states/",
                "target": "/workspace/gcs-data"
            },
            {
                "type": "inline",
                "content": "# Project Notes\n\n- Analyze state population data\n- Create visualizations\n",
                "target": "/workspace/notes/readme.md"
            }
        ]
    }
}'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.REPOSITORY)
            .source("https://github.com/octocat/Spoon-Knife")
            .target("/workspace/spoon-knife")
            .build(),
        Source.builder()
            .type(SourceType.GCS)
            .source("gs://cloud-samples-data/bigquery/us-states/")
            .target("/workspace/gcs-data")
            .build(),
        Source.builder()
            .type(SourceType.INLINE)
            .content("# Project Notes\n\n- Analyze state population data\n- Create visualizations\n")
            .target("/workspace/notes/readme.md")
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("List all files under /workspace and describe what you find."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:   interactions.SourceTypeRepository.ToPointer(),
                Source: genai.Ptr("https://github.com/octocat/Spoon-Knife"),
                Target: genai.Ptr("/workspace/spoon-knife"),
            },
            {
                Type:   interactions.SourceTypeGcs.ToPointer(),
                Source: genai.Ptr("gs://cloud-samples-data/bigquery/us-states/"),
                Target: genai.Ptr("/workspace/gcs-data"),
            },
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Content: genai.Ptr("# Project Notes\n\n- Analyze state population data\n- Create visualizations\n"),
                Target:  genai.Ptr("/workspace/notes/readme.md"),
            },
        },
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("List all files under /workspace and describe what you find."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

You can combine both approaches: mount known sources declaratively, then iterate
with follow-up interactions to install packages or run setup scripts. You can't
set root (`/`) as target when adding a custom source, you must always specify a
sub-directory.

### Hooks {% id="hooks" %}

You can also mount a `.agents/hooks.json` configuration file and custom interception scripts into the sandbox to enforce security guardrails or run automated validations whenever tools execute. For schema definitions and code examples, see [Hooks](/docs/agent-hooks).

### Private sources {% id="private-sources" %}

You can also download from private GitHub repositories or private Cloud
Storage buckets by authenticating the source domain in the network
configuration.

One option is a stored [credential](/docs/agent-credentials) referenced by ID,
so you store the secret once and every environment that needs that source can
reference it:

```json
"network": {
    "allowlist": [
        { "domain": "github.com", "credential": "github-production" },
        { "domain": "*" }
    ]
}
```

You can also set the header inline with `transform`, as the following examples
do. The egress proxy applies both forms the same way, and in neither case does
the secret land inside the sandbox.

For **private Git repositories**, use `Basic` authentication with your
[GitHub Personal Access Token
(PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
Encode the token using `x-oauth-basic` as the username:

```shell
echo -n "x-oauth-basic:ghp_YourPATHere" | base64
```

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Run the test for my backend app and fix any issue.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/your-org/backend",
                "target": "/backend-app"
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "github.com",
                    "transform": {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    }
                },
                {
                    "domain": "*"
                }
            ]
        }
    }
)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Run the test for my backend app and fix any issue.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/your-org/backend",
                target: "/backend-app"
            }
        ],
        network: {
            allowlist: [
                {
                    domain: "github.com",
                    transform: {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    }
                },
                {
                    domain: "*"
                }
            ]
        }
    },
});
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Run the test for my backend app and fix any issue.",
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/your-org/backend",
                "target": "/backend-app"
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "github.com",
                    "transform": {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    }
                },
                {
                    "domain": "*"
                }
            ]
        }
    }
}'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.REPOSITORY)
            .source("https://github.com/your-org/backend")
            .target("/backend-app")
            .build()
    ))
    .network(Network.of(
        EnvironmentNetworkEgressAllowlist.builder()
            .allowlist(Allowlist.of(List.of(
                AllowlistEntry.builder()
                    .domain("github.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Basic YOUR_BASE64_TOKEN"
                    )))
                    .build(),
                AllowlistEntry.builder()
                    .domain("*")
                    .build()
            )))
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Run the test for my backend app and fix any issue."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:   interactions.SourceTypeRepository.ToPointer(),
                Source: genai.Ptr("https://github.com/your-org/backend"),
                Target: genai.Ptr("/backend-app"),
            },
        },
        Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
            Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                {
                    Domain: "github.com",
                    Transform: genai.Ptr(interactions.NewTransform(map[string]string{
                        "Authorization": "Basic YOUR_BASE64_TOKEN",
                    })),
                },
                {
                    Domain: "*",
                },
            })),
        })),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Run the test for my backend app and fix any issue."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

For **private Cloud Storage buckets**, use a standard OAuth 2.0 Bearer token:

```shell
gcloud auth print-access-token
```

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Analyze the discrepancies across the data in workspace",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "gs://my-private-bucket/data",
                "target": "/workspace",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "*.googleapis.com",
                    "transform": {
                        "Authorization": "Bearer YOUR_GCS_TOKEN"
                    }
                },
                {
                    "domain": "*"
                }
            ]
        }
    },
)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Analyze the discrepancies across the data in workspace",
    environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "gs://my-private-bucket/data",
                target: "/workspace",
            }
        ],
        network: {
            allowlist: [
                {
                    domain: "storage.googleapis.com",
                    transform: {
                        "Authorization": "Bearer YOUR_GCS_TOKEN"
                    }
                },
                {
                    domain: "*"
                }
            ]
        }
    },
});
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Analyze the discrepancies across the data in workspace",
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "gs://my-private-bucket/data",
                "target": "/workspace"
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "storage.googleapis.com",
                    "transform": {
                        "Authorization": "Bearer YOUR_GCS_TOKEN"
                    }
                },
                {
                    "domain": "*"
                }
            ]
        }
    }
}'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.GCS)
            .source("gs://my-private-bucket/data")
            .target("/workspace")
            .build()
    ))
    .network(Network.of(
        EnvironmentNetworkEgressAllowlist.builder()
            .allowlist(Allowlist.of(List.of(
                AllowlistEntry.builder()
                    .domain("*.googleapis.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer YOUR_GCS_TOKEN"
                    )))
                    .build(),
                AllowlistEntry.builder()
                    .domain("*")
                    .build()
            )))
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Analyze the discrepancies across the data in workspace"))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:   interactions.SourceTypeGcs.ToPointer(),
                Source: genai.Ptr("gs://my-private-bucket/data"),
                Target: genai.Ptr("/workspace"),
            },
        },
        Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
            Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                {
                    Domain: "*.googleapis.com",
                    Transform: genai.Ptr(interactions.NewTransform(map[string]string{
                        "Authorization": "Bearer YOUR_GCS_TOKEN",
                    })),
                },
                {
                    Domain: "*",
                },
            })),
        })),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Analyze the discrepancies across the data in workspace"),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

## Pre-installed software {% id="pre-installed-software" %}

The sandbox runs on Ubuntu and comes with runtimes and common packages
pre-installed. The agent can install additional packages at runtime using `pip
install` or `npm install`. Packages installed during an interaction persist when
you reuse the same `environment_id`.

| Category | Pre-installed packages |
| :---- | :---- |
| **UNIX tools** | `curl`, `wget`, `git`, `rsync`, `unzip`, `ripgrep`, `fd-find`, `gawk`, `bc`, `tree`, `which`, `lsof`, `htop`, `jq`, `iproute2`, `procps`, `gcloud CLI` |
| **Python 3.12** | `numpy`, `pandas`, `requests`, `google-genai`, `beautifulsoup4`, `pyyaml`, `ast-grep-cli` |
| **Node.js 22** | `create-next-app`, `create-vite`, `typescript` |

## Environment variables {% id="environment-variables" %}

Use the `env` field to set environment variables inside the sandbox. Each entry
maps a variable name to either a literal string for configuration or a
reference to a stored [credential](/docs/agent-credentials) for a secret. The
agent sees them the way it would in any shell, so tools and scripts that read
from the process environment pick them up without extra wiring.

| Field | Type | Description |
| :---- | :---- | :---- |
| `env` | `object` | Map of variable name to value. A value is either a literal `string` or a credential reference of the form `{"credential": "credential-id"}`. |

{% tabs %}
{% tab label="Python" filename="env_vars.py" %}
```py
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Build the project and run the test suite.",
    environment={
        "type": "remote",
        "env": {
            "NODE_ENV": "production",
            "LOG_LEVEL": "debug",
            "API_TOKEN": {"credential": "my-api-token"},
        },
    },
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="env_vars.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Build the project and run the test suite.",
    environment: {
        type: "remote",
        env: {
            NODE_ENV: "production",
            LOG_LEVEL: "debug",
            API_TOKEN: { credential: "my-api-token" },
        },
    },
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": [{"type": "text", "text": "Build the project and run the test suite."}],
    "environment": {
        "type": "remote",
        "env": {
            "NODE_ENV": "production",
            "LOG_LEVEL": "debug",
            "API_TOKEN": {"credential": "my-api-token"}
        }
    }
}'
```
{% /tab %}
{% /tabs %}

Variables apply to every command the agent runs in that interaction, including
shell commands, build steps, and any process it starts.

The two value types behave differently. A literal string is written into the
container as plain text. A credential reference is not: the variable receives a
placeholder, and the egress proxy substitutes the real secret only on outbound
requests to that credential's trusted domains. See
[Use credentials as environment variables](/docs/agent-credentials#environment-variables)
for how that works.

Caution: Literal values are readable by anything running in the sandbox, including the agent itself. Use them for configuration like `NODE_ENV`, not for secrets. Every secret belongs in a credential.

## Network configuration {% id="network-configuration" %}

By default, environments have unrestricted outbound network access. Use the
`network` field to restrict outbound traffic to specific domains. Each rule
specifies a `domain`, plus an optional `credential` to inject a stored secret
and an optional `transform` object to inject headers into matching requests.
These headers can be unique per interaction, and you can update them for the same environment.

| Field | Type | Description |
| :---- | :---- | :---- |
| `domain` | `string` | Domain to match. Use an exact hostname or `*` for all domains. |
| `credential` | `string` | ID of a stored [credential](/docs/agent-credentials). The egress proxy resolves it and injects the auth header at request time. |
| `transform` | `object` | Object containing flat key-value pairs representing headers to inject into matching requests, e.g. `{"Authorization": "Bearer ..."}`. |

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Fetch the latest issues from the GitHub API for my-org/my-repo.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
                {"domain": "*"},
            ]
        },
    },
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Fetch the latest issues from the GitHub API for my-org/my-repo.",
    environment: {
        type: "remote",
        network: {
            allowlist: [
                {
                    domain: "api.github.com",
                    transform: {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                { domain: "pypi.org" },
                { domain: "*" },
            ]
        }
    },
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": [{"type": "text", "text": "Fetch the latest issues from the GitHub API for my-org/my-repo."}],
    "environment": {
        "type": "remote",
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    }
                },
                {"domain": "pypi.org"},
                {"domain": "*"}
            ]
        }
    }
}'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;

Client client = new Client();

Environment env = Environment.builder()
    .network(Network.of(
        EnvironmentNetworkEgressAllowlist.builder()
            .allowlist(Allowlist.of(List.of(
                AllowlistEntry.builder()
                    .domain("api.github.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer ghp_your_github_token"
                    )))
                    .build(),
                AllowlistEntry.builder().domain("pypi.org").build(),
                AllowlistEntry.builder().domain("*").build()
            )))
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Fetch the latest issues from the GitHub API for my-org/my-repo."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
            Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                {
                    Domain: "api.github.com",
                    Transform: genai.Ptr(interactions.NewTransform(map[string]string{
                        "Authorization": "Bearer ghp_your_github_token",
                    })),
                },
                {
                    Domain: "pypi.org",
                },
                {
                    Domain: "*",
                },
            })),
        })),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Fetch the latest issues from the GitHub API for my-org/my-repo."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

When an allowlist is set, only requests to explicitly listed domains are
permitted. You can use wildcards to match subdomains (e.g., `{"domain":
"*.example.com"}`), but note that this does not match the root domain
`example.com`, which must be added separately. To permit all other traffic, such
as routing unlisted domains without injected headers, add `{"domain": "*"}` as a
catch-all entry.

### Credentials {% id="credentials" %}

There are two ways to authenticate outbound traffic, a stored credential
referenced by ID and an inline `transform` on the allowlist rule. The egress
proxy applies both on the wire, so in both cases the secret never enters the
sandbox and never appears in your interaction payloads.

A [managed credential](/docs/agent-credentials) is the one to reach for when you
want to store the secret once and reuse it. Every environment, agent, and
trigger in your project can reference the same ID, and you rotate it in one
place.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

# Store the secret once
client.credentials.create(
    id="github-production",
    type="bearer_token",
    token="ghp_your_github_token",
)

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Fetch the latest issues from the GitHub API for my-org/my-repo.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {"domain": "api.github.com", "credential": "github-production"},
                {"domain": "*"},
            ]
        },
    },
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

// Store the secret once
await client.credentials.create({
    id: "github-production",
    type: "bearer_token",
    token: "ghp_your_github_token",
});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Fetch the latest issues from the GitHub API for my-org/my-repo.",
    environment: {
        type: "remote",
        network: {
            allowlist: [
                { domain: "api.github.com", credential: "github-production" },
                { domain: "*" },
            ]
        }
    },
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
# Store the secret once
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "github-production",
    "type": "bearer_token",
    "token": "ghp_your_github_token"
}'

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Fetch the latest issues from the GitHub API for my-org/my-repo.",
    "environment": {
        "type": "remote",
        "network": {
            "allowlist": [
                { "domain": "api.github.com", "credential": "github-production" },
                { "domain": "*" }
            ]
        }
    }
}'
```
{% /tab %}
{% /tabs %}

An `oauth2` credential also refreshes its access token on its own, so a
long-running interaction does not break when the token expires. See
[Credentials](/docs/agent-credentials) for the full list of
credential types and management operations.

You can also set headers inline with `transform`. This fits when the value
belongs to a single call, for example a token you generate right before creating
the interaction. Headers set this way are injected by the same egress proxy,
they are never exposed inside the sandbox as environment variables or files.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
import subprocess
from google import genai

# Fetch a short-lived access token from your local gcloud CLI
gcloud_token = subprocess.check_output(
    ["gcloud", "auth", "print-access-token"], text=True
).strip()

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="List the files in gs://my-bucket/reports/ using the GCS JSON API.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {
                    "domain": "storage.googleapis.com",
                    "transform": {
                        "Authorization": f"Bearer {gcloud_token}"
                    },
                }
            ]
        },
    },
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

import { execSync } from "child_process";

const gcloudToken = execSync("gcloud auth print-access-token").toString().trim();

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "List the files in gs://my-bucket/reports/ using the GCS JSON API.",
    environment: {
        type: "remote",
        network: {
            allowlist: [
                {
                    domain: "storage.googleapis.com",
                    transform: {
                        "Authorization": `Bearer ${gcloudToken}`
                    },
                }
            ]
        }
    },
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "List the files in gs://my-bucket/reports/ using the GCS JSON API.",
    "environment": {
        "type": "remote",
        "network": {
            "allowlist": [
                {
                    "domain": "storage.googleapis.com",
                    "transform": {
                        "Authorization": "Bearer <YOUR_GCLOUD_TOKEN>"
                    }
                }
            ]
        }
    }
}'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Map;

// Fetch a short-lived access token from your local gcloud CLI
Process process = new ProcessBuilder("gcloud", "auth", "print-access-token").start();
String gcloudToken = new String(process.getInputStream().readAllBytes(), StandardCharsets.UTF_8).trim();

Client client = new Client();

Environment env = Environment.builder()
    .network(Network.of(
        EnvironmentNetworkEgressAllowlist.builder()
            .allowlist(Allowlist.of(List.of(
                AllowlistEntry.builder()
                    .domain("storage.googleapis.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer " + gcloudToken
                    )))
                    .build()
            )))
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("List the files in gs://my-bucket/reports/ using the GCS JSON API."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os/exec"
    "strings"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()

    // Fetch a short-lived access token from your local gcloud CLI
    out, err := exec.Command("gcloud", "auth", "print-access-token").Output()
    if err != nil {
        log.Fatal(err)
    }
    gcloudToken := strings.TrimSpace(string(out))

    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
            Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                {
                    Domain: "storage.googleapis.com",
                    Transform: genai.Ptr(interactions.NewTransform(map[string]string{
                        "Authorization": "Bearer " + gcloudToken,
                    })),
                },
            })),
        })),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("List the files in gs://my-bucket/reports/ using the GCS JSON API."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

`credential` and `transform` can appear on the same rule. The credential is
applied first and `transform` merges on top, so an explicit `transform` header
wins if both set the same key. A common pattern is a credential for the
authentication header plus a `transform` for the extra headers the service
expects alongside it.

### Disable network access {% id="disable-network-access" %}

To block all outbound network access, set `network` to `disabled`:

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Analyze the local files only.",
    environment={
        "type": "remote",
        "network": "disabled",
    },
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Analyze the local files only.",
    environment: {
        type: "remote",
        network: "disabled",
    },
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Analyze the local files only.",
    "environment": {
        "type": "remote",
        "network": "disabled"
    }
}'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.NetworkEnum;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

Environment env = Environment.builder()
    .network(Network.of(NetworkEnum.DISABLED))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Analyze the local files only."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := interactions.Environment{
        Network: genai.Ptr(interactions.NewNetwork(interactions.NetworkEnumDisabled)),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Analyze the local files only."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

### Refresh credentials {% id="refresh-credentials" %}

Inline tokens such as access tokens and short-lived API keys expire.
You can refresh them by passing the existing `environment_id` together with a
new `network` configuration on the next interaction. The new network rules
fully replace the previous ones, while the environment's file system state
(installed packages, files, repositories) is preserved.

If you use a stored [credential](/docs/agent-credentials) instead,
you don't need this. An `oauth2` credential refreshes itself, and rotating any
credential is a `PATCH` on the credential that leaves every allowlist rule
referencing it untouched.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

# First interaction: use an initial token
first = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="List the files in gs://my-bucket/reports/ using the GCS JSON API.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {
                    "domain": "storage.googleapis.com",
                    "transform": {
                        "Authorization": "Bearer INITIAL_TOKEN"
                    },
                }
            ]
        },
    },
)

# Later: refresh the token on the same environment
result = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Now download the file reports/q1.csv from the same bucket.",
    environment={
        "type": "remote",
        "environment_id": first.environment_id,
        "network": {
            "allowlist": [
                {
                    "domain": "storage.googleapis.com",
                    "transform": {
                        "Authorization": "Bearer REFRESHED_TOKEN"
                    },
                }
            ]
        },
    },
)

print(result.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

// First interaction: use an initial token
const first = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "List the files in gs://my-bucket/reports/ using the GCS JSON API.",
    environment: {
        type: "remote",
        network: {
            allowlist: [
                {
                    domain: "storage.googleapis.com",
                    transform: {
                        "Authorization": "Bearer INITIAL_TOKEN"
                    },
                }
            ]
        }
    },
});

// Later: refresh the token on the same environment
const result = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Now download the file reports/q1.csv from the same bucket.",
    environment: {
        type: "remote",
        environment_id: first.environment_id,
        network: {
            allowlist: [
                {
                    domain: "storage.googleapis.com",
                    transform: {
                        "Authorization": "Bearer REFRESHED_TOKEN"
                    },
                }
            ]
        }
    },
});

console.log(result.output_text);
```
{% /tab %}
{% tab label="REST" %}
```shell
# Use the environment_id from a previous interaction
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Now download the file reports/q1.csv from the same bucket.",
    "environment": {
        "type": "remote",
        "environment_id": "<ENVIRONMENT_ID_FROM_PREVIOUS_INTERACTION>",
        "network": {
            "allowlist": [
                {
                    "domain": "storage.googleapis.com",
                    "transform": {
                        "Authorization": "Bearer REFRESHED_TOKEN"
                    }
                }
            ]
        }
    }
}'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;

Client client = new Client();

// First interaction: use an initial token
Environment initialEnv = Environment.builder()
    .network(Network.of(
        EnvironmentNetworkEgressAllowlist.builder()
            .allowlist(Allowlist.of(List.of(
                AllowlistEntry.builder()
                    .domain("storage.googleapis.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer INITIAL_TOKEN"
                    )))
                    .build()
            )))
            .build()
    ))
    .build();

CreateAgentInteraction firstParams = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("List the files in gs://my-bucket/reports/ using the GCS JSON API."))
    .environment(CreateAgentInteractionEnvironment.of(initialEnv))
    .build();

Interaction first = client.interactions.create(CreateInteractionRequestBody.of(firstParams)).interaction().get();

// Later: refresh the token on the same environment
Environment refreshedEnv = Environment.builder()
    .environmentId(first.environmentId().orElse(""))
    .network(Network.of(
        EnvironmentNetworkEgressAllowlist.builder()
            .allowlist(Allowlist.of(List.of(
                AllowlistEntry.builder()
                    .domain("storage.googleapis.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer REFRESHED_TOKEN"
                    )))
                    .build()
            )))
            .build()
    ))
    .build();

CreateAgentInteraction secondParams = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Now download the file reports/q1.csv from the same bucket."))
    .environment(CreateAgentInteractionEnvironment.of(refreshedEnv))
    .build();

Interaction result = client.interactions.create(CreateInteractionRequestBody.of(secondParams)).interaction().get();
System.out.println(result.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // First interaction: use an initial token
    initialEnv := interactions.Environment{
        Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
            Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                {
                    Domain: "storage.googleapis.com",
                    Transform: genai.Ptr(interactions.NewTransform(map[string]string{
                        "Authorization": "Bearer INITIAL_TOKEN",
                    })),
                },
            })),
        })),
    }

    firstRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("List the files in gs://my-bucket/reports/ using the GCS JSON API."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(initialEnv)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    first := firstRes.Interaction

    // Later: refresh the token on the same environment
    refreshedEnv := interactions.Environment{
        EnvironmentID: first.EnvironmentID,
        Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
            Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                {
                    Domain: "storage.googleapis.com",
                    Transform: genai.Ptr(interactions.NewTransform(map[string]string{
                        "Authorization": "Bearer REFRESHED_TOKEN",
                    })),
                },
            })),
        })),
    }

    secondRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Now download the file reports/q1.csv from the same bucket."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(refreshedEnv)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if secondRes.Interaction.OutputText != nil {
        fmt.Println(*secondRes.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

## Environment lifecycle {% id="environment-lifecycle" %}

Environments follow this lifecycle:

| State | Behavior |
| :---- | :---- |
| **Created** | Provisioned when an interaction specifies `environment: "remote"` or a config object. |
| **Active** | Running while an interaction is in progress. |
| **Idle** | Auto-snapshot and stopped after 15 minutes of inactivity. |
| **Offline** | Retained for 7 days since last active. Can be resumed by passing its ID. |
| **Deleted** | Removed from the system automatically after 7-day TTL retention expires or upon manual deletion. |

## Environments API {% id="environments-api" %}

You can use the Environments API to programmatically manage sandbox sessions.
Enumerating environments lets you discover active session IDs and recover state
if a client connection terminates during a long-running task. You can also
inspect session metadata and explicitly delete environments when workflows
conclude rather than waiting for automatic TTL expiration.

### List environments {% id="list-environments" %}

List active environments belonging to your project. Use pagination parameters
to control the response batch size.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

response = client.environments.list(page_size=10)
for env in response.environments:
    print(f"Environment ID: {env.id}, Status: {env.status}")
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const response = await client.environments.list({ page_size: 10 });
for (const env of response.environments || []) {
    console.log(`Environment ID: ${env.id}, Status: ${env.status}`);
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments?pageSize=10" \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.environments.ListEnvironmentsResponse;
import java.util.List;

Client client = new Client();

ListEnvironmentsResponse response = client.environments.listEnvironments()
    .pageSize(10)
    .call()
    .listEnvironmentsResponse()
    .get();

for (Environment env : response.environments().orElse(List.of())) {
    System.out.println("Environment ID: " + env.id().orElse("") + ", Status: " + env.status().orElse(null));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    interactionssdk "google.golang.org/genai/interactions"
    "google.golang.org/genai/interactions/models/components"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
        APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
    }))

    res, err := sdk.Environments.ListEnvironments(ctx, operations.ListEnvironmentsRequest{
        PageSize: genai.Ptr(10),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.ListEnvironmentsResponse != nil {
        for _, env := range res.ListEnvironmentsResponse.Environments {
            fmt.Printf("Environment ID: %s, Status: %v\n", env.ID, env.Status)
        }
    }
}
```
{% /tab %}
{% /tabs %}

The response looks similar to the following:

```json
{
  "environments": [
    {
      "id": "140128b2a13c12c00a5a0d8cf7af9469",
      "status": "active"
    },
    {
      "id": "362b738275a1d74af6f1c62bc050da73",
      "status": "active"
    }
  ],
  "next_page_token": "Cj...5aE="
}
```

### Get an environment {% id="get-an-environment" %}

Retrieve metadata and configuration details for a specific environment by its
resource name.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

env = client.environments.get(id="YOUR_ENVIRONMENT_ID")
print(f"Environment ID: {env.id}, Status: {env.status}")
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const env = await client.environments.get("YOUR_ENVIRONMENT_ID");
console.log(`Environment ID: ${env.id}, Status: ${env.status}`);
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments/YOUR_ENVIRONMENT_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.Environment;

Client client = new Client();

Environment env = client.environments.getEnvironment("YOUR_ENVIRONMENT_ID").environment().get();
System.out.println("Environment ID: " + env.id().orElse("") + ", Status: " + env.status().orElse(null));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    interactionssdk "google.golang.org/genai/interactions"
    "google.golang.org/genai/interactions/models/components"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
        APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
    }))

    res, err := sdk.Environments.GetEnvironment(ctx, operations.GetEnvironmentRequest{
        ID: "YOUR_ENVIRONMENT_ID",
    })
    if err != nil {
        log.Fatal(err)
    }

    env := res.Environment
    fmt.Printf("Environment ID: %s, Status: %v\n", env.ID, env.Status)
}
```
{% /tab %}
{% /tabs %}

The response looks similar to the following:

```json
{
  "id": "140128b2a13c12c00a5a0d8cf7af9469",
  "status": "active",
  "sources": [
    {
      "type": "repository",
      "source": "https://github.com/octocat/Spoon-Knife",
      "target": "/workspace/spoon-knife"
    }
  ],
  "network": {
    "allowlist": [
      {
        "domain": "api.github.com"
      },
      {
        "domain": "github.com"
      }
    ]
  }
}
```

### Delete an environment {% id="delete-an-environment" %}

Explicitly terminate and delete an environment to clean up sandbox resources
when your tasks or pipelines finish.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

client.environments.delete(id="YOUR_ENVIRONMENT_ID")
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

await client.environments.delete("YOUR_ENVIRONMENT_ID");
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/environments/YOUR_ENVIRONMENT_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;

Client client = new Client();

client.environments.deleteEnvironment("YOUR_ENVIRONMENT_ID");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"
    "os"

    "google.golang.org/genai"
    interactionssdk "google.golang.org/genai/interactions"
    "google.golang.org/genai/interactions/models/components"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
        APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
    }))

    _, err := sdk.Environments.DeleteEnvironment(ctx, operations.DeleteEnvironmentRequest{
        ID: "YOUR_ENVIRONMENT_ID",
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}
{% /tabs %}

## Manage files in the environment {% id="download-files-from-the-environment" %}

The agent creates and modifies files inside the sandbox during execution. You
can browse directory contents, get file metadata, download individual files or
entire directories as tar archives, and upload files or extract archives
directly into the environment. Storage in sandbox environments is subject to
fair usage limits.

### List files in a directory {% id="list-files-in-a-directory" %}

List the contents of a directory in the environment. By default, lists the root
directory.

#### Query parameters

| Parameter | Type | Description |
| :---- | :---- | :---- |
| `recursive` | boolean | When `true`, lists all files and directories recursively. Default: `false`. |

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

# List root directory
response = client.environments.files.list(
    environment="YOUR_ENVIRONMENT_ID",
    path="",
)
for file in response.files:
    print(f"{file.name} ({file.type}) - {file.path}")

# List a subdirectory recursively
response = client.environments.files.list(
    environment="YOUR_ENVIRONMENT_ID",
    path="src",
    recursive=True,
)
for file in response.files:
    print(f"{file.name} ({file.type}) - {file.path}")
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

// List root directory
const response = await client.environments.files.list({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "",
});
for (const file of response.files || []) {
    console.log(`${file.name} (${file.type}) - ${file.path}`);
}

// List a subdirectory recursively
const srcResponse = await client.environments.files.list({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "src",
    recursive: true,
});
for (const file of srcResponse.files || []) {
    console.log(`${file.name} (${file.type}) - ${file.path}`);
}
```
{% /tab %}
{% tab label="REST" %}
```shell
# List root directory
curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# List a subdirectory
curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files/src" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# List all files recursively
curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files?recursive=true" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

The response returns a `files` array with metadata for each entry:

```json
{
  "files": [
    {
      "name": "config",
      "path": "config",
      "type": "DIRECTORY",
      "created": "2026-08-12T07:44:18Z",
      "modified": "2026-08-12T07:44:18Z"
    },
    {
      "name": "main.py",
      "path": "src/main.py",
      "type": "FILE",
      "size_bytes": "15",
      "mime_type": "text/x-python; charset=utf-8",
      "created": "2026-08-12T07:44:20Z",
      "modified": "2026-08-12T07:44:20Z"
    }
  ]
}
```

#### File entry fields

| Field | Type | Description |
| :---- | :---- | :---- |
| `name` | string | The file or directory name. |
| `path` | string | The full path relative to the environment root. |
| `type` | string | Either `FILE` or `DIRECTORY`. |
| `size_bytes` | string | File size in bytes (files only). |
| `mime_type` | string | MIME type (files only). |
| `created` | string | ISO 8601 creation timestamp. |
| `modified` | string | ISO 8601 last-modified timestamp. |

### Get file metadata {% id="get-file-metadata" %}

Get metadata for a specific file by path.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

response = client.environments.files.list(
    environment="YOUR_ENVIRONMENT_ID",
    path="src/main.py",
)
file = response.files[0]
print(f"Name: {file.name}, Size: {file.size_bytes} bytes, Type: {file.mime_type}")
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const response = await client.environments.files.list({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "src/main.py",
});
const file = response.files?.[0];
if (file) {
    console.log(`Name: ${file.name}, Size: ${file.size_bytes} bytes, Type: ${file.mime_type}`);
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files/src/main.py" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

The response returns the file metadata wrapped in a `files` array:

```json
{
  "files": [
    {
      "name": "main.py",
      "path": "src/main.py",
      "type": "FILE",
      "size_bytes": "15",
      "mime_type": "text/x-python; charset=utf-8",
      "created": "2026-08-12T07:44:20Z",
      "modified": "2026-08-12T07:44:20Z"
    }
  ]
}
```

If the file doesn't exist, the API returns a `404` error:

```json
{
  "error": {
    "message": "Path 'nonexistent.txt' not found in environment 'ENV_ID'.",
    "code": "not_found"
  }
}
```

### Download a single file {% id="download-a-single-file" %}

Download the contents of a specific file. In the SDKs, use the `download()`
method. In REST requests, append the `?alt=media` query parameter to the file
path. The server responds with `200 OK` and streams the raw file content.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

content = client.environments.files.download(
    environment="YOUR_ENVIRONMENT_ID",
    path="src/main.py",
)

with open("main.py", "wb") as f:
    f.write(content)
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const client = new GoogleGenAI({});

const bytes = await client.environments.files.download({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "src/main.py",
});

fs.writeFileSync("main.py", Buffer.from(bytes));
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files/src/main.py?alt=media" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -o main.py
```
{% /tab %}
{% /tabs %}

### Download a directory as a tar archive {% id="download-a-directory-as-a-tar-archive" %}

Download an entire directory as a tar archive by requesting the directory path
with `?alt=media`. This returns a POSIX tar file (not gzipped). Use
`recursive=true` to include nested subdirectories.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
import tarfile
from google import genai

client = genai.Client()

# Download a subdirectory archive
archive = client.environments.files.download(
    environment="YOUR_ENVIRONMENT_ID",
    path="src",
)

with open("src.tar", "wb") as f:
    f.write(archive)

with tarfile.open("src.tar") as tar:
    tar.extractall(path="./extracted")
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import { execSync } from "child_process";
import * as fs from "fs";

const client = new GoogleGenAI({});

// Download a subdirectory archive
const bytes = await client.environments.files.download({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "src",
});

fs.writeFileSync("src.tar", Buffer.from(bytes));
execSync("tar -xf src.tar -C ./extracted");
```
{% /tab %}
{% tab label="REST" %}
```shell
# Download a subdirectory (top-level files only)
curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files/src?alt=media" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -o src.tar

# Download a subdirectory recursively (includes nested directories)
curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files/config?alt=media&recursive=true" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -o config.tar

# Download root directory
curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files?alt=media" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -o snapshot.tar

# Extract the archive
tar xf snapshot.tar -C ./extracted
```
{% /tab %}
{% /tabs %}

#### Behavior matrix

The following behavior matrix summarizes the expected response and archive behavior across file and directory endpoints, HTTP methods, and query parameters:

| Request | `alt` | `recursive` | `extract` | `overwrite` | Response |
| :---- | :---- | :---- | :---- | :---- | :---- |
| `GET /files` | (none) | (none) | - | - | JSON listing of root directory |
| `GET /files/{path}` (file) | (none) | - | - | - | JSON metadata for the file |
| `GET /files/{path}` (dir) | (none) | `false` | - | - | JSON listing of immediate children |
| `GET /files/{path}` (dir) | (none) | `true` | - | - | JSON listing of all descendants |
| `GET /files/{path}?alt=media` (file) | `media` | - | - | - | Raw file content |
| `GET /files/{path}?alt=media` (dir) | `media` | `false` | - | - | Tar archive of immediate files in directory |
| `GET /files/{path}?alt=media` (dir) | `media` | `true` | - | - | Tar archive of all files recursively |
| `GET /files?alt=media` | `media` | `false` | - | - | Tar archive of root-level files only |
| `PUT /files/{path}` (file) | - | - | `false` | `false` | Writes the file at path. Returns `409 Conflict` if it already exists |
| `PUT /files/{path}?overwrite=true` | - | - | `false` | `true` | Writes or overwrites the file at path |
| `PUT /files/{path}?extract=true` | - | - | `true` | `false` | Unpacks archive into destination directory. Returns `409 Conflict` if any target file exists |
| `PUT /files/{path}?extract=true&overwrite=true` | - | - | `true` | `true` | Unpacks archive, replacing any existing files |

### Upload files to the environment {% id="upload-a-file" %}

Upload individual files or directory archives directly to an existing environment
sandbox using HTTP `PUT`. Parent directories are created automatically if they
do not exist. Storage in environments is subject to fair usage limits.

Note: REST uploads use the `/upload/` path prefix, for example
`https://generativelanguage.googleapis.com/upload/v1beta/environments/{environment_id}/files/{path}`.
A `PUT` sent without the prefix returns a `400` error. The Python and JavaScript
clients add the prefix for you.

#### Upload a single file

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

with open("local_file.txt", "rb") as f:
    result = client.environments.files.upload(
        environment="YOUR_ENVIRONMENT_ID",
        path="workspace/data/file.txt",
        file=f,
        mime_type="text/plain",
        overwrite=True,
    )

file = result.files[0]
print(f"Uploaded: {file.name} ({file.size_bytes} bytes)")
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const client = new GoogleGenAI({});

const content = fs.readFileSync("local_file.txt");
const result = await client.environments.files.upload({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "workspace/data/file.txt",
    file: content,
    mime_type: "text/plain",
    overwrite: true,
});

const file = result.files[0];
console.log(`Uploaded: ${file.name} (${file.size_bytes} bytes)`);
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X PUT "https://generativelanguage.googleapis.com/upload/v1beta/environments/$ENV_ID/files/workspace/data/file.txt" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @local_file.txt
```
{% /tab %}
{% /tabs %}

The response returns metadata for the uploaded file, wrapped in a `files` array
for consistency with the list and get endpoints:

```json
{
  "files": [
    {
      "name": "file.txt",
      "path": "workspace/data/file.txt",
      "type": "FILE",
      "size_bytes": "1024",
      "mime_type": "text/plain"
    }
  ]
}
```

#### Upload and extract a directory archive

To seed an entire codebase or directory structure in a single request, upload a
`.tar` or `.tar.gz` archive with `extract=true`.

{% tabs %}
{% tab label="Python" filename="env_setup.py" %}
```py
from google import genai

client = genai.Client()

with open("source.tar.gz", "rb") as f:
    result = client.environments.files.upload(
        environment="YOUR_ENVIRONMENT_ID",
        path="workspace/src/",
        file=f,
        extract=True,
    )

for entry in result.files:
    print(f"Extracted: {entry.path}")
```
{% /tab %}
{% tab label="JavaScript" filename="env_setup.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const client = new GoogleGenAI({});

const archive = fs.readFileSync("source.tar.gz");
const result = await client.environments.files.upload({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "workspace/src/",
    file: archive,
    extract: true,
});

for (const entry of result.files) {
    console.log(`Extracted: ${entry.path}`);
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X PUT "https://generativelanguage.googleapis.com/upload/v1beta/environments/$ENV_ID/files/workspace/src/?extract=true" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/x-tar" \
  --data-binary @source.tar.gz
```
{% /tab %}
{% /tabs %}

The response lists every file written by the archive:

```json
{
  "files": [
    {
      "name": "app.py",
      "path": "workspace/src/app.py",
      "type": "FILE",
      "size_bytes": "15",
      "mime_type": "text/x-python"
    },
    {
      "name": "requirements.txt",
      "path": "workspace/src/requirements.txt",
      "type": "FILE",
      "size_bytes": "17",
      "mime_type": "text/plain"
    }
  ]
}
```

Note: The archive format is detected from the payload itself, so `.tar` and
`.tar.gz` both work regardless of the `Content-Type` you send.

#### Upload large files with a resumable session

For large payloads, or when uploading over an unreliable connection, use a
resumable session instead of sending the whole body in one request. A resumable
upload splits the transfer into chunks that can be retried individually, so a
failure part way through does not force you to start over.

Start by initiating the session with `uploadType=resumable`. Send an empty body
and use the `X-Upload-Content-Type` and `X-Upload-Content-Length` headers to
declare the media type and total size of the payload you intend to upload:

```http
PUT /upload/v1beta/environments/$ENV_ID/files/workspace/data/large_dataset.bin?uploadType=resumable HTTP/1.1
Host: generativelanguage.googleapis.com
X-Upload-Content-Type: application/octet-stream
X-Upload-Content-Length: 20971520
Content-Length: 0
x-goog-api-key: $GEMINI_API_KEY
```

The response carries the session URL in the `Location` header. This URL already
contains an `upload_id`, so it does not need the API key again:

```http
HTTP/1.1 200 OK
Location: https://generativelanguage.googleapis.com/upload/v1beta/environments/$ENV_ID/files/workspace/data/large_dataset.bin?uploadType=resumable&upload_id=AJjja9bfHjiYlGi60pUazCaTuPY
Content-Length: 0
```

Upload the payload to that URL in chunks. Each chunk declares its byte range and
the total size with a `Content-Range` header:

```http
PUT /upload/v1beta/environments/$ENV_ID/files/workspace/data/large_dataset.bin?uploadType=resumable&upload_id=AJjja9bfHjiYlGi60pUazCaTuPY HTTP/1.1
Host: generativelanguage.googleapis.com
Content-Type: application/octet-stream
Content-Range: bytes 0-10485759/20971520
Content-Length: 10485760

<10 MB binary payload>
```

Every chunk except the last returns `308 Resume Incomplete`. The `Range` header
tells you how many bytes the server has committed, which is where you resume
from if a chunk fails:

```http
HTTP/1.1 308 Resume Incomplete
Range: bytes=0-10485759
Content-Length: 0
```

Send the remaining chunks the same way:

```http
PUT /upload/v1beta/environments/$ENV_ID/files/workspace/data/large_dataset.bin?uploadType=resumable&upload_id=AJjja9bfHjiYlGi60pUazCaTuPY HTTP/1.1
Host: generativelanguage.googleapis.com
Content-Type: application/octet-stream
Content-Range: bytes 10485760-20971519/20971520
Content-Length: 10485760

<remaining 10 MB binary payload>
```

The final chunk completes the upload and returns the file metadata, in the same
`files` envelope as a single-shot upload:

```json
{
  "files": [
    {
      "name": "large_dataset.bin",
      "path": "workspace/data/large_dataset.bin",
      "type": "FILE",
      "size_bytes": "20971520",
      "mime_type": "application/octet-stream"
    }
  ]
}
```

Resumable sessions work with `extract` and `overwrite` as well. Set those query
parameters on the initiating request, not on the individual chunks.

#### Overwrite protection

By default, `overwrite` is `false`. If the destination path already exists, the
request returns a `409 Conflict` error and nothing is written:

```json
{
  "error": {
    "message": "Requested entity already exists",
    "code": "aborted"
  }
}
```

To replace an existing file or directory, set `overwrite=true` (or append
`?overwrite=true` in REST). With `extract=true`, the conflict check applies to
every file in the archive, so the request fails if any target file exists.

### Download full snapshot (deprecated) {% id="download-full-snapshot-deprecated" %}

Caution: The legacy `/files/environment-{id}:download` endpoint is deprecated. Use the [environment files endpoint](/docs/agent-environment#download-a-directory-as-a-tar-archive) to download directories or individual files instead.

To migrate existing code to the environment files API:

*   **Python**: Replace legacy file download requests with:

    ```py
    archive = client.environments.files.download(
        environment="YOUR_ENVIRONMENT_ID",
        path="workspace",
    )
    with open("snapshot.tar", "wb") as f:
        f.write(archive)
    ```

*   **JavaScript**: Replace legacy file download requests with:

    ```javascript
    const bytes = await client.environments.files.download({
        environment: "YOUR_ENVIRONMENT_ID",
        path: "workspace",
    });
    fs.writeFileSync("snapshot.tar", Buffer.from(bytes));
    ```

*   **REST**: Replace `GET /v1beta/files/environment-$ENV_ID:download?alt=media` with:

    ```shell
    curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files?alt=media" \
      -H "x-goog-api-key: $GEMINI_API_KEY" \
      -o snapshot.tar
    ```

## Pricing & resources {% id="pricing-resources" %}

Each environment runs with fixed resource allocations:

| Resource | Value |
| :---- | :---- |
| **CPU** | 4 cores |
| **Memory** | 16 GB |

Environment compute (CPU, memory, sandbox execution) is **not billed** during
the preview period. See
[Pricing](/docs/pricing#pricing-for-agents) for
agent token costs.

## Limitations {% id="limitations" %}

- **Preview status:** Environments and managed agents are in preview. Features and schemas may change.
- **Inline source size:** Inline sources are limited to 1 MB per file, and 2 MB total across all files.
- **Source size**: Git repositories are limited to 500 MB and Cloud Storage repositories to 2 GB.
- **Environment startup:** Provisioning a new environment takes up to ~5 seconds. Large source repositories may increase this time.
- **Environment expiration:** Inactive offline environments are retained for 7
  days before expiring using automatic TTL cleanup. Passing an expired or
  invalid environment ID returns a `404 Not Found` error.
- **File support:** The agent is currently constrained to reading text and image files. Binary file support is not yet available.
- **No mounting from root:** You can't set root (`/`) as target when adding a custom source, you must always specify a sub-directory.

## What's next {% id="whats-next" %}

*   [Agents Overview](/docs/agents): Learn about the core concepts of managed agents.
*   [Quickstart](/docs/managed-agents-quickstart): Start building with multi-turn conversations and streaming.
*   [Antigravity Agent](/docs/antigravity-agent): Explore capabilities, tools, model selection, and pricing for the default agent.
*   [Building Custom Agents](/docs/custom-agents): Define your own agents using `AGENTS.md` and `SKILL.md`.
*   [Hooks](/docs/agent-hooks): Enforce security guardrails and run side-effect validations inside the sandbox.

# Credentials in managed agents
Source: https://aistudio.google.com/docs/agent-credentials
Description: Learn how to store and manage server-side credentials for managed agents, including bearer tokens, OAuth2 configurations, and environment variable secrets.

Credentials are server-managed secrets that let your agents reach third-party
services without the secret ever entering the agent's environment. You store a
credential once, reference it by ID, and the egress proxy resolves and injects
it at request time.

Secret values are write-only. Once stored, they are never returned by any
endpoint, so a compromised agent cannot read back the tokens it is using.

The primary place you use a credential is the network allowlist on
[`environment.network`](/docs/agent-environment). Store the secret
first:

{% tabs %}
{% tab label="Python" filename="credentials_in_managed_agents.py" %}
```py
from google import genai

client = genai.Client()

credential = client.credentials.create(
    id="github-production",
    type="bearer_token",
    token="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)

print(f"Credential ID: {credential.id}, Status: {credential.status}")
```
{% /tab %}
{% tab label="JavaScript" filename="credentials_in_managed_agents.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const credential = await client.credentials.create({
    id: "github-production",
    type: "bearer_token",
    token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

console.log(`Credential ID: ${credential.id}, Status: ${credential.status}`);
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/credentials"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
        Body: credentials.NewCredentialCreateParams(credentials.HTTPBearerConfig{
            ID:    "github-production",
            Token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Credential ID: %s, Status: %v\n", res.Credential.ID, res.Credential.GetStatus())
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "github-production",
    "type": "bearer_token",
    "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'
```
{% /tab %}
{% /tabs %}

Then attach it to the domain it authenticates:

{% tabs %}
{% tab label="Python" filename="credentials_in_managed_agents.py" %}
```py
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Triage the open issues in my-org/my-repo.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {"domain": "api.github.com", "credential": "github-production"},
                {"domain": "*"},
            ]
        },
    },
)
```
{% /tab %}
{% tab label="JavaScript" filename="credentials_in_managed_agents.js" %}
```javascript
const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Triage the open issues in my-org/my-repo.",
    environment: {
        type: "remote",
        network: {
            allowlist: [
                { domain: "api.github.com", credential: "github-production" },
                { domain: "*" },
            ],
        },
    },
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("antigravity-preview-09-2026"),
            Input: interactions.NewInteractionsInput("Triage the open issues in my-org/my-repo."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
                Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
                    Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                        {Domain: "api.github.com", Credential: genai.Ptr("github-production")},
                        {Domain: "*"},
                    })),
                })),
            })),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Triage the open issues in my-org/my-repo.",
    "environment": {
        "type": "remote",
        "network": {
            "allowlist": [
                { "domain": "api.github.com", "credential": "github-production" },
                { "domain": "*" }
            ]
        }
    }
}'
```
{% /tab %}
{% /tabs %}

The agent now makes authenticated requests to `api.github.com`, and the token
never exists inside the sandbox.

## Credential types {% id="credential-types" %}

Every credential has a `type` that determines which fields it accepts and how
the proxy applies it.

| Type | Use case | Behavior |
| :---- | :---- | :---- |
| `bearer_token` | Personal access tokens, bot tokens, static API keys | The proxy injects the token as a request header. No refresh logic. |
| `oauth2` | OAuth apps and user-delegated flows | The proxy exchanges the refresh token for access tokens and refreshes them as they expire. |
| `environment_variable` | Client SDKs that read secrets from the process environment | The agent's environment receives a placeholder. The proxy substitutes the real secret on outbound requests. |

## Use credentials in the network allowlist {% id="network-allowlist" %}

Add `credential` to an allowlist rule and the proxy authenticates every
outbound request to that domain. This is the recommended way to give an agent
access to a private API, a private repository, or a private bucket.

You can mix authenticated and unauthenticated rules in the same allowlist:

{% tabs %}
{% tab label="Python" filename="use_credentials_in_the_network_allowlist.py" %}
```py
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Sync the open Jira issues into the tracking sheet in my repo.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/your-org/backend",
                "target": "/backend-app",
            }
        ],
        "network": {
            "allowlist": [
                {"domain": "github.com", "credential": "github-production"},
                {"domain": "api.atlassian.com", "credential": "jira-oauth"},
                {"domain": "*.googleapis.com"},
            ]
        },
    },
)
```
{% /tab %}
{% tab label="JavaScript" filename="use_credentials_in_the_network_allowlist.js" %}
```javascript
const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Sync the open Jira issues into the tracking sheet in my repo.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/your-org/backend",
                target: "/backend-app",
            },
        ],
        network: {
            allowlist: [
                { domain: "github.com", credential: "github-production" },
                { domain: "api.atlassian.com", credential: "jira-oauth" },
                { domain: "*.googleapis.com" },
            ],
        },
    },
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("antigravity-preview-09-2026"),
            Input: interactions.NewInteractionsInput("Sync the open Jira issues into the tracking sheet in my repo."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
                Sources: []interactions.Source{
                    {
                        Type:   interactions.SourceTypeRepository.ToPointer(),
                        Source: genai.Ptr("https://github.com/your-org/backend"),
                        Target: genai.Ptr("/backend-app"),
                    },
                },
                Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
                    Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                        {Domain: "github.com", Credential: genai.Ptr("github-production")},
                        {Domain: "api.atlassian.com", Credential: genai.Ptr("jira-oauth")},
                        {Domain: "*.googleapis.com"},
                    })),
                })),
            })),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Sync the open Jira issues into the tracking sheet in my repo.",
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/your-org/backend",
                "target": "/backend-app"
            }
        ],
        "network": {
            "allowlist": [
                { "domain": "github.com", "credential": "github-production" },
                { "domain": "api.atlassian.com", "credential": "jira-oauth" },
                { "domain": "*.googleapis.com" }
            ]
        }
    }
}'
```
{% /tab %}
{% /tabs %}

Because the proxy resolves the credential per request, an `oauth2` credential
refreshes its access token transparently. A long-running interaction does not
break when the access token expires.

### Combining `credential` and `transform` {% id="credential-and-transform" %}

Allowlist rules also accept an inline
[`transform`](/docs/agent-environment#private-sources) object that sets headers
directly on the rule. Both mechanisms are applied by the egress proxy on the
wire, so in both cases the header value never exists inside the sandbox. Both
fields can appear on the same rule.

| Rule configuration | Behavior |
| :---- | :---- |
| `credential` only | The proxy resolves the credential and injects its header on every request to the domain. |
| `transform` only | Static header injection. The headers you write are sent as-is. |
| Both | The credential is applied first, then `transform` merges on top. An explicit `transform` header wins if both set the same key. |
| Neither | The domain is allowed and no headers are injected. |

A credential is worth using when you want to store a secret once and reference
it from every environment, agent, and trigger in your project, and when you want
access token refresh and rotation handled for you. An inline `transform` fits
when the value belongs to a single call, for example a token you generate
yourself right before creating the interaction.

Combining the two is common. The credential carries the authentication header
and `transform` adds whatever else the upstream service expects on the same
request:

```json
{
    "domain": "api.atlassian.com",
    "credential": "jira-oauth",
    "transform": {
        "X-Atlassian-Workspace": "my-workspace-id"
    }
}
```

To move a secret out of an inline `transform` and into a credential, store it
with `POST /credentials`, replace the auth header in `transform` with
`"credential": "<id>"`, and leave the rest of the `transform` object alone.

## Use credentials with MCP servers {% id="mcp-servers" %}

Remote MCP servers take the same `credential` field. Set it on an `mcp_server`
tool and the proxy injects the auth header into every request to that server:

{% tabs %}
{% tab label="Python" filename="use_credentials_with_mcp_servers.py" %}
```py
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Create a new issue in my-org/my-repo",
    environment="remote",
    tools=[{
        "type": "mcp_server",
        "name": "github",
        "url": "https://api.githubcopilot.com/mcp",
        "credential": "github-production",
    }],
)
```
{% /tab %}
{% tab label="JavaScript" filename="use_credentials_with_mcp_servers.js" %}
```javascript
const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Create a new issue in my-org/my-repo",
    environment: "remote",
    tools: [{
        type: "mcp_server",
        name: "github",
        url: "https://api.githubcopilot.com/mcp",
        credential: "github-production",
    }],
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("antigravity-preview-09-2026"),
            Input: interactions.NewInteractionsInput("Create a new issue in my-org/my-repo"),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
                Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
                    Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                        {Domain: "api.githubcopilot.com", Credential: genai.Ptr("github-production")},
                    })),
                })),
            })),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.MCPServer{
                    Name: genai.Ptr("github"),
                    URL:  genai.Ptr("https://api.githubcopilot.com/mcp"),
                }),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Create a new issue in my-org/my-repo",
    "environment": "remote",
    "tools": [
        {
            "type": "mcp_server",
            "name": "github",
            "url": "https://api.githubcopilot.com/mcp",
            "credential": "github-production"
        }
    ]
}'
```
{% /tab %}
{% /tabs %}

`credential` and `headers` follow the same precedence rule as the allowlist.
The credential is applied first and `headers` merges on top, so an explicit
header wins if both set the same key:

```json
{
    "type": "mcp_server",
    "name": "jira",
    "url": "https://jira.atlassian.com/mcp",
    "credential": "jira-oauth",
    "headers": {
        "X-Atlassian-Workspace": "my-workspace-id"
    }
}
```

To move a secret out of inline `headers` and into a credential, store it with
`POST /credentials` and replace the auth entry in `headers` with `credential`.
Keep the other headers where they are.

## Use credentials as environment variables {% id="environment-variables" %}

Some client libraries read secrets from the process environment rather than
accepting them as request headers. Socket-mode and long-polling clients are the
common case.

Bind an `environment_variable` credential to a variable name under
`environment.env`:

{% tabs %}
{% tab label="Python" filename="use_credentials_as_environment_variables.py" %}
```py
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Run the sync script and check notifications.",
    environment={
        "type": "remote",
        "env": {
            "NODE_ENV": "production",
            "SLACK_BOT_TOKEN": {"credential": "slack-bot-token"},
        },
    },
)
```
{% /tab %}
{% tab label="JavaScript" filename="use_credentials_as_environment_variables.js" %}
```javascript
const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Run the sync script and check notifications.",
    environment: {
        type: "remote",
        env: {
            NODE_ENV: "production",
            SLACK_BOT_TOKEN: { credential: "slack-bot-token" },
        },
    },
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("antigravity-preview-09-2026"),
            Input: interactions.NewInteractionsInput("Run the sync script and check notifications."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
                Env: genai.Ptr(interactions.NewEnv(map[string]interactions.EnvVar{
                    "NODE_ENV":        {Value: genai.Ptr("production")},
                    "SLACK_BOT_TOKEN": {Credential: genai.Ptr("slack-bot-token")},
                })),
            })),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Run the sync script and check notifications.",
    "environment": {
        "type": "remote",
        "env": {
            "NODE_ENV": "production",
            "SLACK_BOT_TOKEN": { "credential": "slack-bot-token" }
        }
    }
}'
```
{% /tab %}
{% /tabs %}

`env` accepts literal strings and credential references side by side. A literal
string is injected into the container as a normal plaintext variable.

A credential reference is not. The variable receives the placeholder
`__GEMINI_CRED_<credential-id>__`, and the proxy swaps in the real secret only
for outbound requests going to a domain in the credential's `trusted_domains`. A
request to any other domain is rejected, so the secret never leaves the
perimeter and the placeholder is not sent in its place.

Caution: Literal values are injected as plain text and are readable by anything running in the sandbox, including the agent itself. Use them for configuration like `NODE_ENV`, not for secrets. A secret belongs in a credential, which is the only form that gets a placeholder and on-the-wire substitution.

Set `trusted_domains` on every `environment_variable` credential. It is the
control that scopes where the secret can be used.

## Create a credential {% id="create-a-credential" %}

Every create request needs a `type`, plus whichever fields that type requires.

When calling REST directly, all field names use snake_case. Sending a camelCase
field returns a `400`.

### Bearer token {% id="bearer-token" %}

A bearer token credential needs only `token`:

{% tabs %}
{% tab label="Python" filename="bearer_token.py" %}
```py
credential = client.credentials.create(
    id="github-production",
    type="bearer_token",
    token="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)
```
{% /tab %}
{% tab label="JavaScript" filename="bearer_token.js" %}
```javascript
const credential = await client.credentials.create({
    id: "github-production",
    type: "bearer_token",
    token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/credentials"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
        Body: credentials.NewCredentialCreateParams(credentials.HTTPBearerConfig{
            ID:    "github-production",
            Token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created credential: %s\n", res.Credential.ID)
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "github-production",
    "type": "bearer_token",
    "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'
```
{% /tab %}
{% /tabs %}

The response returns metadata only, never the token:

```json
{
  "id": "github-production",
  "type": "bearer_token",
  "status": "active",
  "create_time": "2026-07-15T10:00:00.000000000Z",
  "update_time": "2026-07-15T10:00:00.000000000Z"
}
```

By default the proxy sends `Authorization: Bearer <token>`. Override
`header_name` and `prefix` to target a service that expects something else:

{% tabs %}
{% tab label="Python" filename="bearer_token.py" %}
```py
credential = client.credentials.create(
    id="my-api-key",
    type="bearer_token",
    token="key_xxxxxxxxxxxx",
    header_name="x-goog-api-key",
    prefix="",
)
```
{% /tab %}
{% tab label="JavaScript" filename="bearer_token.js" %}
```javascript
const credential = await client.credentials.create({
    id: "my-api-key",
    type: "bearer_token",
    token: "key_xxxxxxxxxxxx",
    header_name: "x-goog-api-key",
    prefix: "",
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/credentials"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
        Body: credentials.NewCredentialCreateParams(credentials.HTTPBearerConfig{
            ID:         "my-api-key",
            Token:      "key_xxxxxxxxxxxx",
            HeaderName: genai.Ptr("x-goog-api-key"),
            Prefix:     genai.Ptr(""),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created credential: %s\n", res.Credential.ID)
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "my-api-key",
    "type": "bearer_token",
    "token": "key_xxxxxxxxxxxx",
    "header_name": "x-goog-api-key",
    "prefix": ""
}'
```
{% /tab %}
{% /tabs %}

This configuration produces the header `x-goog-api-key: key_xxxxxxxxxxxx`.

The following table shows how `header_name` and `prefix` combine:

| Configuration | Injected header |
| :---- | :---- |
| `{"token": "ghp_xxx"}` | `Authorization: Bearer ghp_xxx` |
| `{"token": "sk_live_xxx"}` | `Authorization: Bearer sk_live_xxx` |
| `{"token": "key_xxx", "header_name": "x-goog-api-key", "prefix": ""}` | `x-goog-api-key: key_xxx` |
| `{"token": "mytoken", "header_name": "X-API-Token", "prefix": ""}` | `X-API-Token: mytoken` |

### OAuth2 {% id="oauth2" %}

An OAuth2 credential requires `client_id`, `client_secret`, `refresh_token`,
and `token_url`. The `scopes` field is optional:

{% tabs %}
{% tab label="Python" filename="oauth2.py" %}
```py
credential = client.credentials.create(
    id="jira-oauth",
    type="oauth2",
    client_id="my-client-id",
    client_secret="my-client-secret",
    token_url="https://auth.atlassian.com/oauth/token",
    refresh_token="rt_xxxxxxxxxxxxxxxxxxxx",
    scopes=["read:jira-work", "write:jira-work"],
)
```
{% /tab %}
{% tab label="JavaScript" filename="oauth2.js" %}
```javascript
const credential = await client.credentials.create({
    id: "jira-oauth",
    type: "oauth2",
    client_id: "my-client-id",
    client_secret: "my-client-secret",
    token_url: "https://auth.atlassian.com/oauth/token",
    refresh_token: "rt_xxxxxxxxxxxxxxxxxxxx",
    scopes: ["read:jira-work", "write:jira-work"],
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/credentials"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
        Body: credentials.NewCredentialCreateParams(credentials.OAuth2Config{
            ID:           "jira-oauth",
            ClientID:     "my-client-id",
            ClientSecret: "my-client-secret",
            TokenURL:     "https://auth.atlassian.com/oauth/token",
            RefreshToken: "rt_xxxxxxxxxxxxxxxxxxxx",
            Scopes:       []string{"read:jira-work", "write:jira-work"},
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created OAuth2 credential: %s\n", res.Credential.ID)
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "jira-oauth",
    "type": "oauth2",
    "client_id": "my-client-id",
    "client_secret": "my-client-secret",
    "token_url": "https://auth.atlassian.com/oauth/token",
    "refresh_token": "rt_xxxxxxxxxxxxxxxxxxxx",
    "scopes": ["read:jira-work", "write:jira-work"]
}'
```
{% /tab %}
{% /tabs %}

Creating an OAuth2 credential performs a live token exchange against
`token_url` to confirm the configuration works. The credential is stored only
if the provider returns a successful token response containing an
`access_token`. Both JSON and form-urlencoded responses are accepted.

This means you need a valid, unexpired refresh token at creation time. If the
provider rejects the exchange, the error is returned to you:

```json
{
  "error": {
    "message": "OAuth token validation failed with HTTP 403: {\"error\":\"unauthorized_client\",\"error_description\":\"refresh_token is invalid\"}",
    "code": "invalid_request"
  }
}
```

Once stored, the proxy refreshes access tokens as they expire. If the provider
rotates refresh tokens and returns a new one during a refresh, the new token
replaces the stored one automatically.

### Environment variable {% id="environment-variable" %}

An `environment_variable` credential requires `value` and `injection_location`:

{% tabs %}
{% tab label="Python" filename="environment_variable.py" %}
```py
credential = client.credentials.create(
    id="slack-bot-token",
    type="environment_variable",
    value="xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
    trusted_domains=["*.slack.com", "slack.com"],
    injection_location="header",
)
```
{% /tab %}
{% tab label="JavaScript" filename="environment_variable.js" %}
```javascript
const credential = await client.credentials.create({
    id: "slack-bot-token",
    type: "environment_variable",
    value: "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
    trusted_domains: ["*.slack.com", "slack.com"],
    injection_location: "header",
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/credentials"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
        Body: credentials.NewCredentialCreateParams(credentials.EnvironmentVariableConfig{
            ID:                "slack-bot-token",
            Value:             "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
            TrustedDomains:    []string{"*.slack.com", "slack.com"},
            InjectionLocation: credentials.NewEnvironmentVariableConfigInjectionLocation(credentials.InjectionLocationEnumHeader),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created environment variable credential: %s\n", res.Credential.ID)
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "slack-bot-token",
    "type": "environment_variable",
    "value": "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
    "trusted_domains": ["*.slack.com", "slack.com"],
    "injection_location": "header"
}'
```
{% /tab %}
{% /tabs %}

The `injection_location` field tells the proxy where in the outbound request to
substitute the secret. It accepts `header`, `query`, or `body`, either as a
single string or as an array when a service needs more than one:

```json
"injection_location": ["header", "query"]
```

Substitution happens only in the locations you list. A request that carries the
placeholder anywhere else is rejected rather than sent on.

To bind the credential to a variable name, see
[Use credentials as environment variables](/docs/agent-credentials#environment-variables).

### Generated IDs {% id="generated-ids" %}

The `id` field is optional. Omit it and the service generates a UUID:

```json
{
  "id": "9e545973-4330-49bb-9a44-930cea9fbe3c",
  "type": "bearer_token",
  "status": "active",
  "create_time": "2026-07-15T10:00:00.000000000Z",
  "update_time": "2026-07-15T10:00:00.000000000Z"
}
```

Supply your own ID when you want a stable, readable reference to use across
interactions. Since the ID appears in the resource path, prefer lowercase
alphanumerics with hyphens or underscores.

## List credentials {% id="list-credentials" %}

List the credentials belonging to your project. Use pagination parameters to
control the response batch size.

{% tabs %}
{% tab label="Python" filename="list_credentials.py" %}
```py
response = client.credentials.list(page_size=10)
for credential in response.credentials:
    print(f"Credential ID: {credential.id}, Type: {credential.type}")
```
{% /tab %}
{% tab label="JavaScript" filename="list_credentials.js" %}
```javascript
const response = await client.credentials.list({ page_size: 10 });
for (const credential of response.credentials) {
    console.log(`Credential ID: ${credential.id}, Type: ${credential.type}`);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Credentials.List(ctx, operations.ListCredentialsRequest{
        PageSize: genai.Ptr(10),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, cred := range res.CredentialListResponse.Credentials {
        fmt.Printf("Credential ID: %s, Type: %v\n", cred.ID, cred.GetType())
    }
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X GET "https://generativelanguage.googleapis.com/v1beta/credentials?page_size=10" \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

The response contains metadata only:

```json
{
  "credentials": [
    {
      "id": "github-production",
      "type": "bearer_token",
      "status": "active",
      "create_time": "2026-07-15T10:00:00.000000000Z",
      "update_time": "2026-07-15T10:00:00.000000000Z"
    },
    {
      "id": "jira-oauth",
      "type": "oauth2",
      "status": "active",
      "create_time": "2026-07-15T10:05:00.000000000Z",
      "update_time": "2026-07-15T10:05:00.000000000Z"
    }
  ],
  "next_page_token": "Cj...5aE="
}
```

Pass `next_page_token` back as `page_token` to fetch the next page. The field
is omitted when there are no further results.

| Parameter | Type | Description |
| :---- | :---- | :---- |
| `page_size` | integer | Maximum number of credentials per page. |
| `page_token` | string | Token from the `next_page_token` of a previous response. |

## Get a credential {% id="get-a-credential" %}

Retrieve metadata for a specific credential by its ID.

{% tabs %}
{% tab label="Python" filename="get_a_credential.py" %}
```py
credential = client.credentials.get(id="github-production")
print(f"Credential ID: {credential.id}, Status: {credential.status}")
```
{% /tab %}
{% tab label="JavaScript" filename="get_a_credential.js" %}
```javascript
const credential = await client.credentials.get("github-production");
console.log(`Credential ID: ${credential.id}, Status: ${credential.status}`);
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Credentials.Get(ctx, operations.GetCredentialRequest{
        ID: "github-production",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Credential ID: %s, Status: %v\n", res.Credential.ID, res.Credential.GetStatus())
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X GET "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

The response looks similar to the following:

```json
{
  "id": "github-production",
  "type": "bearer_token",
  "status": "active",
  "create_time": "2026-07-15T10:00:00.000000000Z",
  "update_time": "2026-08-01T14:30:00.000000000Z"
}
```

Requesting a credential that does not exist returns `404`:

```json
{
  "error": {
    "message": "Result not found.; GetCredential call failed",
    "code": "not_found"
  }
}
```

## Rotate a credential {% id="rotate-a-credential" %}

Replace a secret without touching any allowlist rule, tool definition, or
environment variable that references it. Rotation takes effect on the next
proxy resolution.

The request must include `type`, plus the fields you want to change. Fields you
omit keep their current values.

Rotate a bearer token:

{% tabs %}
{% tab label="Python" filename="rotate_a_credential.py" %}
```py
credential = client.credentials.update(
    id="github-production",
    type="bearer_token",
    token="ghp_new_xxxxxxxxxxxxxxxxxxxx",
)
```
{% /tab %}
{% tab label="JavaScript" filename="rotate_a_credential.js" %}
```javascript
const credential = await client.credentials.update("github-production", {
    type: "bearer_token",
    token: "ghp_new_xxxxxxxxxxxxxxxxxxxx",
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/credentials"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Credentials.Update(ctx, operations.UpdateCredentialRequest{
        ID: "github-production",
        Body: credentials.NewCredentialUpdate(credentials.HTTPBearerUpdateConfig{
            Token: genai.Ptr("ghp_new_xxxxxxxxxxxxxxxxxxxx"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Updated credential %s at %v\n", res.Credential.ID, res.Credential.GetUpdateTime())
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "type": "bearer_token",
    "token": "ghp_new_xxxxxxxxxxxxxxxxxxxx"
}'
```
{% /tab %}
{% /tabs %}

Rotate an OAuth2 refresh token:

{% tabs %}
{% tab label="Python" filename="rotate_a_credential.py" %}
```py
credential = client.credentials.update(
    id="jira-oauth",
    type="oauth2",
    refresh_token="rt_new_xxxxxxxxxxxxxxxxxxxx",
)
```
{% /tab %}
{% tab label="JavaScript" filename="rotate_a_credential.js" %}
```javascript
const credential = await client.credentials.update("jira-oauth", {
    type: "oauth2",
    refresh_token: "rt_new_xxxxxxxxxxxxxxxxxxxx",
});
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/credentials"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Credentials.Update(ctx, operations.UpdateCredentialRequest{
        ID: "jira-oauth",
        Body: credentials.NewCredentialUpdate(credentials.OAuth2UpdateConfig{
            RefreshToken: genai.Ptr("rt_new_xxxxxxxxxxxxxxxxxxxx"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Updated credential %s at %v\n", res.Credential.ID, res.Credential.GetUpdateTime())
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/credentials/jira-oauth" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "type": "oauth2",
    "refresh_token": "rt_new_xxxxxxxxxxxxxxxxxxxx"
}'
```
{% /tab %}
{% /tabs %}

The response reflects the new `update_time`:

```json
{
  "id": "jira-oauth",
  "type": "oauth2",
  "status": "active",
  "create_time": "2026-07-15T10:05:00.000000000Z",
  "update_time": "2026-08-01T14:30:00.000000000Z"
}
```

A credential's `type` is fixed at creation. To change it, delete the credential
and create a new one.

## Delete a credential {% id="delete-a-credential" %}

Delete a credential and its stored secret when it is no longer needed.

{% tabs %}
{% tab label="Python" filename="delete_a_credential.py" %}
```py
client.credentials.delete(id="github-production")
```
{% /tab %}
{% tab label="JavaScript" filename="delete_a_credential.js" %}
```javascript
await client.credentials.delete("github-production");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Credentials.Delete(ctx, operations.DeleteCredentialRequest{
        ID: "github-production",
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

A successful delete returns an empty object:

```json
{}
```

Any allowlist rule, tool, or environment variable still referencing the ID will
fail to resolve, so update those first.

## Field reference {% id="field-reference" %}

Fields common to every credential:

| Field | Type | Required | Description |
| :---- | :---- | :---- | :---- |
| `id` | string | No | Unique identifier. Generated as a UUID when omitted. |
| `type` | string | Yes | One of `bearer_token`, `oauth2`, `environment_variable`. |
| `status` | string | Read-only | Current status of the credential. |
| `create_time` | string | Read-only | RFC 3339 creation timestamp. |
| `update_time` | string | Read-only | RFC 3339 timestamp of the last update. |

Fields for `bearer_token`:

| Field | Type | Required | Description |
| :---- | :---- | :---- | :---- |
| `token` | string | Yes | Write-only. The token value. |
| `header_name` | string | No | Header to inject. Defaults to `Authorization`. |
| `prefix` | string | No | Value prefix. Defaults to `Bearer`. Set to `""` for none. |

Fields for `oauth2`:

| Field | Type | Required | Description |
| :---- | :---- | :---- | :---- |
| `client_id` | string | Yes | OAuth2 client ID. |
| `client_secret` | string | Yes | Write-only. OAuth2 client secret. |
| `refresh_token` | string | Yes | Write-only. Refresh token used to obtain access tokens. |
| `token_url` | string | Yes | Provider token endpoint. |
| `scopes` | array | No | OAuth scopes to request. |

Fields for `environment_variable`:

| Field | Type | Required | Description |
| :---- | :---- | :---- | :---- |
| `value` | string | Yes | Write-only. The secret value. |
| `injection_location` | string or array | Yes | Where to substitute the secret. One or more of `header`, `query`, `body`. |
| `trusted_domains` | array | No | Domain patterns authorized for substitution. |

## Errors {% id="errors" %}

Errors return a JSON object with a `message` and a `code`:

```json
{
  "error": {
    "message": "Credential 'github-production' already exists.; CreateCredential call failed",
    "code": "aborted"
  }
}
```

| HTTP status | `code` | Cause |
| :---- | :---- | :---- |
| 400 | `invalid_request` | Missing required field, unknown field, unsupported `type`, or a failed OAuth2 validation. |
| 404 | `not_found` | No credential with that ID. |
| 409 | `aborted` | A credential with that ID already exists. |

Unknown fields are rejected rather than ignored, and the error names the field:

```json
{
  "error": {
    "message": "Unknown parameter 'headerName'. Did you mean 'header_name'?",
    "code": "invalid_request"
  }
}
```

## What's next {% id="whats-next" %}

*   [Environments](/docs/agent-environment): Learn how agents run code and persist files.
*   [Agents Overview](/docs/agents): Learn about the core concepts of managed agents.
*   [Building Custom Agents](/docs/custom-agents): Define your own agents using `AGENTS.md` and `SKILL.md`.

# Hooks
Source: https://aistudio.google.com/docs/agent-hooks
Description: Configure synchronous hooks inside remote sandboxes to intercept tool calls for security, formatting, and auditing.

Hooks let you run custom scripts or external HTTP requests right before or after the agent executes code or modifies files inside its remote sandbox. Use hooks to extend the agent loop with automated guardrails and background workflows, such as:

* **Enforcing safety and access guardrails** before high-risk shell commands or restricted file reads execute.
* **Automating data pipeline transformations** right after an agent creates or modifies files.
* **Streaming enterprise audit telemetry** to external monitoring systems after tool execution.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import json
from google import genai

client = genai.Client()

hooks_config = {
    "security-gate": {
        "pre_tool_execution": [
            {
                "matcher": "code_execution",
                "hooks": [
                    {
                        "type": "command",
                        "command": "python3 /.agents/hooks-scripts/gate.py",
                        "timeout": 10,
                    }
                ],
            }
        ]
    }
}

gate_script = """#!/usr/bin/env python3
import sys, json
data = json.load(sys.stdin)
cmd = str(data.get("tool_call", {}).get("args", {}))
if "rm -rf" in cmd:
    print(json.dumps({"decision": "deny", "reason": "Destructive command blocked by security gate."}))
else:
    print(json.dumps({"decision": "allow"}))
"""

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Run `rm -rf /tmp/forbidden` using code_execution.",
    tools=[{"type": "code_execution"}],
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/hooks.json",
                "content": json.dumps(hooks_config, indent=2),
            },
            {
                "type": "inline",
                "target": ".agents/hooks-scripts/gate.py",
                "content": gate_script,
            },
        ],
    },
)
print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const hooksConfig = {
    "security-gate": {
        pre_tool_execution: [
            {
                matcher: "code_execution",
                hooks: [
                    {
                        type: "command",
                        command: "python3 /.agents/hooks-scripts/gate.py",
                        timeout: 10,
                    },
                ],
            },
        ],
    },
};

const gateScript = `#!/usr/bin/env python3
import sys, json
data = json.load(sys.stdin)
cmd = str(data.get("tool_call", {}).get("args", {}))
if "rm -rf" in cmd:
    print(json.dumps({"decision": "deny", "reason": "Destructive command blocked by security gate."}))
else:
    print(json.dumps({"decision": "allow"}))
`;

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Run `rm -rf /tmp/forbidden` using code_execution.",
    tools: [{ type: "code_execution" }],
    environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/hooks.json",
                content: JSON.stringify(hooksConfig, null, 2),
            },
            {
                type: "inline",
                target: ".agents/hooks-scripts/gate.py",
                content: gateScript,
            },
        ],
    },
});
console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": [{"type": "text", "text": "Run `rm -rf /tmp/forbidden` using code_execution."}],
      "tools": [{"type": "code_execution"}],
      "environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "inline",
                  "target": ".agents/hooks.json",
                  "content": "{\"security-gate\": {\"pre_tool_execution\": [{\"matcher\": \"code_execution\", \"hooks\": [{\"type\": \"command\", \"command\": \"python3 /.agents/hooks-scripts/gate.py\", \"timeout\": 10}]}]}}"
              },
              {
                  "type": "inline",
                  "target": ".agents/hooks-scripts/gate.py",
                  "content": "#!/usr/bin/env python3\nimport sys, json\ndata = json.load(sys.stdin)\ncmd = str(data.get(\"tool_call\", {}).get(\"args\", {}))\nif \"rm -rf\" in cmd:\n    print(json.dumps({\"decision\": \"deny\", \"reason\": \"Destructive command blocked by security gate.\"}))\nelse:\n    print(json.dumps({\"decision\": \"allow\"}))\n"
              }
          ]
      }
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

String hooksConfig = """
{
  "security-gate": {
    "pre_tool_execution": [
      {
        "matcher": "code_execution",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /.agents/hooks-scripts/gate.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
""";

String gateScript = "#!/usr/bin/env python3\n"
    + "import sys, json\n"
    + "data = json.load(sys.stdin)\n"
    + "cmd = str(data.get(\"tool_call\", {}).get(\"args\", {}))\n"
    + "if \"rm -rf\" in cmd:\n"
    + "    print(json.dumps({\"decision\": \"deny\", \"reason\": \"Destructive command blocked by security gate.\"}))\n"
    + "else:\n"
    + "    print(json.dumps({\"decision\": \"allow\"}))\n";

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/hooks.json")
            .content(hooksConfig)
            .build(),
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/hooks-scripts/gate.py")
            .content(gateScript)
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Run `rm -rf /tmp/forbidden` using code_execution."))
    .tools(List.of(CodeExecution.builder().build()))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    hooksConfig := `{
  "security-gate": {
    "pre_tool_execution": [
      {
        "matcher": "code_execution",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /.agents/hooks-scripts/gate.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}`

    gateScript := `#!/usr/bin/env python3
import sys, json
data = json.load(sys.stdin)
cmd = str(data.get("tool_call", {}).get("args", {}))
if "rm -rf" in cmd:
    print(json.dumps({"decision": "deny", "reason": "Destructive command blocked by security gate."}))
else:
    print(json.dumps({"decision": "allow"}))
`

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/hooks.json"),
                Content: genai.Ptr(hooksConfig),
            },
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/hooks-scripts/gate.py"),
                Content: genai.Ptr(gateScript),
            },
        },
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Run `rm -rf /tmp/forbidden` using code_execution."),
            Tools:       []interactions.Tool{interactions.NewTool(interactions.CodeExecution{})},
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
## Supported lifecycle events {% id="supported-lifecycle-events" %}

Hooks support 2 events inside the sandbox:

| Event | When it fires | What it does |
| :---- | :---- | :---- |
| `pre_tool_execution` | Right before a tool runs | Can approve (`allow`) or block (`deny`) the tool before it executes. When blocked, the model sees your rejection reason and adapts. |
| `post_tool_execution` | Right after a tool finishes | Runs follow-up tasks like formatting code, running unit tests, or logging telemetry. Cannot block or undo completed actions. |

### `pre_tool_execution` {% id="pre-tool-execution" %}

Fires right before a tool executes. Your script reads the tool call details from `stdin` and outputs its decision JSON (`allow` or `deny`) to `stdout`.

**Input payload (`stdin`):**

```json
{
  "tool_call": {
    "name": "code_execution",
    "args": {
      "code": "rm -rf /tmp/forbidden",
      "language": "bash"
    }
  },
  "environment_id": "env_xyz789"
}
```

**Output response (`stdout`):**

To approve the tool call:

```json
{
  "decision": "allow"
}
```

To block the tool call and return feedback to the model:

```json
{
  "decision": "deny",
  "reason": "Destructive command blocked by security gate."
}
```

When a hook denies a command, the tool call is skipped immediately. The agent sees an error result containing your rejection reason right inside its current turn. The model can then self-correct by choosing an alternative command or explaining the block to the user.

If your script outputs unrecognized JSON, plain text, or anything other than `{"decision": "deny"}`, the runtime treats the response as an approval (`allow`).

### `post_tool_execution` {% id="post-tool-execution" %}

Fires right after a tool completes. Your script reads the execution details and any error status from `stdin`.

**Input payload (`stdin`):**

```json
{
  "tool_call": {
    "name": "code_execution",
    "args": {
      "code": "python3 /workspace/app.py",
      "language": "bash"
    }
  },
  "environment_id": "env_xyz789"
}
```

If a shell command prints errors to standard error (`stderr`) or a filesystem operation fails, an `"error"` field containing the error text is included in the payload. When the command succeeds without errors, the `"error"` field is omitted entirely.

**Output response (`stdout`):**

```json
{}
```

Because post-tool hooks run strictly for background tasks like code formatting or logging, the runtime ignores any decision values returned on `stdout`.

## Configuration discovery {% id="configuration-discovery" %}

The runtime automatically discovers hook definitions from `.agents/hooks.json` or `/.agents/hooks.json` inside the sandbox environment. You can provide `hooks.json` alongside your custom scripts using any supported [environment source](/docs/agent-environment#mount-from-a-source):

* **Repository mount**: A Git repository containing `.agents/hooks.json` alongside `AGENTS.md`.
* **Cloud Storage (`gcs`)**: A GCS bucket containing `hooks.json` copied into the environment.
* **Inline sources**: Raw JSON string and script contents passed in `environment.sources` when calling `client.interactions.create`.

### `hooks.json` schema {% id="hooks-json-schema" %}

A `hooks.json` file groups event definitions (`pre_tool_execution` or `post_tool_execution`) under custom names. You can enable or disable each group independently:

```json
{
  "security-gate": {
    "enabled": true,
    "pre_tool_execution": [
      {
        "matcher": "code_execution",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /.agents/hooks-scripts/gate.py",
            "timeout": 10
          }
        ]
      }
    ]
  },
  "auto-format": {
    "post_tool_execution": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /.agents/hooks-scripts/auto_lint.py",
            "timeout": 15
          }
        ]
      }
    ]
  }
}
```

### Matcher syntax and rules {% id="matcher-syntax" %}

Each rule group in `hooks.json` defines when and how handlers fire using the `matcher` and `hooks` properties:

| Field | Type | Description |
| :---- | :---- | :---- |
| `enabled` | `boolean` | Optional. Set to `false` to disable the group (`true` by default). |
| `matcher` | `string` | Regular expression pattern matching target tool names inside the container. |
| `hooks` | `array` | Ordered list of handler definitions (`command` or `http`). Handlers run sequentially in declaration order. |

#### How regex evaluation works

When the agent invokes a tool inside the sandbox, the runtime evaluates the tool's container name against your `matcher` pattern using standard RE2 regular expressions. If the regex matches the tool name, all handlers in the `hooks` array execute in order. If multiple rule groups match the same tool, all corresponding handler arrays run.

You can target any built-in container tool name: code execution (`code_execution`) or filesystem operations (`view_file`, `write_to_file`, `replace_file_content`, `list_dir`, and `delete_file`).

#### Common matcher expressions

* `"code_execution"`: Exact string match for shell commands and script executions.
* `"write_to_file"`: Exact match for filesystem file creation and disk writes.
* `"view_file|write_to_file"`: Pipe separation matches multiple specific tool names in a single rule.
* `".*_file"`: Regex wildcard matching any tool ending in `_file` (such as `view_file`, `write_to_file`, or `delete_file`). This covers only part of the filesystem toolset, `replace_file_content` and `list_dir` do not end in `_file`, so name them explicitly when you need them. Standard RE2 regular expressions require `.*`; simple shell globs like `*_file` are invalid regex syntax and will fail to match.
* `".*"` or `"*"` or `""`: Catch-all pattern that intercepts every single tool call inside the container.

## Handler types {% id="handler-types" %}

### Command hooks {% id="command-hooks" %}

Command hooks execute a shell command or script inside the sandbox. The script receives the event JSON on `stdin` and outputs its decision JSON on `stdout`.

| Field | Type | Description |
| :---- | :---- | :---- |
| `type` | `string` | Must be `"command"`. |
| `command` | `string` | Command line to run inside the sandbox (for example, `python3 /.agents/hooks-scripts/gate.py`). |
| `timeout` | `integer` | Timeout in seconds. Default: `30`. |

### HTTP hooks {% id="http-hooks" %}

HTTP hooks send the event JSON as a POST request to an external HTTPS URL directly from inside the sandbox network. The target server returns its decision in the HTTP response body using the exact same JSON format (`{"decision": "allow"}` or `{"decision": "deny", "reason": "..."}`).

| Field | Type | Description |
| :---- | :---- | :---- |
| `type` | `string` | Must be `"http"`. |
| `url` | `string` | External HTTPS endpoint to POST the event payload to. |
| `headers` | `object` | Optional key-value pairs for non-sensitive custom headers (such as `{"X-Event-Source": "agent-sandbox"}`). For authentication, use a [credential](/docs/agent-credentials) on the network allowlist instead. |
| `timeout` | `integer` | Timeout in seconds. Default: `30`. |

#### Egress proxy and token transformation {% id="egress-proxy-and-token-transformation" %}

Because HTTP hooks execute directly from inside the sandbox network namespace, outgoing requests pass through the transparent egress proxy. This architecture gives you 2 critical security advantages:

* **Network allowlisting:** Target endpoints must be explicitly permitted in your environment's `network.allowlist`. Loopback traffic (`127.0.0.1` or `localhost`) is blocked by the proxy; always target allowlisted external endpoints.
* **Credential injection:** You do not need to store API keys or secret bearer tokens inside `.agents/hooks.json` or mount them into the container. Store the secret once as a [credential](/docs/agent-credentials) and reference it by ID from your environment's `network.allowlist`. The egress proxy automatically intercepts outgoing HTTP hook traffic and injects the real authentication header on the wire before leaving the sandbox. Inline `transform` rules set headers the same way on the wire, a credential is the one to use when you want to reuse the secret across the project and rotate it in one place. See [network configuration](/docs/agent-environment#network-configuration).

## How the runtime handles decisions and failures {% id="execution-and-failure-semantics" %}

* **Synchronous waiting:** The agent pauses and waits for your hooks to finish before continuing.
* **Blocking tool execution:** If your pre-tool hook returns `{"decision": "deny", "reason": "<your reason>"}`, the runtime immediately cancels the tool call. The model sees your rejection reason in its conversation history and adapts by choosing a safe alternative or explaining the block to the user.
* **Handling script crashes, HTTP errors, and timeouts:** If a command script crashes (non-zero exit status), an HTTP hook returns a non-2xx status code (such as a 4xx or 5xx server error), or an operation times out or returns unrecognized JSON, the runtime treats it as an approval (`allow`). Tool execution continues normally so a broken script or unreachable telemetry server never deadlocks your application.

## Common use cases {% id="common-use-cases" %}

### Multi-turn recovery for data privacy and compliance {% id="data-privacy-recovery" %}

When a hook blocks access to restricted resources—such as directories containing Personally Identifiable Information (PII) or confidential financial records—you can pass `previous_interaction_id` on the next call to continue the turn in the same environment. The agent reads the denial explanation and automatically recovers by querying approved public tables instead.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import json
from google import genai

client = genai.Client()

hooks_config = {
    "privacy-gate": {
        "pre_tool_execution": [
            {
                "matcher": "view_file",
                "hooks": [
                    {
                        "type": "command",
                        "command": "python3 /.agents/hooks-scripts/check_privacy.py",
                        "timeout": 5,
                    }
                ],
            }
        ]
    }
}

check_privacy_script = """#!/usr/bin/env python3
import sys, json
data = json.load(sys.stdin)
path = str(data.get("tool_call", {}).get("args", {}).get("path", ""))

if "/private/" in path:
    resp = {
        "decision": "deny",
        "reason": "Access to confidential `/private/` records is blocked by PII compliance policy. Query approved `/public/` summary tables instead."
    }
else:
    resp = {"decision": "allow"}

print(json.dumps(resp))
"""

# Step 1: Agent attempts to read confidential PII records and is intercepted
int_1 = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Use your filesystem tool to read `/workspace/private/employees.json` and summarize the employee details.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/hooks.json",
                "content": json.dumps(hooks_config, indent=2),
            },
            {
                "type": "inline",
                "target": ".agents/hooks-scripts/check_privacy.py",
                "content": check_privacy_script,
            },
            {
                "type": "inline",
                "target": "workspace/private/employees.json",
                "content": '{"employees": [{"id": 1, "salary": 150000, "ssn": "000-00-0000"}]}',
            },
            {
                "type": "inline",
                "target": "workspace/public/summary.json",
                "content": '{"department": "Engineering", "team_size": 42, "status": "active"}',
            },
        ],
    },
)
print(int_1.output_text)

# Step 2: Continue in the same environment using previous_interaction_id; agent recovers with public tables
int_2 = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Understood. Please read the approved `/workspace/public/summary.json` file instead and provide the summary.",
    environment=int_1.environment_id,
    previous_interaction_id=int_1.id,
)
print(int_2.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

const hooksConfig = {
    "privacy-gate": {
        pre_tool_execution: [
            {
                matcher: "view_file",
                hooks: [
                    {
                        type: "command",
                        command: "python3 /.agents/hooks-scripts/check_privacy.py",
                        timeout: 5,
                    },
                ],
            },
        ],
    },
};

const checkPrivacyScript = `#!/usr/bin/env python3
import sys, json
data = json.load(sys.stdin)
path = str(data.get("tool_call", {}).get("args", {}).get("path", ""))

if "/private/" in path:
    resp = {
        "decision": "deny",
        "reason": "Access to confidential \`/private/\` records is blocked by PII compliance policy. Query approved \`/public/\` summary tables instead."
    }
else:
    resp = {"decision": "allow"}

print(json.dumps(resp))
`;

const int1 = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Use your filesystem tool to read `/workspace/private/employees.json` and summarize the employee details.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                "target": ".agents/hooks.json",
                content: JSON.stringify(hooksConfig, null, 2),
            },
            {
                type: "inline",
                "target": ".agents/hooks-scripts/check_privacy.py",
                content: checkPrivacyScript,
            },
            {
                type: "inline",
                "target": "workspace/private/employees.json",
                content: '{"employees": [{"id": 1, "salary": 150000, "ssn": "000-00-0000"}]}',
            },
            {
                type: "inline",
                "target": "workspace/public/summary.json",
                content: '{"department": "Engineering", "team_size": 42, "status": "active"}',
            },
        ],
    },
});
console.log(int1.output_text);

const int2 = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Understood. Please read the approved `/workspace/public/summary.json` file instead and provide the summary.",
    environment: int1.environment_id,
    previous_interaction_id: int1.id,
});
console.log(int2.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
# Step 1: Attempt to access restricted PII directory (blocked by hook)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": [{"type": "text", "text": "Use your filesystem tool to read /workspace/private/employees.json and summarize the employee details."}],
      "environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "inline",
                  "target": ".agents/hooks.json",
                  "content": "{\"privacy-gate\": {\"pre_tool_execution\": [{\"matcher\": \"view_file\", \"hooks\": [{\"type\": \"command\", \"command\": \"python3 /.agents/hooks-scripts/check_privacy.py\", \"timeout\": 5}]}]}}"
              },
              {
                  "type": "inline",
                  "target": ".agents/hooks-scripts/check_privacy.py",
                  "content": "#!/usr/bin/env python3\nimport sys, json\ndata = json.load(sys.stdin)\npath = str(data.get(\"tool_call\", {}).get(\"args\", {}).get(\"path\", \"\"))\nif \"/private/\" in path:\n    resp = {\"decision\": \"deny\", \"reason\": \"Access to confidential `/private/` records is blocked by PII compliance policy. Query approved `/public/` summary tables instead.\"}\nelse:\n    resp = {\"decision\": \"allow\"}\nprint(json.dumps(resp))\n"
              },
              {
                  "type": "inline",
                  "target": "workspace/private/employees.json",
                  "content": "{\"employees\": [{\"id\": 1, \"salary\": 150000, \"ssn\": \"000-00-0000\"}]}"
              },
              {
                  "type": "inline",
                  "target": "workspace/public/summary.json",
                  "content": "{\"department\": \"Engineering\", \"team_size\": 42, \"status\": \"active\"}"
              }
          ]
      }
  }'

# Step 2: Continue in the same environment using $ENV_ID and $INTERACTION_ID from the previous response
# curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
#   -H "Content-Type: application/json" \
#   -H "x-goog-api-key: $GEMINI_API_KEY" \
#   -d '{
#       "agent": "antigravity-preview-09-2026",
#       "input": [{"type": "text", "text": "Understood. Please read the approved /workspace/public/summary.json file instead and provide the summary."}],
#       "environment": "'"$ENV_ID"'",
#       "previous_interaction_id": "'"$INTERACTION_ID"'"
#   }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

String hooksConfig = """
{
  "privacy-gate": {
    "pre_tool_execution": [
      {
        "matcher": "read_file",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /.agents/hooks-scripts/check_privacy.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
""";

String checkPrivacyScript = "#!/usr/bin/env python3\n"
    + "import sys, json\n"
    + "data = json.load(sys.stdin)\n"
    + "path = str(data.get(\"tool_call\", {}).get(\"args\", {}).get(\"path\", \"\"))\n"
    + "if \"/private/\" in path:\n"
    + "    resp = {\n"
    + "        \"decision\": \"deny\",\n"
    + "        \"reason\": \"Access to confidential `/private/` records is blocked by PII compliance policy. Query approved `/public/` summary tables instead.\"\n"
    + "    }\n"
    + "else:\n"
    + "    resp = {\"decision\": \"allow\"}\n"
    + "print(json.dumps(resp))\n";

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/hooks.json")
            .content(hooksConfig)
            .build(),
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/hooks-scripts/check_privacy.py")
            .content(checkPrivacyScript)
            .build(),
        Source.builder()
            .type(SourceType.INLINE)
            .target("workspace/private/employees.json")
            .content("{\"employees\": [{\"id\": 1, \"salary\": 150000, \"ssn\": \"000-00-0000\"}]}")
            .build(),
        Source.builder()
            .type(SourceType.INLINE)
            .target("workspace/public/summary.json")
            .content("{\"department\": \"Engineering\", \"team_size\": 42, \"status\": \"active\"}")
            .build()
    ))
    .build();

// Step 1: Agent attempts to read confidential PII records and is intercepted
CreateAgentInteraction params1 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Use your filesystem tool to read `/workspace/private/employees.json` and summarize the employee details."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction int1 = client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
System.out.println(int1.outputText().orElse(""));

// Step 2: Continue in the same environment using previous_interaction_id; agent recovers with public tables
CreateAgentInteraction params2 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Understood. Please read the approved `/workspace/public/summary.json` file instead and provide the summary."))
    .environment(CreateAgentInteractionEnvironment.of(int1.environmentId().orElse("")))
    .previousInteractionId(int1.id().orElse(""))
    .build();

Interaction int2 = client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();
System.out.println(int2.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    hooksConfig := `{
  "privacy-gate": {
    "pre_tool_execution": [
      {
        "matcher": "read_file",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /.agents/hooks-scripts/check_privacy.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}`

    checkPrivacyScript := `#!/usr/bin/env python3
import sys, json
data = json.load(sys.stdin)
path = str(data.get("tool_call", {}).get("args", {}).get("path", ""))
if "/private/" in path:
    resp = {
        "decision": "deny",
        "reason": "Access to confidential '/private/' records is blocked by PII compliance policy. Query approved '/public/' summary tables instead."
    }
else:
    resp = {"decision": "allow"}
print(json.dumps(resp))
`

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/hooks.json"),
                Content: genai.Ptr(hooksConfig),
            },
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/hooks-scripts/check_privacy.py"),
                Content: genai.Ptr(checkPrivacyScript),
            },
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr("workspace/private/employees.json"),
                Content: genai.Ptr(`{"employees": [{"id": 1, "salary": 150000, "ssn": "000-00-0000"}]}`),
            },
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr("workspace/public/summary.json"),
                Content: genai.Ptr(`{"department": "Engineering", "team_size": 42, "status": "active"}`),
            },
        },
    }

    // Step 1: Agent attempts to read confidential PII records and is intercepted
    res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Use your filesystem tool to read `/workspace/private/employees.json` and summarize the employee details."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    int1 := res1.Interaction
    if int1.OutputText != nil {
        fmt.Println(*int1.OutputText)
    }

    // Step 2: Continue in the same environment using previous_interaction_id; agent recovers with public tables
    res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:                 interactions.AgentOption("antigravity-preview-09-2026"),
            Input:                 interactions.NewInteractionsInput("Understood. Please read the approved `/workspace/public/summary.json` file instead and provide the summary."),
            Environment:           genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(*int1.EnvironmentID)),
            PreviousInteractionID: int1.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res2.Interaction.OutputText != nil {
        fmt.Println(*res2.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
### External audit logging and telemetry {% id="external-audit-logging" %}

Send real-time audit events from inside the sandbox to an external monitoring server whenever files are read or modified.

* **Match multiple tools:** Because matchers use standard regex, you can combine multiple tools in a single rule using pipes (`view_file|write_to_file|replace_file_content`) or wildcards (`.*_file`).
* **Keep secrets out of your configuration:** Store the authentication token as a [credential](/docs/agent-credentials) and reference it by ID from your environment's [network configuration](/docs/agent-environment#network-configuration) (`network.allowlist.credential`). The egress proxy injects the real bearer token on outgoing requests. This example sets the header inline with `transform` instead, which is protected by the same proxy and fits when the token belongs to this one configuration.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import json
from google import genai

client = genai.Client()

# Define hook without secrets; the egress proxy injects headers dynamically
hooks_config = {
    "audit-logging": {
        "post_tool_execution": [
            {
                "matcher": "view_file|write_to_file|replace_file_content",
                "hooks": [
                    {
                        "type": "http",
                        "url": "https://telemetry.example.com/api/v1/agent-events",
                        "timeout": 10,
                    }
                ],
            }
        ]
    }
}

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Use your filesystem tool to create `/workspace/audit.log` containing 'event 1', then immediately read it back using your filesystem read tool.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/hooks.json",
                "content": json.dumps(hooks_config, indent=2),
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "telemetry.example.com",
                    "transform": {
                        "Authorization": "Bearer telemetry_secret_token_123",
                    },
                },
                {"domain": "*"},
            ]
        },
    },
)
print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

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

const client = new GoogleGenAI({});

// Define hook without secrets; the egress proxy injects headers dynamically
const hooksConfig = {
    "audit-logging": {
        post_tool_execution: [
            {
                matcher: "view_file|write_to_file|replace_file_content",
                hooks: [
                    {
                        type: "http",
                        url: "https://telemetry.example.com/api/v1/agent-events",
                        timeout: 10,
                    },
                ],
            },
        ],
    },
};

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Use your filesystem tool to create `/workspace/audit.log` containing 'event 1', then immediately read it back using your filesystem read tool.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/hooks.json",
                content: JSON.stringify(hooksConfig, null, 2),
            },
        ],
        network: {
            allowlist: [
                {
                    domain: "telemetry.example.com",
                    transform: {
                        Authorization: "Bearer telemetry_secret_token_123",
                    },
                },
                { domain: "*" },
            ],
        },
    },
});
console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-09-2026",
      "input": [{"type": "text", "text": "Use your filesystem tool to create /workspace/audit.log containing event 1, then immediately read it back using your filesystem read tool."}],
      "environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "inline",
                  "target": ".agents/hooks.json",
                  "content": "{\"audit-logging\": {\"post_tool_execution\": [{\"matcher\": \"view_file|write_to_file|replace_file_content\", \"hooks\": [{\"type\": \"http\", \"url\": \"https://telemetry.example.com/api/v1/agent-events\", \"timeout\": 10}]}]}}"
              }
          ],
          "network": {
              "allowlist": [
                  {
                      "domain": "telemetry.example.com",
                      "transform": {
                          "Authorization": "Bearer telemetry_secret_token_123"
                      }
                  },
                  {"domain": "*"}
              ]
          }
      }
  }'
```

{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;

Client client = new Client();

// Define hook without secrets; the egress proxy injects headers dynamically
String hooksConfig = """
{
  "audit-logging": {
    "post_tool_execution": [
      {
        "matcher": "read_file|write_file",
        "hooks": [
          {
            "type": "http",
            "url": "https://telemetry.example.com/api/v1/agent-events",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
""";

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.INLINE)
            .target(".agents/hooks.json")
            .content(hooksConfig)
            .build()
    ))
    .network(Network.of(
        EnvironmentNetworkEgressAllowlist.builder()
            .allowlist(Allowlist.of(List.of(
                AllowlistEntry.builder()
                    .domain("telemetry.example.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer telemetry_secret_token_123"
                    )))
                    .build(),
                AllowlistEntry.builder().domain("*").build()
            )))
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Use your filesystem tool to create `/workspace/audit.log` containing 'event 1', then immediately read it back using your filesystem read tool."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Define hook without secrets; the egress proxy injects headers dynamically
    hooksConfig := `{
  "audit-logging": {
    "post_tool_execution": [
      {
        "matcher": "read_file|write_file",
        "hooks": [
          {
            "type": "http",
            "url": "https://telemetry.example.com/api/v1/agent-events",
            "timeout": 10
          }
        ]
      }
    ]
  }
}`

    env := interactions.Environment{
        Sources: []interactions.Source{
            {
                Type:    interactions.SourceTypeInline.ToPointer(),
                Target:  genai.Ptr(".agents/hooks.json"),
                Content: genai.Ptr(hooksConfig),
            },
        },
        Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
            Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
                {
                    Domain: "telemetry.example.com",
                    Transform: genai.Ptr(interactions.NewTransform(map[string]string{
                        "Authorization": "Bearer telemetry_secret_token_123",
                    })),
                },
                {
                    Domain: "*",
                },
            })),
        })),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("antigravity-preview-09-2026"),
            Input:       interactions.NewInteractionsInput("Use your filesystem tool to create `/workspace/audit.log` containing 'event 1', then immediately read it back using your filesystem read tool."),
            Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}
## Limitations {% id="limitations" %}

* **Sandbox tool scope:** Hooks intercept built-in tools inside the sandbox: code execution (`code_execution`) and filesystem operations (`view_file`, `write_to_file`, `replace_file_content`, `list_dir`, and `delete_file`). They do not fire for custom function calling (`function`) or external Model Context Protocol (`mcp_server`) tools handled outside the container.
* **Network allowlists:** HTTP hooks run inside the container network. You must explicitly allow target URLs in your environment's `network.allowlist`. Loopback addresses (`localhost`, `127.0.0.1`) are blocked by the proxy.
* **Automatic approval on errors:** If a hook script crashes (non-zero exit status), times out, or fails, the runtime logs the failure and allows the tool call to continue. This ensures broken linter scripts or hanging processes never deadlock your applications.
* **Sandbox configuration protection:** Because hooks execute inside the container sandbox, agents with filesystem write tools or shell code execution permissions can modify local `.agents/hooks.json` or scripts within writable workspaces. Use container hooks as automated policy guidance and operational guardrails; if strict tamper resistance is required against untrusted model executions, mount configuration sources from read-only repositories.

## What's next {% id="whats-next" %}

- Learn how to configure persistent [remote sandboxes and environments](/docs/agent-environment).
- Explore the capabilities and built-in tools of the [Antigravity agent](/docs/antigravity-agent).
- Review the [Interactions API overview](/docs/interactions-overview) for multi-turn sessions and streaming.

# Gemini Deep Research agent
Source: https://aistudio.google.com/docs/deep-research
Description: Deep Research is an agent designed to perform complex, long-running context gathering and synthesis tasks.

{% callout type="note" %}
This feature is in [preview](/docs/models#preview). The Deep Research agent is exclusively available using the [Interactions API](/docs/interactions-overview). You cannot access it through `generate_content`.
{% /callout %}

The Gemini Deep Research agent autonomously plans, executes, and synthesizes
multi-step research tasks. Powered by Gemini, it navigates complex
information landscapes to produce detailed, cited reports. New
capabilities allow you to collaboratively plan with the agent, connect to
external tools using MCP servers, include
visualizations (like charts and graphs), and provide documents directly
as input.

Research tasks involve iterative searching and reading and can take several
minutes to complete. You must use background execution (set `background=true`)
to run the agent asynchronously and poll for results or stream updates. See
[Handling long running tasks](/docs/deep-research#long-running-tasks) for more details.

The following example shows how to start a research task in the background
and poll for results.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    input="Research the history of Google TPUs.",
    agent="deep-research-preview-04-2026",
    background=True,
)

print(f"Research started: {interaction.id}")

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.steps[-1].content[0].text)
        break
    elif interaction.status == "failed":
        print(f"Research failed: {interaction.error}")
        break
    time.sleep(10)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    input: 'Research the history of Google TPUs.',
    agent: 'deep-research-preview-04-2026',
    background: true
});

console.log(`Research started: ${interaction.id}`);

while (true) {
    const result = await client.interactions.get(interaction.id);
    if (result.status === 'completed') {
        console.log(result.output_text);
        break;
    } else if (result.status === 'failed') {
        console.log(`Research failed: ${JSON.stringify(result.errors)}`);
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 10000));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import java.util.Collections;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of("Research the history of Google TPUs."))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println("Research started: " + interaction.id().orElse(""));

while (true) {
  interaction =
      client.interactions
          .get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())
          .interaction()
          .get();
  if (InteractionStatus.COMPLETED.equals(interaction.status().orElse(null))) {
    System.out.println(interaction.outputText().orElse(""));
    break;
  } else if (InteractionStatus.FAILED.equals(interaction.status().orElse(null))) {
    System.out.println("Research failed: " + interaction.errors().orElse(Collections.emptyList()));
    break;
  }
  Thread.sleep(10000);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:      interactions.AgentOption("deep-research-preview-04-2026"),
            Input:      interactions.NewInteractionsInput("Research the history of Google TPUs."),
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    interaction := res.Interaction
    if interaction.ID != nil {
        fmt.Printf("Research started: %s\n", *interaction.ID)
    }

    for {
        getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        interaction = getRes.Interaction
        if interaction.Status == interactions.InteractionStatusCompleted {
            if interaction.OutputText != nil {
                fmt.Println(*interaction.OutputText)
            }
            break
        } else if interaction.Status == interactions.InteractionStatusFailed {
            fmt.Printf("Research failed: %v\n", interaction.Errors)
            break
        }
        time.Sleep(10 * time.Second)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# 1. Start the research task
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Research the history of Google TPUs.",
    "agent": "deep-research-preview-04-2026",
    "background": true
}'

# 2. Poll for results (Replace INTERACTION_ID)
# curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID" \
# -H "Api-Revision: 2026-05-20" \
# -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## Supported Versions {% id="supported-models" %}

The Deep Research agent comes in two versions:

* **Deep Research** (`deep-research-preview-04-2026`): Designed for speed and efficiency, ideal to be streamed back to a client UI.
* **Deep Research Max** (`deep-research-max-preview-04-2026`): Maximum comprehensiveness for automated context gathering and synthesis.

## Collaborative planning {% id="collaborative-planning" %}

{% callout type="note" %}
Preview: Collaborative planning allows you to review and refine the research
plan before execution.
{% /callout %}

Collaborative planning gives you control over the research direction
before the agent starts its work. When enabled, the agent returns a
proposed research plan instead of executing immediately. You can then
review, modify, or approve the plan through multi-turn interactions.

### Step 1: Request a plan {% id="step-1-request-a-plan" %}

Set `collaborative_planning=True` in the first interaction. The agent
returns a research plan instead of a full report.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

# First interaction: request a research plan
plan_interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Do some research on Google TPUs.",
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": True,
    },
    background=True,
)

# Wait for and retrieve the plan
while (result := client.interactions.get(id=plan_interaction.id)).status != "completed":
    time.sleep(5)
print(result.steps[-1].content[0].text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const planInteraction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Do some research on Google TPUs.',
    agent_config: {
        type: 'deep-research',
        thinking_summaries: 'auto',
        collaborative_planning: true
    },
    background: true
});

let result;
while ((result = await client.interactions.get(planInteraction.id)).status !== 'completed') {
    await new Promise(r => setTimeout(r, 5000));
}
console.log(result.steps.at(-1).content[0].text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;

Client client = new Client();

// First interaction: request a research plan
CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of("Do some research on Google TPUs."))
        .agentConfig(
            DeepResearchAgentConfig.builder()
                .thinkingSummaries(ThinkingSummaries.AUTO)
                .collaborativePlanning(true)
                .build())
        .background(true)
        .build();

Interaction planInteraction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

// Wait for and retrieve the plan
Interaction result;
while (true) {
  result =
      client.interactions
          .get(GetInteractionByIdRequest.builder().id(planInteraction.id().get()).build())
          .interaction()
          .get();
  if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {
    break;
  }
  Thread.sleep(5000);
}
System.out.println(result.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
        ThinkingSummaries:     interactions.ThinkingSummariesAuto.ToPointer(),
        CollaborativePlanning: genai.Ptr(true),
    })

    // First interaction: request a research plan
    planRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("deep-research-preview-04-2026"),
            Input:       interactions.NewInteractionsInput("Do some research on Google TPUs."),
            AgentConfig: &agentCfg,
            Background:  genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Wait for and retrieve the plan
    var result *interactions.Interaction
    for {
        getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *planRes.Interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        result = getRes.Interaction
        if result.Status == interactions.InteractionStatusCompleted {
            break
        }
        time.Sleep(5 * time.Second)
    }
    if result.OutputText != nil {
        fmt.Println(*result.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "deep-research-preview-04-2026",
    "input": "Do some research on Google TPUs.",
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": true
    },
    "background": true
}'
```
{% /tab %}
{% /tabs %}

### Step 2: Refine the plan (optional) {% id="step-2-refine-the-plan-optional" %}

Use `previous_interaction_id` to continue the conversation and iterate
on the plan. Keep `collaborative_planning=True` to stay in planning
mode.

{% tabs %}
{% tab label="Python" %}
```python
# Second interaction: refine the plan
refined_plan = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": True,
    },
    previous_interaction_id=plan_interaction.id,
    background=True,
)

while (result := client.interactions.get(id=refined_plan.id)).status != "completed":
    time.sleep(5)
print(result.steps[-1].content[0].text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const refinedPlan = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Focus more on the differences between Google TPUs and competitor hardware, and less on the history.',
    agent_config: {
        type: 'deep-research',
        thinking_summaries: 'auto',
        collaborative_planning: true
    },
    previous_interaction_id: planInteraction.id,
    background: true
});

let result;
while ((result = await client.interactions.get(refinedPlan.id)).status !== 'completed') {
    await new Promise(r => setTimeout(r, 5000));
}
console.log(result.steps.at(-1).content[0].text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;

Client client = new Client();
String planInteractionId = "PLAN_INTERACTION_ID";

// Second interaction: refine the plan
CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(
            InteractionsInput.of(
                "Focus more on the differences between Google TPUs and competitor hardware, and less on the history."))
        .agentConfig(
            DeepResearchAgentConfig.builder()
                .thinkingSummaries(ThinkingSummaries.AUTO)
                .collaborativePlanning(true)
                .build())
        .previousInteractionId(planInteractionId)
        .background(true)
        .build();

Interaction refinedPlan =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

Interaction result;
while (true) {
  result =
      client.interactions
          .get(GetInteractionByIdRequest.builder().id(refinedPlan.id().get()).build())
          .interaction()
          .get();
  if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {
    break;
  }
  Thread.sleep(5000);
}
System.out.println(result.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    planInteractionID := "PLAN_INTERACTION_ID"
    agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
        ThinkingSummaries:     interactions.ThinkingSummariesAuto.ToPointer(),
        CollaborativePlanning: genai.Ptr(true),
    })

    // Second interaction: refine the plan
    refinedRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:                 interactions.AgentOption("deep-research-preview-04-2026"),
            Input:                 interactions.NewInteractionsInput("Focus more on the differences between Google TPUs and competitor hardware, and less on the history."),
            AgentConfig:           &agentCfg,
            PreviousInteractionID: genai.Ptr(planInteractionID),
            Background:            genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    var result *interactions.Interaction
    for {
        getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *refinedRes.Interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        result = getRes.Interaction
        if result.Status == interactions.InteractionStatusCompleted {
            break
        }
        time.Sleep(5 * time.Second)
    }
    if result.OutputText != nil {
        fmt.Println(*result.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "deep-research-preview-04-2026",
    "input": "Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": true
    },
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "background": true
}'
```
{% /tab %}
{% /tabs %}

### Step 3: Approve and execute {% id="step-3-approve-and-execute" %}

Set `collaborative_planning=False` (or omit it) to approve the plan and
start the research.

{% tabs %}
{% tab label="Python" %}
```python
# Third interaction: approve the plan and kick off research
final_report = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Plan looks good!",
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": False,
    },
    previous_interaction_id=refined_plan.id,
    background=True,
)

while (result := client.interactions.get(id=final_report.id)).status != "completed":
    time.sleep(5)
print(result.steps[-1].content[0].text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const finalReport = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Plan looks good!',
    agent_config: {
        type: 'deep-research',
        thinking_summaries: 'auto',
        collaborative_planning: false
    },
    previous_interaction_id: refinedPlan.id,
    background: true
});

let result;
while ((result = await client.interactions.get(finalReport.id)).status !== 'completed') {
    await new Promise(r => setTimeout(r, 5000));
}
console.log(result.steps.at(-1).content[0].text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;

Client client = new Client();
String refinedPlanId = "REFINED_PLAN_ID";

// Third interaction: approve the plan and kick off research
CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of("Plan looks good!"))
        .agentConfig(
            DeepResearchAgentConfig.builder()
                .thinkingSummaries(ThinkingSummaries.AUTO)
                .collaborativePlanning(false)
                .build())
        .previousInteractionId(refinedPlanId)
        .background(true)
        .build();

Interaction finalReport =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

Interaction result;
while (true) {
  result =
      client.interactions
          .get(GetInteractionByIdRequest.builder().id(finalReport.id().get()).build())
          .interaction()
          .get();
  if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {
    break;
  }
  Thread.sleep(5000);
}
System.out.println(result.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    refinedPlanID := "REFINED_PLAN_ID"
    agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
        ThinkingSummaries:     interactions.ThinkingSummariesAuto.ToPointer(),
        CollaborativePlanning: genai.Ptr(false),
    })

    // Third interaction: approve the plan and kick off research
    finalRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:                 interactions.AgentOption("deep-research-preview-04-2026"),
            Input:                 interactions.NewInteractionsInput("Plan looks good!"),
            AgentConfig:           &agentCfg,
            PreviousInteractionID: genai.Ptr(refinedPlanID),
            Background:            genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    var result *interactions.Interaction
    for {
        getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *finalRes.Interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        result = getRes.Interaction
        if result.Status == interactions.InteractionStatusCompleted {
            break
        }
        time.Sleep(5 * time.Second)
    }
    if result.OutputText != nil {
        fmt.Println(*result.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "deep-research-preview-04-2026",
    "input": "Plan looks good!",
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": false
    },
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "background": true
}'
```
{% /tab %}
{% /tabs %}

## Visualization {% id="visualization" %}

{% callout type="note" %}
Preview: Visualization allows the agent to generate charts and graphs to support
its findings.
{% /callout %}

When `visualization` is set to `"auto"`, the agent can generate charts,
graphs, and other visual elements to support its research findings.
Generated images are included in the response steps and streamed as
`image` deltas. For best results, explicitly ask for visuals in your
query - for example, "Include charts showing trends over time" or
"Generate graphics comparing market share." Setting `visualization` to
`"auto"` enables the capability, but the agent generates visuals only
when the prompt requests them.

{% tabs %}
{% tab label="Python" %}
```python
import base64

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Analyze global semiconductor market trends. Include graphics showing market share changes.",
    agent_config={
        "type": "deep-research",
        "visualization": "auto",
    },
    background=True,
)

print(f"Research started: {interaction.id}")

while (result := client.interactions.get(id=interaction.id)).status != "completed":
    time.sleep(5)

for step in result.steps:
    if step.type == "model_output":
        for content_item in step.content:
            if content_item.type == "text":
                print(content_item.text)
            elif content_item.type == "image" and content_item.data:
                image_bytes = base64.b64decode(content_item.data)
                print(f"Received image: {len(image_bytes)} bytes")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Analyze global semiconductor market trends. Include graphics showing market share changes.',
    agent_config: {
        type: 'deep-research',
        visualization: 'auto'
    },
    background: true
});

console.log(`Research started: ${interaction.id}`);

let result;
while ((result = await client.interactions.get(interaction.id)).status !== 'completed') {
    await new Promise(r => setTimeout(r, 5000));
}

for (const step of result.steps) {
    if (step.type === 'model_output') {
        for (const contentItem of step.content || []) {
            if (contentItem.type === 'text') {
                console.log(contentItem.text);
            } else if (contentItem.type === 'image' && contentItem.data) {
                console.log(`[Image Output: ${contentItem.data.substring(0, 20)}...]`);
            }
        }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.Visualization;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import java.util.Base64;
import java.util.Collections;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(
            InteractionsInput.of(
                "Analyze global semiconductor market trends. Include graphics showing market share changes."))
        .agentConfig(DeepResearchAgentConfig.builder().visualization(Visualization.AUTO).build())
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println("Research started: " + interaction.id().orElse(""));

Interaction result;
while (true) {
  result =
      client.interactions
          .get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())
          .interaction()
          .get();
  if (InteractionStatus.COMPLETED.equals(result.status().orElse(null))) {
    break;
  }
  Thread.sleep(5000);
}

for (Step step : result.steps().orElse(Collections.emptyList())) {
  if (step instanceof ModelOutputStep) {
    for (Content contentItem : ((ModelOutputStep) step).content().orElse(Collections.emptyList())) {
      if (contentItem instanceof TextContent) {
        System.out.println(((TextContent) contentItem).text().orElse(""));
      } else if (contentItem instanceof ImageContent) {
        ImageContent img = (ImageContent) contentItem;
        if (img.data().isPresent()) {
          byte[] imageBytes = Base64.getDecoder().decode(img.data().get());
          System.out.println("Received image: " + imageBytes.length + " bytes");
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
        Visualization: interactions.VisualizationAuto.ToPointer(),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("deep-research-preview-04-2026"),
            Input:       interactions.NewInteractionsInput("Analyze global semiconductor market trends. Include graphics showing market share changes."),
            AgentConfig: &agentCfg,
            Background:  genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.ID != nil {
        fmt.Printf("Research started: %s\n", *res.Interaction.ID)
    }

    var result *interactions.Interaction
    for {
        getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *res.Interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        result = getRes.Interaction
        if result.Status == interactions.InteractionStatusCompleted {
            break
        }
        time.Sleep(5 * time.Second)
    }

    for _, step := range result.Steps {
        if outStep := step.ModelOutputStep; outStep != nil {
            for _, contentItem := range outStep.Content {
                if textContent := contentItem.TextContent; textContent != nil {
                    fmt.Println(textContent.GetText())
                } else if imgContent := contentItem.ImageContent; imgContent != nil && imgContent.Data != nil {
                    imageBytes, err := base64.StdEncoding.DecodeString(*imgContent.Data)
                    if err == nil {
                        fmt.Printf("Received image: %d bytes\n", len(imageBytes))
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "deep-research-preview-04-2026",
    "input": "Analyze global semiconductor market trends. Include graphics showing market share changes.",
    "agent_config": {
        "type": "deep-research",
        "visualization": "auto"
    },
    "background": true
}'
```
{% /tab %}
{% /tabs %}

## Supported tools {% id="supported-tools" %}

Deep Research supports multiple built-in and external tools. By default
(when no `tools` parameter is provided), the agent has access to Google
Search, URL Context, and Code Execution. You can explicitly
specify tools to restrict or extend the agent's capabilities.

| Tool | Type value | Description |
| :--- | :--- | :--- |
| Google Search | `google_search` | Search the public web. Enabled by default. |
| URL Context | `url_context` | Read and summarize web page content. Enabled by default. |
| Code Execution | `code_execution` | Execute code to perform calculations and data analysis. Enabled by default. |
| MCP Server | `mcp_server` | Connect to remote MCP servers for external tool access. |
| File Search | `file_search` | Search your uploaded document corpora. |

### Google Search {% id="google-search" %}

Explicitly enable Google Search as the only tool:

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="What are the latest developments in quantum computing?",
    tools=[{"type": "google_search"}],
    background=True,
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'What are the latest developments in quantum computing?',
    tools: [{ type: 'google_search' }],
    background: true
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of("What are the latest developments in quantum computing?"))
        .tools(Arrays.asList(GoogleSearch.builder().build()))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("deep-research-preview-04-2026"),
            Input: interactions.NewInteractionsInput("What are the latest developments in quantum computing?"),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.GoogleSearch{}),
            },
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "deep-research-preview-04-2026",
    "input": "What are the latest developments in quantum computing?",
    "tools": [{"type": "google_search"}],
    "background": true
}'
```
{% /tab %}
{% /tabs %}

### URL Context {% id="url-context" %}

Give the agent the ability to read and summarize specific web pages:

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Summarize the content of https://www.wikipedia.org/.",
    tools=[{"type": "url_context"}],
    background=True,
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Summarize the content of https://www.wikipedia.org/.',
    tools: [{ type: 'url_context' }],
    background: true
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.URLContext;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of("Summarize the content of https://www.wikipedia.org/."))
        .tools(Arrays.asList(URLContext.builder().build()))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("deep-research-preview-04-2026"),
            Input: interactions.NewInteractionsInput("Summarize the content of https://www.wikipedia.org/."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.URLContext{}),
            },
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "deep-research-preview-04-2026",
    "input": "Summarize the content of https://www.wikipedia.org/.",
    "tools": [{"type": "url_context"}],
    "background": true
}'
```
{% /tab %}
{% /tabs %}

### Code Execution {% id="code-execution" %}

Allow the agent to execute code for calculations and data analysis:

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Calculate the 50th Fibonacci number.",
    tools=[{"type": "code_execution"}],
    background=True,
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Calculate the 50th Fibonacci number.',
    tools: [{ type: 'code_execution' }],
    background: true
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of("Calculate the 50th Fibonacci number."))
        .tools(Arrays.asList(CodeExecution.builder().build()))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("deep-research-preview-04-2026"),
            Input: interactions.NewInteractionsInput("Calculate the 50th Fibonacci number."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.CodeExecution{}),
            },
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Calculate the 50th Fibonacci number.",
    "agent": "deep-research-preview-04-2026",
    "tools": [{"type": "code_execution"}],
    "background": true
}'
```
{% /tab %}
{% /tabs %}

### MCP servers {% id="mcp-servers" %}

{% callout type="note" %}
Preview: Connect to remote MCP servers to give the agent access to external
tools and services.
{% /callout %}

Provide the server `name` and `url` in the tools configuration. You can also
pass authentication credentials and restrict which tools the agent can call.

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `type` | `string` | Yes | Must be `"mcp_server"`. |
| `name` | `string` | No | A display name for the MCP server. |
| `url` | `string` | No | The full URL for the MCP server endpoint. |
| `headers` | `object` | No | Key-value pairs sent as HTTP headers with every request to the server (for example, authentication tokens). |
| `allowed_tools` | `array` | No | Restrict which tools from the server the agent may call. |

#### Basic usage {% id="mcp-basic" %}

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Check the status of my last server deployment.",
    tools=[
        {
            "type": "mcp_server",
            "name": "Deployment Tracker",
            "url": "https://mcp.example.com/mcp",
            "headers": {"Authorization": "Bearer my-token"},
        }
    ],
    background=True,
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Check the status of my last server deployment.',
    tools: [
        {
            type: 'mcp_server',
            name: 'Deployment Tracker',
            url: 'https://mcp.example.com/mcp',
            headers: { Authorization: 'Bearer my-token' }
        }
    ],
    background: true
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.MCPServer;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of("Check the status of my last server deployment."))
        .tools(
            Arrays.asList(
                MCPServer.builder()
                    .name("Deployment Tracker")
                    .url("https://mcp.example.com/mcp")
                    .headers(Collections.singletonMap("Authorization", "Bearer my-token"))
                    .build()))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("deep-research-preview-04-2026"),
            Input: interactions.NewInteractionsInput("Check the status of my last server deployment."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.MCPServer{
                    Name: genai.Ptr("Deployment Tracker"),
                    URL:  genai.Ptr("https://mcp.example.com/mcp"),
                    Headers: map[string]string{
                        "Authorization": "Bearer my-token",
                    },
                }),
            },
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "deep-research-preview-04-2026",
    "input": "Check the status of my last server deployment.",
    "tools": [
        {
            "type": "mcp_server",
            "name": "Deployment Tracker",
            "url": "https://mcp.example.com/mcp",
            "headers": {"Authorization": "Bearer my-token"}
        }
    ],
    "background": true
}'
```
{% /tab %}
{% /tabs %}

### File Search {% id="file-search" %}

Give the agent access to your own data by using the [File Search](/docs/file-search) tool.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    input="Compare our 2025 fiscal year report against current public web news.",
    agent="deep-research-preview-04-2026",
    background=True,
    tools=[
        {
            "type": "file_search",
            "file_search_store_names": ['fileSearchStores/my-store-name']
        }
    ]
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    input: 'Compare our 2025 fiscal year report against current public web news.',
    agent: 'deep-research-preview-04-2026',
    background: true,
    tools: [
        { type: 'file_search', file_search_store_names: ['fileSearchStores/my-store-name'] },
    ]
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(
            InteractionsInput.of(
                "Compare our 2025 fiscal year report against current public web news."))
        .tools(
            Arrays.asList(
                FileSearch.builder()
                    .fileSearchStoreNames(Arrays.asList("fileSearchStores/my-store-name"))
                    .build()))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("deep-research-preview-04-2026"),
            Input: interactions.NewInteractionsInput("Compare our 2025 fiscal year report against current public web news."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.FileSearch{
                    FileSearchStoreNames: []string{"fileSearchStores/my-store-name"},
                }),
            },
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Compare our 2025 fiscal year report against current public web news.",
    "agent": "deep-research-preview-04-2026",
    "background": true,
    "tools": [
        {"type": "file_search", "file_search_store_names": ["fileSearchStores/my-store-name"]},
    ]
}'
```
{% /tab %}
{% /tabs %}

## Steerability and formatting {% id="steerability-and-formatting" %}

You can steer the agent's output by providing specific formatting instructions
in your prompt. This allows you to structure reports into specific sections and
subsections, include data tables, or adjust tone for different audiences (e.g.,
"technical," "executive," "casual").

Define the desired output format explicitly in your input text.

{% tabs %}
{% tab label="Python" %}
```python
prompt = """
Research the competitive landscape of EV batteries.

Format the output as a technical report with the following structure:

1. Executive Summary
2. Key Players (Must include a data table comparing capacity and chemistry)
3. Supply Chain Risks
"""

interaction = client.interactions.create(
    input=prompt,
    agent="deep-research-preview-04-2026",
    background=True
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const prompt = `
Research the competitive landscape of EV batteries.

Format the output as a technical report with the following structure:

1. Executive Summary
2. Key Players (Must include a data table comparing capacity and chemistry)
3. Supply Chain Risks
`;

const interaction = await client.interactions.create({
    input: prompt,
    agent: 'deep-research-preview-04-2026',
    background: true,
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

String prompt =
    "Research the competitive landscape of EV batteries.\n\n"
        + "Format the output as a technical report with the following structure:\n"
        + "1. Executive Summary\n"
        + "2. Key Players (Must include a data table comparing capacity and chemistry)\n"
        + "3. Supply Chain Risks";

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of(prompt))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Research the competitive landscape of EV batteries.\n\n" +
        "Format the output as a technical report with the following structure:\n" +
        "1. Executive Summary\n" +
        "2. Key Players (Must include a data table comparing capacity and chemistry)\n" +
        "3. Supply Chain Risks"

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:      interactions.AgentOption("deep-research-preview-04-2026"),
            Input:      interactions.NewInteractionsInput(prompt),
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Research the competitive landscape of EV batteries.\n\nFormat the output as a technical report with the following structure: \n1. Executive Summary\n2. Key Players (Must include a data table comparing capacity and chemistry)\n3. Supply Chain Risks",
    "agent": "deep-research-preview-04-2026",
    "background": true
}'
```
{% /tab %}
{% /tabs %}

## Multimodal inputs {% id="multimodal-inputs" %}

Deep Research supports multimodal inputs, including images and documents (PDFs),
allowing the agent to analyze visual content and conduct web-based research
contextualized by the provided inputs.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

prompt = """Analyze the interspecies dynamics and behavioral risks present
in the provided image of the African watering hole. Specifically, investigate
the symbiotic relationship between the avian species and the pachyderms
shown, and conduct a risk assessment for the reticulated giraffes based on
their drinking posture relative to the specific predator visible in the
foreground."""

interaction = client.interactions.create(
    input=[
        {"type": "text", "text": prompt},
        {
            "type": "image",
            "mime_type": "image/jpeg",
            "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"
        }
    ],
    agent="deep-research-preview-04-2026",
    background=True
)

print(f"Research started: {interaction.id}")

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.steps[-1].content[0].text)
        break
    elif interaction.status == "failed":
        print(f"Research failed: {interaction.error}")
        break
    time.sleep(10)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const prompt = `Analyze the interspecies dynamics and behavioral risks present
in the provided image of the African watering hole. Specifically, investigate
the symbiotic relationship between the avian species and the pachyderms
shown, and conduct a risk assessment for the reticulated giraffes based on
their drinking posture relative to the specific predator visible in the
foreground.`;

const interaction = await client.interactions.create({
    input: [
        { type: 'text', text: prompt },
        {
            type: 'image',
            mime_type: "image/jpeg",
            uri: 'https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg'
        }
    ],
    agent: 'deep-research-preview-04-2026',
    background: true
});

console.log(`Research started: ${interaction.id}`);

while (true) {
    const result = await client.interactions.get(interaction.id);
    if (result.status === 'completed') {
        console.log(result.output_text);
        break;
    } else if (result.status === 'failed') {
        console.log(`Research failed: ${JSON.stringify(result.errors)}`);
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 10000));
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import java.util.Arrays;
import java.util.Collections;

Client client = new Client();

String prompt =
    "Analyze the interspecies dynamics and behavioral risks present "
        + "in the provided image of the African watering hole. Specifically, investigate "
        + "the symbiotic relationship between the avian species and the pachyderms "
        + "shown, and conduct a risk assessment for the reticulated giraffes based on "
        + "their drinking posture relative to the specific predator visible in the "
        + "foreground.";

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    TextContent.builder().text(prompt).build(),
                    ImageContent.builder()
                        .mimeType(ImageContentMimeType.IMAGE_JPEG)
                        .uri(
                            "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg")
                        .build())))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println("Research started: " + interaction.id().orElse(""));

while (true) {
  interaction =
      client.interactions
          .get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())
          .interaction()
          .get();
  if (InteractionStatus.COMPLETED.equals(interaction.status().orElse(null))) {
    System.out.println(interaction.outputText().orElse(""));
    break;
  } else if (InteractionStatus.FAILED.equals(interaction.status().orElse(null))) {
    System.out.println("Research failed: " + interaction.errors().orElse(Collections.emptyList()));
    break;
  }
  Thread.sleep(10000);
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Analyze the interspecies dynamics and behavioral risks present " +
        "in the provided image of the African watering hole. Specifically, investigate " +
        "the symbiotic relationship between the avian species and the pachyderms " +
        "shown, and conduct a risk assessment for the reticulated giraffes based on " +
        "their drinking posture relative to the specific predator visible in the " +
        "foreground."

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("deep-research-preview-04-2026"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{Text: prompt}),
                interactions.NewContent(interactions.ImageContent{
                    MimeType: interactions.ImageContentMimeType("image/jpeg").ToPointer(),
                    URI:      genai.Ptr("https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"),
                }),
            }),
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    interaction := res.Interaction
    if interaction.ID != nil {
        fmt.Printf("Research started: %s\n", *interaction.ID)
    }

    for {
        getRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        interaction = getRes.Interaction
        if interaction.Status == interactions.InteractionStatusCompleted {
            if interaction.OutputText != nil {
                fmt.Println(*interaction.OutputText)
            }
            break
        } else if interaction.Status == interactions.InteractionStatusFailed {
            fmt.Printf("Research failed: %v\n", interaction.Errors)
            break
        }
        time.Sleep(10 * time.Second)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# 1. Start the research task with image input
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": [
        {"type": "text", "text": "Analyze the interspecies dynamics and behavioral risks present in the provided image of the African watering hole. Specifically, investigate the symbiotic relationship between the avian species and the pachyderms shown, and conduct a risk assessment for the reticulated giraffes based on their drinking posture relative to the specific predator visible in the foreground."},
        {"type": "image", "mime_type": "image/jpeg", "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"}
    ],
    "agent": "deep-research-preview-04-2026",
    "background": true
}'

# 2. Poll for results (Replace INTERACTION_ID)
# curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID" \
# -H "Api-Revision: 2026-05-20" \
# -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

### Document understanding {% id="document-understanding" %}

{% callout type="note" %}
Preview: Document understanding allows passing documents directly as multimodal
input.
{% /callout %}

Pass documents directly as multimodal input. The agent analyzes the
provided documents and conducts research grounded in their content.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input=[
        {"type": "text", "text": "What is this document about?"},
        {
            "type": "document",
            "uri": "https://arxiv.org/pdf/1706.03762",
            "mime_type": "application/pdf",
        },
    ],
    background=True,
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: [
        { type: 'text', text: 'What is this document about?' },
        {
            type: 'document',
            uri: 'https://arxiv.org/pdf/1706.03762',
            mime_type: 'application/pdf'
        }
    ],
    background: true
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    TextContent.builder().text("What is this document about?").build(),
                    DocumentContent.builder()
                        .uri("https://arxiv.org/pdf/1706.03762")
                        .mimeType(DocumentContentMimeType.APPLICATION_PDF)
                        .build())))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent: interactions.AgentOption("deep-research-preview-04-2026"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{Text: "What is this document about?"}),
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr("https://arxiv.org/pdf/1706.03762"),
                    MimeType: interactions.DocumentContentMimeType("application/pdf").ToPointer(),
                }),
            }),
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# 1. Start the research task with document input
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "deep-research-preview-04-2026",
    "input": [
        {"type": "text", "text": "What is this document about?"},
        {"type": "document", "uri": "https://arxiv.org/pdf/1706.03762", "mime_type": "application/pdf"}
    ],
    "background": true
}'
```
{% /tab %}
{% /tabs %}

## Handling long-running tasks {% id="long-running-tasks" %}

Deep Research is a multi-step process involving planning, searching, reading,
and writing. This cycle typically exceeds the standard timeout limits of
synchronous API calls.

Agents are required to use `background=True`. The API returns a partial
`Interaction` object immediately. You can use the `id` property to retrieve an
interaction for polling. The interaction state will transition from
`in_progress` to `completed` or `failed`.

### Streaming {% id="streaming" %}

Deep Research supports streaming to receive real-time updates on the research
progress including thought summaries, text output, and generated images.
You must set `stream=True` and `background=True`.

To receive intermediate reasoning steps (thoughts) and progress updates,
you must enable **thinking summaries** by setting `thinking_summaries` to
`"auto"` in the `agent_config`. Without this, the stream may only provide the
final results.

{% callout type="note" %}
Note: The streaming connection can drop or expire. Since Deep Research tasks can
run longer, your application should check the interaction status and reconnect
as shown in the examples below.
{% /callout %}

#### Stream event types {% id="stream-event-types" %}

| Event type | Delta type | Description |
| :--- | :--- | :--- |
| `step.delta` | `thought` | Intermediate reasoning step from the agent. |
| `step.delta` | `text` | Part of the final text output. |
| `step.delta` | `image` | A generated image (base64-encoded). |

The following example starts a research task and processes the stream with
automatic reconnection. It tracks the `interaction_id` and `last_event_id` so
that if the connection drops (for example, after the 600-second timeout), it can
resume from where it left off.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction_id = None
last_event_id = None
is_complete = False

def process_stream(stream):
    global interaction_id, last_event_id, is_complete
    for event in stream:
        if event.event_type == "interaction.created":
            interaction_id = event.interaction.id
        if event.event_id:
            last_event_id = event.event_id
        if event.event_type == "step.delta":
            if event.delta.type == "text":
                print(event.delta.text, end="", flush=True)
            elif event.delta.type == "thought":
                print(f"Thought: {event.delta.text}", flush=True)
        elif event.event_type in ("interaction.completed", "interaction.error"):
            is_complete = True

stream = client.interactions.create(
    input="Research the history of Google TPUs.",
    agent="deep-research-preview-04-2026",
    background=True,
    stream=True,
    agent_config={"type": "deep-research", "thinking_summaries": "auto"},
)
process_stream(stream)

# Reconnect if the connection drops
while not is_complete and interaction_id:
    status = client.interactions.get(interaction_id)
    if status.status != "in_progress":
        break
    stream = client.interactions.get(
        id=interaction_id, stream=True, last_event_id=last_event_id,
    )
    process_stream(stream)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

let interactionId;
let lastEventId;
let isComplete = false;

const initialStream = await client.interactions.create({
    input: 'Research the history of Google TPUs.',
    agent: 'deep-research-preview-04-2026',
    background: true,
    stream: true,
    agent_config: { type: 'deep-research', thinking_summaries: 'auto' },
});

async function processStream(stream = initialStream) {
    for await (const event of stream) {
        if (event.event_type === 'interaction.created') {
            interactionId = event.interaction.id;
        }
        if (event.event_id) lastEventId = event.event_id;
        if (event.event_type === 'step.delta') {
            if (event.delta.type === 'text') {
                process.stdout.write(event.delta.text || '');
            } else if (event.delta.type === 'thought_summary') {
                if (event.delta.content?.type === 'text') {
                    console.log(`Thought: ${event.delta.content.text}`);
                }
            }
        } else if (['interaction.completed', 'interaction.error'].includes(event.event_type)) {
            isComplete = true;
        }
    }
}

await processStream(initialStream);

// Reconnect if the connection drops
while (!isComplete && interactionId) {
    const status = await client.interactions.get(interactionId);
    if (status.status !== 'in_progress') break;
    const resumeStream = await client.interactions.get(interactionId, {
        stream: true, last_event_id: lastEventId,
    });
    await processStream(resumeStream);
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.ErrorEvent;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionCompletedEvent;
import com.google.genai.gaos.models.interactions.InteractionCreatedEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.interactions.ThoughtSummaryDelta;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import com.google.genai.gaos.utils.EventStream;

class StreamProcessor {
  String interactionId = null;
  String lastEventId = null;
  boolean isComplete = false;

  void processStream(EventStream<InteractionSSEStreamEvent> stream) {
    for (InteractionSSEStreamEvent streamEvent : stream) {
      InteractionSSEEvent event = streamEvent.data().orElse(null);
      if (event instanceof InteractionCreatedEvent) {
        InteractionCreatedEvent created = (InteractionCreatedEvent) event;
        interactionId = created.interaction().flatMap(i -> i.id()).orElse(null);
        if (created.eventId().isPresent()) {
          lastEventId = created.eventId().get();
        }
      } else if (event instanceof StepDelta) {
        StepDelta stepDelta = (StepDelta) event;
        if (stepDelta.eventId().isPresent()) {
          lastEventId = stepDelta.eventId().get();
        }
        if (stepDelta.delta().isPresent()) {
          if (stepDelta.delta().get() instanceof TextDelta) {
            System.out.print(((TextDelta) stepDelta.delta().get()).text().orElse(""));
            System.out.flush();
          } else if (stepDelta.delta().get() instanceof ThoughtSummaryDelta) {
            ThoughtSummaryDelta thought = (ThoughtSummaryDelta) stepDelta.delta().get();
            Content content = thought.content().orElse(null);
            if (content instanceof TextContent) {
              System.out.println("Thought: " + ((TextContent) content).text().orElse(""));
            }
          }
        }
      } else if (event instanceof InteractionCompletedEvent || event instanceof ErrorEvent) {
        isComplete = true;
      }
    }
  }
}

Client client = new Client();
StreamProcessor processor = new StreamProcessor();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of("Research the history of Google TPUs."))
        .background(true)
        .stream(true)
        .agentConfig(
            DeepResearchAgentConfig.builder().thinkingSummaries(ThinkingSummaries.AUTO).build())
        .build();

try (EventStream<InteractionSSEStreamEvent> stream =
    client.interactions.create(CreateInteractionRequestBody.of(params)).events()) {
  processor.processStream(stream);
}

// Reconnect if the connection drops
while (!processor.isComplete && processor.interactionId != null) {
  Interaction status =
      client.interactions
          .get(GetInteractionByIdRequest.builder().id(processor.interactionId).build())
          .interaction()
          .get();
  if (!InteractionStatus.IN_PROGRESS.equals(status.status().orElse(null))) {
    break;
  }
  try (EventStream<InteractionSSEStreamEvent> stream =
      client.interactions
          .get(
              GetInteractionByIdRequest.builder()
                  .id(processor.interactionId)
                  .stream(true)
                  .lastEventId(processor.lastEventId)
                  .build())
          .events()) {
    processor.processStream(stream);
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
    "google.golang.org/genai/interactions/types/stream"
)

type StreamProcessor struct {
    interactionID string
    lastEventID   *string
    isComplete    bool
}

func (p *StreamProcessor) processStream(s *stream.EventStream[interactions.InteractionSSEStreamEvent]) {
    defer s.Close()
    for s.Next() {
        event := s.Value()
        if created := event.GetDataInteractionCreated(); created != nil {
            p.interactionID = created.Interaction.ID
            if created.EventID != nil {
                p.lastEventID = created.EventID
            }
        } else if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if stepDelta.EventID != nil {
                p.lastEventID = stepDelta.EventID
            }
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            } else if thoughtDelta := stepDelta.GetDeltaThoughtSummary(); thoughtDelta != nil {
                if textContent := thoughtDelta.GetContentText(); textContent != nil {
                    fmt.Printf("Thought: %s\n", textContent.GetText())
                }
            }
        } else if event.GetDataInteractionCompleted() != nil || event.GetDataError() != nil {
            p.isComplete = true
        }
    }
}

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    processor := &StreamProcessor{}
    agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
        ThinkingSummaries: interactions.ThinkingSummariesAuto.ToPointer(),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("deep-research-preview-04-2026"),
            Input:       interactions.NewInteractionsInput("Research the history of Google TPUs."),
            Background:  genai.Ptr(true),
            Stream:      genai.Ptr(true),
            AgentConfig: &agentCfg,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    processor.processStream(res.InteractionSSEStreamEvent)

    // Reconnect if the connection drops
    for !processor.isComplete && processor.interactionID != "" {
        statusRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: processor.interactionID,
        })
        if err != nil || statusRes.Interaction.Status != interactions.InteractionStatusInProgress {
            break
        }
        streamRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID:          processor.interactionID,
            Stream:      genai.Ptr(true),
            LastEventID: processor.lastEventID,
        })
        if err != nil {
            break
        }
        processor.processStream(streamRes.InteractionSSEStreamEvent)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# 1. Start the stream (save the INTERACTION_ID from the interaction.start event
# and the last "event_id" you receive)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Research the history of Google TPUs.",
    "agent": "deep-research-preview-04-2026",
    "background": true,
    "stream": true,
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto"
    }
}'

# 2. If the connection drops, reconnect with your saved IDs
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID?stream=true&last_event_id=LAST_EVENT_ID" \
-H "Api-Revision: 2026-05-20" \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## Follow-up questions and interactions {% id="follow-up-questions-and-interactions" %}

You can continue the conversation after the agent returns the final report by
using the `previous_interaction_id`. This lets you to ask for clarification,
summarization or elaboration on specific sections of the research without
restarting the entire task.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    input="Can you elaborate on the second point in the report?",
    model="gemini-4-argon",
    previous_interaction_id="COMPLETED_INTERACTION_ID"
)

print(interaction.steps[-1].content[0].text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    input: 'Can you elaborate on the second point in the report?',
    model: 'gemini-4-argon',
    previous_interaction_id: 'COMPLETED_INTERACTION_ID'
});
console.log(interaction.steps.at(-1).content[0].text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-4-argon")
        .input(InteractionsInput.of("Can you elaborate on the second point in the report?"))
        .previousInteractionId("COMPLETED_INTERACTION_ID")
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-4-argon"),
            Input:                 interactions.NewInteractionsInput("Can you elaborate on the second point in the report?"),
            PreviousInteractionID: genai.Ptr("COMPLETED_INTERACTION_ID"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Can you elaborate on the second point in the report?",
    "model": "gemini-4-argon",
    "previous_interaction_id": "COMPLETED_INTERACTION_ID"
}'
```
{% /tab %}
{% /tabs %}

## When to use Gemini Deep Research agent {% id="when-to-use-deep-research" %}

Deep Research is an **agent**, not just a model. It is best suited for workloads
that require an "analyst-in-a-box" approach rather than low-latency chat.

| Feature | Standard Gemini Models | Gemini Deep Research agent |
| :---- | :---- | :---- |
| **Latency** | Seconds | Minutes (Async/Background) |
| **Process** | Generate \-\> Output | Plan \-\> Search \-\> Read \-\> Iterate \-\> Output |
| **Output** | Conversational text, code, short summaries | Detailed reports, long-form analysis, comparative tables |
| **Best For** | Chatbots, extraction, creative writing | Market analysis, due diligence, literature reviews, competitive landscaping |

## Agent configuration {% id="agent-configuration" %}

Deep Research uses the `agent_config` parameter to control behavior.
Pass it as a dictionary with the following fields:

| Field | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `type` | `string` | Required | Must be `"deep-research"`. |
| `thinking_summaries` | `string` | `"none"` | Set to `"auto"` to receive intermediate reasoning steps during streaming. Set to `"none"` to disable. |
| `visualization` | `string` | `"auto"` | Set to `"auto"` to enable agent-generated charts and images. Set to `"off"` to disable. |
| `collaborative_planning` | `boolean` | `false` | Set to `true` to enable multi-turn plan review before research begins. |

{% tabs %}
{% tab label="Python" %}
```python
agent_config = {
    "type": "deep-research",
    "thinking_summaries": "auto",
    "visualization": "auto",
    "collaborative_planning": False,
}

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Research the competitive landscape of cloud GPUs.",
    agent_config=agent_config,
    background=True,
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Research the competitive landscape of cloud GPUs.',
    agent_config: {
        type: 'deep-research',
        thinking_summaries: 'auto',
        visualization: 'auto',
        collaborative_planning: false,
    },
    background: true,
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.interactions.Visualization;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

DeepResearchAgentConfig agentConfig =
    DeepResearchAgentConfig.builder()
        .thinkingSummaries(ThinkingSummaries.AUTO)
        .visualization(Visualization.AUTO)
        .collaborativePlanning(false)
        .build();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of("Research the competitive landscape of cloud GPUs."))
        .agentConfig(agentConfig)
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    agentCfg := interactions.NewCreateAgentInteractionAgentConfig(interactions.DeepResearchAgentConfig{
        ThinkingSummaries:     interactions.ThinkingSummariesAuto.ToPointer(),
        Visualization:         interactions.VisualizationAuto.ToPointer(),
        CollaborativePlanning: genai.Ptr(false),
    })

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
            Agent:       interactions.AgentOption("deep-research-preview-04-2026"),
            Input:       interactions.NewInteractionsInput("Research the competitive landscape of cloud GPUs."),
            AgentConfig: &agentCfg,
            Background:  genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Api-Revision: 2026-05-20" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Research the competitive landscape of cloud GPUs.",
    "agent": "deep-research-preview-04-2026",
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto",
        "visualization": "auto",
        "collaborative_planning": false
    },
    "background": true
}'
```
{% /tab %}
{% /tabs %}

## Availability and pricing {% id="availability-and-pricing" %}

You can access the Gemini Deep Research agent using the Interactions API in
Google AI Studio and the Gemini API.

Pricing follows a [pay-as-you-go model](/docs/pricing#pricing-for-agents) based
on the underlying Gemini models and the specific tools the agent utilizes.
Unlike standard chat requests, where a request leads to one output, a Deep
Research task is an agentic workflow. A single request triggers an autonomous
loop of planning, searching, reading, and reasoning.

### Estimated costs {% id="estimated-costs" %}

Costs vary based on the depth of research required. The agent autonomously
determines how much reading and searching is necessary to answer your prompt.

* **Deep Research** (`deep-research-preview-04-2026`): For a typical query
  requiring moderate analysis, the agent might use ~80 search queries, ~250k
  input tokens (~50-70% cached), and ~60k output tokens.
    * **Estimated total:** ~$1.00 - $3.00 per task
* **Deep Research Max** (`deep-research-max-preview-04-2026`): For deep
  competitive landscape analysis or extensive due diligence, the agent might use
  up to ~160 search queries, ~900k input tokens (~50-70% cached), and ~80k
  output tokens.
    * **Estimated total:** ~$3.00 - $7.00 per task

{% callout type="note" %}
Note: These figures are estimates based on preview rates and are subject to
change.
{% /callout %}

## Safety considerations {% id="safety-considerations" %}

Giving an agent access to the web and your private files requires careful
consideration of safety risks.

* **Prompt injection using files:** The agent reads the contents of the files
    you provide. Ensure that uploaded documents (PDFs, text files) come from
    trusted sources. A malicious file could contain hidden text designed to
    manipulate the agent's output.

* **Web content risks:** The agent searches the public web. While we implement
    robust safety filters, there is a risk that the agent may encounter and
    process malicious web pages. We recommend reviewing the `citations` provided
    in the response to verify the sources.

* **Exfiltration:** Be cautious when asking the agent to summarize sensitive
    internal data if you are also allowing it to browse the web.

## Best practices {% id="best-practices" %}

* **Prompt for unknowns:** Instruct the agent on how to handle missing data.
    For example, add *"If specific figures for 2025 are not available,
    explicitly state they are projections or unavailable rather than
    estimating"* to your prompt.

* **Provide context:** Ground the agent's research by providing background
    information or constraints directly in the input prompt.

* **Use collaborative planning:** For complex queries, enable collaborative
    planning to review and refine the research plan before execution.

* **Multimodal inputs:** Deep Research agent supports multi-modal inputs.
    Use cautiously, as this increases costs and risks context window overflow.

## Limitations {% id="limitations" %}

* **Custom tools:** You cannot currently provide custom Function Calling tools
    but you can use remote MCP (Model Context Protocol) servers with the Deep
    Research agent.

* **Structured output:** The Deep Research agent currently
    doesn't support structured outputs.

* **Max research time:** The Deep Research agent has a maximum research time
    of 60 minutes. Most tasks should complete within 20 minutes.

* **Store requirement:** Agent execution using `background=True` requires
    `store=True`.

* **Google search:** [Google
    Search](/docs/google-search) is enabled by
    default and [specific
    restrictions](/docs/terms#use-restrictions2)
    apply to the grounded results.

## What's next {% id="whats-next" %}

* Learn more about the [Interactions API](/docs/interactions-overview).
* Learn how to use your own data using the [File Search](/docs/file-search)
    tool.

# Using tools with Gemini API
Source: https://aistudio.google.com/docs/tools
Description: Use tools with the Gemini API to extend the capabilities of Gemini models, enabling them to access real-time information and perform complex computational tasks.

Tools extend the capabilities of Gemini models, enabling them to take action in
the world, access real-time information, and perform complex computational
tasks. Models can use tools in both standard request-response interactions and
real-time streaming sessions using the [Live API](/docs/live-api/tools).

Tools are specific capabilities (like Google Search or Code Execution) that a
model can use to answer queries. The Gemini API provides a suite of fully
managed, built-in tools, or you can define custom tools using [Function
Calling](/docs/function-calling).

To build multi-step, goal-oriented systems, see the [Agents
Overview](/docs/agents).

## Available built-in tools {% id="build-in-tools" %}

{% table %}
* Tool
* Description
* Use Cases
---
* [Google Search](/docs/google-search)
* Ground responses in current events and facts from the web to reduce hallucinations.
*
  Answering questions about recent events, verifying facts with diverse sources.
---
* [Google Maps](/docs/maps-grounding)
* Build location-aware assistants that can find places, get directions, and provide rich local context.
*
  Planning travel itineraries with multiple stops, finding local businesses based on user criteria.
---
* [Code Execution](/docs/code-execution)
* Allow the model to write and run Python code to solve math problems or process data accurately.
*
  Solving complex mathematical equations, processing and analyzing text data precisely.
---
* [URL Context](/docs/url-context)
* Direct the model to read and analyze content from specific web pages or documents.
*
  Answering questions based on specific URLs or documents, retrieving information across different web pages.
---
* [Computer Use](/docs/computer-use)
* Enable Gemini to view a screen and generate actions to interact with web browser UIs (Client-side execution).
*
  Automating repetitive web-based workflows, testing web application user interfaces.
---
* [File Search](/docs/file-search)
* Index and search your own documents to enable Retrieval Augmented Generation (RAG).
*
  Searching technical manuals, question answering over proprietary data.
{% /table %}

See the [Pricing page](/docs/pricing#pricing-for-tools) for details
on costs associated with specific tools.

## How tools execution works {% id="how-tools-execution-works" %}

Tools allow the model to request actions during a conversation. The flow differs
depending on whether the tool is built-in (managed by Google) or custom (managed
by you).

### Built-in tool flow {% id="built-in-tool-flow" %}

For built-in tools (Google Search, Google Maps, URL Context, File Search,
Code Execution), the entire process happens within one API call:

1. **You** send a prompt: "What is the square root of the latest stock price of
    GOOG?"

2. **Gemini** decides it needs tools and executes them on Google's servers
    (e.g., searches for the stock price, then runs Python code to calculate the
    square root).

3. **Gemini** sends back the final answer grounded in the tool results.

### Custom tool flow (Function calling) {% id="custom-tool-flow-function-calling" %}

For custom tools and Computer Use, your application handles the execution:

1. **You** send a prompt along with functions (tools) declarations.
2. **Gemini** might send back structured JSON to call a specific function
    (for example, `{"name": "get_order_status", "args": {"order_id": "123"}}`),
    always with a unique `id`.

3. **You** execute the function in your application or environment.
4. **You** send the function results, with the same `id` as the function call,
    back to Gemini.

5. **Gemini** uses the results to generate a final response or another tool
    call.

{% callout type="note" %}
Preview: For those building with a mix of bash and custom tools, Gemini 3.1 Pro
Preview comes with a separate endpoint available via the API called
[`gemini-3.1-pro-preview-customtools`](/docs/models/gemini-3.1-pro-preview#gemini-31-pro-preview-customtools).
{% /callout %}

Learn more in the [Function calling guide](/docs/function-calling).

### Combining built-in and custom tools flow {% id="combining-built-in-and-custom-tools-flow" %}

{% callout type="note" %}
Preview: Gemini 4 and Gemini 3 series models support the option to combine built-in tools
with custom tools in a single turn.
{% /callout %}

For requests that combine built-in tools and custom tools (function calls), the
model uses [tool context circulation](/docs/tool-combination) to
coordinate execution across different environments:

1. **You** send a prompt and declare the built-in tools and custom functions you
   want to enable, setting a flag to turn on combination support.

2. **Gemini** executes built-in tools and yields to the user if any
   client-side function calls are generated (which executes first depends on the
   prompt and what the model decides). It sends back a response with:

      * Confirmation of the tool call
      * Results of the tool response (this may come after the JSON if the model
        generated two parallel function calls)

      * Structured JSON to call your function
      * Encrypted thought signatures to preserve context
3. **You** execute the function in your application or environment.
4. **You** return all parts of Gemini's response, plus your function call
   results.

5. **Gemini** generates the final response using all combined context.

Read the [Tool combination guide](/docs/tool-combination) to learn
how to turn on support for built-in and custom tools combination and examples of
context circulation.

## Structured outputs vs. function calling {% id="structured-outputs-vs-function-calling" %}

Gemini offers two methods for generating structured outputs. Use [Function
calling](/docs/function-calling) when the model needs to perform an
intermediate step by connecting to your own tools or data systems. Use
[Structured Outputs](/docs/structured-output) when you strictly need
the model's final response to adhere to a specific schema, such as for rendering
a custom UI.

## Structured outputs with tools {% id="structured-outputs" %}

{% callout type="note" %}
Preview: This feature is available only to Gemini 4 and Gemini 3 series models.
{% /callout %}

You can combine [Structured Outputs](/docs/structured-output) with
built-in tools to ensure that model responses grounded in external data or
computation still adhere to a strict schema.

See [Structured outputs with tools](/docs/structured-output?example=recipe#tools)
for code examples.

# Grounding with Google Search
Source: https://aistudio.google.com/docs/google-search
Description: Ground your model's responses in real-time information from Google Search to improve factual accuracy and provide citations.

Grounding with Google Search connects the Gemini model to real-time web content
and works with all available languages. This allows
Gemini to provide more accurate answers and cite verifiable sources beyond its
knowledge cutoff.

Grounding helps you build applications that can:

* **Increase factual accuracy:** Reduce model hallucinations by basing
    responses on real-world information.

* **Access real-time information:** Answer questions about recent events and
    topics.

* **Provide citations:** Build user trust by showing the sources for the
    model's claims.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Who won the euro 2024?",
    tools=[{"type": "google_search"}]
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Who won the euro 2024?",
    tools: [{ type: "google_search" }]
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Who won the euro 2024?"))
        .tools(Arrays.asList(GoogleSearch.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Who won the euro 2024?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleSearch{}),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Who won the euro 2024?",
    "tools": [{"type": "google_search"}]
  }'
```
{% /tab %}
{% /tabs %}

## How grounding with Google Search works {% id="how-it-works" %}

When you enable the `google_search` tool, the model handles the entire workflow
of searching, processing, and citing information automatically.

![grounding-overview](/googledevai/static/gemini-api/docs/images/google-search-tool-overview.png)

1. **User Prompt:** Your application sends a user's prompt to the Gemini API
    with the `google_search` tool enabled.

2. **Prompt Analysis:** The model analyzes the prompt and determines if a
    Google Search can improve the answer.

3. **Google Search:** If needed, the model automatically generates one or
    multiple search queries and executes them.

4. **Search Results Processing:** The model processes the search results,
    synthesizes the information, and formulates a response.

5. **Grounded Response:** The API returns a final, user-friendly response that
    is grounded in the search results. This response includes the model's text
    answer with inline `annotations` containing the citations, as well as
    `google_search_call` and `google_search_result` steps with the search
    queries and search suggestions.

## Understanding the grounding response {% id="understanding-the-grounding-response" %}

When a response is successfully grounded, the model's text output includes
inline `annotations` directly on the text content block. These annotations
provide citation information linking parts of the response to their sources.

```json
{
  "steps": [
    {
      "type": "thought",
      "summary": [
        {
          "type": "text",
          "text": "The user is asking for the winner of Euro 2024. I need to search for the result of the Euro 2024 final."
        }
      ],
      "signature": "CoMDAXLI2nynRYojJIy6B1Jh9os2crpWLfB0..."
    },
    {
      "type": "google_search_call",
      "arguments": {
        "queries": ["UEFA Euro 2024 winner"]
      }
    },
    {
      "type": "google_search_result",
      "call_id": "search_001",
      "result": [
        {
          "search_suggestions": ""
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.aljazeera.com/sports/euro-2024-final",
              "title": "aljazeera.com",
              "start_index": 0,
              "end_index": 56
            },
            {
              "type": "url_citation",
              "url": "https://www.uefa.com/euro2024/news/spain-wins-euro-2024",
              "title": "uefa.com",
              "start_index": 57,
              "end_index": 124
            }
          ]
        }
      ]
    }
  ]
}
```

The key fields in the response:

* `google_search_call` : Contains the search `queries` the model executed.
* `google_search_result` : Contains `search_suggestions`, an HTML snippet
    for rendering search suggestions in your UI. Full usage requirements are
    detailed in the [Terms of Service](/docs/terms#grounding-with-google-search).

* `text` with `annotations` : The model's synthesized answer with inline
    citations. Each `url_citation` annotation links a text segment (defined
    by `start_index` and `end_index`) to a source URL. This is the key to
    building inline citations.

Grounding with Google Search can also be used in combination with the [URL
context tool](/docs/url-context) to ground responses in
both public web data and the specific URLs you provide.

## Attributing sources with inline citations {% id="attributing-sources-with-inline-citations" %}

The API returns inline `url_citation` annotations on the text content block,
giving you complete control over how you display sources in your user interface.
Each annotation includes `start_index` and `end_index` to identify which part
of the text it cites. Here's how to extract and display them.

{% tabs %}
{% tab label="Python" %}
```python
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nCitations:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            cited_text = content_block.text[annotation.start_index:annotation.end_index]
                            print(f" [{annotation.title}]({annotation.url})")
                            print(f" Cited text: \"{cited_text}\"")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const contentBlock of step.content || []) {
      if (contentBlock.type === 'text') {
        console.log(contentBlock.text);
        if (contentBlock.annotations) {
          console.log("\nCitations:");
          for (const annotation of contentBlock.annotations) {
            if (annotation.type === 'url_citation') {
              const citedText = contentBlock.text.slice(annotation.startIndex, annotation.endIndex);
              console.log(` [${annotation.title}](${annotation.url})`);
              console.log(` Cited text: "${citedText}"`);
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.URLCitation;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Who won the euro 2024?"))
        .tools(Arrays.asList(GoogleSearch.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            String text = textContent.text().orElse("");
            System.out.println(text);
            if (textContent.annotations().isPresent()
                && !textContent.annotations().get().isEmpty()) {
              System.out.println("\nCitations:");
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof URLCitation) {
                  URLCitation citation = (URLCitation) annotation;
                  int start = citation.startIndex().orElse(0);
                  int end = citation.endIndex().orElse(0);
                  String citedText =
                      (start >= 0 && end <= text.length() && start <= end)
                          ? text.substring(start, end)
                          : "";
                  System.out.printf(
                      "  [%s](%s)%n", citation.title().orElse(""), citation.url().orElse(""));
                  System.out.printf("    Cited text: \"%s\"%n", citedText);
                }
              }
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Who won the euro 2024?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleSearch{}),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    text := content.TextContent.Text
                    fmt.Println(text)
                    if len(content.TextContent.Annotations) > 0 {
                        fmt.Println("\nCitations:")
                        for _, annotation := range content.TextContent.Annotations {
                            if annotation.URLCitation != nil {
                                c := annotation.URLCitation
                                start := 0
                                if c.StartIndex != nil {
                                    start = *c.StartIndex
                                }
                                end := 0
                                if c.EndIndex != nil {
                                    end = *c.EndIndex
                                }
                                citedText := ""
                                if start >= 0 && end <= len(text) && start <= end {
                                    citedText = text[start:end]
                                }
                                title := ""
                                if c.Title != nil {
                                    title = *c.Title
                                }
                                url := ""
                                if c.URL != nil {
                                    url = *c.URL
                                }
                                fmt.Printf("  [%s](%s)\n", title, url)
                                fmt.Printf("    Cited text: %q\n", citedText)
                            }
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% /tabs %}

The output will show the text followed by its citations:

```none
Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.

Citations:
  [aljazeera.com](https://www.aljazeera.com/sports/euro-2024-final)
    Cited text: "Spain won Euro 2024, defeating England 2-1 in the final."
  [uefa.com](https://www.uefa.com/euro2024/news/spain-wins-euro-2024)
    Cited text: "This victory marks Spain's record fourth European Championship title."
```

## Pricing {% id="pricing" %}

When you use Grounding with Google Search with Gemini 3 and newer models, your
project is billed for **each** search query that the model decides to execute.
This per-query billing model includes 5,000 free search requests per month
shared across all Gemini 3 and newer models, and then costs **$14 per 1,000
search requests**.

For example, if the model decides to execute multiple search queries to answer
a single prompt (e.g. searching for `"UEFA Euro 2024 winner"` and `"Spain vs
England Euro 2024 final score"` within the same API call), this counts as two
billable uses of the tool for that request. For billing purposes, we ignore
empty web search queries when counting unique queries.

When you use search grounding with Gemini 2.5 or older models, your project is
billed per prompt.

For detailed pricing information, see the [Gemini API pricing
page](/docs/pricing).

{% callout type="note" %}
**Note:** Grounding with Google Search has a default limit of **1,500 requests
per day (RPD)** per project on Gemini 3 and newer models in the Paid Tier of the
Gemini Developer API. If your application requires a higher daily limit, submit
a request in [Google AI Studio](https://aistudio.google.com/rate-limit) (select
**Request more quota** next to the `generate_content_search_request_paid` limit).
{% /callout %}

## Supported models {% id="supported-models" %}

You can find full capabilities on the [model
overview](https://ai.google.dev/docs/models) page.

| Model | Grounding with Google Search |
| ------------------ | :--------------------------: |
| Gemini 4 Argon | ✔️ |
| Gemini 3.8 Flash | ✔️ |
| Gemini 3.6 Flash | ✔️ |
| Gemini 3.5 Flash-Lite | ✔️ |
| Gemini 3.1 Flash Image Preview | ✔️ |
| Gemini 3.1 Pro Preview | ✔️ |
| Gemini 3 Pro Image Preview | ✔️ |
| Gemini 3 Flash Preview | ✔️ |
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
| Gemini 2.0 Flash | ✔️ |

{% callout type="note" %}
Older models use a `google_search_retrieval` tool. For all current models,
use the `google_search` tool as shown in the examples.
{% /callout %}

## Supported tool combinations {% id="tool-combination" %}

You can use Grounding with Google Search with other tools like
[code execution](/docs/code-execution),
[URL context](/docs/url-context), and
[Grounding with Google Maps](/docs/maps-grounding) (supported on Gemini 3.5
Flash and later models) to power more complex use cases. Gemini 3 models also
support combining these built-in tools with custom tools (function calling).
Learn more on the [tool combinations](/docs/tool-combination) page.

## What's next {% id="whats-next" %}

* Learn about other available tools, like [Function Calling](/docs/function-calling).
* Learn how to augment prompts with specific URLs using the [URL context tool](/docs/url-context).

# Grounding with Google Maps
Source: https://aistudio.google.com/docs/maps-grounding
Description: Ground your model's responses in rich, real-world data from Google Maps to provide factually accurate, location-aware answers

Grounding with Google Maps connects the generative capabilities of Gemini with
the rich, factual, and up-to-date data of Google Maps. This feature enables
developers to easily incorporate location-aware functionality into their
applications. When a user query has a context related to Maps data, the Gemini
model leverages Google Maps to provide factually accurate and fresh answers that
are relevant to the user's specified location or general area.

* **Accurate, location-aware responses:** Leverage Google Maps' extensive and
    current data for geographically specific queries.

* **Enhanced personalization:** Tailor recommendations and information based
    on user-provided locations.

## Get started {% id="get-started" %}

This example demonstrates how to integrate Grounding with Google Maps into your
application to provide accurate, location-aware responses to user queries. The
prompt asks for local recommendations with an optional user location, enabling
the Gemini model to use Google Maps data.

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What are the best Italian restaurants within a 15-minute walk from here?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

# Print the model's text response and annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f" - {annotation.name}: {annotation.url}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What are the best Italian restaurants within a 15-minute walk from here?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  // Print the model's text response and annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(` - {annotation.name}: {annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.PlaceCitation;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "What are the best Italian restaurants within a 15-minute walk from here?"))
        .tools(
            Arrays.asList(
                GoogleMaps.builder().latitude(34.050481).longitude(-118.248526).build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

// Print the model's text response and annotations
if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            System.out.println(textContent.text().orElse(""));
            if (textContent.annotations().isPresent()
                && !textContent.annotations().get().isEmpty()) {
              System.out.println("\nSources:");
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof PlaceCitation) {
                  PlaceCitation citation = (PlaceCitation) annotation;
                  System.out.printf(
                      "  - %s: %s%n", citation.name().orElse(""), citation.url().orElse(""));
                }
              }
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("What are the best Italian restaurants within a 15-minute walk from here?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleMaps{
                        Latitude:  genai.Ptr(34.050481),
                        Longitude: genai.Ptr(-118.248526),
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Print the model's text response and annotations
    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    fmt.Println(content.TextContent.Text)
                    if len(content.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range content.TextContent.Annotations {
                            if annotation.PlaceCitation != nil {
                                c := annotation.PlaceCitation
                                name := ""
                                if c.Name != nil {
                                    name = *c.Name
                                }
                                url := ""
                                if c.URL != nil {
                                    url = *c.URL
                                }
                                fmt.Printf("  - %s: %s\n", name, url)
                            }
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What are the best Italian restaurants within a 15-minute walk from here?",
    "tools": [{
      "type": "google_maps",
      "latitude": 34.050481,
      "longitude": -118.248526
    }]
  }'
```
{% /tab %}
{% /tabs %}

## How Grounding with Google Maps works {% id="how-it-works" %}

Grounding with Google Maps integrates the Gemini API with the Google Geo
ecosystem by using the Maps API as a grounding source. When a user's query
contains geographical context, the Gemini model can invoke the Grounding with
Google Maps tool. The model can then generate responses grounded in Google Maps
data relevant to the provided location.

The process typically involves:

1. **User query:** A user submits a query to your application, potentially
    including geographical context (e.g., "coffee shops near me," "museums in
    San Francisco").

2. **Tool invocation:** The Gemini model, recognizing the geographical intent,
    invokes the Grounding with Google Maps tool. This tool can optionally be
    provided with the user's `latitude` and `longitude`. The tool is a textual
    search tool and behaves similarly to searching on Maps, in that local
    queries ("near me") will use the coordinates, while specific or non-local
    queries are unlikely to be influenced by the explicit location.

3. **Data retrieval:** The Grounding with Google Maps service queries Google
    Maps for relevant information (e.g., places, reviews, photos, addresses,
    opening hours).

4. **Grounded generation:** The retrieved Maps data is used to inform the
    Gemini model's response, ensuring factual accuracy and relevance.

5. **Response & annotations:** The model returns a text response with inline
    annotations linking to Google Maps sources, allowing developers to
    display citations.

## Why and when to use Grounding with Google Maps {% id="why-use" %}

Grounding with Google Maps is ideal for applications that require accurate,
up-to-date, and location-specific information. It enhances the user experience
by providing relevant and personalized content backed by Google Maps' extensive
database of over 250 million places worldwide.

You should use Grounding with Google Maps when your application needs to:

* Provide complete and accurate responses to geo-specific questions.
* Build conversational trip planners and local guides.
* Recommend points of interest based on
    location and user preferences like restaurants or shops.

* Create location-aware experiences for social, retail, or food delivery
    services.

Grounding with Google Maps excels in use cases where proximity and current
factual data are critical, such as finding the "best coffee shop near me" or
getting directions.

## Use cases {% id="use-cases" %}

Grounding with Google Maps supports a variety of location-aware use cases.

### Handling place-specific questions {% id="place-specific" %}

Ask detailed questions about a specific place to get answers based on Google
user reviews and other Maps data.

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f" - {annotation.name}: {annotation.url}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(` - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.PlaceCitation;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Is there a cafe near the corner of 1st and Main that has outdoor seating?"))
        .tools(
            Arrays.asList(
                GoogleMaps.builder().latitude(34.050481).longitude(-118.248526).build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            System.out.println(textContent.text().orElse(""));
            if (textContent.annotations().isPresent()
                && !textContent.annotations().get().isEmpty()) {
              System.out.println("\nSources:");
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof PlaceCitation) {
                  PlaceCitation citation = (PlaceCitation) annotation;
                  System.out.printf(
                      "  - %s: %s%n", citation.name().orElse(""), citation.url().orElse(""));
                }
              }
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Is there a cafe near the corner of 1st and Main that has outdoor seating?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleMaps{
                        Latitude:  genai.Ptr(34.050481),
                        Longitude: genai.Ptr(-118.248526),
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    fmt.Println(content.TextContent.Text)
                    if len(content.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range content.TextContent.Annotations {
                            if annotation.PlaceCitation != nil {
                                c := annotation.PlaceCitation
                                name := ""
                                if c.Name != nil {
                                    name = *c.Name
                                }
                                url := ""
                                if c.URL != nil {
                                    url = *c.URL
                                }
                                fmt.Printf("  - %s: %s\n", name, url)
                            }
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% /tabs %}

### Providing location-based personalization {% id="location-personalization" %}

Get recommendations tailored to a user's preferences and a specific geographical
area.

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Which family-friendly restaurants near here have the best playground reviews?",
    tools=[{
        "type": "google_maps",
        "latitude": 30.2672,
        "longitude": -97.7431
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f" - {annotation.name}: {annotation.url}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Which family-friendly restaurants near here have the best playground reviews?",
    tools: [{
      type: "google_maps",
      latitude: 30.2672,
      longitude: -97.7431
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(` - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.PlaceCitation;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Which family-friendly restaurants near here have the best playground reviews?"))
        .tools(
            Arrays.asList(GoogleMaps.builder().latitude(30.2672).longitude(-97.7431).build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            System.out.println(textContent.text().orElse(""));
            if (textContent.annotations().isPresent()
                && !textContent.annotations().get().isEmpty()) {
              System.out.println("\nSources:");
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof PlaceCitation) {
                  PlaceCitation citation = (PlaceCitation) annotation;
                  System.out.printf(
                      "  - %s: %s%n", citation.name().orElse(""), citation.url().orElse(""));
                }
              }
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Which family-friendly restaurants near here have the best playground reviews?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleMaps{
                        Latitude:  genai.Ptr(30.2672),
                        Longitude: genai.Ptr(-97.7431),
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    fmt.Println(content.TextContent.Text)
                    if len(content.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range content.TextContent.Annotations {
                            if annotation.PlaceCitation != nil {
                                c := annotation.PlaceCitation
                                name := ""
                                if c.Name != nil {
                                    name = *c.Name
                                }
                                url := ""
                                if c.URL != nil {
                                    url = *c.URL
                                }
                                fmt.Printf("  - %s: %s\n", name, url)
                            }
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% /tabs %}

### Assisting with itinerary planning {% id="itinerary-planning" %}

Generate multi-day plans with directions and information about various
locations, perfect for travel applications.

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476
    }]
)
# ... code to process response
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.",
    tools: [{
      type: "google_maps",
      latitude: 37.78193,
      longitude: -122.40476
    }]
  });
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

String prompt =
    "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.";

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of(prompt))
        .tools(
            Arrays.asList(GoogleMaps.builder().latitude(37.78193).longitude(-122.40476).build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

// ... code to process response
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput(prompt),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleMaps{
                        Latitude:  genai.Ptr(37.78193),
                        Longitude: genai.Ptr(-122.40476),
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    // ... code to process response
    fmt.Println(resp.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab label="REST" %}
```shell
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.",
    "tools": [{
      "type": "google_maps",
      "latitude": 37.78193,
      "longitude": -122.40476
    }]
  }'
```
{% /tab %}
{% /tabs %}

## Service usage requirements {% id="service-usage-requirements" %}

This section describes the service usage requirements for Grounding with Google
Maps.

### Inform the user about the use of Google Maps sources {% id="inform-sources" %}

With each Google Maps Grounded result, you'll receive source annotations on
the `model_output` step's content blocks that support each response. The
following metadata is returned:

* source url
* name

When presenting results from Grounding with Google Maps, you must specify the
associated Google Maps sources, and inform your users of the following:

* The Google Maps sources must immediately follow the generated content that
    the sources support. This generated content is also referred to as Google
    Maps Grounded Result.

* The Google Maps sources must be viewable within one user interaction.

### Display Google Maps sources with Google Maps links {% id="display-sources" %}

For each source annotation, a link preview must
be generated following these requirements:

* Attribute each source to Google Maps following the Google Maps text
    [attribution guidelines](/docs/maps-grounding#maps-attribution-guidelines).

* Display the source name provided in the response.
* Link to the source using the `url` from the annotation.

### Google Maps text attribution guidelines {% id="maps-attribution-guidelines" %}

When you attribute sources to Google Maps in text, follow these guidelines:

* Don't modify the text Google Maps in any way:
    * Don't change the capitalization of Google Maps.
    * Don't wrap Google Maps onto multiple lines.
    * Don't localize Google Maps into another language.
    * Prevent browsers from translating Google Maps by using the HTML
        attribute translate="no".

For more information about some of our Google Maps data providers and their
license terms, see the [Google Maps and Google Earth legal notices](https://www.google.com/help/legalnotices_maps/).

## Best practices {% id="best-practices" %}

* **Provide user location:** For the most relevant and personalized responses,
    always include the `latitude` and `longitude` in your `google_maps` tool
    configuration when the user's location is known.

* **Inform End-Users:** Clearly inform your end-users that Google Maps
    data is being used to answer their queries, especially when the tool is
    enabled.

* **Toggle Off When Not Needed:** Grounding with Google Maps is off by
    default. Only enable it (`"tools": [{"type": "google_maps"}]`) when a query
    has a clear geographical context, to optimize performance and cost.

## Limitations {% id="limitations" %}

* Grounding with Google Maps currently only supports English language prompts
    and responses.

* The tool may not be available in all regions.
* Results may vary based on location accuracy and available Maps data.
* **Geographical Scope:** Grounding with Google Maps is globally available.
* **Default State:** The Grounding with Google Maps tool is off by default.
    You must explicitly enable it in your API requests.

## Pricing and rate limits {% id="pricing-and-rate-limits" %}

Grounding with Google Maps pricing differs depending on the model generation:

*   **Gemini 3 and newer models:** Your project is billed for each search query
    that the model decides to execute, with 5,000 free requests per month shared
    across all Gemini 3 and newer models, and then **$14 per 1,000 search
    queries**. A single search prompt (your API request to the model) might
    result in the model executing multiple search queries to find the necessary
    information. Each of these queries counts as a billable use of the tool.
*   **Gemini 2.5 and older models:** Your project is billed per search prompt
    ($25 per 1,000 grounded prompts). A request is only billed if the prompt
    successfully returns at least one Google Maps grounded result, regardless of
    how many individual search queries the model performed internally to get
    that result.

The quota for Grounding with Google Maps typically aligns with the underlying
Gemini model rate limits. For detailed pricing information, see the [Gemini API
pricing page](/docs/pricing).

## Supported models {% id="supported-models" %}

The following models support Grounding with Google Maps:

| Model | Grounding with Google Maps |
| ------------------ | :--------------------------: |
| [Gemini 4 Argon](/docs/models/gemini-4-argon) | ✔️ |
| [Gemini 3.8 Flash](/docs/models/gemini-3.8-flash) | ✔️ |
| [Gemini 3.6 Flash](/docs/models/gemini-3.6-flash) | ✔️ |
| [Gemini 3.5 Flash-Lite](/docs/models/gemini-3.5-flash-lite) | ✔️ |
| [Gemini 3.1 Pro Preview](/docs/models/gemini-3.1-pro-preview) | ✔️ |
| [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite) | ✔️ |
| [Gemini 3 Flash Preview](/docs/models/gemini-3-flash-preview) | ✔️ |
| [Gemini 2.5 Pro](/docs/models/gemini-2.5-pro) | ✔️ |
| [Gemini 2.5 Flash](/docs/models/gemini-2.5-flash) | ✔️ |
| [Gemini 2.5 Flash-Lite](/docs/models/gemini-2.5-flash-lite) | ✔️ |

## Supported tool combinations {% id="tool-combination" %}

You can use Grounding with Google Maps with other built-in tools like
[Grounding with Google Search](/docs/google-search) (supported on Gemini 3.5
Flash and later models) to power more complex use cases. Gemini 3 models also
support combining these built-in tools with custom tools (function calling).
Learn more on the [tool combinations](/docs/tool-combination) page.

## What's next {% id="whats-next" %}

* Learn about other [available tools](/docs/tools).
* To learn more about responsible AI best practices and Gemini API's safety
    filters, see [the Safety settings guide](/docs/safety-settings).

# Code execution
Source: https://aistudio.google.com/docs/code-execution
Description: Learn how to use the Gemini API code execution feature.

The Gemini API provides a code execution tool that enables the model to
generate and run Python code. The model can then learn iteratively from the
code execution results until it arrives at a final output. You can use code
execution to build applications that benefit from code-based reasoning. For
example, you can use code execution to solve equations or process text. You can
also use the [libraries](/docs/code-execution#supported-libraries) included in the code execution
environment to perform more specialized tasks.

Gemini is only able to execute code in Python. You can still ask Gemini to
generate code in another language, but the model can't use the code execution
tool to run it.

## Enable code execution {% id="enable-code-execution" %}

To enable code execution, configure the code execution tool on the model. This
allows the model to generate and run code.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the sum of the first 50 prime numbers? "
          "Generate and run code for the calculation, and make sure you get all 50.",
    tools=[{"type": "code_execution"}]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
    elif step.type == "code_execution_call":
        print(step.arguments.code)
    elif step.type == "code_execution_result":
        print(step.result)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the sum of the first 50 prime numbers? " +
           "Generate and run code for the calculation, and make sure you get all 50.",
    tools: [{ type: "code_execution" }]
});

for (const step of interaction.steps) {
    if (step.type === "model_output") {
        for (const contentBlock of step.content || []) {
            if (contentBlock.type === "text") {
                console.log(contentBlock.text);
            }
        }
    } else if (step.type === "code_execution_call") {
        console.log(step.arguments.code);
    } else if (step.type === "code_execution_result") {
        console.log(step.result);
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;
import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(
            InteractionsInput.of(
                "What is the sum of the first 50 prime numbers? "
                    + "Generate and run code for the calculation, and make sure you get all 50."))
        .tools(Arrays.asList(CodeExecution.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

for (Step step : interaction.steps().orElse(Collections.emptyList())) {
  if (step instanceof ModelOutputStep) {
    ModelOutputStep outputStep = (ModelOutputStep) step;
    for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {
      if (contentBlock instanceof TextContent) {
        System.out.println(((TextContent) contentBlock).text().orElse(""));
      }
    }
  } else if (step instanceof CodeExecutionCallStep) {
    CodeExecutionCallStep callStep = (CodeExecutionCallStep) step;
    callStep.arguments().ifPresent(args -> System.out.println(args.code().orElse("")));
  } else if (step instanceof CodeExecutionResultStep) {
    CodeExecutionResultStep resultStep = (CodeExecutionResultStep) step;
    System.out.println(resultStep.result().orElse(""));
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(
                "What is the sum of the first 50 prime numbers? " +
                    "Generate and run code for the calculation, and make sure you get all 50.",
            ),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.CodeExecution{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if outStep := step.ModelOutputStep; outStep != nil {
            for _, contentBlock := range outStep.Content {
                if textContent := contentBlock.TextContent; textContent != nil {
                    fmt.Println(textContent.GetText())
                }
            }
        } else if callStep := step.CodeExecutionCallStep; callStep != nil {
            if code := callStep.Arguments.GetCode(); code != nil {
                fmt.Println(*code)
            }
        } else if resultStep := step.CodeExecutionResultStep; resultStep != nil {
            fmt.Println(resultStep.GetResult())
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
    "model": "gemini-3.8-flash",
    "input": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50.",
    "tools": [{"type": "code_execution"}]
}'
```
{% /tab %}
{% /tabs %}

The output might look something like the following, which has been formatted for
readability:

```none
Okay, I need to calculate the sum of the first 50 prime numbers. Here's how I'll
approach this:

1. **Generate Prime Numbers:** I'll use an iterative method to find prime
    numbers. I'll start with 2 and check if each subsequent number is divisible
    by any number between 2 and its square root. If not, it's a prime.

2. **Store Primes:** I'll store the prime numbers in a list until I have 50 of
    them.

3. **Calculate the Sum:** Finally, I'll sum the prime numbers in the list.

Here's the Python code to do this:

def is_prime(n):
  """Efficiently checks if a number is prime."""
  if n <= 1:
    return False
  if n <= 3:
    return True
  if n % 2 == 0 or n % 3 == 0:
    return False
  i = 5
  while i * i <= n:
    if n % i == 0 or n % (i + 2) == 0:
      return False
    i += 6
  return True

primes = []
num = 2
while len(primes) < 50:
  if is_prime(num):
    primes.append(num)
  num += 1

sum_of_primes = sum(primes)
print(f'{primes=}')
print(f'{sum_of_primes=}')

primes=[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67,
71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151,
157, 163, 167, 173, 179, 181, 191, 193, 197, 199, 211, 223, 227, 229]
sum_of_primes=5117

The sum of the first 50 prime numbers is 5117.
```

This output combines several content parts that the model returns when using
code execution:

* `text`: Inline text generated by the model
* `code_execution_call`: Code generated by the model that is meant to be executed
* `code_execution_result`: Result of the executable code

## Code Execution with images (Gemini 3) {% id="images" %}

The Gemini 3 Flash model can now write and execute Python code to actively
manipulate and inspect images.

**Use cases**

* **Zoom and inspect**: The model implicitly detects when details are too small
(e.g., reading a distant gauge) and writes code to crop and re-examine the area
at higher resolution.

* **Visual math**: The model can run multi-step calculations using code (e.g.,
summing line items on a receipt).

* **Image annotation**: The model can annotate images to answer questions, such
as drawing arrows to show relationships.

{% callout type="note" %}
While the model automatically handles zooming for small details, you
should prompt it explicitly to use code for other tasks, such as "Write code to
count the number of gears" or "Rotate this image to make it upright".
{% /callout %}

## Enable Code Execution with images {% id="code-exec-with-images" %}

Code Execution with images is officially supported in Gemini 3 Flash. You can
activate this behavior by enabling both Code Execution as a tool and Thinking.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import requests
import base64
from PIL import Image
import io

image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "image", "data": base64.b64encode(image_bytes).decode('utf-8'), "mime_type": "image/jpeg"},
        {"type": "text", "text": "Zoom into the expression pedals and tell me how many pedals are there?"}
    ],
    tools=[{"type": "code_execution"}]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                display(Image.open(io.BytesIO(base64.b64decode(content_block.data))))
    elif step.type == "code_execution_call":
        print(step.arguments.code)
    elif step.type == "code_execution_result":
        print(step.result)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

async function main() {
  const client = new GoogleGenAI({});

  const imageUrl = "https://goo.gle/instrument-img";
  const response = await fetch(imageUrl);
  const imageArrayBuffer = await response.arrayBuffer();
  const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');

  const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      {
        type: "image",
        data: base64ImageData,
        mime_type: "image/jpeg"
      },
      { type: "text", text: "Zoom into the expression pedals and tell me how many pedals are there?" }
    ],
    tools: [{ type: "code_execution" }]
  });

  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === "text") {
          console.log("Text:", contentBlock.text);
        }
      }
    } else if (step.type === "code_execution_call") {
      console.log(`\nGenerated Code:\n`, step.arguments.code);
    } else if (step.type === "code_execution_result") {
      console.log(`\nExecution Output:\n`, step.result);
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;
import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.io.InputStream;
import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;

String imageUrl = "https://goo.gle/instrument-img";
byte[] imageBytes;
try (InputStream in = URI.create(imageUrl).toURL().openStream()) {
  imageBytes = in.readAllBytes();
}
String base64Image = Base64.getEncoder().encodeToString(imageBytes);

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    ImageContent.builder()
                        .data(base64Image)
                        .mimeType(ImageContentMimeType.IMAGE_JPEG)
                        .build(),
                    TextContent.builder()
                        .text(
                            "Zoom into the expression pedals and tell me how many pedals are there?")
                        .build())))
        .tools(Arrays.asList(CodeExecution.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

for (Step step : interaction.steps().orElse(Collections.emptyList())) {
  if (step instanceof ModelOutputStep) {
    ModelOutputStep outputStep = (ModelOutputStep) step;
    for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {
      if (contentBlock instanceof TextContent) {
        System.out.println(((TextContent) contentBlock).text().orElse(""));
      } else if (contentBlock instanceof ImageContent) {
        ImageContent imgContent = (ImageContent) contentBlock;
        if (imgContent.data().isPresent()) {
          byte[] decoded = Base64.getDecoder().decode(imgContent.data().get());
          Files.write(Paths.get("output_image.jpg"), decoded);
        }
      }
    }
  } else if (step instanceof CodeExecutionCallStep) {
    CodeExecutionCallStep callStep = (CodeExecutionCallStep) step;
    callStep.arguments().ifPresent(args -> System.out.println(args.code().orElse("")));
  } else if (step instanceof CodeExecutionResultStep) {
    CodeExecutionResultStep resultStep = (CodeExecutionResultStep) step;
    System.out.println(resultStep.result().orElse(""));
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "io"
    "log"
    "net/http"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageURL := "https://goo.gle/instrument-img"
    httpResp, err := http.Get(imageURL)
    if err != nil {
        log.Fatal(err)
    }
    defer httpResp.Body.Close()
    imageBytes, err := io.ReadAll(httpResp.Body)
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.ImageContent{
                    Data:     genai.Ptr(base64Image),
                    MimeType: interactions.ImageContentMimeType("image/jpeg").ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: "Zoom into the expression pedals and tell me how many pedals are there?",
                }),
            }),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.CodeExecution{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if outStep := step.ModelOutputStep; outStep != nil {
            for _, contentBlock := range outStep.Content {
                if textContent := contentBlock.TextContent; textContent != nil {
                    fmt.Println(textContent.GetText())
                } else if imgContent := contentBlock.ImageContent; imgContent != nil && imgContent.Data != nil {
                    decoded, err := base64.StdEncoding.DecodeString(*imgContent.Data)
                    if err == nil {
                        _ = os.WriteFile("output_image.jpg", decoded, 0644)
                    }
                }
            }
        } else if callStep := step.CodeExecutionCallStep; callStep != nil {
            if code := callStep.Arguments.GetCode(); code != nil {
                fmt.Println(*code)
            }
        } else if resultStep := step.CodeExecutionResultStep; resultStep != nil {
            fmt.Println(resultStep.GetResult())
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
IMG_URL="https://goo.gle/instrument-img"
MODEL="gemini-3.8-flash"

MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
  MIME_TYPE="image/jpeg"
fi

if [[ "$(uname)" == "Darwin" ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)
elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64)
else
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)
fi

# Use jq to create the JSON payload to avoid "Argument list too long" error with large base64 strings
echo -n "$IMAGE_B64" > image_b64.txt
jq -n \
  --rawfile b64 image_b64.txt \
  --arg mime "$MIME_TYPE" \
  '{
    model: "gemini-3.8-flash",
    input: [
      {type: "image", data: $b64, mime_type: $mime},
      {type: "text", text: "Zoom into the expression pedals and tell me how many pedals are there?"}
    ],
    tools: [{type: "code_execution"}]
  }' > payload.json

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -d @payload.json
```
{% /tab %}
{% /tabs %}

## Use code execution in multi-turn interactions {% id="code-in-chat" %}

You can also use code execution as part of a multi-turn conversation using
`previous_interaction_id`.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="I have a math question for you.",
    tools=[{"type": "code_execution"}]
)
print(interaction1.output_text)

interaction2 = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction1.id,
    input="What is the sum of the first 50 prime numbers? "
          "Generate and run code for the calculation, and make sure you get all 50.",
    tools=[{"type": "code_execution"}]
)

for step in interaction2.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
    elif step.type == "code_execution_call":
        print(step.arguments.code)
    elif step.type == "code_execution_result":
        print(step.result)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction1 = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "I have a math question for you.",
    tools: [{ type: "code_execution" }]
});
console.log(interaction1.output_text);

const interaction2 = await client.interactions.create({
    model: "gemini-3.8-flash",
    previous_interaction_id: interaction1.id,
    input: "What is the sum of the first 50 prime numbers? " +
           "Generate and run code for the calculation, and make sure you get all 50.",
    tools: [{ type: "code_execution" }]
});

for (const step of interaction2.steps) {
    if (step.type === "model_output") {
        for (const contentBlock of step.content || []) {
            if (contentBlock.type === "text") {
                console.log(contentBlock.text);
            }
        }
    } else if (step.type === "code_execution_call") {
        console.log(step.arguments.code);
    } else if (step.type === "code_execution_result") {
        console.log(step.result);
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;
import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;

Client client = new Client();

CreateModelInteraction params1 =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(InteractionsInput.of("I have a math question for you."))
        .tools(Arrays.asList(CodeExecution.builder().build()))
        .build();

Interaction interaction1 =
    client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
System.out.println(interaction1.outputText().orElse(""));

CreateModelInteraction params2 =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .previousInteractionId(interaction1.id().get())
        .input(
            InteractionsInput.of(
                "What is the sum of the first 50 prime numbers? "
                    + "Generate and run code for the calculation, and make sure you get all 50."))
        .tools(Arrays.asList(CodeExecution.builder().build()))
        .build();

Interaction interaction2 =
    client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();

for (Step step : interaction2.steps().orElse(Collections.emptyList())) {
  if (step instanceof ModelOutputStep) {
    ModelOutputStep outputStep = (ModelOutputStep) step;
    for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {
      if (contentBlock instanceof TextContent) {
        System.out.println(((TextContent) contentBlock).text().orElse(""));
      }
    }
  } else if (step instanceof CodeExecutionCallStep) {
    CodeExecutionCallStep callStep = (CodeExecutionCallStep) step;
    callStep.arguments().ifPresent(args -> System.out.println(args.code().orElse("")));
  } else if (step instanceof CodeExecutionResultStep) {
    CodeExecutionResultStep resultStep = (CodeExecutionResultStep) step;
    System.out.println(resultStep.result().orElse(""));
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("I have a math question for you."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.CodeExecution{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res1.Interaction.OutputText != nil {
        fmt.Println(*res1.Interaction.OutputText)
    }

    res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            PreviousInteractionID: res1.Interaction.ID,
            Input: interactions.NewInteractionsInput(
                "What is the sum of the first 50 prime numbers? " +
                    "Generate and run code for the calculation, and make sure you get all 50.",
            ),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.CodeExecution{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res2.Interaction.Steps {
        if outStep := step.ModelOutputStep; outStep != nil {
            for _, contentBlock := range outStep.Content {
                if textContent := contentBlock.TextContent; textContent != nil {
                    fmt.Println(textContent.GetText())
                }
            }
        } else if callStep := step.CodeExecutionCallStep; callStep != nil {
            if code := callStep.Arguments.GetCode(); code != nil {
                fmt.Println(*code)
            }
        } else if resultStep := step.CodeExecutionResultStep; resultStep != nil {
            fmt.Println(resultStep.GetResult())
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
# First turn
RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
    "model": "gemini-3.8-flash",
    "input": "I have a math question for you.",
    "tools": [{"type": "code_execution"}]
}')

INTERACTION_ID=$(echo $RESPONSE1 | jq -r '.id')

# Second turn with previous_interaction_id
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "'"$INTERACTION_ID"'",
    "input": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50.",
    "tools": [{"type": "code_execution"}]
}'
```
{% /tab %}
{% /tabs %}

## Input/output (I/O) {% id="input-output" %}

Starting with
[Gemini 2.0 Flash](/docs/models), code
execution supports file input and graph output. Using these input and output
capabilities, you can upload CSV and text files, ask questions about the
files, and have [Matplotlib](https://matplotlib.org/) graphs generated as part
of the response. The output files are returned as inline images in the response.

### I/O pricing {% id="input-output-pricing" %}

When using code execution I/O, you're charged for input tokens and output
tokens:

**Input tokens:**

* User prompt

**Output tokens:**

* Code generated by the model
* Code execution output in the code environment
* Thinking tokens
* Summary generated by the model

### I/O details {% id="input-output-details" %}

When you're working with code execution I/O, be aware of the following technical
details:

* The maximum runtime of the code environment is 30 seconds.
* If the code environment generates an error, the model may decide to
  regenerate the code output. This can happen up to 5 times.

* The maximum file input size is limited by the model token window. If you upload a file that exceeds the model's maximum context window, the API will return an error.
* Code execution works best with text and CSV files.
* The input file can be passed as inline data or uploaded using the
  [Files API](/docs/files),
  and the output file is always returned as inline data.

## Billing {% id="billing" %}

There's no additional charge for enabling code execution from the Gemini API.
You'll be billed at the current rate of input and output tokens based on the
Gemini model you're using.

Here are a few other things to know about billing for code execution:

* You're only billed once for the input tokens you pass to the model, and you're
  billed for the final output tokens returned to you by the model.

* Tokens representing generated code are counted as output tokens. Generated
  code can include text and multimodal output like images.

* Code execution results are also counted as output tokens.

The billing model is shown in the following diagram:

![code execution billing model](/googledevai/static/gemini-api/docs/images/code-execution-diagram.png)

* You're billed at the current rate of input and output tokens based on the
  Gemini model you're using.

* If Gemini uses code execution when generating your response, the original
  prompt, the generated code, and the result of the executed code are labeled
  *intermediate tokens* and are billed as *input tokens*.

* Gemini then generates a summary and returns the generated code, the result of
  the executed code, and the final summary. These are billed as *output tokens*.

* The Gemini API includes an intermediate token count in the API response, so
  you know why you're getting additional input tokens beyond your initial
  prompt.

## Limitations {% id="limitations" %}

* The model can only generate and execute code. It can't return other artifacts
  like media files.

* In some cases, enabling code execution can lead to regressions in other areas
  of model output (for example, writing a story).

* There is some variation in the ability of the different models to use code
  execution successfully.

## Supported tools combinations {% id="supported-tools-combinations" %}

Code execution tool can be combined with
[Grounding with Google Search](/docs/google-search) to
power more complex use cases.

Gemini 4 and Gemini 3 models support combining built-in tools (like Code Execution) with
custom tools (function calling).

## Supported libraries {% id="supported-libraries" %}

The code execution environment includes the following libraries:

* attrs
* chess
* contourpy
* fpdf
* geopandas
* imageio
* jinja2
* joblib
* jsonschema
* jsonschema-specifications
* lxml
* matplotlib
* mpmath
* numpy
* opencv-python
* openpyxl
* packaging
* pandas
* pillow
* protobuf
* pylatex
* pyparsing
* PyPDF2
* python-dateutil
* python-docx
* python-pptx
* reportlab
* scikit-learn
* scipy
* seaborn
* six
* striprtf
* sympy
* tabulate
* tensorflow
* toolz
* xlrd

You can't install your own libraries.

{% callout type="note" %}
Only `matplotlib` is supported for graph rendering using code execution.
{% /callout %}

## What's next {% id="whats-next" %}

* Try the [Code execution quickstart](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Code_Execution.ipynb) in Google Colab.
* Learn about other Gemini API tools:
  * [Function calling](/docs/function-calling)
  * [Grounding with Google Search](/docs/google-search)

# URL context
Source: https://aistudio.google.com/docs/url-context
Description: Ground your model's responses in real-time information by providing URLs as context for more accurate and citation-backed answers.

The URL context tool lets you provide additional context to the models in the
form of URLs. By including URLs in your request, the model will access
the content from those pages (as long as it's not a URL type listed in the
[limitations section](/docs/url-context#limitations)) to inform
and enhance its response.

The URL context tool is useful for tasks like the following:

* **Extract Data**: Pull specific info like prices, names, or key
    findings from multiple URLs.

* **Compare Documents**: Analyze multiple reports, articles, or PDFs to
    identify differences and track trends.

* **Synthesize & Create Content**: Combine information from several source
    URLs to generate accurate summaries, blog posts, or reports.

* **Analyze Code & Docs**: Point to a GitHub repository or technical
    documentation to explain code, generate setup instructions, or answer
    questions.

## Compare two pages {% class="hide-from-toc" id="get-started" %}

The following example shows how to compare two recipes from different websites.

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    tools=[{"type": "url_context"}]
)

# Print the model's text response and its source annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            print(f" - {annotation.title}: {annotation.url}")
```
{% /tab %}
{% tab label="Javascript" %}
```javascript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
    tools: [{ type: "url_context" }]
  });

  // Print the model's text response and its source annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'url_citation') {
                console.log(` - ${annotation.title}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    url1 := "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
    url2 := "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(
                fmt.Sprintf("Compare the ingredients and cooking times from the recipes at %s and %s", url1, url2),
            ),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.URLContext{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Print the model's text response and its source annotations
    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                    if len(contentBlock.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range contentBlock.TextContent.Annotations {
                            if annotation.URLCitation != nil {
                                fmt.Printf("  - %s: %s\n", annotation.URLCitation.GetTitle(), annotation.URLCitation.GetURL())
                            }
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}
{% tab label="REST" %}

  ```shell
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.8-flash",
      "input": "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
      "tools": [{"type": "url_context"}]
  }'
  ```
{% /tab %}
{% /tabs %}

## How it works {% id="how-it-works" %}

The URL Context tool uses a two-step retrieval process to
balance speed, cost, and access to fresh data. When you provide a URL, the tool
first attempts to fetch the content from an internal index cache. This acts as a
highly optimized cache. If a URL is not available in the index (for example, if
it's a very new page), the tool automatically falls back to do a live fetch.
This directly accesses the URL to retrieve its content in real-time.

## Combining with other tools {% id="code-examples-with-search" %}

You can combine the URL context tool with other tools to create more powerful
workflows.

[Gemini 3 models](/docs/url-context#supported-models) support combining built-in tools
(like URL Context) with custom tools (function calling). Learn more on the
[tool combinations](/docs/tool-combination) page.

### Grounding with search {% id="grounding-with-search" %}

When both URL context and
[Grounding with Google Search](/docs/google-search) are enabled,
the model can use its search capabilities to find
relevant information online and then use the URL context tool to get a more
in-depth understanding of the pages it finds. This approach is powerful for
prompts that require both broad searching and deep analysis of specific pages.

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Give me three day events schedule based on {{'YOUR_URL'}}. Also let me know what needs to taken care of considering weather and commute.",
    tools=[
        {"type": "url_context"},
        {"type": "google_search"}
    ]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
```
{% /tab %}
{% tab label="Javascript" %}
```javascript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Give me three day events schedule based on {{'YOUR_URL'}}. Also let me know what needs to taken care of considering weather and commute.",
    tools: [
      { type: "url_context" },
      { type: "google_search" }
    ]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === 'text') console.log(contentBlock.text);
      }
    }
  }
}

await main();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.URLContext{}),
                interactions.NewTool(interactions.GoogleSearch{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                }
            }
        }
    }
}
```
{% /tab %}
{% tab label="REST" %}
```shell
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.8-flash",
      "input": "Give me three day events schedule based on {{'YOUR_URL'}}. Also let me know what needs to taken care of considering weather and commute.",
      "tools": [
          {"type": "url_context"},
          {"type": "google_search"}
      ]
  }'
```
{% /tab %}
{% /tabs %}

## Understanding the response {% id="contextual-response" %}

When the model uses the URL context tool, its text response includes inline
`url_citation` annotations on the text content block. Each annotation links a
segment of the response text (via `start_index` and `end_index`) to the source
URL it was derived from. This is the primary way to surface citations in your
application - see the [main example above](/docs/url-context#get-started) for how to extract them.

The response also includes a `url_context_result` step with metadata about each
URL retrieval attempt (status, retrieved URL). This is mainly useful for
debugging.

### Safety checks {% id="safety-checks" %}

The system performs a content moderation check on URLs to confirm
they meet safety standards. If a URL fails this check, the corresponding
`url_context_result` step will show a `status` of `"unsafe"`.

### Token count {% id="token-count" %}

The content retrieved from the URLs you specify in your prompt is counted
as part of the input tokens. You can see the token count in the
`usage` object of the interaction. The following is an example:

```none
'usage': {
  'output_tokens': 45,
  'input_tokens': 27,
  'input_tokens_details': [{'modality': 'TEXT', 'token_count': 27}],
  'thoughts_tokens': 31,
  'tool_use_input_tokens': 10309,
  'tool_use_input_tokens_details': [{'modality': 'TEXT', 'token_count': 10309}],
  'total_tokens': 10412
}
```

Price per token depends on the model used, see the
[pricing](/docs/pricing) page for details.

## Supported models {% id="supported-models" %}

| Model | URL Context |
| ------------------ | :--------------------------: |
| [Gemini 4 Argon](/docs/models/gemini-4-argon) | ✔️ |
| [Gemini 3.8 Flash](/docs/models/gemini-3.8-flash) | ✔️ |
| [Gemini 3.6 Flash](/docs/models/gemini-3.6-flash) | ✔️ |
| [Gemini 3.5 Flash-Lite](/docs/models/gemini-3.5-flash-lite) | ✔️ |
| [Gemini 3.1 Pro Preview](/docs/models/gemini-3.1-pro-preview) | ✔️ |
| [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite) | ✔️ |
| [Gemini 3 Flash Preview](/docs/models/gemini-3-flash-preview) | ✔️ |
| [Gemini 2.5 Pro](/docs/models/gemini-2.5-pro) | ✔️ |
| [Gemini 2.5 Flash](/docs/models/gemini-2.5-flash) | ✔️ |
| [Gemini 2.5 Flash-Lite](/docs/models/gemini-2.5-flash-lite) | ✔️ |

## Best Practices {% id="best-practices" %}

* **Provide specific URLs**: For the best results, provide direct URLs to the
    content you want the model to analyze. The model will only retrieve content
    from the URLs you provide, not any content from nested links.

* **Check for accessibility**: Verify that the URLs you provide don't lead to
    pages that require a login or are behind a paywall.

* **Use the complete URL**: Provide the full URL, including the protocol
    (e.g., https://www.google.com instead of just google.com).

## Limitations {% id="limitations" %}
* Request limit: The tool can process up to 20 URLs per request.
* URL content size: The maximum size for content retrieved from a single
  URL is 34MB.

* Public accessibility: The URLs must be publicly accessible on the web.
Localhost addresses (e.g., localhost, 127.0.0.1), private networks, and
tunneling services (e.g., ngrok, pinggy) are not supported.

### Supported and unsupported content types {% id="url-types" %}

The tool can extract content from URLs with the following content types:

  * Text (text/html, application/json, text/plain, text/xml, text/css,
    text/javascript , text/csv, text/rtf)

  * Image (image/png, image/jpeg, image/bmp, image/webp)
  * PDF (application/pdf)

The following content types are **not** supported:

  * Paywalled content
  * YouTube videos (See
  [video understanding](/docs/video-understanding#youtube) to learn
  how to process YouTube URLs)

  * Google workspace files like Google docs or spreadsheets
  * Video and audio files

# Computer use
Source: https://aistudio.google.com/docs/computer-use
Description: Learn how to use the Gemini API computer use feature.

The Computer Use tool lets you build browser, mobile, and desktop control agents
that interact with and automate tasks. Using screenshots, the model can "see" a
computer screen, and "act" by generating specific UI actions like mouse clicks
and keyboard inputs. Similar to function calling, you will need to implement the
client-side execution environment to receive and execute the Computer Use
actions.

For the list of supported models, see
[Model versions](/docs/computer-use#model-versions). Gemini 4 and Gemini 3.x
models support several advanced capabilities:

* **Multi-environment support:** build agents for [browser, mobile, and desktop](/docs/computer-use#supported-environments) environments.
* **Streamlined actions with intents:** actions include an `intent` field that explains the model's reasoning behind each step.
* **Configurable safety policies:** fine-tune [safety behavior](/docs/computer-use#safety-policies) with built-in policy categories and overrides.
* **Prompt injection detection:** opt-in [screenshot scanning](/docs/computer-use#prompt-injection) to detect hidden adversarial instructions.

With Computer Use, you can build agents that:

* Automate repetitive data entry or form filling on websites.
* Perform automated testing of web applications and user flows
* Conduct research across various websites (e.g., gathering product
    information, prices, and reviews from ecommerce sites to inform a purchase)

Here's a minimal example of initializing the client and sending a prompt to the model with the `computer_use` tool enabled for a browser environment:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Search for 'Gemini API' on Google.",
    tools=[{"type": "computer_use", "environment": "browser"}]
)

print(interaction)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
  model: 'gemini-3.8-flash',
  input: "Search for 'Gemini API' on Google.",
  tools: [{ type: "computer_use", environment: "browser" }]
});

console.log(interaction);
```
{% /tab %}
{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.EnvironmentEnum;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(InteractionsInput.of("Search for 'Gemini API' on Google."))
        .tools(
            Arrays.asList(
                ComputerUse.builder().environment(EnvironmentEnum.BROWSER).build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction);
```
{% /tab %}
{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Search for 'Gemini API' on Google."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.ComputerUse{
                    Environment: interactions.EnvironmentEnumBrowser.ToPointer(),
                }),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction)
}
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
Computer Use may contain errors and security
vulnerabilities. We recommend supervising closely for important tasks, and that
you avoid using the Computer Use capability for tasks involving critical
decisions, sensitive data, or actions where serious errors cannot be corrected.
We encourage you to review the [Safety best practices](/docs/computer-use#safety-best-practices),
the [Prohibited Use
Policy](https://policies.google.com/terms/generative-ai/use-policy) and [Gemini
API Additional Terms of Service](/docs/terms).
{% /callout %}

## How Computer Use works {% id="how-computer-use" %}

To build an agent with the Computer Use model, you need to set up a
continuous loop between your application and the API. Here is what your code
will do at each step:

1. [__Send a request to the model__](/docs/computer-use#send-request)
    * Your application sends an API request containing the Computer Use tool,
        your configuration settings (like the target environment), the user's
        prompt, and a screenshot of the current screen.
2. [__Receive the model response__](/docs/computer-use#model-response)
    * The model analyzes the screen and the prompt, returning a response
        which includes a suggested `function_call` representing a UI action (such
        as a click, scroll, or keystroke).
    *   For **Gemini 4 and Gemini 3.x models**, the response also includes a
        reasoning `intent` explaining why the model chose that action.
    * The response may also include a `safety_decision` from an internal safety
        system that classifies the action as regular/allowed,
        `require_confirmation` (requiring user approval), or blocked.
3. [__Execute the received action__](/docs/computer-use#execute-actions)
    * If the action is allowed (or the user confirms it), your client-side
        code parses the `function_call`, scales the normalized coordinates to match
        your viewport, and executes the action in your target environment using
        automation tools (such as Playwright). If the action is blocked, your
        client should halt the execution or handle the interruption.
4. [__Capture the new environment state__](/docs/computer-use#capture-state)
    * After the action finishes executing, your application captures a new
        screenshot and sends it back to the model in a `function_result` to
        request the next step.

This process then repeats from step 2, continually soliciting the next action
from the model until the task is completed or terminated.

![Computer use overview](/googledevai/static/gemini-api/docs/images/computer_use.png)

## How to implement Computer Use {% id="implement-computer-use" %}

Before building with the Computer Use tool you will need to set up:

* **Secure execution environment:** Run your agent in a sandboxed VM or
    container to isolate it from your host system and limit its potential impact.
    The [reference implementation](https://github.com/google/computer-use-preview/)
    includes a ready-to-use Docker-based sandbox you can use as a starting point.
* **Client-side action handler:** Implement client-side logic to execute coordinates, type text, and take screenshots.

The examples below use a web browser as the execution environment and
[Playwright](https://playwright.dev/) as the client-side handler.

### 0. Set up Playwright

First, install the required packages:

```bash
pip install google-genai playwright
playwright install chromium
```

Then, initialize a Playwright browser instance to use for execution:

```python
from playwright.sync_api import sync_playwright

# 1. Configure screen dimensions for the target environment
SCREEN_WIDTH = 1440
SCREEN_HEIGHT = 900

# 2. Start the Playwright browser
# In production, utilize a sandboxed environment.
playwright = sync_playwright().start()
# Set headless=False to see the actions performed on your screen
browser = playwright.chromium.launch(headless=False)

# 3. Create a context and page with the specified dimensions
context = browser.new_context(
    viewport={"width": SCREEN_WIDTH, "height": SCREEN_HEIGHT}
)
page = context.new_page()

# 4. Navigate to an initial page to start the task
page.goto("https://www.google.com")

# The 'page', 'SCREEN_WIDTH', and 'SCREEN_HEIGHT' variables
# will be used in the steps below.
```

### 1. Send a request to the model {% id="send-request" %}

Initialize the client library and configure the Computer Use tool. Note that there is no need to specify the display size when issuing a request; the model predicts pixel coordinates scaled to the height and width of the screen.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

Use the `google-genai` Python SDK (version `2.7.0` or higher) to configure a request targeting the browser environment:

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input="Find a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th",
    tools=[
        {
            "type": "computer_use",
            "environment": "browser",
            "enable_prompt_injection_detection": True
        }
    ]
)

print(interaction)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

Use the `@google/genai` Node.js SDK to configure a request targeting the browser environment:

```javascript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
  model: 'gemini-3.8-flash',
  input: "Find a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th",
  tools: [
    {
      type: "computer_use",
      environment: "browser",
      enable_prompt_injection_detection: true
    }
  ]
});

console.log(interaction);
```

{% /tab %}
{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.EnvironmentEnum;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(
            InteractionsInput.of(
                "Find a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th"))
        .tools(
            Arrays.asList(
                ComputerUse.builder()
                    .environment(EnvironmentEnum.BROWSER)
                    .enablePromptInjectionDetection(true)
                    .build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction);
```
{% /tab %}
{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Find a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th"),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.ComputerUse{
                    Environment:                    interactions.EnvironmentEnumBrowser.ToPointer(),
                    EnablePromptInjectionDetection: genai.Ptr(true),
                }),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction)
}
```
{% /tab %}
{% tab label="REST" filename="sample.sh" %}

Use curl to send a request:

```shell
curl -X POST \
  "https://generativelanguage.googleapis.com/v1/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Find me a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th. Start by navigating directly to flights.google.com",
    "tools": [
      {
        "type": "computer_use",
        "environment": "browser",
        "enable_prompt_injection_detection": true
      }
    ]
  }'
```

{% /tab %}
{% /tabs %}

### 2. Receive the model response {% id="model-response" %}

The model response suggests a function call containing coordinates and a
tailored reasoning intent explaining the action:

```json
{
  "steps": [
    {
      "type": "function_call",
      "name": "click",
      "arguments": {
        "x": 450,
        "y": 120,
        "intent": "Click the search box to type the destination."
      }
    }
  ]
}
```

### 3. Execute the received actions {% id="execute-actions" %}

Your application must parse the response coordinates, scale them from the normalized 1000x1000 coordinates, and execute the action:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from typing import Any, List, Tuple
import time

def denormalize_x(x: int, screen_width: int) -> int:
    """Convert normalized x coordinate (0-1000) to actual pixel coordinate."""
    return int(x / 1000 * screen_width)

def denormalize_y(y: int, screen_height: int) -> int:
    """Convert normalized y coordinate (0-1000) to actual pixel coordinate."""
    return int(y / 1000 * screen_height)

def execute_function_calls(interaction, page, screen_width, screen_height):
    results = []
    function_calls = [
        step for step in interaction.steps if step.type == "function_call"
    ]

    for function_call in function_calls:
        action_result = {}
        fname = function_call.name
        args = function_call.arguments
        print(f"  -> Executing: {fname} (Intent: {args.get('intent', 'N/A')})")

        try:
            if fname == "open_app":
                pass # Handled / already open
            elif fname in ("click", "double_click", "triple_click", "middle_click", "right_click", "move", "long_press"):
                actual_x = denormalize_x(args["x"], screen_width)
                actual_y = denormalize_y(args["y"], screen_height)

                if fname == "click":
                    page.mouse.click(actual_x, actual_y)
                elif fname == "double_click":
                    page.mouse.dblclick(actual_x, actual_y)
                elif fname == "right_click":
                    page.mouse.click(actual_x, actual_y, button="right")
                elif fname == "middle_click":
                    page.mouse.click(actual_x, actual_y, button="middle")
                elif fname == "move":
                    page.mouse.move(actual_x, actual_y)
            elif fname == "type":
                actual_x = denormalize_x(args["x"], screen_width) if "x" in args else None
                actual_y = denormalize_y(args["y"], screen_height) if "y" in args else None
                text = args["text"]
                press_enter = args.get("press_enter", False)

                if actual_x is not None and actual_y is not None:
                    page.mouse.click(actual_x, actual_y)
                # Clear field first
                page.keyboard.press("Meta+A")
                page.keyboard.press("Backspace")
                page.keyboard.type(text)
                if press_enter:
                    page.keyboard.press("Enter")
            elif fname == "navigate":
                page.goto(args["url"])
            elif fname == "go_back":
                page.go_back()
            elif fname == "go_forward":
                page.go_forward()
            elif fname == "wait":
                time.sleep(args.get("seconds", 1))
            else:
                print(f"Warning: Custom or unhandled function {fname}")

            page.wait_for_load_state(timeout=5000)
            time.sleep(1)

        except Exception as e:
            print(f"Error executing {fname}: {e}")
            action_result = {"error": str(e)}

        results.append((fname, function_call.id, action_result))

    return results
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
function denormalizeX(x, screenWidth) {
    // Convert normalized x coordinate (0-1000) to actual pixel coordinate.
    return Math.floor((x / 1000) * screenWidth);
}

function denormalizeY(y, screenHeight) {
    // Convert normalized y coordinate (0-1000) to actual pixel coordinate.
    return Math.floor((y / 1000) * screenHeight);
}

async function executeFunctionCalls(interaction, page, screenWidth, screenHeight) {
    const results = [];
    const functionCalls = interaction.steps.filter(step => step.type === "function_call");

    for (const functionCall of functionCalls) {
        const actionResult = {};
        const fname = functionCall.name;
        const args = functionCall.arguments;
        console.log(`  -> Executing: ${fname} (Intent: ${args.intent || 'N/A'})`);

        try {
            if (fname === "open_app") {
                // Handled / already open
            } else if (["click", "double_click", "triple_click", "middle_click", "right_click", "move", "long_press"].includes(fname)) {
                const actualX = denormalizeX(args.x, screenWidth);
                const actualY = denormalizeY(args.y, screenHeight);

                if (fname === "click") {
                    await page.mouse.click(actualX, actualY);
                } else if (fname === "double_click") {
                    await page.mouse.dblclick(actualX, actualY);
                } else if (fname === "right_click") {
                    await page.mouse.click(actualX, actualY, { button: "right" });
                } else if (fname === "middle_click") {
                    await page.mouse.click(actualX, actualY, { button: "middle" });
                } else if (fname === "move") {
                    await page.mouse.move(actualX, actualY);
                }
            } else if (fname === "type") {
                const actualX = args.x !== undefined ? denormalizeX(args.x, screenWidth) : null;
                const actualY = args.y !== undefined ? denormalizeY(args.y, screenHeight) : null;
                const text = args.text;
                const pressEnter = args.press_enter || false;

                if (actualX !== null && actualY !== null) {
                    await page.mouse.click(actualX, actualY);
                }
                // Clear field first
                await page.keyboard.press("Meta+A");
                await page.keyboard.press("Backspace");
                await page.keyboard.type(text);
                if (pressEnter) {
                    await page.keyboard.press("Enter");
                }
            } else if (fname === "navigate") {
                await page.goto(args.url);
            } else if (fname === "go_back") {
                await page.goBack();
            } else if (fname === "go_forward") {
                await page.goForward();
            } else if (fname === "wait") {
                await new Promise(resolve => setTimeout(resolve, (args.seconds || 1) * 1000));
            } else {
                console.log(`Warning: Custom or unhandled function ${fname}`);
            }

            await page.waitForLoadState('load', { timeout: 5000 }).catch(() => {});
            await new Promise(resolve => setTimeout(resolve, 1000));
        } catch (e) {
            console.log(`Error executing ${fname}: ${e}`);
            actionResult.error = e.message;
        }

        results.push([fname, functionCall.id, actionResult]);
    }

    return results;
}
```

{% /tab %}
{% tab label="Java" %}

```java
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.Step;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

class ActionExecutor {
  int denormalizeX(int x, int screenWidth) {
    return (int) (x / 1000.0 * screenWidth);
  }

  int denormalizeY(int y, int screenHeight) {
    return (int) (y / 1000.0 * screenHeight);
  }

  List<Map<String, Object>> executeFunctionCalls(
      Interaction interaction, int screenWidth, int screenHeight) {
    List<Map<String, Object>> results = new ArrayList<>();

    for (Step step : interaction.steps().orElse(Collections.emptyList())) {
      if (step instanceof FunctionCallStep) {
        FunctionCallStep functionCall = (FunctionCallStep) step;
        String fname = functionCall.name().orElse("");
        Map<String, Object> args = functionCall.arguments().orElse(Collections.emptyMap());
        Map<String, Object> actionResult = new HashMap<>();

        System.out.println(
            "  -> Executing: " + fname + " (Intent: " + args.getOrDefault("intent", "N/A") + ")");

        try {
          if (fname.equals("click")) {
            int actualX = denormalizeX(((Number) args.get("x")).intValue(), screenWidth);
            int actualY = denormalizeY(((Number) args.get("y")).intValue(), screenHeight);
            // Perform mouse click at (actualX, actualY) using your browser automation library
          } else if (fname.equals("type")) {
            String text = (String) args.get("text");
            // Type text into active element using your browser automation library
          } else if (fname.equals("navigate")) {
            String url = (String) args.get("url");
            // Navigate browser to url
          }
        } catch (Exception e) {
          actionResult.put("error", e.getMessage());
        }

        Map<String, Object> entry = new HashMap<>();
        entry.put("name", fname);
        entry.put("callId", functionCall.id().orElse(""));
        entry.put("result", actionResult);
        results.add(entry);
      }
    }
    return results;
  }
}
```
{% /tab %}
{% tab label="Go" %}

```go
package main

import (
    "fmt"

    "google.golang.org/genai/interactions/models/interactions"
)

func denormalizeX(x, screenWidth int) int {
    return int(float64(x) / 1000.0 * float64(screenWidth))
}

func denormalizeY(y, screenHeight int) int {
    return int(float64(y) / 1000.0 * float64(screenHeight))
}

func executeFunctionCalls(interaction *interactions.Interaction, screenWidth, screenHeight int) []map[string]any {
    var results []map[string]any

    for _, step := range interaction.Steps {
        if functionCall := step.FunctionCallStep; functionCall != nil {
            fname := functionCall.Name
            args := functionCall.Arguments
            actionResult := map[string]any{}

            intent := args["intent"]
            if intent == nil {
                intent = "N/A"
            }
            fmt.Printf("  -> Executing: %s (Intent: %v)\n", fname, intent)

            switch fname {
            case "click":
                xVal, _ := args["x"].(float64)
                yVal, _ := args["y"].(float64)
                actualX := denormalizeX(int(xVal), screenWidth)
                actualY := denormalizeY(int(yVal), screenHeight)
                _ = actualX
                _ = actualY
                // Perform mouse click at (actualX, actualY) using your browser automation library
            case "type":
                text, _ := args["text"].(string)
                _ = text
                // Type text into active element using your browser automation library
            case "navigate":
                url, _ := args["url"].(string)
                _ = url
                // Navigate browser to url
            }

            results = append(results, map[string]any{
                "name":   fname,
                "callId": functionCall.ID,
                "result": actionResult,
            })
        }
    }
    return results
}

func main() {
    // Example helper usage with an Interaction response
}
```
{% /tab %}
{% /tabs %}
### 4. Capture the new environment state {% id="capture-state" %}

After executing the actions, send the result of the function execution back to
the model so it can use this information to generate the next action. If
multiple actions (parallel calls) were executed, you must send a
`function_result` for each one in the subsequent user turn.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import json
import base64

def get_function_responses(page, results):
    screenshot_bytes = page.screenshot(type="png")
    current_url = page.url
    function_responses = []
    for name, call_id, result in results:
        function_responses.append({
            "type": "function_result",
            "name": name,
            "call_id": call_id,
            "result": [
                {
                    "type": "text",
                    "text": json.dumps({"url": current_url, **result})
                },
                {
                    "type": "image",
                    "data": base64.b64encode(screenshot_bytes).decode("utf-8"),
                    "mime_type": "image/png"
                }
            ]
        })
    return function_responses
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
async function getFunctionResponses(page, results) {
    const screenshotBuffer = await page.screenshot({ type: 'png' });
    const screenshotBase64 = screenshotBuffer.toString('base64');
    const currentUrl = page.url();
    const functionResponses = [];

    for (const [name, callId, result] of results) {
        functionResponses.push({
            type: "function_result",
            name: name,
            call_id: callId,
            result: [
                {
                    type: "text",
                    text: JSON.stringify({ url: currentUrl, ...result })
                },
                {
                    type: "image",
                    data: screenshotBase64,
                    mime_type: "image/png"
                }
            ]
        });
    }
    return functionResponses;
}
```

Once you have defined how to capture and format the environment state, you can
combine all these steps into a continuous execution loop.

{% /tab %}
{% tab label="Java" %}

```java
import com.google.genai.gaos.models.interactions.FunctionResultStep;
import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;
import java.util.Map;

class StateCapturer {
  List<Step> getFunctionResponses(
      byte[] screenshotBytes, String currentUrl, List<Map<String, Object>> results) {
    List<Step> functionResponses = new ArrayList<>();
    String base64Screenshot = Base64.getEncoder().encodeToString(screenshotBytes);

    for (Map<String, Object> entry : results) {
      String name = (String) entry.get("name");
      String callId = (String) entry.get("callId");
      String jsonResult = String.format("{\"url\": \"%s\"}", currentUrl);

      FunctionResultStep responseStep =
          FunctionResultStep.builder()
              .name(name)
              .callId(callId)
              .result(
                  FunctionResultStepResultUnion.of(
                      Arrays.asList(
                          TextContent.builder().text(jsonResult).build(),
                          ImageContent.builder()
                              .data(base64Screenshot)
                              .mimeType(ImageContentMimeType.IMAGE_PNG)
                              .build())))
              .build();
      functionResponses.add(responseStep);
    }
    return functionResponses;
  }
}
```
{% /tab %}
{% tab label="Go" %}

```go
package main

import (
    "encoding/base64"
    "fmt"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
)

func getFunctionResponses(screenshotBytes []byte, currentURL string, results []map[string]any) []interactions.Step {
    var functionResponses []interactions.Step
    base64Screenshot := base64.StdEncoding.EncodeToString(screenshotBytes)

    for _, entry := range results {
        name, _ := entry["name"].(string)
        callID, _ := entry["callId"].(string)
        jsonResult := fmt.Sprintf(`{"url": "%s"}`, currentURL)

        responseStep := interactions.NewStep(interactions.FunctionResultStep{
            Name:   genai.Ptr(name),
            CallID: callID,
            Result: interactions.NewFunctionResultStepResultUnion([]interactions.FunctionResultSubcontent{
                interactions.NewFunctionResultSubcontent(interactions.TextContent{
                    Text: jsonResult,
                }),
                interactions.NewFunctionResultSubcontent(interactions.ImageContent{
                    Data:     genai.Ptr(base64Screenshot),
                    MimeType: interactions.ImageContentMimeType("image/png").ToPointer(),
                }),
            }),
        })
        functionResponses = append(functionResponses, responseStep)
    }
    return functionResponses
}

func main() {
    // Example helper usage to build FunctionResultStep responses
}
```
{% /tab %}
{% /tabs %}
## Build an agent loop {% id="agent-loop" %}

To enable multi-step interactions, combine the four steps from the [How to
implement Computer Use](/docs/computer-use#implement-computer-use) section into a single loop.
This loop continues requesting actions and feeding the results back to the model
until the task is complete.

Remember to manage the conversation history correctly by appending both the
model responses and your function responses to the history at each step.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import time
from typing import Any, List, Tuple
from playwright.sync_api import sync_playwright

from google import genai

client = genai.Client()

# Constants for screen dimensions
SCREEN_WIDTH = 1440
SCREEN_HEIGHT = 900

# Setup Playwright
print("Initializing browser...")
playwright = sync_playwright().start()
browser = playwright.chromium.launch(headless=False)
context = browser.new_context(viewport={"width": SCREEN_WIDTH, "height": SCREEN_HEIGHT})
page = context.new_page()

# Define helper functions. Copy/paste from steps 3 and 4
# def denormalize_x(...)
# def denormalize_y(...)
# def execute_function_calls(...)
# def get_function_responses(...)

try:
    # Go to initial page
    page.goto("https://ai.google.dev/gemini-api/docs")

    # Take initial screenshot
    initial_screenshot = page.screenshot(type="png")
    USER_PROMPT = "Go to ai.google.dev/gemini-api/docs and search for pricing."
    print(f"Goal: {USER_PROMPT}")

    # First interaction
    interaction = client.interactions.create(
        model='gemini-3.8-flash',
        input=[
            {"type": "text", "text": USER_PROMPT},
            {"type": "image", "data": base64.b64encode(initial_screenshot).decode("utf-8"), "mime_type": "image/png"}
        ],
        tools=[{
            "type": "computer_use",
            "environment": "browser",
            "enable_prompt_injection_detection": True
        }]
    )

    # Agent Loop
    turn_limit = 5
    for i in range(turn_limit):
        print(f"\n--- Turn {i+1} ---")

        has_function_calls = any(
            step.type == "function_call"
            for step in interaction.steps
        )
        if not has_function_calls:
            text_response = " ".join([
                content_block.text for step in interaction.steps if step.type == "model_output"
                for content_block in step.content if content_block.type == "text"
            ])
            print("Agent finished:", text_response)
            break

        print("Executing actions...")
        results = execute_function_calls(interaction, page, SCREEN_WIDTH, SCREEN_HEIGHT)

        print("Capturing state...")
        function_responses = get_function_responses(page, results)

        # Continue conversation with function responses
        interaction = client.interactions.create(
            model='gemini-3.8-flash',
            previous_interaction_id=interaction.id,
            input=function_responses,
            tools=[{
                "type": "computer_use",
                "environment": "browser",
                "enable_prompt_injection_detection": True
            }]
        )

finally:
    # Cleanup
    print("\nClosing browser...")
    browser.close()
    playwright.stop()
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { chromium } from 'playwright';
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

// Constants for screen dimensions
const SCREEN_WIDTH = 1440;
const SCREEN_HEIGHT = 900;

console.log("Initializing browser...");
const browser = await chromium.launch({ headless: false });
const context = await browser.newContext({
    viewport: { width: SCREEN_WIDTH, height: SCREEN_HEIGHT }
});
const page = await context.newPage();

// Define helper functions. Copy/paste from steps 3 and 4:
// function denormalizeX(...)
// function denormalizeY(...)
// async function executeFunctionCalls(...)
// async function getFunctionResponses(...)

try {
    // Go to initial page
    await page.goto("https://ai.google.dev/gemini-api/docs");

    // Take initial screenshot
    const initialScreenshotBuffer = await page.screenshot({ type: 'png' });
    const initialScreenshotBase64 = initialScreenshotBuffer.toString('base64');
    const USER_PROMPT = "Go to ai.google.dev/gemini-api/docs and search for pricing.";
    console.log(`Goal: ${USER_PROMPT}`);

    // First interaction
    let interaction = await ai.interactions.create({
        model: 'gemini-3.8-flash',
        input: [
            { type: 'text', text: USER_PROMPT },
            { type: 'image', data: initialScreenshotBase64, mime_type: 'image/png' }
        ],
        tools: [{
            type: 'computer_use',
            environment: 'browser',
            enable_prompt_injection_detection: true
        }]
    });

    // Agent Loop
    const turnLimit = 5;
    for (let i = 0; i < turnLimit; i++) {
        console.log(`\n--- Turn ${i + 1} ---`);

        const hasFunctionCalls = (interaction.steps || []).some(step => step.type === "function_call");
        if (!hasFunctionCalls) {
            const textResponses = [];
            for (const step of interaction.steps || []) {
                if (step.type === "model_output") {
                    for (const contentBlock of step.content || []) {
                        if (contentBlock.type === "text") {
                            textResponses.push(contentBlock.text);
                        }
                    }
                }
            }
            console.log("Agent finished:", textResponses.join(" "));
            break;
        }

        console.log("Executing actions...");
        const results = await executeFunctionCalls(interaction, page, SCREEN_WIDTH, SCREEN_HEIGHT);

        console.log("Capturing state...");
        const functionResponses = await getFunctionResponses(page, results);

        // Continue conversation with function responses
        interaction = await ai.interactions.create({
            model: 'gemini-3.8-flash',
            previous_interaction_id: interaction.id,
            input: functionResponses,
            tools: [{
                type: 'computer_use',
                environment: 'browser',
                enable_prompt_injection_detection: true
            }]
        });
    }
} finally {
    // Cleanup
    console.log("\nClosing browser...");
    await browser.close();
}
```

{% /tab %}
{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.EnvironmentEnum;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.util.List;

Client client = new Client();

// Constants for screen dimensions
int screenWidth = 1440;
int screenHeight = 900;

// Capture initial screenshot from browser driver (e.g. Playwright)
byte[] initialScreenshot = new byte[0];
String base64Screenshot = Base64.getEncoder().encodeToString(initialScreenshot);
String userPrompt = "Go to ai.google.dev/gemini-api/docs and search for pricing.";
System.out.println("Goal: " + userPrompt);

ComputerUse computerUseTool =
    ComputerUse.builder()
        .environment(EnvironmentEnum.BROWSER)
        .enablePromptInjectionDetection(true)
        .build();

CreateModelInteraction initialParams =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    TextContent.builder().text(userPrompt).build(),
                    ImageContent.builder()
                        .data(base64Screenshot)
                        .mimeType(ImageContentMimeType.IMAGE_PNG)
                        .build())))
        .tools(Arrays.asList(computerUseTool))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(initialParams)).interaction().get();

int turnLimit = 5;
for (int i = 0; i < turnLimit; i++) {
  System.out.println("\n--- Turn " + (i + 1) + " ---");

  boolean hasFunctionCalls =
      interaction.steps().orElse(Collections.emptyList()).stream()
          .anyMatch(step -> step instanceof FunctionCallStep);

  if (!hasFunctionCalls) {
    StringBuilder textResponse = new StringBuilder();
    for (Step step : interaction.steps().orElse(Collections.emptyList())) {
      if (step instanceof ModelOutputStep) {
        for (Content contentBlock :
            ((ModelOutputStep) step).content().orElse(Collections.emptyList())) {
          if (contentBlock instanceof TextContent) {
            textResponse.append(((TextContent) contentBlock).text().orElse("")).append(" ");
          }
        }
      }
    }
    System.out.println("Agent finished: " + textResponse.toString().trim());
    break;
  }

  System.out.println("Executing actions and capturing state...");
  // Execute function calls against browser driver and capture List<Step> functionResponses
  List<Step> functionResponses = new ArrayList<>();

  CreateModelInteraction nextParams =
      CreateModelInteraction.builder()
          .model("gemini-3.8-flash")
          .previousInteractionId(interaction.id().get())
          .input(InteractionsInput.ofStep(functionResponses))
          .tools(Arrays.asList(computerUseTool))
          .build();

  interaction =
      client.interactions.create(CreateInteractionRequestBody.of(nextParams)).interaction().get();
}
```
{% /tab %}
{% tab label="Go" %}

```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "strings"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Constants for screen dimensions
    screenWidth := 1440
    screenHeight := 900
    _ = screenWidth
    _ = screenHeight

    // Capture initial screenshot from browser driver (e.g. Playwright)
    initialScreenshot := []byte{}
    base64Screenshot := base64.StdEncoding.EncodeToString(initialScreenshot)
    userPrompt := "Go to ai.google.dev/gemini-api/docs and search for pricing."
    fmt.Println("Goal:", userPrompt)

    computerUseTool := interactions.NewTool(interactions.ComputerUse{
        Environment:                    interactions.EnvironmentEnumBrowser.ToPointer(),
        EnablePromptInjectionDetection: genai.Ptr(true),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{Text: userPrompt}),
                interactions.NewContent(interactions.ImageContent{
                    Data:     genai.Ptr(base64Screenshot),
                    MimeType: interactions.ImageContentMimeType("image/png").ToPointer(),
                }),
            }),
            Tools: []interactions.Tool{computerUseTool},
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    interaction := res.Interaction

    turnLimit := 5
    for i := 0; i < turnLimit; i++ {
        fmt.Printf("\n--- Turn %d ---\n", i+1)

        hasFunctionCalls := false
        for _, step := range interaction.Steps {
            if step.FunctionCallStep != nil {
                hasFunctionCalls = true
                break
            }
        }

        if !hasFunctionCalls {
            var parts []string
            for _, step := range interaction.Steps {
                if outStep := step.ModelOutputStep; outStep != nil {
                    for _, contentBlock := range outStep.Content {
                        if textContent := contentBlock.TextContent; textContent != nil {
                            parts = append(parts, textContent.GetText())
                        }
                    }
                }
            }
            fmt.Println("Agent finished:", strings.TrimSpace(strings.Join(parts, " ")))
            break
        }

        fmt.Println("Executing actions and capturing state...")
        // Execute function calls against browser driver and capture []interactions.Step functionResponses
        var functionResponses []interactions.Step

        nextRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
            Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
                Model:                 interactions.Model("gemini-3.8-flash"),
                PreviousInteractionID: interaction.ID,
                Input:                 interactions.NewInteractionsInput(functionResponses),
                Tools:                 []interactions.Tool{computerUseTool},
            }),
        })
        if err != nil {
            log.Fatal(err)
        }
        interaction = nextRes.Interaction
    }
}
```
{% /tab %}
{% /tabs %}
## Supported environments {% id="supported-environments" %}

Gemini 4 and Gemini 3.x models support three environments specified in the
`computer_use` configurations:

### Browser environment (`ENVIRONMENT_BROWSER`)

Available actions under browser tool:

| Command name | Description | Arguments (in function call) |
| :--- | :--- | :--- |
| **click** | Left clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **double_click** | Double clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **triple_click** | Triple clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **middle_click** | Middle clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **right_click** | Right clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **mouse_down** | Presses and holds the mouse button at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **mouse_up** | Releases the mouse button at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **move** | Moves the cursor to the specified position. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **type** | Types text. | `text`: str<br/>`press_enter`: bool (Optional, default `false`)<br/>`intent`: str |
| **drag_and_drop** | Drags an item from the start coordinate to the end coordinate. | `start_y`: int (0-999)<br/>`start_x`: int (0-999)<br/>`end_y`: int (0-999)<br/>`end_x`: int (0-999)<br/>`intent`: str |
| **wait** | Pauses execution for a specified number of seconds. | `seconds`: int (Optional, default `1`)<br/>`intent`: str |
| **press_key** | Presses the specified key and releases it. | `key`: str<br/>`intent`: str |
| **key_down** | Presses and holds the specified key. | `key`: str<br/>`intent`: str |
| **key_up** | Releases the specified key. | `key`: str<br/>`intent`: str |
| **hotkey** | Presses the specified key combination. | `keys`: `List[str]`<br/>`intent`: `str` |
| **take_screenshot** | Returns a screenshot of the current screen. | `intent`: str |
| **scroll** | Scrolls up, down, left, or right at a coordinate by a pixel distance. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`direction`: str (`"up"`, `"down"`, `"left"`, `"right"`)<br/>`magnitude_in_pixels`: int (0-999, Optional, default `300`)<br/>`intent`: str |
| **go_back** | Navigates back to the previous webpage in the browser history. | `intent`: str |
| **navigate** | Navigates directly to a specified URL. | `url`: str<br/>`intent`: str |
| **go_forward** | Navigates forward to the next webpage in the browser history. | `intent`: str |

### Mobile environment (`ENVIRONMENT_MOBILE`) {% id="mobile-environment" %}

Android-optimized environment actions:

| Command name | Description | Arguments (in function call) |
| :--- | :--- | :--- |
| **open_app** | Opens an application by its name. | `app_name`: str<br/>`intent`: str |
| **click** | Left clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **list_apps** | Lists available applications on the device, returning their names and package names. | `intent`: str |
| **wait** | Pauses execution for a specified number of seconds. | `seconds`: int (Optional, default `1`)<br/>`intent`: str |
| **go_back** | Navigates back to the previous screen or webpage. | `intent`: str |
| **type** | Types text. | `text`: str<br/>`press_enter`: bool (Optional, default `false`)<br/>`intent`: str |
| **drag_and_drop** | Drags an item from the start coordinate to the end coordinate. | `start_y`: int (0-999)<br/>`start_x`: int (0-999)<br/>`end_y`: int (0-999)<br/>`end_x`: int (0-999)<br/>`intent`: str |
| **long_press** | Performs a long press at a coordinate on the screen. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`seconds`: int (Optional, default `2`)<br/>`intent`: str |
| **press_key** | Presses the specified key and releases it. | `key`: str<br/>`intent`: str |
| **take_screenshot** | Returns a screenshot of the current screen. | `intent`: str |

### Desktop environment (`ENVIRONMENT_DESKTOP`) {% id="desktop-environment" %}

Desktop environments OS-level cursor commands:

| Command name | Description | Arguments (in function call) |
| :--- | :--- | :--- |
| **click** | Left clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **double_click** | Double clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **triple_click** | Triple clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **middle_click** | Middle clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **right_click** | Right clicks at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **mouse_down** | Presses and holds the mouse button at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **mouse_up** | Releases the mouse button at the coordinate. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **move** | Moves the cursor to the specified position. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`intent`: str |
| **type** | Types text. | `text`: str<br/>`press_enter`: bool (Optional, default `false`)<br/>`intent`: str |
| **drag_and_drop** | Drags an item from the start coordinate to the end coordinate. | `start_y`: int (0-999)<br/>`start_x`: int (0-999)<br/>`end_y`: int (0-999)<br/>`end_x`: int (0-999)<br/>`intent`: str |
| **wait** | Pauses execution for a specified number of seconds. | `seconds`: int (Optional, default `1`)<br/>`intent`: str |
| **press_key** | Presses the specified key and releases it. | `key`: str<br/>`intent`: str |
| **key_down** | Presses and holds the specified key. | `key`: str<br/>`intent`: str |
| **key_up** | Releases the specified key. | `key`: str<br/>`intent`: str |
| **hotkey** | Presses the specified key combination. | `keys`: `List[str]`<br/>`intent`: `str` |
| **take_screenshot** | Returns a screenshot of the current screen. | `intent`: str |
| **scroll** | Scrolls up, down, left, or right at a coordinate by a pixel distance. | `y`: int (0-999)<br/>`x`: int (0-999)<br/>`direction`: str (`"up"`, `"down"`, `"left"`, `"right"`)<br/>`magnitude_in_pixels`: int (0-999, Optional, default `300`)<br/>`intent`: str |

## Custom user-defined functions {% id="custom-functions" %}

You can extend the functionality of the model by including custom user-defined functions. For example, in human-in-the-loop (HITL) scenarios you can exclude default predefined actions and register custom actions.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

Exclude standard predefined browser actions (such as `click`) and register a custom `yield_to_user` tool:

```python
from google import genai

client = genai.Client()

yield_to_user_tool = {
    "type": "function",
    "name": "yield_to_user",
    "description": "Yields control back to the user for assistance or verification when an automated action is unsafe or ambiguous.",
    "parameters": {
        "type": "object",
        "properties": {
            "reason": {
                "type": "string",
                "description": "The reason why the agent is yielding control to the human."
            }
        },
        "required": ["reason"]
    }
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Click the submit button. If you need a second factor authentication code, ask me.",
    tools=[
        {
            "type": "computer_use",
            "environment": "mobile",
            "excluded_predefined_functions": ["click"]
        },
        yield_to_user_tool
    ]
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

Exclude standard predefined browser actions (such as `click`) and register a custom `yield_to_user` tool:

```javascript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Click the submit button. If you need a second factor authentication code, ask me.",
    tools: [
        {
            type: "computer_use",
            environment: "mobile",
            excluded_predefined_functions: ["click"]
        },
        {
            type: "function",
            name: "yield_to_user",
            description: "Yields control back to the user for assistance or verification when an automated action is unsafe or ambiguous.",
            parameters: {
                type: "object",
                properties: {
                    reason: {
                        type: "string",
                        description: "The reason why the agent is yielding control to the human."
                    }
                },
                required: ["reason"]
            }
        }
    ]
});
```

{% /tab %}
{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.EnvironmentEnum;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> reasonProp = new HashMap<>();
reasonProp.put("type", "string");
reasonProp.put("description", "The reason why the agent is yielding control to the human.");

Map<String, Object> properties = new HashMap<>();
properties.put("reason", reasonProp);

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");
parameters.put("properties", properties);
parameters.put("required", Collections.singletonList("reason"));

Function yieldToUserTool =
    Function.builder()
        .name("yield_to_user")
        .description(
            "Yields control back to the user for assistance or verification when an automated action is unsafe or ambiguous.")
        .parameters(parameters)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(
            InteractionsInput.of(
                "Click the submit button. If you need a second factor authentication code, ask me."))
        .tools(
            Arrays.asList(
                ComputerUse.builder()
                    .environment(EnvironmentEnum.MOBILE)
                    .excludedPredefinedFunctions(Arrays.asList("click"))
                    .build(),
                yieldToUserTool))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}

```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    yieldToUserTool := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("yield_to_user"),
        Description: genai.Ptr("Yields control back to the user for assistance or verification when an automated action is unsafe or ambiguous."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "reason": map[string]any{
                    "type":        "string",
                    "description": "The reason why the agent is yielding control to the human.",
                },
            },
            "required": []string{"reason"},
        },
    })

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Click the submit button. If you need a second factor authentication code, ask me."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.ComputerUse{
                    Environment:                 interactions.EnvironmentEnumMobile.ToPointer(),
                    ExcludedPredefinedFunctions: []string{"click"},
                }),
                yieldToUserTool,
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}
{% /tabs %}

## Managing thinking levels {% id="thinking-levels" %}

For computer use agents, you can configure different thinking levels to balance action quality and execution speed. Lower thinking levels generally achieve a good balance for standard automation tasks.

## Safety and security {% id="safety-security" %}

### Configuring safety policies {% id="safety-policies" %}

Gemini 4 and Gemini 3.x models include built-in safety service categories that
help to determine if user confirmation is required.

| Safety policy category | Description |
| :--- | :--- |
| `FINANCIAL_TRANSACTIONS` | Blocks or triggers confirmation for actions involving payments, retail checkout, or regulated goods. |
| `SENSITIVE_DATA_MODIFICATION` | Protects health, financial, or government records from unauthorized modification. |
| `COMMUNICATION_TOOL` | Restricts the agent from autonomously sending emails, chat messages, or drafts. |
| `ACCOUNT_CREATION` | Restricts the agent from autonomously registering new accounts on websites. |
| `DATA_MODIFICATION` | Regulates overall file system modifications, data sharing, and storage deletion. |
| `USER_CONSENT_MANAGEMENT` | Requires user takeover for cookie consent banners and privacy prompts. |
| `LEGAL_TERMS_AND_AGREEMENTS` | Prevents the model from autonomously accepting Terms of Service or legally binding contracts. |

#### Safety overrides

You can override select policies by passing overrides:

{% callout type="note" %}
Safety overrides indicate your preference, but the model may still return
a `safety_decision` with `require_confirmation` in some cases. Your application
should always implement safety decision handling regardless of configured
overrides.
{% /callout %}

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Clean up the local folder by archiving old logs.",
    tools=[
        {
            "type": "computer_use",
            "environment": "desktop",
            "disabled_safety_policies": [
                "data_modification"
            ]
        }
    ]
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Clean up the local folder by archiving old logs.",
    tools: [
        {
            type: "computer_use",
            environment: "desktop",
            disabled_safety_policies: [
                "data_modification"
            ]
        }
    ]
});
```

{% /tab %}
{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DisabledSafetyPolicy;
import com.google.genai.gaos.models.interactions.EnvironmentEnum;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(InteractionsInput.of("Clean up the local folder by archiving old logs."))
        .tools(
            Arrays.asList(
                ComputerUse.builder()
                    .environment(EnvironmentEnum.DESKTOP)
                    .disabledSafetyPolicies(
                        Arrays.asList(DisabledSafetyPolicy.DATA_MODIFICATION))
                    .build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}

```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Clean up the local folder by archiving old logs."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.ComputerUse{
                    Environment: interactions.EnvironmentEnumDesktop.ToPointer(),
                    DisabledSafetyPolicies: []interactions.DisabledSafetyPolicy{
                        interactions.DisabledSafetyPolicyDataModification,
                    },
                }),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}
{% /tabs %}

### Prompt injection detection {% id="prompt-injection" %}

Computer Use for Gemini 3.5 Flash-Lite or later supports an advanced safety
mechanism to detect prompt injection attacks. When enabled, this feature checks
whether an included screenshot contains hidden adversarial instructions (for
example, "Ignore previous commands") and blocks execution when detected.

Prompt injection detection is an opt-in feature. The default is `false`.

The following examples demonstrate how to enable prompt injection detection
in your Computer Use tool configuration:

{% tabs %}
{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Search for flight deals and summarize top results.",
    tools=[
        {
            "type": "computer_use",
            "environment": "desktop",
            "enable_prompt_injection_detection": True,
        }
    ],
)
```
{% /tab %}
{% tab label="JavaScript" %}

```javascript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Search for flight deals and summarize top results.",
    tools: [
        {
            type: "computer_use",
            environment: "desktop",
            enable_prompt_injection_detection: true,
        }
    ]
});
```
{% /tab %}
{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.EnvironmentEnum;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(InteractionsInput.of("Search for flight deals and summarize top results."))
        .tools(
            Arrays.asList(
                ComputerUse.builder()
                    .environment(EnvironmentEnum.DESKTOP)
                    .enablePromptInjectionDetection(true)
                    .build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}

```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Search for flight deals and summarize top results."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.ComputerUse{
                    Environment:                    interactions.EnvironmentEnumDesktop.ToPointer(),
                    EnablePromptInjectionDetection: genai.Ptr(true),
                }),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="cURL" %}

```bash
curl "https://generativelanguage.googleapis.com/v1/interactions?key=${GEMINI_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
  "model": "gemini-3.8-flash",
  "input": "Search for flight deals and summarize top results.",
  "tools": [
    {
      "type": "computer_use",
      "environment": "desktop",
      "enable_prompt_injection_detection": true
    }
  ]
}'
```
{% /tab %}
{% /tabs %}
### Acknowledge safety decision {% id="safety-decisions" %}

The response may include a `safety_decision` parameter in the function call arguments:

```json
{
  "steps": [
    {
      "type": "function_call",
      "name": "click",
      "arguments": {
        "x": 60,
        "y": 100,
        "safety_decision": {
          "explanation": "Must check check-box",
          "decision": "require_confirmation"
        }
      }
    }
  ]
}
```

If the `safety_decision` is `require_confirmation`, prompt the end user. If the user confirms, set `safety_acknowledgement` in `function_result`.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
def get_safety_confirmation(safety_decision):
    # Prompt user for confirmation
    print(f"Safety confirmation required: {safety_decision.get('explanation', '')}")
    return "CONTINUE" # Or TERMINATE

# Inside execute_function_calls, check for safety_decision:
if 'safety_decision' in function_call.arguments:
    decision = get_safety_confirmation(function_call.arguments['safety_decision'])
    if decision == "TERMINATE":
        break
    # Include safety_acknowledgement inside the action result
    action_result["safety_acknowledgement"] = True
```

{% /tab %}
{% /tabs %}
### Safety best practices {% id="safety-best-practices" %}

Computer Use presents unique security and operational risks, as a model acting
on a user's behalf might encounter untrusted content on screens or make errors
in executing actions. Implement the following best practices to protect user
data and systems:

1. **Human-in-the-Loop (HITL):**
    * **Enforce user confirmation:** When the safety response indicates
        `require_confirmation`, prompt the user for approval.
    * **Provide custom safety instructions:** Implement a custom system instruction to define and enforce your own safety boundaries. For example:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
            from google import genai

            client = genai.Client()

            system_instruction = """
            ## **RULE 1: Seek User Confirmation (USER_CONFIRMATION)**

            This is your first and most important check. If the next required action falls
            into any of the following categories, you MUST stop immediately, and seek the
            user's explicit permission.

            **Procedure for Seeking Confirmation:**
            * **For Consequential Actions:** Perform all preparatory steps (e.g., navigating,
              filling out forms, typing a message). You will ask for confirmation **AFTER**
              all necessary information is entered on the screen, but **BEFORE** you perform
              the final, irreversible action (e.g., before clicking "Send", "Submit",
              "Confirm Purchase", "Share").
            * **For Prohibited Actions:** If the action is strictly forbidden (e.g., accepting
              legal terms, solving a CAPTCHA), you must first inform the user about the
              required action and ask for their confirmation to proceed.

            **USER_CONFIRMATION Categories:**

            *   **Consent and Agreements:** You are FORBIDDEN from accepting, selecting, or
                agreeing to any of the following on the user's behalf. You must ask the
                user to confirm before performing these actions.
                *   Terms of Service
                *   Privacy Policies
                *   Cookie consent banners
                *   End User License Agreements (EULAs)
                *   Any other legally significant contracts or agreements.
            *   **Robot Detection:** You MUST NEVER attempt to solve or bypass the
                following. You must ask the user to confirm before performing these actions.
                *   CAPTCHAs (of any kind)
                *   Any other anti-robot or human-verification mechanisms, even if you are
                    capable.
            *   **Financial Transactions:**
                *   Completing any purchase.
                *   Managing or moving money (e.g., transfers, payments).
                *   Purchasing regulated goods or participating in gambling.
            *   **Sending Communications:**
                *   Sending emails.
                *   Sending messages on any platform (e.g., social media, chat apps).
                *   Posting content on social media or forums.
            *   **Accessing or Modifying Sensitive Information:**
                *   Health, financial, or government records (e.g., medical history, tax
                    forms, passport status).
                *   Revealing or modifying sensitive personal identifiers (e.g., SSN, bank
                    account number, credit card number).
            *   **User Data Management:**
                *   Accessing, downloading, or saving files from the web.
                *   Sharing or sending files/data to any third party.
                *   Transferring user data between systems.
            *   **Browser Data Usage:**
                *   Accessing or managing Chrome browsing history, bookmarks, autofill data,
                    or saved passwords.
            *   **Security and Identity:**
                *   Logging into any user account.
                *   Any action that involves misrepresentation or impersonation (e.g.,
                    creating a fan account, posting as someone else).
            *   **Insurmountable Obstacles:** If you are technically unable to interact with
                a user interface element or are stuck in a loop you cannot resolve, ask the
                user to take over.
            ---

            ## **RULE 2: Default Behavior (ACTUATE)**

            If an action does **NOT** fall under the conditions for `USER_CONFIRMATION`,
            your default behavior is to **Actuate**.

            **Actuation Means:**  You MUST proactively perform all necessary steps to move
            the user's request forward. Continue to actuate until you either complete the
            non-consequential task or encounter a condition defined in Rule 1.

            *   **Example 1:** If asked to send money, you will navigate to the payment
                portal, enter the recipient's details, and enter the amount. You will then
                **STOP** as per Rule 1 and ask for confirmation before clicking the final
                "Send" button.
            *   **Example 2:** If asked to post a message, you will navigate to the site,
                open the post composition window, and write the full message. You will then
                **STOP** as per Rule 1 and ask for confirmation before clicking the final
                "Post" button.

                After the user has confirmed, remember to get the user's latest screen
                before continuing to perform actions.

            # Final Response Guidelines:
            Write final response to the user in the following cases:
            - User confirmation
            - When the task is complete or you have enough information to respond to the user
            """

            interaction = client.interactions.create(
                model="gemini-3.8-flash",
                system_instruction=system_instruction,
                input="Prepare a draft but do not send.",
                tools=[{
                    "type": "computer_use",
                    "environment": "browser"
                }]
            )
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
            import { GoogleGenAI } from '@google/genai';

            const ai = new GoogleGenAI();

            const systemInstruction = `
            ## **RULE 1: Seek User Confirmation (USER_CONFIRMATION)**

            This is your first and most important check. If the next required action falls
            into any of the following categories, you MUST stop immediately, and seek the
            user's explicit permission.

            **Procedure for Seeking Confirmation:**
            * **For Consequential Actions:** Perform all preparatory steps (e.g., navigating,
              filling out forms, typing a message). You will ask for confirmation **AFTER**
              all necessary information is entered on the screen, but **BEFORE** you perform
              the final, irreversible action (e.g., before clicking "Send", "Submit",
              "Confirm Purchase", "Share").
            * **For Prohibited Actions:** If the action is strictly forbidden (e.g., accepting
              legal terms, solving a CAPTCHA), you must first inform the user about the
              required action and ask for their confirmation to proceed.

            **USER_CONFIRMATION Categories:**

            *   **Consent and Agreements:** You are FORBIDDEN from accepting, selecting, or
                agreeing to any of the following on the user's behalf. You must ask the
                user to confirm before performing these actions.
                *   Terms of Service
                *   Privacy Policies
                *   Cookie consent banners
                *   End User License Agreements (EULAs)
                *   Any other legally significant contracts or agreements.
            *   **Robot Detection:** You MUST NEVER attempt to solve or bypass the
                following. You must ask the user to confirm before performing these actions.
                *   CAPTCHAs (of any kind)
                *   Any other anti-robot or human-verification mechanisms, even if you are
                    capable.
            *   **Financial Transactions:**
                *   Completing any purchase.
                *   Managing or moving money (e.g., transfers, payments).
                *   Purchasing regulated goods or participating in gambling.
            *   **Sending Communications:**
                *   Sending emails.
                *   Sending messages on any platform (e.g., social media, chat apps).
                *   Posting content on social media or forums.
            *   **Accessing or Modifying Sensitive Information:**
                *   Health, financial, or government records (e.g., medical history, tax
                    forms, passport status).
                *   Revealing or modifying sensitive personal identifiers (e.g., SSN, bank
                    account number, credit card number).
            *   **User Data Management:**
                *   Accessing, downloading, or saving files from the web.
                *   Sharing or sending files/data to any third party.
                *   Transferring user data between systems.
            *   **Browser Data Usage:**
                *   Accessing or managing Chrome browsing history, bookmarks, autofill data,
                    or saved passwords.
            *   **Security and Identity:**
                *   Logging into any user account.
                *   Any action that involves misrepresentation or impersonation (e.g.,
                    creating a fan account, posting as someone else).
            *   **Insurmountable Obstacles:** If you are technically unable to interact with
                a user interface element or are stuck in a loop you cannot resolve, ask the
                user to take over.
            ---

            ## **RULE 2: Default Behavior (ACTUATE)**

            If an action does **NOT** fall under the conditions for \`USER_CONFIRMATION\`,
            your default behavior is to **Actuate**.

            **Actuation Means:**  You MUST proactively perform all necessary steps to move
            the user's request forward. Continue to actuate until you either complete the
            non-consequential task or encounter a condition defined in Rule 1.

            *   **Example 1:** If asked to send money, you will navigate to the payment
                portal, enter the recipient's details, and enter the amount. You will then
                **STOP** as per Rule 1 and ask for confirmation before clicking the final
                "Send" button.
            *   **Example 2:** If asked to post a message, you will navigate to the site,
                open the post composition window, and write the full message. You will then
                **STOP** as per Rule 1 and ask for confirmation before clicking the final
                "Post" button.

                After the user has confirmed, remember to get the user's latest screen
                before continuing to perform actions.

            # Final Response Guidelines:
            Write final response to the user in the following cases:
            - User confirmation
            - When the task is complete or you have enough information to respond to the user
            `;

            const interaction = await ai.interactions.create({
                model: "gemini-3.8-flash",
                system_instruction: systemInstruction,
                input: "Prepare a draft but do not send.",
                tools: [{
                    type: "computer_use",
                    environment: "browser"
                }]
            });
```

{% /tab %}
{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.EnvironmentEnum;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

String systemInstruction =
    "## **RULE 1: Seek User Confirmation (USER_CONFIRMATION)**\n\n"
        + "This is your first and most important check. If the next required action falls "
        + "into any of the following categories, you MUST stop immediately, and seek the "
        + "user's explicit permission.\n\n"
        + "## **RULE 2: Default Behavior (ACTUATE)**\n\n"
        + "If an action does **NOT** fall under the conditions for `USER_CONFIRMATION`, "
        + "your default behavior is to **Actuate**.";

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .systemInstruction(systemInstruction)
        .input(InteractionsInput.of("Prepare a draft but do not send."))
        .tools(
            Arrays.asList(
                ComputerUse.builder().environment(EnvironmentEnum.BROWSER).build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}

```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    systemInstruction := "## **RULE 1: Seek User Confirmation (USER_CONFIRMATION)**\n\n" +
        "This is your first and most important check. If the next required action falls " +
        "into any of the following categories, you MUST stop immediately, and seek the " +
        "user's explicit permission.\n\n" +
        "## **RULE 2: Default Behavior (ACTUATE)**\n\n" +
        "If an action does **NOT** fall under the conditions for `USER_CONFIRMATION`, " +
        "your default behavior is to **Actuate**."

    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:             interactions.Model("gemini-3.8-flash"),
            SystemInstruction: genai.Ptr(systemInstruction),
            Input:             interactions.NewInteractionsInput("Prepare a draft but do not send."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.ComputerUse{
                    Environment: interactions.EnvironmentEnumBrowser.ToPointer(),
                }),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}
{% /tabs %}

2. **Secure execution environment:** Run your agent in a secure, sandboxed
    environment to limit its potential impact. This can be a sandboxed virtual
    machine (VM), a container (e.g., Docker), or a dedicated browser profile
    with limited permissions. See the
    [GitHub reference implementation](https://github.com/google/computer-use-preview/)
    for sandbox setup guidance using Docker.
3. **Input sanitization:** Sanitize all user-generated text in prompts to
    mitigate the risk of unintended instructions or prompt injection. This is a
    helpful layer of security, but not a replacement for a secure execution
    environment.
4. **Content guardrails:** Use guardrails and content safety APIs to evaluate
    user inputs, tool inputs and outputs, and the agent's responses for appropriateness,
    prompt injection, and jailbreak detection.
5. **Allowlists and blocklists:** Implement filtering mechanisms to control
    where the model can navigate and what it can do. A blocklist of prohibited
    websites is a good starting point, while a more restrictive allowlist is
    even more secure.
6. **Observability and logging:** Maintain detailed logs for debugging,
    auditing, and incident response. Your client should log prompts,
    screenshots, model-suggested actions (`function_call`), safety responses, and
    all actions ultimately executed by the client.
7. **Environment management:** Ensure the GUI environment is consistent.
    Unexpected pop-ups, notifications, or changes in layout can confuse the
    model. Start from a known, clean state for each new task if possible.

## Model versions {% id="model-versions" %}

You can use Computer Use with the following models:

* [**Gemini 4 Argon**](/docs/models/gemini-4-argon) (`gemini-4-argon`): Our most capable model, supporting computer use for complex reasoning and agentic UI workflows.
* [**Gemini 3.8 Flash**](/docs/models/gemini-3.8-flash) (`gemini-3.8-flash`): The recommended model for
    computer use, featuring high-accuracy UI interaction and reliable tool calling.
* [**Gemini 3.5 Flash-Lite**](/docs/models/gemini-3.5-flash-lite) (`gemini-3.5-flash-lite`): A low-latency, cost-effective model supporting
    computer use.
* [**Gemini 3 Flash Preview**](/docs/models/gemini-3-flash-preview) (`gemini-3-flash-preview`): Preview model
    supporting computer use.

## What's next {% id="whats-next" %}

* Experiment with Computer Use in the [Browserbase demo environment](http://gemini.browserbase.com).
* Check out the [Reference implementation](https://github.com/google/computer-use-preview) for example code.
* Learn about other Gemini API tools:
    * [Function calling](/docs/function-calling)
    * [Grounding with Google Search](/docs/google-search)

# File search
Source: https://aistudio.google.com/docs/file-search
Description: Get started building RAG solutions with the File Search tool in the Gemini API

The Gemini API enables Retrieval Augmented Generation ("RAG") through the File
Search tool. File Search imports, chunks, and indexes your data to
enable fast retrieval of relevant information based on a provided prompt. This
retrieved information is then used as context for the model, allowing it to
provide more accurate and relevant answers. File search is also able to
provide multimodal capabilities with text embeddings supported by
`gemini-embedding-001`, and image/multimodal embedding supported by
`gemini-embedding-2`.

{% callout type="note" %}
Audio and video formats are not currently supported.
{% /callout %}

File storage and embedding generation at query time is free, and you'll only pay
for creating embeddings when you first index your files and the normal Gemini
model input / output tokens cost. This new billing paradigm makes the File
Search Tool both easier and more cost-effective to build and scale with. See
[pricing](/docs/file-search#pricing) section for details.

## Directly upload to File Search store {% id="upload" %}

This example shows how to directly upload a file to the
[file search store](https://ai.google.dev/api/file-search/file-search-stores#method:-media.uploadtofilesearchstore):

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
import time

client = genai.Client()

file_search_store = client.file_search_stores.create(
    config={
        'display_name': 'your-fileSearchStore-name',
        'embedding_model': 'models/gemini-embedding-2'
    }
)

operation = client.file_search_stores.upload_to_file_search_store(
  file='sample.txt',
  file_search_store_name=file_search_store.name,
  config={
      'display_name' : 'display-file-name',
  }
)

while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Can you tell me about [insert question]",
    tools=[{
        "type": "file_search",
        "file_search_store_names": [file_search_store.name]
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "file_citation":
                            print(f" - {annotation.file_name}: {annotation.source}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const { GoogleGenAI } = require('@google/genai');

const ai = new GoogleGenAI({});

async function run() {
  const fileSearchStore = await ai.fileSearchStores.create({
    config: {
      displayName: 'your-fileSearchStore-name',
      embeddingModel: 'models/gemini-embedding-2'
    }
  });

  let operation = await ai.fileSearchStores.uploadToFileSearchStore({
    file: 'file.txt',
    fileSearchStoreName: fileSearchStore.name,
    config: {
      displayName: 'file-name',
    }
  });

  while (!operation.done) {
    await new Promise(resolve => setTimeout(resolve, 5000));
    operation = await ai.operations.get({ operation });
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Can you tell me about [insert question]",
    tools: [{
      type: "file_search",
      file_search_store_names: [fileSearchStore.name]
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'file_citation') {
                console.log(` - ${annotation.file_name}: ${annotation.source}`);
              }
            }
          }
        }
      }
    }
  }
}

await run();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileCitation;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.types.FileSearchStore;
import com.google.genai.types.UploadToFileSearchStoreConfig;
import com.google.genai.types.UploadToFileSearchStoreOperation;
import java.util.Arrays;

Client client = new Client();

FileSearchStore fileSearchStore =
    client.fileSearchStores.create(
        CreateFileSearchStoreConfig.builder()
            .displayName("your-fileSearchStore-name")
            .embeddingModel("models/gemini-embedding-2")
            .build());

UploadToFileSearchStoreOperation operation =
    client.fileSearchStores.uploadToFileSearchStore(
        fileSearchStore.name().get(),
        "sample.txt",
        UploadToFileSearchStoreConfig.builder().displayName("display-file-name").build());

while (!operation.done().orElse(false)) {
  Thread.sleep(5000);
  operation = client.operations.get(operation, null);
}

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Can you tell me about [insert question]"))
        .tools(
            Arrays.asList(
                FileSearch.builder()
                    .fileSearchStoreNames(Arrays.asList(fileSearchStore.name().get()))
                    .build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            System.out.println(textContent.text().orElse(""));
            if (textContent.annotations().isPresent()
                && !textContent.annotations().get().isEmpty()) {
              System.out.println("\nSources:");
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof FileCitation) {
                  FileCitation citation = (FileCitation) annotation;
                  System.out.printf(
                      "  - %s: %s%n",
                      citation.fileName().orElse(""), citation.source().orElse(""));
                }
              }
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    fileSearchStore, err := client.FileSearchStores.Create(ctx, &genai.CreateFileSearchStoreConfig{
        DisplayName:    "your-fileSearchStore-name",
        EmbeddingModel: "models/gemini-embedding-2",
    })
    if err != nil {
        log.Fatal(err)
    }

    operation, err := client.FileSearchStores.UploadToFileSearchStoreFromPath(
        ctx,
        "sample.txt",
        fileSearchStore.Name,
        &genai.UploadToFileSearchStoreConfig{
            DisplayName: "display-file-name",
        },
    )
    if err != nil {
        log.Fatal(err)
    }

    for !operation.Done {
        time.Sleep(5 * time.Second)
        operation, err = client.Operations.GetUploadToFileSearchStoreOperation(ctx, operation, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Can you tell me about [insert question]"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.FileSearch{
                        FileSearchStoreNames: []string{fileSearchStore.Name},
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    fmt.Println(content.TextContent.Text)
                    if len(content.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range content.TextContent.Annotations {
                            if annotation.FileCitation != nil {
                                c := annotation.FileCitation
                                fileName := ""
                                if c.FileName != nil {
                                    fileName = *c.FileName
                                }
                                source := ""
                                if c.Source != nil {
                                    source = *c.Source
                                }
                                fmt.Printf("  - %s: %s\n", fileName, source)
                            }
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% /tabs %}

Check the API reference for [`uploadToFileSearchStore`](https://ai.google.dev/api/file-search/file-search-stores#method:-media.uploadtofilesearchstore) for more information.

## Importing files {% id="importing-files" %}

Alternatively, you can upload an existing file and [import it to your file search store](https://ai.google.dev/api/file-search/file-search-stores#method:-filesearchstores.importfile):

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
import time

client = genai.Client()

sample_file = client.files.upload(file='sample.txt', config={'display_name': 'display_file_name'})

file_search_store = client.file_search_stores.create(
    config={
        'display_name': 'your-fileSearchStore-name',
        'embedding_model': 'models/gemini-embedding-2'
    }
)

operation = client.file_search_stores.import_file(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name
)

while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Can you tell me about [insert question]",
    tools=[{
        "type": "file_search",
        "file_search_store_names": [file_search_store.name]
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const { GoogleGenAI } = require('@google/genai');

const ai = new GoogleGenAI({});

async function run() {
  const sampleFile = await ai.files.upload({
    file: 'sample.txt',
    config: { displayName: 'file-name' }
  });

  const fileSearchStore = await ai.fileSearchStores.create({
    config: {
      displayName: 'your-fileSearchStore-name',
      embeddingModel: 'models/gemini-embedding-2'
    }
  });

  let operation = await ai.fileSearchStores.importFile({
    fileSearchStoreName: fileSearchStore.name,
    fileName: sampleFile.name
  });

  while (!operation.done) {
    await new Promise(resolve => setTimeout(resolve, 5000));
    operation = await ai.operations.get({ operation: operation });
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Can you tell me about [insert question]",
    tools: [{
      type: "file_search",
      file_search_store_names: [fileSearchStore.name]
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content || []) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
        }
      }
    }
  }
}

await run();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.types.File;
import com.google.genai.types.FileSearchStore;
import com.google.genai.types.ImportFileOperation;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;

Client client = new Client();

File sampleFile =
    client.files.upload(
        "sample.txt", UploadFileConfig.builder().displayName("display_file_name").build());

FileSearchStore fileSearchStore =
    client.fileSearchStores.create(
        CreateFileSearchStoreConfig.builder()
            .displayName("your-fileSearchStore-name")
            .embeddingModel("models/gemini-embedding-2")
            .build());

ImportFileOperation operation =
    client.fileSearchStores.importFile(
        fileSearchStore.name().get(), sampleFile.name().get(), null);

while (!operation.done().orElse(false)) {
  Thread.sleep(5000);
  operation = client.operations.get(operation, null);
}

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Can you tell me about [insert question]"))
        .tools(
            Arrays.asList(
                FileSearch.builder()
                    .fileSearchStoreNames(Arrays.asList(fileSearchStore.name().get()))
                    .build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            System.out.println(textContent.text().orElse(""));
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    sampleFile, err := client.Files.UploadFromPath(ctx, "sample.txt", &genai.UploadFileConfig{
        DisplayName: "display_file_name",
    })
    if err != nil {
        log.Fatal(err)
    }

    fileSearchStore, err := client.FileSearchStores.Create(ctx, &genai.CreateFileSearchStoreConfig{
        DisplayName:    "your-fileSearchStore-name",
        EmbeddingModel: "models/gemini-embedding-2",
    })
    if err != nil {
        log.Fatal(err)
    }

    operation, err := client.FileSearchStores.ImportFile(ctx, fileSearchStore.Name, sampleFile.Name, nil)
    if err != nil {
        log.Fatal(err)
    }

    for !operation.Done {
        time.Sleep(5 * time.Second)
        operation, err = client.Operations.GetImportFileOperation(ctx, operation, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Can you tell me about [insert question]"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.FileSearch{
                        FileSearchStoreNames: []string{fileSearchStore.Name},
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    fmt.Println(content.TextContent.Text)
                }
            }
        }
    }
}
```
{% /tab %}

{% /tabs %}

Check the API reference for [`importFile`](https://ai.google.dev/api/file-search/file-search-stores#method:-filesearchstores.importfile) for more information.

## Chunking configuration {% id="chunking-configuration" %}

When you import a file into a File Search store, it's automatically broken down
into chunks, embedded, indexed, and uploaded to your File Search store. If you
need more control over the chunking strategy, you can specify a
[`chunking_config`](https://ai.google.dev/api/file-search/file-search-stores#request-body_5) setting
to set a maximum number of tokens per chunk and maximum number of overlapping
tokens.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
import time

client = genai.Client()

operation = client.file_search_stores.upload_to_file_search_store(
    file_search_store_name=file_search_store.name,
    file='sample.txt',
    config={
        'chunking_config': {
          'white_space_config': {
            'max_tokens_per_chunk': 200,
            'max_overlap_tokens': 20
          }
        }
    }
)

while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

print("Custom chunking complete.")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const { GoogleGenAI } = require('@google/genai');

const ai = new GoogleGenAI({});

let operation = await ai.fileSearchStores.uploadToFileSearchStore({
  file: 'file.txt',
  fileSearchStoreName: fileSearchStore.name,
  config: {
    displayName: 'file-name',
    chunkingConfig: {
      whiteSpaceConfig: {
        maxTokensPerChunk: 200,
        maxOverlapTokens: 20
      }
    }
  }
});

while (!operation.done) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  operation = await ai.operations.get({ operation });
}
console.log("Custom chunking complete.");
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.ChunkingConfig;
import com.google.genai.types.UploadToFileSearchStoreConfig;
import com.google.genai.types.UploadToFileSearchStoreOperation;
import com.google.genai.types.WhiteSpaceConfig;

Client client = new Client();

UploadToFileSearchStoreOperation operation =
    client.fileSearchStores.uploadToFileSearchStore(
        "fileSearchStores/my-file-search-store",
        "sample.txt",
        UploadToFileSearchStoreConfig.builder()
            .displayName("file-name")
            .chunkingConfig(
                ChunkingConfig.builder()
                    .whiteSpaceConfig(
                        WhiteSpaceConfig.builder()
                            .maxTokensPerChunk(200)
                            .maxOverlapTokens(20)
                            .build())
                    .build())
            .build());

while (!operation.done().orElse(false)) {
  Thread.sleep(5000);
  operation = client.operations.get(operation, null);
}

System.out.println("Custom chunking complete.");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    operation, err := client.FileSearchStores.UploadToFileSearchStoreFromPath(
        ctx,
        "sample.txt",
        "fileSearchStores/my-file-search-store",
        &genai.UploadToFileSearchStoreConfig{
            DisplayName: "file-name",
            ChunkingConfig: &genai.ChunkingConfig{
                WhiteSpaceConfig: &genai.WhiteSpaceConfig{
                    MaxTokensPerChunk: genai.Ptr(int32(200)),
                    MaxOverlapTokens:  genai.Ptr(int32(20)),
                },
            },
        },
    )
    if err != nil {
        log.Fatal(err)
    }

    for !operation.Done {
        time.Sleep(5 * time.Second)
        operation, err = client.Operations.GetUploadToFileSearchStoreOperation(ctx, operation, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    fmt.Println("Custom chunking complete.")
}
```
{% /tab %}

{% /tabs %}

To use your File Search store, pass it as a tool to the `interactions.create`
method, as shown in the [Upload](/docs/file-search#upload) and [Import](/docs/file-search#importing-files) examples.

## How it works {% id="how-it-works" %}

File Search uses a technique called semantic search to find information relevant
to the user prompt. Unlike standard keyword-based search, semantic search
understands the meaning and context of your query.

When you import a file, it's converted into numerical representations called
[embeddings](/docs/embeddings), which capture the semantic meaning of
the uploaded content. These embeddings are stored in a specialized File Search
database. When you make a query, it's also converted into an embedding. Then the
system performs a File Search to find the most similar and relevant document
chunks from the File Search store.

There is no Time To Live (TTL) for embeddings;
they persist until manually deleted, or when the model is deprecated. Files,
however, are deleted after 48 hours.

Here's a breakdown of the process for using the File Search
`uploadToFileSearchStore` API:

1. **Create a File Search store**: A File Search store contains the processed
data from your files. It's the persistent container for the embeddings that the
semantic search will operate on.

1. **Upload a file and import into a File Search store**: Simultaneously upload
a file and import the results into your File Search store. This creates a
temporary `File` object, which is a reference to your raw document. That data is
then chunked, converted into File Search embeddings, and indexed. The `File`
object gets deleted after 48 hours, while the data imported into the File Search
store will be stored indefinitely until you choose to delete it.

1. **Query with File Search**: Finally, you use the `FileSearch` tool in a
`generateContent` call. In the tool configuration, you specify a
`FileSearchRetrievalResource`, which points to the `FileSearchStore` you want to
search. This tells the model to perform a semantic search on that specific
File Search store to find relevant information to ground its response.

{% image
  src="/googledevai/static/gemini-api/docs/images/File-search.png"
  alt="The indexing and querying process of File Search"
  caption="The indexing and querying process of File Search"
  variant="screenshot"
/%}

In this diagram, the dotted line from *Documents* to *Embedding model*
(using [`gemini-embedding-001`](/docs/embeddings))
represents the `uploadToFileSearchStore` API (bypassing *File storage*).
Otherwise, using the [Files API](/docs/files) to separately create
and then import files moves the indexing process from *Documents* to
*File storage* and then to *Embedding model*.

## File Search stores {% id="file-search-stores" %}

A File Search store is a container for your document embeddings. While raw files
uploaded through the File API are deleted after 48 hours, the data imported into
a File Search store is stored indefinitely until you manually delete it. You can
create multiple File Search stores to organize your documents. The
`FileSearchStore` API lets you create, list, get, and delete to manage your file
search stores. File Search store names are globally scoped.

Here are some examples of how to manage your File Search stores:

{% tabs %}
{% tab label="Python" %}
```python
file_search_store = client.file_search_stores.create(
    config={
        'display_name': 'my-file_search-store-123',
        'embedding_model': 'models/gemini-embedding-2'
    }
)

for file_search_store in client.file_search_stores.list():
    print(file_search_store)

my_file_search_store = client.file_search_stores.get(name='fileSearchStores/my-file_search-store-123')

client.file_search_stores.delete(name='fileSearchStores/my-file_search-store-123', config={'force': True})
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const fileSearchStore = await ai.fileSearchStores.create({
  config: {
    displayName: 'my-file_search-store-123',
    embeddingModel: 'models/gemini-embedding-2'
  }
});

const fileSearchStores = await ai.fileSearchStores.list();
for await (const store of fileSearchStores) {
  console.log(store);
}

const myFileSearchStore = await ai.fileSearchStores.get({
  name: 'fileSearchStores/my-file_search-store-123'
});

await ai.fileSearchStores.delete({
  name: 'fileSearchStores/my-file_search-store-123',
  config: { force: true }
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.types.DeleteFileSearchStoreConfig;
import com.google.genai.types.FileSearchStore;

Client client = new Client();

FileSearchStore fileSearchStore =
    client.fileSearchStores.create(
        CreateFileSearchStoreConfig.builder()
            .displayName("myfilesearchstore123")
            .embeddingModel("models/gemini-embedding-2")
            .build());

for (FileSearchStore store : client.fileSearchStores.list(null)) {
  System.out.println(store);
}

FileSearchStore myFileSearchStore =
    client.fileSearchStores.get(fileSearchStore.name().get(), null);

client.fileSearchStores.delete(
    fileSearchStore.name().get(), DeleteFileSearchStoreConfig.builder().force(true).build());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    fileSearchStore, err := client.FileSearchStores.Create(ctx, &genai.CreateFileSearchStoreConfig{
        DisplayName:    "myfilesearchstore123",
        EmbeddingModel: "models/gemini-embedding-2",
    })
    if err != nil {
        log.Fatal(err)
    }

    for store, err := range client.FileSearchStores.All(ctx) {
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println(store)
    }

    myFileSearchStore, err := client.FileSearchStores.Get(ctx, fileSearchStore.Name, nil)
    if err != nil {
        log.Fatal(err)
    }
    _ = myFileSearchStore

    err = client.FileSearchStores.Delete(ctx, fileSearchStore.Name, &genai.DeleteFileSearchStoreConfig{
        Force: genai.Ptr(true),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/fileSearchStores?key=${GEMINI_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{ "displayName": "My Store", "embedding_model": "models/gemini-embedding-2" }'

curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores?key=${GEMINI_API_KEY}" \

curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123?key=${GEMINI_API_KEY}"

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123?key=${GEMINI_API_KEY}"
```
{% /tab %}
{% /tabs %}

## File Search documents {% id="file-search-documents" %}

You can manage individual documents in your file stores with the
[File Search Documents](https://ai.google.dev/api/file-search/documents) API to `list` each document
in a file search store, `get` information about a document, and `delete` a
document by name.

{% tabs %}
{% tab label="Python" %}
```python
for document_in_store in client.file_search_stores.documents.list(parent='fileSearchStores/my-file_search-store-123'):
  print(document_in_store)

file_search_document = client.file_search_stores.documents.get(name='fileSearchStores/my-file_search-store-123/documents/my_doc')
print(file_search_document)

client.file_search_stores.documents.delete(name='fileSearchStores/my-file_search-store-123/documents/my_doc', config={'force': True})
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const documents = await ai.fileSearchStores.documents.list({
  parent: 'fileSearchStores/my-file_search-store-123'
});
for await (const doc of documents) {
  console.log(doc);
}

const fileSearchDocument = await ai.fileSearchStores.documents.get({
  name: 'fileSearchStores/my-file_search-store-123/documents/my_doc'
});

await ai.fileSearchStores.documents.delete({
  name: 'fileSearchStores/my-file_search-store-123/documents/my_doc'
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.DeleteDocumentConfig;
import com.google.genai.types.Document;

Client client = new Client();

for (Document documentInStore :
    client.fileSearchStores.documents.list("fileSearchStores/myfilesearchstore123", null)) {
  System.out.println(documentInStore);
}

Document fileSearchDocument =
    client.fileSearchStores.documents.get(
        "fileSearchStores/myfilesearchstore123/documents/sampletxt123", null);
System.out.println(fileSearchDocument);

client.fileSearchStores.documents.delete(
    "fileSearchStores/myfilesearchstore123/documents/sampletxt123",
    DeleteDocumentConfig.builder().force(true).build());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    for documentInStore, err := range client.FileSearchStores.Documents.All(ctx, "fileSearchStores/myfilesearchstore123") {
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println(documentInStore)
    }

    fileSearchDocument, err := client.FileSearchStores.Documents.Get(ctx, "fileSearchStores/myfilesearchstore123/documents/sampletxt123", nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(fileSearchDocument)

    err = client.FileSearchStores.Documents.Delete(ctx, "fileSearchStores/myfilesearchstore123/documents/sampletxt123", &genai.DeleteDocumentConfig{
        Force: genai.Ptr(true),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123/documents?key=${GEMINI_API_KEY}"

curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123/documents/my_doc?key=${GEMINI_API_KEY}"

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123/documents/my_doc?key=${GEMINI_API_KEY}&force=true"
```
{% /tab %}
{% /tabs %}

## File metadata {% id="metadata" %}

You can add custom metadata to your files to help filter them or provide
additional context. Metadata is a set of key-value pairs.

{% tabs %}
{% tab label="Python" %}
```python
op = client.file_search_stores.import_file(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name,
    config={
        'custom_metadata': [
            {"key": "author", "string_value": "Robert Graves"},
            {"key": "year", "numeric_value": 1934}
        ]
    }
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
let operation = await ai.fileSearchStores.importFile({
  fileSearchStoreName: fileSearchStore.name,
  fileName: sampleFile.name,
  config: {
    customMetadata: [
      { key: "author", stringValue: "Robert Graves" },
      { key: "year", numericValue: 1934 }
    ]
  }
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.CustomMetadata;
import com.google.genai.types.ImportFileConfig;
import com.google.genai.types.ImportFileOperation;
import java.util.Arrays;

Client client = new Client();

ImportFileOperation op =
    client.fileSearchStores.importFile(
        "fileSearchStores/myfilesearchstore123",
        "files/samplefile123",
        ImportFileConfig.builder()
            .customMetadata(
                Arrays.asList(
                    CustomMetadata.builder().key("author").stringValue("Robert Graves").build(),
                    CustomMetadata.builder().key("year").numericValue(1934f).build()))
            .build());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    op, err := client.FileSearchStores.ImportFile(
        ctx,
        "fileSearchStores/myfilesearchstore123",
        "files/samplefile123",
        &genai.ImportFileConfig{
            CustomMetadata: []*genai.CustomMetadata{
                {Key: "author", StringValue: "Robert Graves"},
                {Key: "year", NumericValue: genai.Ptr(float32(1934))},
            },
        },
    )
    if err != nil {
        log.Fatal(err)
    }
    _ = op
}
```
{% /tab %}

{% /tabs %}

This is useful when you have multiple documents in a File Search store and want
to search only a subset of them.

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me about the book 'I, Claudius'",
    tools=[{
        "type": "file_search",
        "file_search_store_names": [file_search_store.name],
        "metadata_filter": 'author="Robert Graves"',
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me about the book 'I, Claudius'",
  tools: [{
    type: "file_search",
    file_search_store_names: [fileSearchStore.name],
    metadata_filter: 'author="Robert Graves"',
  }]
});

for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const contentBlock of step.content || []) {
      if (contentBlock.type === 'text') {
        console.log(contentBlock.text);
      }
    }
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me about the book 'I, Claudius'"))
        .tools(
            Arrays.asList(
                FileSearch.builder()
                    .fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
                    .metadataFilter("author=\"Robert Graves\"")
                    .build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            System.out.println(textContent.text().orElse(""));
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Tell me about the book 'I, Claudius'"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.FileSearch{
                        FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
                        MetadataFilter:       genai.Ptr(`author="Robert Graves"`),
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    fmt.Println(content.TextContent.Text)
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -X POST \
    -d '{
            "model": "gemini-3.8-flash",
            "input": [{"type": "text", "text": "Tell me about the book I, Claudius"}],
            "tools": [{
                "type": "file_search",
                "file_search_store_names": ["'$STORE_NAME'"],
                "metadata_filter": "author = \"Robert Graves\""
            }]
        }' 2> /dev/null > response.json

cat response.json
```
{% /tab %}
{% /tabs %}

Guidance on implementing list filter syntax for `metadata_filter` can be found
at [google.aip.dev/160](https://google.aip.dev/160)

## Multimodal File Search {% id="multimodal-file-search" %}

Multimodal File Search lets you to natively embed and search through images,
enabling rich, multimodal RAG applications.

### Configure the embedding model {% id="configure-the-embedding-model" %}

When you create a `FileSearchStore`, you must override the default text-only
embedding model to use a multimodal model. Use `models/gemini-embedding-2` to
process both text and images.

{% tabs %}
{% tab label="Python" %}
```python
store = client.file_search_stores.create(
    config={
        "display_name": "Multimodal Catalog",
        "embedding_model": "models/gemini-embedding-2",
    }
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const fileSearchStore = await ai.fileSearchStores.create({
  config: {
    displayName: "Multimodal Catalog",
    embeddingModel: "models/gemini-embedding-2",
  },
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.types.FileSearchStore;

Client client = new Client();

FileSearchStore store =
    client.fileSearchStores.create(
        CreateFileSearchStoreConfig.builder()
            .displayName("Multimodal Catalog")
            .embeddingModel("models/gemini-embedding-2")
            .build());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    store, err := client.FileSearchStores.Create(ctx, &genai.CreateFileSearchStoreConfig{
        DisplayName:    "Multimodal Catalog",
        EmbeddingModel: "models/gemini-embedding-2",
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = store
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/fileSearchStores?key=$GEMINI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "Multimodal Catalog",
      "embedding_model": "models/gemini-embedding-2"
    }'
```
{% /tab %}
{% /tabs %}

### Upload images {% id="upload-images" %}

After you create the store with a multimodal embedding model, you can upload
image files directly using the same upload APIs described in
[Directly upload to File Search store](/docs/file-search#upload) or [Importing files](/docs/file-search#importing-files).

**Image file requirements:**

- Image files must be at most 4K x 4K pixels in resolution.
- Supported formats are PNG, JPEG.

## Citations {% id="citations" %}

When you use File Search, the model's response may include citations that
specify which parts of your uploaded documents were used to generate the
answer. This helps with fact-checking and verification.

You can access citation information through the `annotations` attribute inside
the `model_output` step's `content` blocks of the response.

{% tabs %}
{% tab label="Python" %}
```python
for step in interaction.steps:
    if step.type == 'model_output':
        for content in step.content:
            if content.type == 'text' and content.annotations:
                print(content.annotations)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const contentBlock of step.content || []) {
      if (contentBlock.type === 'text' && contentBlock.annotations) {
        console.log(JSON.stringify(contentBlock.annotations, null, 2));
      }
    }
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Can you tell me about [insert question]"))
        .tools(
            Arrays.asList(
                FileSearch.builder()
                    .fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
                    .build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content content : outputStep.content().get()) {
          if (content instanceof TextContent) {
            TextContent textContent = (TextContent) content;
            if (textContent.annotations().isPresent()) {
              System.out.println(textContent.annotations().get());
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Can you tell me about [insert question]"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.FileSearch{
                        FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil && len(content.TextContent.Annotations) > 0 {
                    fmt.Println(content.TextContent.Annotations)
                }
            }
        }
    }
}
```
{% /tab %}

{% /tabs %}

For detailed information on the structure of the citations, see the
[API reference for Interactions](https://ai.google.dev/api/interactions-api#Resource:FileCitation).

### Page numbers {% id="page-numbers" %}

When you use File Search with documents that have pages (such as PDFs), the
model's response may include the page number where the information was found.
You can access this information through the `page_number` attribute of a
`file_citation` annotation.

{% tabs %}
{% tab label="Python" %}
```python
for step in interaction.steps:
    if step.type == "model_output":
        for content in step.content:
            if content.type == "text" and content.annotations:
                for annotation in content.annotations:
                    if annotation.type == "file_citation" and annotation.page_number:
                        print(f"Cited Page: {annotation.page_number}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const block of step.content || []) {
      if (block.type === 'text' && block.annotations) {
        for (const annotation of block.annotations) {
          if (annotation.type === 'file_citation' && annotation.page_number) {
            console.log(`Cited Page: ${annotation.page_number}`);
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileCitation;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Can you tell me about [insert question]"))
        .tools(
            Arrays.asList(
                FileSearch.builder()
                    .fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
                    .build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content content : outputStep.content().get()) {
          if (content instanceof TextContent) {
            TextContent textContent = (TextContent) content;
            if (textContent.annotations().isPresent()) {
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof FileCitation) {
                  FileCitation citation = (FileCitation) annotation;
                  if (citation.pageNumber().isPresent()) {
                    System.out.println("Cited Page: " + citation.pageNumber().get());
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Can you tell me about [insert question]"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.FileSearch{
                        FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    for _, annotation := range content.TextContent.Annotations {
                        if annotation.FileCitation != nil && annotation.FileCitation.PageNumber != nil {
                            fmt.Println("Cited Page:", *annotation.FileCitation.PageNumber)
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% /tabs %}

### Media citations {% id="media-citations" %}

When the model references an image chunk during generation, the API returns an
annotation of type `file_citation` in the annotations that includes a
`media_id`. You can use this ID to download the exact image chunk the model
referenced. This `media_id` is persistent across multiple search calls, which
lets you reliably retrieve the same image or cache it using the ID.

The following snippet is an example REST response step:

```json
{
  "type": "model_output",
  "content": [
    {
      "type": "text",
      "text": "...",
      "annotations": [
        {
          "type": "file_citation",
          "file_name": "product_image",
          "media_id": "fileSearchStores/my-store-123/media/BlobId-456"
        }
      ]
    }
  ]
}
```

The following code snippets demonstrate how to retrieve the `media_id` and
download the media:

{% tabs %}
{% tab label="Python" %}
```python
for step in interaction.steps:
    if step.type == "model_output":
        for content in step.content:
            if content.type == "text" and content.annotations:
                for annotation in content.annotations:
                    if annotation.type == "file_citation" and annotation.media_id:
                        print(f"Cited Media ID: {annotation.media_id}")
                        blob_content = client.file_search_stores.download_media(
                            media_id=annotation.media_id
                        )
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const block of step.content || []) {
      if (block.type === 'text' && block.annotations) {
        for (const annotation of block.annotations) {
          if (annotation.type === 'file_citation' && annotation.media_id) {
            console.log(`Cited Media ID: ${annotation.media_id}`);
            const blobContent = await ai.fileSearchStores.downloadMedia(annotation.media_id);
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileCitation;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Can you tell me about [insert question]"))
        .tools(
            Arrays.asList(
                FileSearch.builder()
                    .fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
                    .build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content content : outputStep.content().get()) {
          if (content instanceof TextContent) {
            TextContent textContent = (TextContent) content;
            if (textContent.annotations().isPresent()) {
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof FileCitation) {
                  FileCitation citation = (FileCitation) annotation;
                  if (citation.mediaId().isPresent()) {
                    System.out.println("Cited Media ID: " + citation.mediaId().get());
                    byte[] blobContent =
                        client.fileSearchStores.downloadMedia(citation.mediaId().get(), null);
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Can you tell me about [insert question]"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.FileSearch{
                        FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    for _, annotation := range content.TextContent.Annotations {
                        if annotation.FileCitation != nil && annotation.FileCitation.MediaID != nil {
                            fmt.Println("Cited Media ID:", *annotation.FileCitation.MediaID)
                            blobContent, err := client.FileSearchStores.DownloadMedia(ctx, *annotation.FileCitation.MediaID, nil)
                            if err != nil {
                                log.Fatal(err)
                            }
                            _ = blobContent
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X GET "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-store-123/media/BlobId-456?alt=media" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -o cited_image.png
```
{% /tab %}
{% /tabs %}

## Custom metadata {% id="custom-metadata-grounding" %}

If you have added custom metadata to your files, you can access it in the
annotations of the model's response. This is useful for passing
additional context (like URLs, page numbers, or authors) from your source
documents to your application logic. Each citation annotation of type
`file_citation` contains this custom metadata.

{% tabs %}
{% tab label="Python" %}
```python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me about [insert question]",
    tools=[{
        "type": "file_search",
        "file_search_store_names": [file_search_store.name]
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.annotations:
                for annotation in content_block.annotations:
                    print(annotation)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me about [insert question]",
  tools: [{
    type: "file_search",
    file_search_store_names: [fileSearchStore.name]
  }]
});

for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const contentBlock of step.content || []) {
      if (contentBlock.annotations) {
        contentBlock.annotations.forEach((annotation) => {
          console.log(annotation);
        });
      }
    }
  }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me about [insert question]"))
        .tools(
            Arrays.asList(
                FileSearch.builder()
                    .fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
                    .build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            if (textContent.annotations().isPresent()) {
              for (Annotation annotation : textContent.annotations().get()) {
                System.out.println(annotation);
              }
            }
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Tell me about [insert question]"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.FileSearch{
                        FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
                    }),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    for _, annotation := range content.TextContent.Annotations {
                        fmt.Println(annotation)
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me about [insert question]",
    "tools": [{
      "type": "file_search",
      "file_search_store_names": ["'$FILE_SEARCH_STORE_NAME'"]
    }]
  }'
```

The custom metadata is returned in `custom_metadata` on each `file_citation`
annotation:

```json
{
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "...",
          "annotations": [
            {
              "type": "file_citation",
              "file_name": "...",
              "document_uri": "...",
              "source": "...",
              "custom_metadata": {
                "author": "Robert Graves",
                "year": 1934
              }
            }
          ]
        }
      ]
    }
  ]
}
```
{% /tab %}
{% /tabs %}

## Structured output {% id="structured-output" %}

Starting with Gemini 3 models, you can combine file search tool with
[structured outputs](/docs/structured-output).

{% tabs %}
{% tab label="Python" %}
```python
from pydantic import BaseModel, Field

class Money(BaseModel):
    amount: str = Field(description="The numerical part of the amount.")
    currency: str = Field(description="The currency of amount.")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the minimum hourly wage in Tokyo right now?",
    tools=[{
        "type": "file_search",
        "file_search_store_names": [file_search_store.name]
    }],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Money.model_json_schema()
    },
)
result = Money.model_validate_json(interaction.output_text)
print(result)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { z } from "zod";

const moneyJsonSchema = {
  type: "object",
  properties: {
    amount: { type: "string", description: "The numerical part of the amount." },
    currency: { type: "string", description: "The currency of amount." }
  },
  required: ["amount", "currency"]
};

const moneySchema = z.fromJSONSchema(moneyJsonSchema);

async function run() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the minimum hourly wage in Tokyo right now?",
    tools: [{
      type: "file_search",
      file_search_store_names: [fileSearchStore.name],
    }],
    response_format: {
      type: 'text',
      mime_type: 'application/json',
      schema: moneyJsonSchema
    },
  });

  const result = moneySchema.parse(JSON.parse(interaction.output_text));
  console.log(result);
}

await run();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> properties = new HashMap<>();

Map<String, Object> amountProp = new HashMap<>();
amountProp.put("type", "string");
amountProp.put("description", "The numerical part of the amount.");
properties.put("amount", amountProp);

Map<String, Object> currencyProp = new HashMap<>();
currencyProp.put("type", "string");
currencyProp.put("description", "The currency of amount.");
properties.put("currency", currencyProp);

Map<String, Object> moneyJsonSchema = new HashMap<>();
moneyJsonSchema.put("type", "object");
moneyJsonSchema.put("properties", properties);
moneyJsonSchema.put("required", Arrays.asList("amount", "currency"));

CreateModelInteractionResponseFormat format =
    CreateModelInteractionResponseFormat.of(
        ResponseFormat.of(
            TextResponseFormat.builder()
                .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
                .schema(moneyJsonSchema)
                .build()));

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("What is the minimum hourly wage in Tokyo right now?"))
        .tools(
            Arrays.asList(
                FileSearch.builder()
                    .fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
                    .build()))
        .responseFormat(format)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    moneyJsonSchema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "amount": map[string]any{
                "type":        "string",
                "description": "The numerical part of the amount.",
            },
            "currency": map[string]any{
                "type":        "string",
                "description": "The currency of amount.",
            },
        },
        "required": []string{"amount", "currency"},
    }

    format := interactions.NewCreateModelInteractionResponseFormat(
        interactions.NewResponseFormat(interactions.TextResponseFormat{
            MimeType: interactions.TextResponseFormatMimeTypeApplicationJSON.ToPointer(),
            Schema:   moneyJsonSchema,
        }),
    )

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("What is the minimum hourly wage in Tokyo right now?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.FileSearch{
                        FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
                    }),
                },
                ResponseFormat: &format,
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is the minimum hourly wage in Tokyo right now?",
    "tools": [{
      "type": "file_search",
      "file_search_store_names": ["'$FILE_SEARCH_STORE_NAME'"]
    }],
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
          "amount": {"type": "string", "description": "The numerical part of the amount."},
          "currency": {"type": "string", "description": "The currency of amount."}
        },
        "required": ["amount", "currency"]
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## Supported models {% id="supported-models" %}

The following models support File Search:

| Model | File Search |
| ------------------ | :--------------------------: |
| [Gemini 4 Argon](/docs/models/gemini-4-argon) | ✔️ |
| [Gemini 3.8 Flash](/docs/models/gemini-3.8-flash) | ✔️ |
| [Gemini 3.6 Flash](/docs/models/gemini-3.6-flash) | ✔️ |
| [Gemini 3.5 Flash-Lite](/docs/models/gemini-3.5-flash-lite) | ✔️ |
| [Gemini 3.1 Pro Preview](/docs/models/gemini-3.1-pro-preview) | ✔️ |
| [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite) | ✔️ |
| [Gemini 3 Flash Preview](/docs/models/gemini-3-flash-preview) | ✔️ |
| [Gemini 2.5 Pro](/docs/models/gemini-2.5-pro) | ✔️ |
| [Gemini 2.5 Flash-Lite](/docs/models/gemini-2.5-flash-lite) | ✔️ |

## Supported tool combinations {% id="tool-combination" %}

Gemini 4 and Gemini 3 models support combining built-in tools (like File Search) with custom
tools (function calling). Learn more on the
[tool combinations](/docs/tool-combination) page.

## Supported file types {% id="supported-files" %}

File Search supports a wide range of file formats, listed in the following
sections.

## Limitations {% id="limitations" %}

* **Live API:** File Search is not supported in the
    [Live API](/docs/live-api).

* **Tool incompatibility:** File Search cannot be combined with other tools
    like [Grounding with Google Search](/docs/google-search),
    [URL Context](/docs/url-context), etc. at this time.

### Rate limits {% id="rate-limits" %}

The File Search API has the following limits to enforce service stability:

* **Maximum file size / per document limit**: 100 MB
* **Total size of project File Search stores** (based on user tier):
  * **Free**: 1 GB
  * **Tier 1**: 10 GB
  * **Tier 2**: 100 GB
  * **Tier 3**: 1 TB
* **Recommendation**: Limit the size of each File Search store to under 20 GB to ensure optimal retrieval latencies.

{% callout type="note" %}
The limit on File Search store size is computed on the backend, based on
the size of your input plus the embeddings generated and stored with it. This
is typically approximately 3 times the size of your input data.
{% /callout %}

## Pricing {% id="pricing" %}

* You are charged for embeddings at indexing time based on existing
  [embeddings pricing](/docs/pricing#gemini-embedding-2).

* Storage is free of charge.
* Query time embeddings are free of charge.
* Retrieved document tokens are charged as regular
  [context tokens](/docs/tokens).

## What's next {% id="whats-next" %}

* Visit the API reference for [File Search Stores](https://ai.google.dev/api/file-search/file-search-stores) and File Search [Documents](https://ai.google.dev/api/file-search/documents).

# Combine built-in tools and function calling
Source: https://aistudio.google.com/docs/tool-combination
Description: Learn how to maintain context and enable built-in and custom tool combinations in the Gemini API.

{% callout type="note" %}
This feature is in [preview](/docs/models#preview) and supported for [Gemini 4](/docs/models#gemini-4) and [Gemini 3](/docs/models#gemini-3) models.
{% /callout %}

Gemini allows the combination of [built-in tools](/docs/tools), such
as `google_search`, and [function calling](/docs/function-calling)
(also known as *custom tools*) in a single interaction by preserving and
exposing the context history of tool calls. Built-in and custom tool
combinations allow for complex, agentic workflows where, for example, the model
can ground itself in real-time web data before calling your specific business
logic.

Here's an example that enables built-in and custom tool combinations with
`google_search` and a custom function `getWeather`:

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

getWeather = {
    "type": "function",
    "name": "getWeather",
    "description": "Gets the weather for a requested city.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "The city and state, e.g. Utqiaġvik, Alaska",
            },
        },
        "required": ["city"],
    },
}

# The Interactions API manages context automatically across tool calls.
# The model will first use Google Search, then call getWeather.
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the northernmost city in the United States? What's the weather like there today?",
    tools=[
        {"type": "google_search"},
        getWeather,
    ],
)

# Process steps: the interaction contains search results and a function call
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function call: {step.name} with args: {step.arguments}")
        # In a real application, you would execute the function here
        # and provide the result back to the model.
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

// The Interactions API manages context automatically across tool calls.
// The model will first use Google Search, then call getWeather.
const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the northernmost city in the United States? What's the weather like there today?",
    tools: [
        { type: "google_search" },
        {
            type: "function",
            name: "get_weather",
            description: "Get current weather",
            parameters: {
                type: "object",
                properties: { location: { type: "string" } },
                required: ["location"],
            },
        },
    ],
});

// Process steps: the interaction contains search results and a function call
for (const step of interaction.steps) {
    if (step.type === "function_call") {
        console.log(`Function call: ${step.name} with args: ${JSON.stringify(step.arguments)}`);
        // In a real application, you would execute the function here
        // and provide the result back to the model.
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");

Function customFunc =
    Function.builder()
        .name("get_user_location")
        .description("Retrieves user current location.")
        .parameters(parameters)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("What is the weather like where I am right now?"))
        .tools(Arrays.asList(customFunc, new GoogleSearch()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    customFunc := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_user_location"),
        Description: genai.Ptr("Retrieves user current location."),
        Parameters: map[string]any{
            "type": "object",
        },
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("What is the weather like where I am right now?"),
            Tools: []interactions.Tool{
                customFunc,
                interactions.NewTool(interactions.GoogleSearch{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20" \
-d '{
  "model": "gemini-3.8-flash",
  "input": "What is the northernmost city in the United States? What'\''s the weather like there today?",
  "tools": [
    { "type": "google_search" },
    {
      "type": "function",
      "name": "getWeather",
      "description": "Get the weather in a given location",
      "parameters": {
          "type": "object",
          "properties": {
              "location": {
                  "type": "string",
                  "description": "The city and state, e.g. San Francisco, CA"
              }
          },
          "required": ["location"]
      }
    }
  ]
}'
```
{% /tab %}
{% /tabs %}

## How it works {% id="how-it-works" %}

Gemini 3 models use *tool context circulation* to enable built-in and custom
tool combinations. Tool context circulation makes it possible to preserve and
expose the context of built-in tools and share it with custom tools in the same
interaction.

### Enable tool combination {% id="enable" %}

* Include the [`function_declarations`](/docs/function-calling#function-declarations), along
  with the built-in tools you want to use, to trigger the combination behavior.

### API returns steps {% id="api-returns-steps" %}

In an interaction response, the API returns separate steps for built-in tool
calls and function (custom tool) calls:

  * **Built-in tool steps**: The API manages these automatically, preserving
    context across turns.

  * **Function call steps**: The API returns `function_call` steps for your
    custom functions. You execute the function and provide the result back.

### Critical fields in returned steps {% id="critical-fields" %}

Certain fields in the returned steps are critical to maintaining tool context
and enabling tool combinations:

* **`id`**: Found on `function_call` and `function_response` steps. A unique
  identifier that maps a call to its response.
* **`signature`**: Found on `thought` steps, as well as all tool call (e.g.,
  `function_call`) and result (e.g., `function_response`) steps for Gemini 3+
  models. This encrypted context enables **tool context circulation** across
  interactions.

**Managing these fields:**

* **Stateful Mode (Recommended)**: When you use `previous_interaction_id`, the
  server automatically handles both `id` and `signature` fields.
* **Stateless Mode**: When managing conversation history manually, you must
  ensure that you pass both the `id` and the `signature` fields back to the
  model in subsequent requests to validate authenticity and maintain context.
  The
  official SDKs handle this automatically if you pass the full response object
  back to history.

### Tool-specific data {% id="data" %}

Some built-in tools return user-visible data arguments specific to the tool
type.

{% table %}
* Tool
* User visible tool call args (if any)
* User visible tool response (if any)
---
* **google_search**
* `queries`
* `search_suggestions`
---
* **google_maps**
* `queries`
* `places`

  `google_maps_widget_context_token`
---
* **url_context**
* `urls`

  URLs to be browsed

* `status`: Browse status

  `retrieved_url`: URLs browsed
---
* **file_search**
* None
* None
{% /table %}

## Tokens and pricing {% id="tokens" %}

Note that built-in tool call parts in requests are counted towards
`prompt_token_count`. Since these intermediate tool steps are now visible and
returned to you, they are part of the conversation history. This is only the
case for *requests*, not *responses*.

The Google Search tool is an exception to this rule. Google Search already
applies its own pricing model at the query level, so tokens are not
double-charged (see the [Pricing](/docs/pricing) page).

Read the [Tokens](/docs/tokens) page for more information.

## Limitations {% id="limitations" %}

* Default to `validated` mode (`auto` mode is not supported) when
  tool context circulation is enabled.

* Built-in tools like `google_search` rely on location and current time
  information, so if your `system_instruction` or
  `function_declaration.description` has conflicting location and time
  information, the tool combination feature might not work well.

## Supported tools {% id="supported-tools" %}

Standard tool context circulation applies to server-side (built-in) tools.
Code Execution is also a server-side tool, but has its own built-in solution to
context circulation. Computer Use and function calling are client-side tools,
and also have built-in solutions to context circulation.

| Tool | Execution side | Context Circulation Support |
| :---- | :---- | :---- |
| [Google Search](/docs/google-search) | Server-side | Supported |
| [Google Maps](/docs/maps-grounding) | Server-side | Supported |
| [URL Context](/docs/url-context) | Server-side | Supported |
| [File Search](/docs/file-search) | Server-side | Supported |
| [Code Execution](/docs/code-execution) | Server-side | Supported (built in, uses `code_execution` and `code_execution_result` steps) |
| [Computer Use](/docs/computer-use) | Client-side | Supported (built in, uses `function_call` and `function_response` steps) |
| [Custom functions](/docs/function-calling) | Client-side | Supported (built in, uses `function_call` and `function_response` steps) |

## What's next {% id="whats-next" %}

* Learn more about [Function calling](/docs/function-calling) in the Gemini API.
* Explore the supported tools:
  * [Google Search](/docs/google-search)
  * [Google Maps](/docs/maps-grounding)
  * [URL Context](/docs/url-context)
  * [File Search](/docs/file-search)

# Get started with Gemini Live API using the Google GenAI SDK
Source: https://aistudio.google.com/docs/live-api/get-started-sdk
Description: Build real-time Live API applications using the Google GenAI SDK.

The Gemini Live API allows for real-time, bidirectional interaction with Gemini
models, supporting audio, video, and text inputs and native audio outputs. This
guide explains how to integrate with the API using the Google GenAI SDK on your
server.

{% button href="https://aistudio.google.com/live" variant="primary" icon="mic" %}
  Try the Live API in Google AI Studio
{% /button %}

{% button href="https://github.com/google-gemini/gemini-live-api-examples/tree/main/gemini-live-genai-python-sdk" variant="primary" icon="code" %}
  Clone the example app from GitHub
{% /button %}

{% button href="/docs/coding-agents" variant="primary" icon="terminal" %}
  Use coding agent skills
{% /button %}

## Overview {% id="overview" %}

The Gemini Live API uses WebSockets for real-time communication. The
`google-genai` SDK provides a high-level asynchronous interface for managing
these connections.

Key concepts:

* **Session**: A persistent connection to the model.
* **Config**: Setting up modalities (audio/text), voice, and system instructions.
* **Real-time Input**: Sending audio and video frames as blobs.

## Connecting to the Live API {% id="connecting-to-the-live-api" %}

Start a Live API session with an API key:

{% tabs %}
{% tab label="Python" %}

```python
import asyncio
from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

model = "gemini-3.8-live"
config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started")
        # Send content...

if __name__ == "__main__":
    asyncio.run(main())
```

{% /tab %}
{% tab label="JavaScript" %}

```js
import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY"});
const model = 'gemini-3.8-live';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        console.debug(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  console.debug("Session started");
  // Send content...

  session.close();
}

await main();
```

{% /tab %}
{% /tabs %}

## Sending text {% id="sending-text" %}

Text can be sent using `send_realtime_input` (Python) or `sendRealtimeInput`
(JavaScript).

{% tabs %}
{% tab label="Python" %}

```python
await session.send_realtime_input(text="Hello, how are you?")
```
{% /tab %}
{% tab label="JavaScript" %}

```js
session.sendRealtimeInput({
  text: 'Hello, how are you?'
});
```
{% /tab %}
{% /tabs %}

## Sending audio {% id="sending-audio" %}

Audio needs to be sent as raw PCM data (raw 16-bit PCM audio, 16kHz,
little-endian).

{% tabs %}
{% tab label="Python" %}

```python
# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
    audio=types.Blob(
        data=chunk,
        mime_type="audio/pcm;rate=16000"
    )
)
```
{% /tab %}
{% tab label="JavaScript" %}

```js
// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
  audio: {
    data: chunk.toString('base64'),
    mimeType: 'audio/pcm;rate=16000'
  }
});
```
{% /tab %}
{% /tabs %}

For an example of how to get the audio from the client device (e.g. the browser)
see the end-to-end example on [GitHub](https://github.com/google-gemini/gemini-live-api-examples/blob/main/gemini-live-genai-python-sdk/frontend/media-handler.js#L31-L70).

## Sending video {% id="sending-video" %}

Video frames are sent as individual images (e.g., JPEG or PNG) at a specific
frame rate (max 1 frame per second).

{% tabs %}
{% tab label="Python" %}

```python
# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
    video=types.Blob(
        data=frame,
        mime_type="image/jpeg"
    )
)
```
{% /tab %}
{% tab label="JavaScript" %}

```js
// Assuming 'frame' is a Buffer of JPEG-encoded image data
session.sendRealtimeInput({
  video: {
    data: frame.toString('base64'),
    mimeType: 'image/jpeg'
  }
});
```
{% /tab %}
{% /tabs %}

For an example of how to get the video from the client device (e.g. the browser)
see the end-to-end example on [GitHub](https://github.com/google-gemini/gemini-live-api-examples/blob/main/gemini-live-genai-python-sdk/frontend/media-handler.js#L84-L120).

## Receiving audio {% id="receiving-audio" %}

The model's audio responses are received as chunks of data.

{% tabs %}
{% tab label="Python" %}

```python
async for response in session.receive():
    if response.server_content and response.server_content.model_turn:
        for part in response.server_content.model_turn.parts:
            if part.inline_data:
                audio_data = part.inline_data.data
                # Process or play the audio data
```
{% /tab %}
{% tab label="JavaScript" %}

```js
// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
  for (const part of content.modelTurn.parts) {
    if (part.inlineData) {
      const audioData = part.inlineData.data;
      // Process or play audioData (base64 encoded string)
    }
  }
}
```
{% /tab %}
{% /tabs %}

See the example app on GitHub to learn how to [receive the audio on your server](https://github.com/google-gemini/gemini-live-api-examples/blob/main/gemini-live-genai-python-sdk/gemini_live.py#L86-L98) and [play it in the browser](https://github.com/google-gemini/gemini-live-api-examples/blob/main/gemini-live-genai-python-sdk/frontend/media-handler.js#L145-L174).

## Receiving text {% id="receiving-text" %}

Transcriptions for both user input and model output are available in the server
content.

{% tabs %}
{% tab label="Python" %}

```python
async for response in session.receive():
    content = response.server_content
    if content:
        if content.input_transcription:
            print(f"User: {content.input_transcription.text}")
        if content.output_transcription:
            print(f"Gemini: {content.output_transcription.text}")
```
{% /tab %}
{% tab label="JavaScript" %}

```js
// Inside the onmessage callback
const content = response.serverContent;
if (content?.inputTranscription) {
  console.log('User:', content.inputTranscription.text);
}
if (content?.outputTranscription) {
  console.log('Gemini:', content.outputTranscription.text);
}
```
{% /tab %}
{% /tabs %}

## Handling tool calls {% id="handling-tool-calls" %}

The API supports tool calling (function calling). When the model requests a tool
call, you must execute the function and send the response back.

{% tabs %}
{% tab label="Python" %}

```python
async for response in session.receive():
    if response.tool_call:
        function_responses = []
        for fc in response.tool_call.function_calls:
            # 1. Execute the function locally
            result = my_tool_function(**fc.args)

            # 2. Prepare the response
            function_responses.append(types.FunctionResponse(
                name=fc.name,
                id=fc.id,
                response={"result": result}
            ))

        # 3. Send the tool response back to the session
        await session.send_tool_response(function_responses=function_responses)
```
{% /tab %}
{% tab label="JavaScript" %}

```js
// Inside the onmessage callback
if (response.toolCall) {
  const functionResponses = [];
  for (const fc of response.toolCall.functionCalls) {
    const result = myToolFunction(fc.args);
    functionResponses.push({
      name: fc.name,
      id: fc.id,
      response: { result }
    });
  }
  session.sendToolResponse({ functionResponses });
}
```
{% /tab %}
{% /tabs %}

## What's next {% id="whats-next" %}

* Read the full Live API [Capabilities](/docs/live-api/capabilities) guide for key capabilities and configurations; including Voice Activity Detection and native audio features.
* Read the [Tool use](/docs/live-api/tools) guide to learn how to integrate Live API with tools and function calling.
* Read the [Session management](/docs/live-api/session-management) guide for managing long running conversations.
* Read the [Ephemeral tokens](/docs/live-api/ephemeral-tokens) guide for secure authentication in [client-to-server](/docs/live-api#implementation-approach) applications.
* For more information about the underlying WebSockets API, see the [WebSockets API reference](https://ai.google.dev/api/live).

# Get started with Gemini Live API using WebSockets
Source: https://aistudio.google.com/docs/live-api/get-started-websocket
Description: Build bidirectional Live API applications directly using raw WebSockets.

The Gemini Live API allows for real-time, bidirectional interaction with Gemini
models, supporting audio, video, and text inputs and native audio outputs. This
guide explains how to integrate directly with the API using raw WebSockets.

{% button href="https://aistudio.google.com/live" variant="primary" icon="mic" %}
  Try the Live API in Google AI Studio
  {% /button %}

{% button href="https://github.com/google-gemini/gemini-live-api-examples/tree/main/gemini-live-ephemeral-tokens-websocket" variant="primary" icon="code" %}
  Clone the example app from GitHub
{% /button %}

{% button href="/docs/coding-agents" variant="primary" icon="terminal" %}
  Use coding agent skills
{% /button %}

## Overview {% id="overview" %}

The Gemini Live API uses WebSockets for real-time communication. Unlike using
an SDK, this approach involves directly managing the WebSocket connection and
sending/receiving messages in a specific JSON format defined by the API.

Key concepts:

* **WebSocket Endpoint**: The specific URL to connect to.
* **Message Format**: All communication is done via JSON messages conforming to [`BidiGenerateContentClientMessage`](https://ai.google.dev/api/live#bidigeneratecontentclientmessage) and [`BidiGenerateContentServerMessage`](https://ai.google.dev/api/live#bidigeneratecontentservermessage) structures.
* **Session Management**: You are responsible for maintaining the WebSocket connection.

## Authentication {% id="authentication" %}

Authentication is handled by including your API key as a query parameter in
the WebSocket URL.

The endpoint format is:

```none
wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

## Authentication with ephemeral tokens {% id="authentication-with-ephemeral-tokens" %}

If you are using [ephemeral tokens](/docs/live-api/ephemeral-tokens), you need to connect to the `v1beta` endpoint.
The ephemeral token needs to be passed as an `access_token` query parameter.

The endpoint format for ephemeral keys is:

```none
wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContentConstrained?access_token={short-lived-token}
```

Replace `{short-lived-token}` with the actual ephemeral token.

## Connect to the Live API {% id="connecting-to-the-live-api" %}

To start a live session, establish a WebSocket connection to the authenticated
endpoint. The first message sent over the WebSocket must be a
[`BidiGenerateContentSetup`](https://ai.google.dev/api/live#bidigeneratecontentsetup) containing the
`config`. For the full configuration options, see the
[Live API - WebSockets API reference](https://ai.google.dev/api/live).

{% tabs %}
{% tab label="Python" %}

```python
import asyncio
import websockets
import json

API_KEY = "YOUR_API_KEY"
MODEL_NAME = "gemini-3.8-live"
WS_URL = f"wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key={API_KEY}"

async def connect_and_configure():
    async with websockets.connect(WS_URL) as websocket:
        print("WebSocket Connected")

        # 1. Send the initial configuration
        setup_message = {
            "setup": {
                "model": f"models/{MODEL_NAME}",
                "responseModalities": ["AUDIO"],
                "systemInstruction": {
                    "parts": [{"text": "You are a helpful assistant."}]
                }
            }
        }
        await websocket.send(json.dumps(setup_message))
        print("Configuration sent")

        # Keep the session alive for further interactions
        await asyncio.sleep(3600) # Example: keep open for an hour

async def main():
    await connect_and_configure()

if __name__ == "__main__":
    asyncio.run(main())
```

{% /tab %}
{% tab label="JavaScript" %}

```js
const API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.8-live";
const WS_URL = `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=${API_KEY}`;

const websocket = new WebSocket(WS_URL);

websocket.onopen = () => {
  console.log('WebSocket Connected');

  // 1. Send the initial configuration
  const setupMessage = {
    setup: {
      model: `models/${MODEL_NAME}`,
      responseModalities: ['AUDIO'],
      systemInstruction: {
        parts: [{ text: 'You are a helpful assistant.' }]
      }
    }
  };
  websocket.send(JSON.stringify(setupMessage));
  console.log('Configuration sent');
};

websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Received:', response);
  // Handle different types of responses here
};

websocket.onerror = (error) => {
  console.error('WebSocket Error:', error);
};

websocket.onclose = () => {
  console.log('WebSocket Closed');
};
```

{% /tab %}
{% /tabs %}

## Send text {% id="sending-text" %}

To send text input, construct a [`BidiGenerateContentRealtimeInput`](https://ai.google.dev/api/live#bidigeneratecontentrealtimeinput) message with the `text` field.

{% tabs %}
{% tab label="Python" %}

```python
# Inside the websocket context
async def send_text(websocket, text):
    text_message = {
        "realtimeInput": {
            "text": text
        }
    }
    await websocket.send(json.dumps(text_message))
    print(f"Sent text: {text}")

# Example usage: await send_text(websocket, "Hello, how are you?")
```
{% /tab %}
{% tab label="JavaScript" %}

```js
function sendTextMessage(text) {
  if (websocket.readyState === WebSocket.OPEN) {
    const textMessage = {
      realtimeInput: {
        text: text
      }
    };
    websocket.send(JSON.stringify(textMessage));
    console.log('Text message sent:', text);
  } else {
    console.warn('WebSocket not open.');
  }
}

// Example usage:
sendTextMessage("Hello, how are you?");
```
{% /tab %}
{% /tabs %}

## Send audio {% id="sending-audio" %}

Audio needs to be sent as raw PCM data (raw 16-bit PCM audio, 16kHz, little-endian). Construct a [`BidiGenerateContentRealtimeInput`](https://ai.google.dev/api/live#bidigeneratecontentrealtimeinput) message with the audio data. The `mimeType` is crucial.

{% tabs %}
{% tab label="Python" %}

```python
# Inside the websocket context
async def send_audio_chunk(websocket, chunk_bytes):
    import base64
    encoded_data = base64.b64encode(chunk_bytes).decode('utf-8')
    audio_message = {
        "realtimeInput": {
            "audio": {
                "data": encoded_data,
                "mimeType": "audio/pcm;rate=16000"
            }
        }
    }
    await websocket.send(json.dumps(audio_message))
    # print("Sent audio chunk") # Avoid excessive logging

# Assuming 'chunk' is your raw PCM audio bytes
# await send_audio_chunk(websocket, chunk)
```
{% /tab %}
{% tab label="JavaScript" %}

```js
// Assuming 'chunk' is a Buffer of raw PCM audio
function sendAudioChunk(chunk) {
  if (websocket.readyState === WebSocket.OPEN) {
    const audioMessage = {
      realtimeInput: {
        audio: {
          data: chunk.toString('base64'),
          mimeType: 'audio/pcm;rate=16000'
        }
      }
    };
    websocket.send(JSON.stringify(audioMessage));
    // console.log('Sent audio chunk');
  }
}
// Example usage: sendAudioChunk(audioBuffer);
```
{% /tab %}
{% /tabs %}

For an example of how to get the audio from the client device (e.g. the browser)
see the end-to-end example on
[GitHub](https://github.com/google-gemini/gemini-live-api-examples/blob/main/gemini-live-ephemeral-tokens-websocket/frontend/mediaUtils.js#L38-L74).

## Send video {% id="sending-video" %}

Video frames are sent as individual images (e.g., JPEG or PNG). Similar to
audio, use `realtimeInput` with a `Blob`, specifying the correct `mimeType`.

{% tabs %}
{% tab label="Python" %}

```python
# Inside the websocket context
async def send_video_frame(websocket, frame_bytes, mime_type="image/jpeg"):
    import base64
    encoded_data = base64.b64encode(frame_bytes).decode('utf-8')
    video_message = {
        "realtimeInput": {
            "video": {
                "data": encoded_data,
                "mimeType": mime_type
            }
        }
    }
    await websocket.send(json.dumps(video_message))
    # print("Sent video frame")

# Assuming 'frame' is your JPEG-encoded image bytes
# await send_video_frame(websocket, frame)
```
{% /tab %}
{% tab label="JavaScript" %}

```js
// Assuming 'frame' is a Buffer of JPEG-encoded image data
function sendVideoFrame(frame, mimeType = 'image/jpeg') {
  if (websocket.readyState === WebSocket.OPEN) {
    const videoMessage = {
      realtimeInput: {
        video: {
          data: frame.toString('base64'),
          mimeType: mimeType
        }
      }
    };
    websocket.send(JSON.stringify(videoMessage));
    // console.log('Sent video frame');
  }
}
// Example usage: sendVideoFrame(jpegBuffer);
```
{% /tab %}
{% /tabs %}

For an example of how to get the video from the client device (e.g. the browser)
see the end-to-end example on [GitHub](https://github.com/google-gemini/gemini-live-api-examples/blob/main/gemini-live-ephemeral-tokens-websocket/frontend/mediaUtils.js#L185-L222).

## Receive responses {% id="receiving-responses" %}

The WebSocket will send back [`BidiGenerateContentServerMessage`](https://ai.google.dev/api/live#bidigeneratecontentservermessage) messages. You need to parse these JSON messages and handle different types of content.

{% tabs %}
{% tab label="Python" %}

```python
# Inside the websocket context, in a receive loop
async def receive_loop(websocket):
    async for message in websocket:
        response = json.loads(message)
        print("Received:", response)

        if "serverContent" in response:
            server_content = response["serverContent"]
            # Receiving Audio
            if "modelTurn" in server_content and "parts" in server_content["modelTurn"]:
                for part in server_content["modelTurn"]["parts"]:
                    if "inlineData" in part:
                        audio_data_b64 = part["inlineData"]["data"]
                        # Process or play the base64 encoded audio data
                        # audio_data = base64.b64decode(audio_data_b64)
                        print(f"Received audio data (base64 len: {len(audio_data_b64)})")

            # Receiving Text Transcriptions
            if "inputTranscription" in server_content:
                print(f"User: {server_content['inputTranscription']['text']}")
            if "outputTranscription" in server_content:
                print(f"Gemini: {server_content['outputTranscription']['text']}")

        # Handling Tool Calls
        if "toolCall" in response:
            await handle_tool_call(websocket, response["toolCall"])

# Example usage: await receive_loop(websocket)
```
{% /tab %}
{% tab label="JavaScript" %}

```js
websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Received:', response);

  if (response.serverContent) {
    const serverContent = response.serverContent;
    // Receiving Audio
    if (serverContent.modelTurn?.parts) {
      for (const part of serverContent.modelTurn.parts) {
        if (part.inlineData) {
          const audioData = part.inlineData.data; // Base64 encoded string
          // Process or play audioData
          console.log(`Received audio data (base64 len: ${audioData.length})`);
        }
      }
    }

    // Receiving Text Transcriptions
    if (serverContent.inputTranscription) {
      console.log('User:', serverContent.inputTranscription.text);
    }
    if (serverContent.outputTranscription) {
      console.log('Gemini:', serverContent.outputTranscription.text);
    }
  }

  // Handling Tool Calls
  if (response.toolCall) {
    handleToolCall(response.toolCall);
  }
};
```
{% /tab %}
{% /tabs %}

For an example of how to handle the response, see the end-to-end example on
[GitHub](https://github.com/google-gemini/gemini-live-api-examples/blob/main/gemini-live-ephemeral-tokens-websocket/frontend/geminilive.js#L22-L75).

## Handle tool calls {% id="handling-tool-calls" %}

When the model requests a tool call, the
[`BidiGenerateContentServerMessage`](https://ai.google.dev/api/live#bidigeneratecontentservermessage)
will contain a `toolCall` field. You must execute the function locally and send
the result back to the WebSocket using a
[`BidiGenerateContentToolResponse`](https://ai.google.dev/api/live#bidigeneratecontenttoolresponse)
message.

{% tabs %}
{% tab label="Python" %}

```python
# Placeholder for your tool function
def my_tool_function(args):
    print(f"Executing tool with args: {args}")
    # Implement your tool logic here
    return {"status": "success", "data": "some result"}

async def handle_tool_call(websocket, tool_call):
    function_responses = []
    for fc in tool_call["functionCalls"]:
        # 1. Execute the function locally
        try:
            result = my_tool_function(fc.get("args", {}))
            response_data = {"result": result}
        except Exception as e:
            print(f"Error executing tool {fc['name']}: {e}")
            response_data = {"error": str(e)}

        # 2. Prepare the response
        function_responses.append({
            "name": fc["name"],
            "id": fc["id"],
            "response": response_data
        })

    # 3. Send the tool response back to the session
    tool_response_message = {
        "toolResponse": {
            "functionResponses": function_responses
        }
    }
    await websocket.send(json.dumps(tool_response_message))
    print("Sent tool response")

# This function is called within the receive_loop when a toolCall is detected.
```
{% /tab %}
{% tab label="JavaScript" %}

```js
// Placeholder for your tool function
function myToolFunction(args) {
  console.log(`Executing tool with args:`, args);
  // Implement your tool logic here
  return { status: 'success', data: 'some result' };
}

function handleToolCall(toolCall) {
  const functionResponses = [];
  for (const fc of toolCall.functionCalls) {
    // 1. Execute the function locally
    let result;
    try {
      result = myToolFunction(fc.args || {});
    } catch (e) {
      console.error(`Error executing tool ${fc.name}:`, e);
      result = { error: e.message };
    }

    // 2. Prepare the response
    functionResponses.push({
      name: fc.name,
      id: fc.id,
      response: { result }
    });
  }

  // 3. Send the tool response back to the session
  if (websocket.readyState === WebSocket.OPEN) {
    const toolResponseMessage = {
      toolResponse: {
        functionResponses: functionResponses
      }
    };
    websocket.send(JSON.stringify(toolResponseMessage));
    console.log('Sent tool response');
  } else {
    console.warn('WebSocket not open to send tool response.');
  }
}
// This function is called within websocket.onmessage when a toolCall is detected.
```
{% /tab %}
{% /tabs %}

## What's next {% id="whats-next" %}

* Read the full Live API [Capabilities](/docs/live-api/capabilities) guide for key
  capabilities and configurations; including Voice Activity Detection and native
  audio features.
* Read the [Tool use](/docs/live-api/tools) guide to learn how to integrate Live API
  with tools and function calling.
* Read the [Session management](/docs/live-api/session-management) guide for managing long
  running conversations.
* Read the [Ephemeral tokens](/docs/live-api/ephemeral-tokens) guide for secure
  authentication in [client-to-server](/docs/live-api#implementation-approach) applications.
* For more information about the underlying WebSockets API, see the
  [WebSockets API reference](https://ai.google.dev/api/live).

# Live API capabilities guide
Source: https://aistudio.google.com/docs/live-api/capabilities
Description: Explore the capabilities and configuration options of the Gemini Live API.

{% callout type="note" %}
The Live API is in preview.
{% /callout %}

This is a comprehensive guide that covers capabilities and configurations
available with the Live API.
See [Get started with Live API](/docs/live-api) page for an
overview and sample code for common use cases.

## Before you begin {% id="before-you-begin" .hide-from-toc %}

- **Familiarize yourself with core concepts:** If you haven't already done so,
  read the [Get started with Live API ](/docs/live-api) page first.
  This will introduce you to the fundamental principles of the Live API, how it
  works, and the different [implementation approaches](/docs/live-api#implementation-approach).
-   **Try the Live API in AI Studio:** You may find it useful to try the
    Multimodal Live API in
    [Google AI Studio](https://aistudio.google.com/app/live-api) before you
    start building. To use the Live API in Google AI Studio, select **Stream**.

## Model comparison {% id="model-comparison" %}

The following table summarizes the key differences between
[Gemini 3.8 Live](/docs/models/gemini-3.8-live),
[Gemini 3.8 Live Extended Thinking](/docs/models/gemini-3.8-live-extended-thinking),
[Gemini 3.1 Flash Live Preview](/docs/models/gemini-3.1-flash-live-preview), and
[Gemini 2.5 Flash Live Preview](/docs/models/gemini-2.5-flash-native-audio-preview-12-2025):

{% table %}

*   Feature
*   Gemini 3.8 Live
*   Gemini 3.8 Live Extended Thinking
*   Gemini 3.1 Flash Live Preview
*   Gemini 2.5 Flash Live Preview
---

*   **[Thinking](/docs/live-api/thinking)**
*   Supported (interleaved reasoning). `thinkingLevel` is not supported; omit from setup.
*   Supported (configurable background reasoning: `low`, `medium`, `high`; `minimal` is not supported). Supports thought summaries (`includeThoughts`).
*   Uses `thinkingLevel` (`minimal`, `low`, `medium`, `high`). Defaults to `minimal` to optimize for lowest latency.
*   Uses `thinkingBudget` to set thinking token budget.
---

*   **[Receiving response](/api-reference/live#BidiGenerateContentServerContent)**
*   A single server event can contain multiple content parts simultaneously (for example, `inlineData` and transcript). Ensure your code processes all parts in each event to avoid missing content.
*   A single server event can contain multiple content parts simultaneously. When asynchronous reasoning is active, `turnComplete: true` does not indicate an idle session; check `interaction_status` (`IN_PROGRESS` versus `IDLE`).
*   A single server event can contain multiple content parts simultaneously (for example, `inlineData` and transcript). Ensure your code processes all parts in each event to avoid missing content.
*   Each server event contains only one content part. Parts are delivered in separate events.
---

*   **[Client content](/docs/live-api/capabilities#incremental-updates)**
*   `send_client_content` is supported throughout the entire session lifecycle with explicit roles (`user` or `model`). `turn_complete=true` unconditionally interrupts generation.
*   `send_client_content` is supported throughout the entire session lifecycle with explicit roles (`user` or `model`). `turn_complete=true` unconditionally interrupts generation.
*   `send_client_content` is supported throughout the entire session lifecycle with explicit roles (`user` or `model`). `turn_complete=true` unconditionally interrupts generation.
*   `send_client_content` is supported throughout the conversation for sending incremental content updates and establishing context.
---

*   **[Turn coverage](/api-reference/live#RealtimeInputConfig.TurnCoverage)**
*   Defaults to `TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`. The model's turn includes detected audio activity and all video frames.
*   Defaults to `TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`. The model's turn includes detected audio activity and all video frames.
*   Defaults to `TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`. The model's turn includes detected audio activity and all video frames.
*   Defaults to `TURN_INCLUDES_ONLY_ACTIVITY`. The model's turn includes only the detected activity.
---

*   **[Custom VAD](/docs/live-api/capabilities#disable-automatic-vad)** (`activity_start`/`activity_end`)
*   Supported. Disable automatic VAD and send `activityStart` and `activityEnd` messages manually to control turn boundaries.
*   Supported. Disable automatic VAD and send `activityStart` and `activityEnd` messages manually to control turn boundaries.
*   Supported. Disable automatic VAD and send `activityStart` and `activityEnd` messages manually to control turn boundaries.
*   Supported. Disable automatic VAD and send `activityStart` and `activityEnd` messages manually to control turn boundaries.
---

*   **[Automatic VAD configuration](/docs/live-api/capabilities#configure-automatic-vad)**
*   Supported. Configure parameters such as `start_of_speech_sensitivity`, `end_of_speech_sensitivity`, `prefix_padding_ms`, and `silence_duration_ms`.
*   Supported. Configure parameters such as `start_of_speech_sensitivity`, `end_of_speech_sensitivity`, `prefix_padding_ms`, and `silence_duration_ms`.
*   Supported. Configure parameters such as `start_of_speech_sensitivity`, `end_of_speech_sensitivity`, `prefix_padding_ms`, and `silence_duration_ms`.
*   Supported. Configure parameters such as `start_of_speech_sensitivity`, `end_of_speech_sensitivity`, `prefix_padding_ms`, and `silence_duration_ms`.
---

*   **[Asynchronous function calling](/docs/live-api/tools#async-function-calling)** (`behavior: NON_BLOCKING`)
*   Supported (default). Set `behavior: NON_BLOCKING` or use backward-compatible blocking mode (`behavior: BLOCKING`). Function scheduling (`SILENT`, `WHEN_IDLE`, `INTERRUPTED`) is supported.
*   Supported (Async only). Only `NON_BLOCKING` execution is supported. Blocking mode and function scheduling are not supported.
*   Not supported. Function calling is synchronous only. The model waits for the tool response before responding.
*   Supported (both synchronous and asynchronous).
---

*   **[Proactive audio](/docs/live-api/capabilities#proactive-audio)**
*   Permanently enabled (`proactive_audio: false` returns an error).
*   Permanently enabled (`proactive_audio: false` returns an error).
*   Not supported
*   Supported (configurable). Set `proactive_audio` to `true` in `proactivity` config.
---

*   **[Affective dialogue](/docs/live-api/capabilities#affective-dialog)**
*   Not supported (removed; omit `enable_affective_dialog`).
*   Not supported (removed; omit `enable_affective_dialog`).
*   Not supported
*   Supported. Set `enable_affective_dialog` to `true` in session config.
{% /table %}
To migrate from Gemini 3.1 Flash Live Preview to Gemini 3.8 Live, see the
[migration guide](/docs/models/gemini-3.8-live#migrating). To learn more about
Thinking, see [Thinking in the Live API](/docs/live-api/thinking) and
[Upgrading to Gemini 3.8 Live Extended Thinking](/docs/models/gemini-3.8-live-extended-thinking#upgrading).

## Establishing a connection {% id="establish-connection" %}

The following example shows how to create a connection with an API key:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import asyncio
from google import genai

client = genai.Client()

model = "gemini-3.8-live"
config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started")
        # Send content...

if __name__ == "__main__":
    asyncio.run(main())
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.8-live';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        console.debug(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  console.debug("Session started");
  // Send content...

  session.close();
}

await main();
```

{% /tab %}
{% /tabs %}
## Interaction modalities {% id="modalities" %}

The following sections provide examples and supporting context for the different
input and output modalities available in Live API.

### Sending audio {% id="send-receive-audio" %}

Audio needs to be sent as raw PCM data (raw 16-bit PCM audio, 16kHz, little-endian).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
    audio=types.Blob(
        data=chunk,
        mime_type="audio/pcm;rate=16000"
    )
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
  audio: {
    data: chunk.toString('base64'),
    mimeType: 'audio/pcm;rate=16000'
  }
});
```

{% /tab %}
{% /tabs %}
### Audio formats {% id="audio-formats" %}

Audio data in the Multimodal Live API is always raw, little-endian,
16-bit PCM. Audio output always uses a sample rate of 24kHz. Input audio
is natively 16kHz, but the Multimodal Live API will resample if needed
so any sample rate can be sent. To convey the sample rate of input audio, set
the MIME type of each audio-containing [Blob](https://ai.google.dev/api/caching#Blob) to a value
like `audio/pcm;rate=16000`.

### Receiving audio {% id="receive-audio" %}

The model's audio responses are received as chunks of data.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
async for response in session.receive():
    if response.server_content and response.server_content.model_turn:
        for part in response.server_content.model_turn.parts:
            if part.inline_data:
                audio_data = part.inline_data.data
                # Process or play the audio data
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
  for (const part of content.modelTurn.parts) {
    if (part.inlineData) {
      const audioData = part.inlineData.data;
      // Process or play audioData (base64 encoded string)
    }
  }
}
```

{% /tab %}
{% /tabs %}
### Sending text {% id="send-text" %}

Text can be sent using `send_realtime_input` (Python) or `sendRealtimeInput` (JavaScript).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
await session.send_realtime_input(text="Hello, how are you?")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
session.sendRealtimeInput({
  text: 'Hello, how are you?'
});
```

{% /tab %}
{% /tabs %}
### Sending video {% id="send-video" %}

Video frames are sent as individual images (e.g., JPEG or PNG) at a specific frame rate (max 1 frame per second).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
    video=types.Blob(
        data=frame,
        mime_type="image/jpeg"
    )
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
// Assuming 'frame' is a Buffer of JPEG-encoded image data
session.sendRealtimeInput({
  video: {
    data: frame.toString('base64'),
    mimeType: 'image/jpeg'
  }
});
```

{% /tab %}
{% /tabs %}
#### Incremental content updates {% id="incremental-updates" %}

Use incremental updates to send text input, establish session context, or
restore session context. For short contexts you can send turn-by-turn
interactions to represent the exact sequence of events:

{% callout type="note" %} For Gemini 3.8 and 3.1 models, if you want to seed
initial conversation history using `send_client_content` before starting a
realtime stream, set
[`initial_history_in_client_content`](https://ai.google.dev/api/live#HistoryConfig)
to `true` in your session config's `history_config`. You can also use
`send_client_content` mid-session to append structured text turns. {% /callout
%}

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
let inputTurns = [
  { "role": "user", "parts": [{ "text": "What is the capital of France?" }] },
  { "role": "model", "parts": [{ "text": "Paris" }] },
]

session.sendClientContent({ turns: inputTurns, turnComplete: false })

inputTurns = [{ "role": "user", "parts": [{ "text": "What is the capital of Germany?" }] }]

session.sendClientContent({ turns: inputTurns, turnComplete: true })
```

{% /tab %} {% /tabs %}

For longer contexts it's recommended to provide a single message summary to free
up the context window for subsequent interactions. See
[Session Resumption](/docs/live-api/session-management#session-resumption) for
another method for loading session context.

### Audio transcriptions {% id="audio-transcription" %}

In addition to the model response, you can also receive transcriptions of
both the audio output and the audio input.

To enable transcription of the model's audio output, send
`output_audio_transcription` in the setup config. The transcription language is
inferred from the model's response.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import asyncio
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.8-live"

config = {
    "response_modalities": ["AUDIO"],
    "output_audio_transcription": {}
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)

if __name__ == "__main__":
    asyncio.run(main())
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.8-live';

const config = {
  responseModalities: [Modality.AUDIO],
  outputAudioTranscription: {}
};

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  const inputTurns = 'Hello how are you?';
  session.sendClientContent({ turns: inputTurns });

  const turns = await handleTurn();

  for (const turn of turns) {
    if (turn.serverContent && turn.serverContent.outputTranscription) {
      console.debug('Received output transcription: %s\n', turn.serverContent.outputTranscription.text);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

await main();
```

{% /tab %} {% /tabs %}

To enable transcription of the model's audio input, send
`input_audio_transcription` in setup config.

{% tabs %} {% tab label="Python" filename="sample.py" %}

```python
import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.8-live"

config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {},
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_data = Path("16000.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_data, mime_type='audio/pcm;rate=16000')
        )

        async for msg in session.receive():
            if msg.server_content.input_transcription:
                print('Transcript:', msg.server_content.input_transcription.text)

if __name__ == "__main__":
    asyncio.run(main())
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
import pkg from 'wavefile';
const { WaveFile } = pkg;

const ai = new GoogleGenAI({});
const model = 'gemini-3.8-live';

const config = {
  responseModalities: [Modality.AUDIO],
  inputAudioTranscription: {}
};

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  // Send Audio Chunk
  const fileBuffer = fs.readFileSync("16000.wav");

  // Ensure audio conforms to API requirements (16-bit PCM, 16kHz, mono)
  const wav = new WaveFile();
  wav.fromBuffer(fileBuffer);
  wav.toSampleRate(16000);
  wav.toBitDepth("16");
  const base64Audio = wav.toBase64();

  // If already in correct format, you can use this:
  // const fileBuffer = fs.readFileSync("sample.pcm");
  // const base64Audio = Buffer.from(fileBuffer).toString('base64');

  session.sendRealtimeInput(
    {
      audio: {
        data: base64Audio,
        mimeType: "audio/pcm;rate=16000"
      }
    }
  );

  const turns = await handleTurn();
  for (const turn of turns) {
    if (turn.text) {
      console.debug('Received text: %s\n', turn.text);
    }
    else if (turn.data) {
      console.debug('Received inline data: %s\n', turn.data);
    }
    else if (turn.serverContent && turn.serverContent.inputTranscription) {
      console.debug('Received input transcription: %s\n', turn.serverContent.inputTranscription.text);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

await main();
```

{% /tab %}
{% /tabs %}

To improve how input transcription recognizes specific terms, such as proper
nouns, brand names, or technical terms, add a `custom_vocabulary` list to
`input_audio_transcription`. You can provide up to 1,000 terms, but best results
are typically achieved with up to 100 terms. For more details, see
[Custom vocabulary biasing](/docs/live-api/live-transcribe#custom-vocabulary-biasing).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {
        "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"],
    },
}
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
const config = {
  responseModalities: [Modality.AUDIO],
  inputAudioTranscription: {
    customVocabulary: ['Gemini', 'Kubernetes', 'BigQuery'],
  },
};
```

{% /tab %}
{% /tabs %}
### Change voice and language {% id="change-voice-and-language" %}

[Native audio output](/docs/live-api/capabilities#native-audio-output) models support any of the voices
available for our [Text-to-Speech (TTS)](/docs/speech-generation#voices)
models. You can listen to all the voices in [AI Studio](https://aistudio.google.com/app/live-api).

To specify a voice, set the voice name within the `speechConfig` object as part
of the session configuration:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
config = {
    "response_modalities": ["AUDIO"],
    "speech_config": {
        "voice_config": {"prebuilt_voice_config": {"voice_name": "Kore"}}
    },
}
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
const config = {
  responseModalities: [Modality.AUDIO],
  speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } }
};
```

{% callout type="note" %}
If you're using the `generateContent` API, the set of available voices is
{% /callout %}
slightly different. See the [speech generation guide](/docs/speech-generation#voices)
for `generateContent` audio generation voices.

The Multimodal Live API supports [multiple languages](/docs/live-api/capabilities#supported-languages).
[Native audio output](/docs/live-api/capabilities#native-audio-output) models automatically choose
the appropriate language and don't support explicitly setting the language
code.

{% /tab %}
{% /tabs %}
## Native audio capabilities {% id="native-audio-output" %}

Our latest models feature [native audio output](/docs/models/gemini-3.8-live),
which provides natural, realistic-sounding speech and improved multilingual
performance.

### Thinking {% id="native-audio-output-thinking" %}

Gemini 3.8 Live Extended Thinking and Gemini 3.1 models use `thinkingLevel` to
control thinking depth. For `gemini-3.8-live`, `thinkingLevel` is not supported
and must be omitted in setup. Gemini 3.8 Live Extended Thinking supports `low`,
`medium`, and `high` (`minimal` is not supported). Gemini 3.1 models support
`minimal`, `low`, `medium`, and `high`. For complete details and code examples,
see [Thinking in the Live API](/docs/live-api/thinking).

{% tabs %} {% tab label="Python" filename="sample.py" %}

```python
model = "gemini-3.8-live-extended-thinking"

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    thinking_config=types.ThinkingConfig(
        thinking_level="MEDIUM",
    )
)

async with client.aio.live.connect(model=model, config=config) as session:
    # Send audio input and receive audio
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
const model = 'gemini-3.8-live-extended-thinking';
const config = {
  responseModalities: [Modality.AUDIO],
  thinkingConfig: {
    thinkingLevel: 'MEDIUM',
  },
};

async function main() {

  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: ...,
  });

  // Send audio input and receive audio

  session.close();
}

await main();
```

{% /tab %} {% /tabs %}

Additionally, you can enable thought summaries by setting `includeThoughts` to
`true` in your configuration. See
[Receive thought summaries](/docs/thinking#summaries) for more
info:

{% tabs %} {% tab label="Python" filename="sample.py" %}

```python
model = "gemini-3.8-live-extended-thinking"

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    thinking_config=types.ThinkingConfig(
        thinking_level="HIGH",
        include_thoughts=True
    )
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
const model = 'gemini-3.8-live-extended-thinking';
const config = {
  responseModalities: [Modality.AUDIO],
  thinkingConfig: {
    thinkingLevel: 'HIGH',
    includeThoughts: true,
  },
};
```

{% /tab %}
{% /tabs %}

### Affective dialog {% id="affective-dialog" %}

This feature lets Gemini adapt its response style to the input expression and
tone.

{% callout type="note" %}
Supported on Gemini 2.5 Flash Live only. Removed in Gemini 3.8 Live and Gemini
3.8 Live Extended Thinking (omit `enable_affective_dialog`), and not supported
on Gemini 3.1 Flash Live Preview.
{% /callout %}

To use affective dialog, set the api version to `v1beta` and set
`enable_affective_dialog` to `true` in the setup message:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
client = genai.Client(http_options={"api_version": "v1beta"})

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    enable_affective_dialog=True
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
const ai = new GoogleGenAI({ httpOptions: {"apiVersion": "v1beta"} });

const config = {
  responseModalities: [Modality.AUDIO],
  enableAffectiveDialog: true
};
```

{% /tab %}
{% /tabs %}
### Proactive audio {% id="proactive-audio" %}

When this feature is enabled, Gemini can proactively decide not to respond
if the content is not relevant.

{% callout type="note" %}
Permanently enabled on Gemini 3.8 Live and Gemini 3.8 Live Extended Thinking
(setting `proactive_audio: false` returns an error). Configurable on Gemini 2.5
Flash Live, and not supported on Gemini 3.1 Flash Live Preview.
{% /callout %}

To use it, set the api version to `v1beta` and configure the `proactivity`
field in the setup message and set `proactive_audio` to `true`:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
client = genai.Client(http_options={"api_version": "v1beta"})

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    proactivity={'proactive_audio': True}
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
const ai = new GoogleGenAI({ httpOptions: {"apiVersion": "v1beta"} });

const config = {
  responseModalities: [Modality.AUDIO],
  proactivity: { proactiveAudio: true }
}
```

{% /tab %}
{% /tabs %}
## Live translation {% id="live-translate" %}

The Live API supports real-time, low-latency translation of spoken conversations. This capability lets you build real-time voice-to-voice translation applications.

For more information and examples, see the [Live Translation guide](/docs/live-api/live-translate).

## Voice Activity Detection (VAD) {% id="interruptions" %}

Voice Activity Detection (VAD) allows the model to recognize when a person is
speaking. This is essential for creating natural conversations, as it allows a
user to interrupt the model at any time.

When VAD detects an interruption, the ongoing generation is canceled and
discarded. Only the information already sent to the client is retained in the
session history. The server then sends a
[`BidiGenerateContentServerContent`](https://ai.google.dev/api/live#bidigeneratecontentservercontent)
message to report the interruption.

The Gemini server then discards any pending function calls and sends a
`BidiGenerateContentServerContent` message with the IDs of the canceled calls.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

        # If realtime playback is implemented in your application,
        # you should stop playing audio and clear queued playback here.
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
const turns = await handleTurn();

for (const turn of turns) {
  if (turn.serverContent && turn.serverContent.interrupted) {
    // The generation was interrupted

    // If realtime playback is implemented in your application,
    // you should stop playing audio and clear queued playback here.
  }
}
```

{% /tab %}
{% /tabs %}
### Automatic VAD {% id="use-automatic-vad" .hide-from-toc %}

By default, the model automatically performs VAD on
a continuous audio input stream. VAD can be configured with the
[`realtimeInputConfig.automaticActivityDetection`](https://ai.google.dev/api/live#RealtimeInputConfig.AutomaticActivityDetection)
field of the [setup configuration](https://ai.google.dev/api/live#BidiGenerateContentSetup).

When the audio stream is paused for more than a second (for example,
because the user switched off the microphone), an
[`audioStreamEnd`](https://ai.google.dev/api/live#BidiGenerateContentRealtimeInput.FIELDS.bool.BidiGenerateContentRealtimeInput.audio_stream_end)
event should be sent to flush any cached audio. The client can resume sending
audio data at any time.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.8-live"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

        async for response in session.receive():
            if response.text is not None:
                print(response.text)

if __name__ == "__main__":
    asyncio.run(main())
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
// example audio file to try:
// URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
// !wget -q $URL -O sample.pcm
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const model = 'gemini-3.8-live';
const config = { responseModalities: [Modality.AUDIO] };

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  // Send Audio Chunk
  const fileBuffer = fs.readFileSync("sample.pcm");
  const base64Audio = Buffer.from(fileBuffer).toString('base64');

  session.sendRealtimeInput(
    {
      audio: {
        data: base64Audio,
        mimeType: "audio/pcm;rate=16000"
      }
    }

  );

  // if stream gets paused, send:
  // session.sendRealtimeInput({ audioStreamEnd: true })

  const turns = await handleTurn();
  for (const turn of turns) {
    if (turn.text) {
      console.debug('Received text: %s\n', turn.text);
    }
    else if (turn.data) {
      console.debug('Received inline data: %s\n', turn.data);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

await main();
```

With `send_realtime_input`, the API will respond to audio automatically based
on VAD. While `send_client_content` adds messages to the model context in
order, `send_realtime_input` is optimized for responsiveness at the expense of
deterministic ordering.

{% /tab %}
{% /tabs %}
### Automatic VAD configuration {% id="configure-automatic-vad" .hide-from-toc %}

For more control over the VAD activity, you can configure the following
parameters. See [API reference](https://ai.google.dev/api/live#automaticactivitydetection) for more
info.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google.genai import types

config = {
    "response_modalities": ["AUDIO"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
import { GoogleGenAI, Modality, StartSensitivity, EndSensitivity } from '@google/genai';

const config = {
  responseModalities: [Modality.AUDIO],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: false, // default
      startOfSpeechSensitivity: StartSensitivity.START_SENSITIVITY_LOW,
      endOfSpeechSensitivity: EndSensitivity.END_SENSITIVITY_LOW,
      prefixPaddingMs: 20,
      silenceDurationMs: 100,
    }
  }
};
```

{% /tab %}
{% /tabs %}
### Hybrid VAD {% id="hybrid-vad" .hide-from-toc %}

Hybrid VAD combines the benefits of automatic VAD (robust speech start detection) and manual VAD (low-latency response finalization).

In this configuration:

1. **Automatic VAD remains enabled** on the server. The server automatically
    detects the start of user speech, using prefix padding to avoid clipping
    the beginning of utterances.
2. The client uses a **client-side VAD** to detect when the user stops
    speaking.
3. When the client-side VAD detects the end of speech, it sends an
    [`audio_stream_end`](https://ai.google.dev/api/live#BidiGenerateContentRealtimeInput.FIELDS.bool.BidiGenerateContentRealtimeInput.audio_stream_end)
    signal to the server.
4. The server treats the `audio_stream_end` signal as an immediate
    finalization prompt, bypassing the default server-side silence detection
    delay and returning the transcript and model response with minimal latency.
5. If the client-side VAD fails to trigger, the server-side VAD acts as a
    fallback to detect the end of speech.

Note that if the client-side VAD threshold is set too aggressively, it may cause
speech cutoffs. However, this approach prevents front-truncation issues which
might occur with manual VAD.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Set up with automatic VAD enabled (default)
config = {
    "response_modalities": ["AUDIO"],
}

async with client.aio.live.connect(model=model, config=config) as session:
    # Send audio data normally
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )

    # When client-side VAD detects the end of speech, send:
    await session.send_realtime_input(audio_stream_end=True)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
// Set up with automatic VAD enabled (default)
const config = {
  responseModalities: [Modality.AUDIO],
};

// Send audio data normally
session.sendRealtimeInput({
  audio: {
    data: base64Audio,
    mimeType: "audio/pcm;rate=16000"
  }
});

// When client-side VAD detects the end of speech, send:
session.sendRealtimeInput({ audioStreamEnd: true });
```

{% /tab %}
{% /tabs %}
### Disable automatic VAD {% id="disable-automatic-vad" .hide-from-toc %}

Alternatively, the automatic VAD can be disabled by setting
`realtimeInputConfig.automaticActivityDetection.disabled` to `true` in the setup
message. In this configuration the client is responsible for detecting user
speech and sending
[`activityStart`](https://ai.google.dev/api/live#BidiGenerateContentRealtimeInput.FIELDS.BidiGenerateContentRealtimeInput.ActivityStart.BidiGenerateContentRealtimeInput.activity_start)
and [`activityEnd`](https://ai.google.dev/api/live#BidiGenerateContentRealtimeInput.FIELDS.BidiGenerateContentRealtimeInput.ActivityEnd.BidiGenerateContentRealtimeInput.activity_end)
messages at the appropriate times. An `audioStreamEnd` isn't sent in
this configuration. Instead, any interruption of the stream is marked by
an `activityEnd` message.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
config = {
    "response_modalities": ["AUDIO"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
const config = {
  responseModalities: [Modality.AUDIO],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: true,
    }
  }
};

session.sendRealtimeInput({ activityStart: {} })

session.sendRealtimeInput(
  {
    audio: {
      data: base64Audio,
      mimeType: "audio/pcm;rate=16000"
    }
  }

);

session.sendRealtimeInput({ activityEnd: {} })
```

{% /tab %}
{% /tabs %}
### Understanding VAD parameters and their impact on quality {% id="vad-quality-best-practices" .hide-from-toc %}

When using automatic VAD, two key parameters control how audio is
segmented into speech turns before being sent to the model:

- **`prefixPaddingMs`**: The amount of audio to include *before* speech
    is detected. This "look-back" ensures the model captures the full
    onset of speech, including the first syllable which may start before
    the VAD triggers. A value of `0` may cause the beginning of words to
    be clipped.
- **`silenceDurationMs`**: How long the server waits through silence
    before ending a speech turn. This determines how tolerant the system
    is of natural mid-sentence pauses (e.g., thinking, breathing, or
    clause boundaries).

#### Impact of `silenceDurationMs` on audio quality

The `silenceDurationMs` value directly affects the size and completeness
of audio chunks the model receives for processing:

- **Recommended (500ms–800ms):** Provides a good balance—the model
    receives complete, contextually rich audio chunks while keeping latency
    reasonable. The server's internal default is approximately 800ms.
- **Too low (e.g., 100ms–200ms):** The system ends speech turns during
    natural pauses, splitting a single utterance into multiple small audio
    fragments. The model receives these fragments individually, losing
    cross-fragment context and resulting in lower transcription and response
    quality.
- **Too high (e.g., 2000ms+):** The system waits a long time after the
    user stops speaking, increasing perceived latency before the model
    responds.

#### Best practices for manual (client-side) VAD

When you disable automatic VAD and manage `activityStart`/`activityEnd`
signals from your own client-side voice detection, be aware that the
server's built-in audio buffering mechanisms are bypassed. This means:

1. **No pre-speech buffer:** The server no longer prepends audio before
    the detected speech start. Your client should include sufficient audio
    context before sending `activityStart`.
2. **No silence tolerance:** The server acts immediately on your
    `activityEnd` signal with no additional wait. If your client-side VAD
    uses an aggressive end-of-speech threshold (e.g., 200ms of silence),
    speech may be cut off mid-sentence during natural pauses.

To preserve audio quality with manual VAD, use an end-of-speech silence
threshold of at least **500ms** in your client's voice activity detector.
Thresholds below this value often cause fragmented audio that degrades
transcription and model response quality.

## Token count {% id="token-count" %}

You can find the total number of consumed tokens in the
[usageMetadata](https://ai.google.dev/api/live#usagemetadata) field of the returned server message.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
const turns = await handleTurn();

for (const turn of turns) {
  if (turn.usageMetadata) {
    console.debug('Used %s tokens in total. Response token breakdown:\n', turn.usageMetadata.totalTokenCount);

    for (const detail of turn.usageMetadata.responseTokensDetails) {
      console.debug('%s\n', detail);
    }
  }
}
```

{% /tab %}
{% /tabs %}
## Media resolution {% id="media-resolution" %}

You can specify the media resolution for the input media by setting the
`mediaResolution` field as part of the session configuration:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from google.genai import types

config = {
    "response_modalities": ["AUDIO"],
    "media_resolution": types.MediaResolution.MEDIA_RESOLUTION_LOW,
}
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```js
import { GoogleGenAI, Modality, MediaResolution } from '@google/genai';

const config = {
    responseModalities: [Modality.AUDIO],
    mediaResolution: MediaResolution.MEDIA_RESOLUTION_LOW,
};
```

{% /tab %}
{% /tabs %}

You can configure `mediaResolution` for multimodal sessions that include
audio, video, or image inputs. While `mediaResolution` adjusts the token
allocation per frame for visual inputs, audio streams are tokenized at a
fixed rate per second across all resolution settings. For more information,
see the [Media resolution](/docs/media-resolution) guide.

## Limitations {% id="limitations" %}

Consider the following limitations of the Multimodal Live API
when you plan your project.

### Response modalities {% id="response-modalities" %}

The native audio models only support `AUDIO response modality. If you need the
model response as text, use the [output audio transcription](/docs/live-api/capabilities#audio-transcription)
feature.

### Client authentication {% id="client-authentication" %}

The Multimodal Live API only provides server-to-server authentication by
default. If you're implementing your Multimodal Live API application using a
[client-to-server approach](/docs/live-api#implementation-approach), you need to
use [ephemeral tokens](/docs/live-api/ephemeral-tokens) to mitigate security
risks.

### Session duration {% id="maximum-session-duration" %}

Audio-only sessions are limited to 15 minutes, and audio plus video sessions are
limited to 2 minutes. However, you can configure different
[session management techniques](/docs/live-api/session-management) for unlimited
extensions on session duration.

### Context window {% id="context-window" %}

A session has a context window limit of:

- 128k tokens for [native audio output](/docs/live-api/capabilities#native-audio-output) models
- 32k tokens for other Multimodal Live API models

## Supported languages {% id="supported-languages" %}

Multimodal Live API supports the following 99 languages.

{% callout type="note" %}
[Native audio output](/docs/live-api/capabilities#native-audio-output) models can switch between
languages naturally during conversation. You can also restrict the languages
it speaks in by specifying it in the system instructions.
{% /callout %}

| Language | BCP-47 Code | Language | BCP-47 Code |
| :--- | :--- | :--- | :--- |
| Afrikaans | `af` | Latvian | `lv` |
| Akan | `ak` | Lithuanian | `lt` |
| Albanian | `sq` | Macedonian | `mk` |
| Amharic | `am` | Malay | `ms` |
| Arabic | `ar` | Malayalam | `ml` |
| Armenian | `hy` | Maltese | `mt` |
| Assamese | `as` | Maori | `mi` |
| Azerbaijani | `az` | Marathi | `mr` |
| Basque | `eu` | Mongolian | `mn` |
| Belarusian | `be` | Nepali | `ne` |
| Bengali | `bn` | Norwegian | `no`, `nb` |
| Bosnian | `bs` | Odia | `or` |
| Bulgarian | `bg` | Oromo | `om` |
| Burmese | `my` | Pashto | `ps` |
| Catalan | `ca` | Persian | `fa` |
| Cebuano | `ceb` | Polish | `pl` |
| Chinese (Simplified) | `zh-Hans` | Portuguese (Brazil) | `pt-BR` |
| Chinese (Traditional) | `zh-Hant` | Portuguese (Portugal) | `pt-PT` |
| Croatian | `hr` | Punjabi | `pa` |
| Czech | `cs` | Quechua | `qu` |
| Danish | `da` | Romanian | `ro` |
| Dutch | `nl` | Romansh | `rm` |
| English | `en` | Russian | `ru` |
| Estonian | `et` | Serbian | `sr` |
| Faroese | `fo` | Sindhi | `sd` |
| Filipino | `fil` | Sinhala | `si` |
| Finnish | `fi` | Slovak | `sk` |
| French | `fr` | Slovenian | `sl` |
| Galician | `gl` | Somali | `so` |
| Georgian | `ka` | Southern Sotho | `st` |
| German | `de` | Spanish | `es` |
| Greek | `el` | Swahili | `sw` |
| Gujarati | `gu` | Swedish | `sv` |
| Hausa | `ha` | Tajik | `tg` |
| Hebrew | `he` | Tamil | `ta` |
| Hindi | `hi` | Telugu | `te` |
| Hungarian | `hu` | Thai | `th` |
| Icelandic | `is` | Tswana | `tn` |
| Indonesian | `id` | Turkish | `tr` |
| Irish | `ga` | Turkmen | `tk` |
| Italian | `it` | Ukrainian | `uk` |
| Japanese | `ja` | Urdu | `ur` |
| Kannada | `kn` | Uzbek | `uz` |
| Kazakh | `kk` | Vietnamese | `vi` |
| Khmer | `km` | Welsh | `cy` |
| Kinyarwanda | `rw` | Western Frisian | `fy` |
| Korean | `ko` | Wolof | `wo` |
| Kurdish | `ku` | Yoruba | `yo` |
| Kyrgyz | `ky` | Zulu | `zu` |
| Lao | `lo` |  |  |

## What's next {% id="whats-next" %}

-   Read the [Thinking in the Live API](/docs/live-api/thinking),
    [Tool Use](/docs/live-api/tools), and
    [Session Management](/docs/live-api/session-management) guides for essential
    information on using the Live API effectively.
- Try the Multimodal Live API in [Google AI Studio](https://aistudio.google.com/app/live).
-   For more info about the Live API models, see
    [Gemini 3.8 Live](/docs/models/gemini-3.8-live) and
    [Gemini 3.8 Live Extended Thinking](/docs/models/gemini-3.8-live-extended-thinking)
    on the Models page.
- Try more examples in the [Live API cookbook](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_LiveAPI.ipynb),
the [Live API Tools cookbook](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_LiveAPI_tools.ipynb),
and the [Live API Get Started script](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Get_started_LiveAPI.py).

# Thinking in the Live API
Source: https://aistudio.google.com/docs/live-api/thinking
Description: Learn about Thinking in the Gemini Live API, including architectural differences, interaction status tracking, and non-blocking tools.

The Gemini Live API enables real-time, bidirectional voice conversations with
Gemini models.

Standard voice models work well for immediate back-and-forth dialogue. You speak
to the model, and it generates a spoken reply right away. But when a request
requires planning, complex analysis, or external tools, direct responses hit a
limit. The model must either answer without reasoning or pause silently while
waiting for tools to finish.

Thinking in the Live API (`gemini-3.8-live-extended-thinking`) adds background
reasoning to real-time voice sessions. The model plans and calls asynchronous
tools in the background while speaking natural conversational fillers to keep
the interaction active.

This architecture changes the conversational lifecycle in two key ways:

-   **Conversational fillers**: The model speaks intermediate updates (such as
    "Checking flight options now") while executing tools in the background.
-   **Interaction status tracking**: Because the model can speak multiple times
    during a single request, the server emits `interaction_status:
    "IN_PROGRESS"` during background processing and `interaction_status: "IDLE"`
    when the overall task completes.

The following diagram compares the interaction lifecycles between standard Live
voice sessions and Thinking with background reasoning:

![Live API function calling and state tracking comparison](/googledevai/static/gemini-api/docs/images/thinking-model-comparison.svg)

## Choosing the right model {% id="choosing-a-model" %}

When deciding between `gemini-3.8-live` and `gemini-3.8-live-extended-thinking`,
weigh three main considerations: response latency, task complexity, and client
state handling.

### When to use Gemini 3.8 Live {% id="when-to-use-live" %}

Use `gemini-3.8-live` for low-latency conversational voice agents where
immediate turn-taking is essential and tasks are direct.

-   **Conversational voice assistants**: Customer service triage, language
    practice, voice search, and interactive storytelling.
-   **Fast tool execution**: Workflows where external tools return within
    milliseconds (such as reading sensor values or controlling smart devices).
-   **Simple client logic**: Applications where each user turn receives a single
    model response, and `turnComplete: true` reliably signals when the session
    is idle.

### When to use Gemini 3.8 Live Extended Thinking {% id="when-to-use-thinking" %}

Use `gemini-3.8-live-extended-thinking` when your agent must evaluate complex
data, plan multiple steps, or handle tools that take several seconds to run.

-   **Multi-step diagnostics and support**: Technical support agents diagnosing
    system issues across multiple logs, error codes, and configuration checks.
-   **Coordinated data retrieval**: Travel and booking agents that search
    flights, query hotels, and compare prices across parallel API calls.
-   **STEM and code tutoring**: Educational agents that verify formulas, debug
    code, or work through multi-step logic before speaking an explanation.
-   **Masking tool latency**: Voice experiences where long-running functions
    would otherwise create awkward silence for the listener.

### Key differences summary {% id="key-differences" %}

The following table summarizes the technical differences between both models:

{% table %}

*   Feature
*   Gemini 3.8 Live
*   Gemini 3.8 Live Extended Thinking
---

*   **Primary use cases**
*   Low-latency voice agents, direct commands, fast tools
*   Multi-step problem solving, complex planning, multi-tool workflows
---

*   **Model endpoint**
*   `gemini-3.8-live`
*   `gemini-3.8-live-extended-thinking`
---

*   **Reasoning architecture**
*   Interleaved reasoning with fixed latency profile (`thinking_level` not supported)
*   Configurable background reasoning (`thinking_level`: `low`, `medium`, `high`; `MINIMAL` not supported)
---

*   **Turn boundaries**
*   `turnComplete: true` closes the turn and returns to idle
*   `turnComplete: true` finishes an utterance; `interaction_status` controls session lifecycle
---

*   **Conversational fillers**
*   Model waits for tool execution before speaking
*   Model streams intermediate conversational fillers while processing
---

*   **Tool execution**
*   Supports synchronous (`BLOCKING`) and asynchronous (`NON_BLOCKING`) tools
*   Requires asynchronous (`NON_BLOCKING`) tool declarations
{% /table %}
## Migration and integration paths {% id="migration-paths" %}

Follow these steps to upgrade existing voice applications or integrate Thinking
into your Live API sessions.

### Upgrading from Gemini 3.1 Flash Live {% id="upgrading-from-31" %}

For existing voice applications using `gemini-3.1-flash-live-preview`, upgrading
to `gemini-3.8-live` requires updating the model string and omitting
`thinking_level` (or `thinking_config`) from your setup configuration, as
`thinking_level` is not supported for `gemini-3.8-live`:

```json
{
  "setup": {
    "model": "models/gemini-3.8-live"
  }
}
```

The turn lifecycle and `turnComplete` signals remain identical.

### Adopting Thinking {% id="adopting-thinking" %}

To adopt `gemini-3.8-live-extended-thinking`, update three integration points:

1.  **Track `interaction_status` instead of `turnComplete`**: In Thinking
    sessions, the model can emit intermediate conversational fillers while
    reasoning. Inspect the `interaction_status` field on incoming server
    messages to manage UI state. Only return to idle when `interaction_status`
    is `IDLE`.

   {% tabs %}
   {% tab label="Python" %}

   ```python
   status = getattr(message, "interaction_status", None)
   if status == "IDLE":
       # Ready for user input
       set_ui_state("listening")
   elif status == "IN_PROGRESS":
       # Reasoning or executing tools
       set_ui_state("thinking")
   ```

   {% /tab %}
   {% tab label="JavaScript" %}

   ```js
   if (message.interactionStatus === 'IDLE') {
     // Ready for user input
     setUiState('listening');
   } else if (message.interactionStatus === 'IN_PROGRESS') {
     // Reasoning or executing tools
     setUiState('thinking');
   }
   ```

   {% /tab %}
   {% /tabs %}
2. **Declare non-blocking functions**: Set `"behavior": "NON_BLOCKING"` on all
   function declarations. Thinking models run tools asynchronously in the
   background while streaming verbal updates. Synchronous blocking tools return
   an error.

   {% tabs %}
   {% tab label="Python" %}

   ```python
   search_flights = types.FunctionDeclaration(
       name="search_flights",
       description="Searches for available flights.",
       behavior="NON_BLOCKING",
       parameters={
           "type": "OBJECT",
           "properties": {
               "destination": {"type": "STRING"},
           },
           "required": ["destination"],
       },
   )
   ```

   {% /tab %}
   {% tab label="JavaScript" %}

   ```js
   const searchFlights = {
     name: 'search_flights',
     description: 'Searches for available flights.',
     behavior: 'NON_BLOCKING',
     parameters: {
       type: 'OBJECT',
       properties: {
         destination: { type: 'STRING' },
       },
       required: ['destination'],
     },
   };
   ```

   {% /tab %}
   {% /tabs %}
3. **Configure reasoning depth**: Set `thinking_config` in your session
   configuration to adjust reasoning levels (`low`, `medium`, or `high`;
   `MINIMAL` is not supported).

   {% tabs %}
   {% tab label="Python" %}

   ```python
   config = types.LiveConnectConfig(
       response_modalities=["AUDIO"],
       thinking_config=types.ThinkingConfig(
           thinking_level="low",
       ),
       tools=[types.Tool(function_declarations=[search_flights])],
   )
   ```

   {% /tab %}
   {% tab label="JavaScript" %}

   ```js
   const config = {
     responseModalities: [Modality.AUDIO],
     thinkingConfig: {
       thinkingLevel: 'low',
     },
     tools: [{ functionDeclarations: [searchFlights] }],
   };
   ```

   {% /tab %}
   {% /tabs %}
## Protocol side-by-side comparison {% id="protocol-comparison" %}

This section compares the WebSocket messages exchanged during each phase of a
Live API session.

### Step 1: Session setup {% id="step-1-setup" %}

Both models connect to the same WebSocket endpoint:

```text
wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateContent?key=$API_KEY
```

-   **Identical**: WebSocket URL and API key authentication.
-   **Model string**: `gemini-3.8-live` versus
    `gemini-3.8-live-extended-thinking`.
-   **Thinking configuration**: Thinking adds `thinkingConfig` to adjust
    reasoning depth.
-   **Tool behavior**: Thinking requires `"behavior": "NON_BLOCKING"` on
    function declarations.

{% tabs %}
{% tab label="Gemini 3.8 Live" %}

```json
{
  "setup": {
    "model": "models/gemini-3.8-live",
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {
          "prebuiltVoiceConfig": {
            "voiceName": "Puck"
          }
        }
      }
    }
  }
}
```

{% /tab %}
{% tab label="Gemini 3.8 Live Extended Thinking" %}

```json
{
  "setup": {
    "model": "models/gemini-3.8-live-extended-thinking",
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {
          "prebuiltVoiceConfig": {
            "voiceName": "Puck"
          }
        }
      },
      "thinkingConfig": {
        "thinkingLevel": "LOW"
      }
    },
    "tools": [{
      "functionDeclarations": [{
        "name": "searchFlights",
        "description": "Searches for flights between cities.",
        "behavior": "NON_BLOCKING",
        "parameters": {
          "type": "OBJECT",
          "properties": {
            "destination": { "type": "STRING" }
          },
          "required": ["destination"]
        }
      }]
    }]
  }
}
```

{% /tab %}
{% /tabs %}
Both models receive the same server acknowledgment upon connection:

```json
{
  "setupComplete": {}
}
```

### Step 2: User audio input {% id="step-2-user-input" %}

Audio streaming is identical across both models. Real-time 16kHz raw PCM audio
chunks are streamed using `realtimeInput`:

```json
{
  "realtimeInput": {
    "audio": {
      "data": "UklGRiQAAABXQVZF...",
      "mimeType": "audio/pcm;rate=16000"
    }
  }
}
```

### Step 3: Model response and state lifecycle {% id="step-3-model-response" %}

Both models stream 24kHz PCM audio chunks in `serverContent.modelTurn`. However,
lifecycle management differs:

#### Gemini 3.8 Live response flow

1.  The server streams audio chunks for the turn.
2.  The server sends `turnComplete: true`, indicating the model is finished
    speaking and the session is idle.

```json
// 1. Audio stream chunks
{
  "serverContent": {
    "modelTurn": {
      "parts": [
        {
          "inlineData": {
            "mimeType": "audio/pcm;rate=24000",
            "data": "..."
          }
        }
      ]
    }
  }
}

// 2. Turn completion -> Signals client to switch UI to Idle/Listening
{
  "serverContent": {
    "turnComplete": true
  }
}
```

#### Gemini 3.8 Live Extended Thinking response flow

1.  **Spoken filler**: The model emits intermediate speech (such as *"Checking
    flights to Seattle..."*) with `turnComplete: true` and `interactionStatus:
    "IN_PROGRESS"`.
2.  **Asynchronous tool call**: The server emits the tool call while
    `interactionStatus` remains `"IN_PROGRESS"`, indicating that the server is
    actively processing the multi-step turn and waiting for the tool response.
3.  **Tool response**: The client executes the function and returns the output.
4.  **Final response**: The server delivers the complete answer with
    `turnComplete: true` and `interactionStatus: "IDLE"`.

```json
// 1. Spoken verbal filler while background reasoning proceeds
{
  "serverContent": {
    "modelTurn": {
      "parts": [
        {
          "inlineData": {
            "mimeType": "audio/pcm;rate=24000",
            "data": "..."
          }
        }
      ]
    },
    "turnComplete": true,
    "interactionStatus": "IN_PROGRESS"
  }
}

// 2. Asynchronous tool call emitted with IN_PROGRESS status
{
  "toolCall": {
    "functionCalls": [
      {
        "id": "call_123",
        "name": "searchFlights",
        "args": {
          "destination": "Seattle"
        }
      }
    ]
  },
  "interactionStatus": "IN_PROGRESS"
}

// 3. Client executes function and returns result
{
  "toolResponse": {
    "functionResponses": [
      {
        "response": {
          "output": {
            "flight": "DL 145",
            "price": "$145"
          }
        },
        "id": "call_123"
      }
    ]
  }
}

// 4. Final spoken answer delivered -> session transitions to IDLE when done
{
  "serverContent": {
    "modelTurn": {
      "parts": [
        {
          "inlineData": {
            "mimeType": "audio/pcm;rate=24000",
            "data": "..."
          }
        }
      ]
    },
    "interactionStatus": "IDLE",
    "turnComplete": true
  }
}
```

## SDK implementation examples {% id="sdk-examples" %}

The following examples show how to configure Thinking and handle
`interaction_status` using the Google GenAI SDK.

{% tabs %}
{% tab label="Python" %}

```python
import asyncio
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.8-live-extended-thinking"

# Define non-blocking function declaration
search_flights = types.FunctionDeclaration(
    name="search_flights",
    description="Searches for available flights to a destination.",
    behavior="NON_BLOCKING",
    parameters={
        "type": "OBJECT",
        "properties": {
            "destination": {"type": "STRING"}
        },
        "required": ["destination"]
    }
)

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    thinking_config=types.ThinkingConfig(
        thinking_level="low"
    ),
    tools=[types.Tool(function_declarations=[search_flights])]
)

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session connected with Thinking")

        async for message in session.receive():
            # Inspect interaction status for server lifecycle tracking
            status = getattr(message, "interaction_status", None)
            if status:
                print(f"Interaction status: {status}")

            # Handle audio output parts
            if message.server_content and message.server_content.model_turn:
                for part in message.server_content.model_turn.parts:
                    if part.inline_data:
                        # Process 24kHz audio chunk
                        pass

            # Handle asynchronous tool call
            if message.tool_call:
                for call in message.tool_call.function_calls:
                    print(f"Executing tool: {call.name}")
                    # Simulate function execution
                    response = types.FunctionResponse(
                        id=call.id,
                        name=call.name,
                        response={"result": "Flight DL 145 ($145)"}
                    )
                    await session.send_tool_response(
                        function_responses=[response]
                    )

            # Status is IDLE when reasoning and all turns are complete
            if status == "IDLE":
                print("Session is idle and ready for user input.")

if __name__ == "__main__":
    asyncio.run(main())
```

{% /tab %}
{% tab label="JavaScript" %}

```js
import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.8-live-extended-thinking';

const searchFlights = {
  name: 'search_flights',
  description: 'Searches for available flights to a destination.',
  behavior: 'NON_BLOCKING',
  parameters: {
    type: 'OBJECT',
    properties: {
      destination: { type: 'STRING' }
    },
    required: ['destination']
  }
};

const config = {
  responseModalities: [Modality.AUDIO],
  thinkingConfig: {
    thinkingLevel: 'low'
  },
  tools: [{ functionDeclarations: [searchFlights] }]
};

async function main() {
  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: {
      onopen: () => console.log('Session connected'),
      onmessage: async (event) => {
        const message = JSON.parse(event.data);

        if (message.interactionStatus) {
          console.log(`Interaction status: ${message.interactionStatus}`);
        }

        if (message.toolCall) {
          for (const call of message.toolCall.functionCalls) {
            console.log(`Executing tool: ${call.name}`);
            session.sendToolResponse({
              functionResponses: [{
                id: call.id,
                name: call.name,
                response: { result: 'Flight DL 145 ($145)' }
              }]
            });
          }
        }

        if (message.interactionStatus === 'IDLE') {
          console.log('Session is idle and waiting for input.');
        }
      }
    }
  });
}

main();
```

{% /tab %}
{% /tabs %}
## What's next {% id="whats-next" %}

-   Read the [Gemini 3.8 Live][live-model] and
    [Gemini 3.8 Live Extended Thinking][thinking-model] model pages.
-   Check the [Model comparison][model-comparison] table for detailed feature
    comparisons across all Live API models.
-   Learn more about function calling in the [Live API Tool use][tool-use]
    guide.
-   Review [Session management][session-management] to handle session resumption
    and context lifecycle.

[live-model]: /docs/models/gemini-3.8-live
[thinking-model]: /docs/models/gemini-3.8-live-extended-thinking
[model-comparison]: /docs/live-api/capabilities#model-comparison
[tool-use]: /docs/live-api/tools
[session-management]: /docs/live-api/session-management

# Live transcription with Gemini Live API
Source: https://aistudio.google.com/docs/live-api/live-transcribe
Description: Low-latency, real-time speech-to-text transcription using the gemini-3.5-transcribe-live model.

The Gemini Live API supports low-latency, real-time speech-to-text transcription using the [`gemini-3.5-transcribe-live`](/docs/models/gemini-3.5-transcribe) model. By connecting to the Live API over WebSockets or using the Google Gen AI SDK, you can stream continuous audio input and receive incremental, real-time text transcriptions as speech occurs.

{% button href="https://aistudio.google.com/live?model=gemini-3.5-transcribe-live" variant="primary" icon="mic" %}
  Try Live Transcription in Google AI Studio
{% /button %}

{% button href="https://github.com/google-gemini/cookbook" variant="primary" icon="code" %}
  Open the Colab cookbook
{% /button %}

{% button href="/docs/coding-agents#gemini-live-api-dev" variant="primary" icon="terminal" %}
  Use coding agent skills
{% /button %}

By leveraging the Gemini Live API, developer platforms such as
[Agora](https://docs.agora.io/en/ai/models/asr/gemini),
[Fishjam](https://docs.fishjam.io/tutorials/gemini-live-integration),
[LiveKit](https://docs.livekit.io/agents/models/stt/gemini/),
[Pipecat](https://docs.pipecat.ai/api-reference/server/services/stt/google),
[Vercel](https://vercel.com/docs/ai-gateway/modalities/speech-to-text), and
[Vision Agents](https://visionagents.ai/integrations/stt/gemini)
enable developers to build and deploy high-performance voice-driven interfaces
with ease. These platforms manage complex real-time media streaming
infrastructure behind the scenes, allowing developers to focus entirely on
crafting the user experience.

## Live agent versus live Transcription {% id="live-agent-versus-live-transcription" %}

While both use the Live API bidirectional streaming connection, Live Transcription operates as a dedicated, low-latency speech recognition pipeline rather than a conversational agent.

| Feature | Live Agent | Live Transcription |
| :--- | :--- | :--- |
| **Primary role** | Conversational assistant that listens, reasons, and speaks back. | Real-time speech-to-text pipeline that transcribes incoming audio. |
| **Response modality** | Spoken audio and text (`response_modalities=["AUDIO"]`). | Streaming text transcriptions (`response_modalities=["TEXT"]`). |
| **Interaction style** | Turn-based dialogue with pause detection and interruptions. | Continuous stream processing as the speaker talks. |
| **Supported features** | Function calling, Google Search, system instructions, input audio transcription with speech biasing (`custom_vocabulary`) on `gemini-3.8-live`. | Speech biasing (`custom_vocabulary`), language detection, manual & hybrid VAD, Smart transcription. |
| **Input stream** | Multimodal: audio, video, images, text. | Audio input (raw 16-bit PCM). |

## Get started {% id="get-started" %}

The following examples demonstrate how to open a bidirectional streaming session with `gemini-3.5-transcribe-live` and receive real-time transcriptions.

{% tabs %}
{% tab label="Python" filename="live_transcribe_quickstart.py" %}
```python
import asyncio
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.5-transcribe-live"

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        language_codes=[],  # Automatic language detection
    ),
)

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session established with Live Transcription")

        # Receive transcription events
        async for response in session.receive():
            server_content = response.server_content
            if server_content and server_content.input_transcription:
                print("Transcript:", server_content.input_transcription.text)

if __name__ == "__main__":
    asyncio.run(main())
```
{% /tab %}
{% tab label="JavaScript" filename="live_transcribe_quickstart.js" %}
```javascript
import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.5-transcribe-live';

const config = {
  responseModalities: [Modality.TEXT],
  inputAudioTranscription: {
    languageCodes: [], // Automatic language detection
  },
};

async function main() {
  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: {
      onopen: () => console.log('Connected to Live Transcription'),
      onmessage: (message) => {
        const content = message.serverContent;
        if (content?.inputTranscription) {
          console.log('Transcript:', content.inputTranscription.text);
        }
      },
      onerror: (e) => console.error('Error:', e.message),
      onclose: (e) => console.log('Connection closed:', e.reason),
    },
  });
}

await main();
```
{% /tab %}
{% tab label="WebSockets" filename="live_transcribe_quickstart_ws.js" %}
```javascript
const API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.5-transcribe-live";
const WS_URL = `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=${API_KEY}`;

const websocket = new WebSocket(WS_URL);

websocket.onopen = () => {
  console.log('WebSocket connected');

  const setupMessage = {
    setup: {
      model: `models/${MODEL_NAME}`,
      generationConfig: {
        responseModalities: ['TEXT'],
      },
      inputAudioTranscription: {
        languageCodes: []
      }
    }
  };
  websocket.send(JSON.stringify(setupMessage));
};

websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  const content = response.serverContent;
  if (content?.inputTranscription) {
    console.log('Transcript:', content.inputTranscription.text);
  }
};
```
{% /tab %}
{% /tabs %}

## Interim and finalized transcriptions {% id="interim-transcriptions" %}

As audio streams into the Live API, the server emits two complementary transcription fields within `server_content`:

*   **`interim_input_transcription`**: low-latency, speculative partial hypotheses updated while the speaker is actively talking. These partial updates occur rapidly with minimal delay. Use `interim_input_transcription` to render responsive live UI subtitles or preview captions.
*   **`input_transcription`**: the finalized transcript emitted when the speaker pauses, the turn completes, or speech is finalized. Once emitted, this text represents the model's authoritative transcription of that speech segment. In smart transcription mode, this will include the cleaned, formatted response.

The following example demonstrates how to display streaming interim partials and commit final transcripts:

{% tabs %}
{% tab label="Python" filename="live_transcribe_interim.py" %}
```python
async def receive_transcripts(session):
    async for response in session.receive():
        server_content = response.server_content
        if not server_content:
            continue

        # Real-time interim hypothesis (updates dynamically as user speaks)
        if server_content.interim_input_transcription:
            interim_text = server_content.interim_input_transcription.text
            print(f"\r[Interim] {interim_text}", end="", flush=True)

        # Finalized transcript (emitted on speech completion)
        if server_content.input_transcription:
            final_text = server_content.input_transcription.text
            print(f"\n[Final] {final_text}")
```
{% /tab %}
{% tab label="JavaScript" filename="live_transcribe_interim.js" %}
```javascript
onmessage: (message) => {
  const content = message.serverContent;
  if (!content) return;

  if (content.interimInputTranscription) {
    // Update live subtitle preview on screen
    renderInterimPreview(content.interimInputTranscription.text);
  }

  if (content.inputTranscription) {
    // Append final committed transcript to chat history
    commitFinalTranscript(content.inputTranscription.text);
  }
};
```
{% /tab %}
{% tab label="WebSockets" filename="live_transcribe_interim_ws.js" %}
```javascript
websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  const content = response.serverContent;
  if (content?.interimInputTranscription) {
    console.log('[Interim]:', content.interimInputTranscription.text);
  }
  if (content?.inputTranscription) {
    console.log('[Final]:', content.inputTranscription.text);
  }
};
```
{% /tab %}
{% /tabs %}

## Sending audio {% id="sending-audio" %}

Stream audio chunks over the active connection as raw 16-bit PCM audio.

*   **Audio format:** Raw 16-bit PCM at 16kHz (mono, little-endian).
*   **Chunk size:** Send audio in chunks of 100ms (1,024 to 2,048 frames).
*   **MIME type:** `audio/pcm;rate=16000` (or the matching sample rate).

{% tabs %}
{% tab label="Python" filename="live_transcribe_send_audio.py" %}
```python
# Stream a raw PCM audio chunk
await session.send_realtime_input(
    audio=types.Blob(
        data=audio_chunk_bytes,
        mime_type="audio/pcm;rate=16000"
    )
)

# Signal the end of the audio stream when finished
await session.send_realtime_input(audio_stream_end=True)
```
{% /tab %}
{% tab label="JavaScript" filename="live_transcribe_send_audio.js" %}
```javascript
// Send base64-encoded PCM audio chunk
session.sendRealtimeInput({
  audio: {
    data: audioChunkBase64,
    mimeType: 'audio/pcm;rate=16000'
  }
});

// Signal stream end
session.sendRealtimeInput({
  audioStreamEnd: true
});
```
{% /tab %}
{% tab label="WebSockets" filename="live_transcribe_send_audio_ws.js" %}
```javascript
// Send base64-encoded PCM audio chunk
websocket.send(JSON.stringify({
  realtimeInput: {
    audio: {
      data: audioChunkBase64,
      mimeType: 'audio/pcm;rate=16000'
    }
  }
}));

// Signal stream end
websocket.send(JSON.stringify({
  realtimeInput: {
    audioStreamEnd: true
  }
}));
```
{% /tab %}
{% /tabs %}

## Transcription features {% id="transcription-features" %}

### Automatic language detection {% id="automatic-language-detection" %}

By default, omitting `language_codes` or setting `language_codes=[]` enables automatic language identification. The model dynamically detects the spoken language across utterances, including multilingual conversations and code-switching.

{% tabs %}
{% tab label="Python" filename="live_transcribe_auto_lang.py" %}
```python
config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        language_codes=[],
    ),
)
```
{% /tab %}
{% tab label="JavaScript" filename="live_transcribe_auto_lang.js" %}
```javascript
const config = {
  responseModalities: [Modality.TEXT],
  inputAudioTranscription: {
    languageCodes: [],
  },
};
```
{% /tab %}
{% tab label="WebSockets" filename="live_transcribe_auto_lang_ws.js" %}
```javascript
const setupMessage = {
  setup: {
    model: 'models/gemini-3.5-transcribe-live',
    generationConfig: {
      responseModalities: ['TEXT'],
    },
    inputAudioTranscription: {
      languageCodes: [],
    },
  },
};
websocket.send(JSON.stringify(setupMessage));
```
{% /tab %}
{% /tabs %}

### Specific language hint {% id="specific-language-hint" %}

Provide explicit BCP-47 language codes (for example, `["es-ES"]` for Spanish or `["fr-FR"]` for French) to bias recognition toward specific languages (see [Supported languages](/docs/live-api/live-transcribe#supported-languages)).

{% tabs %}
{% tab label="Python" filename="live_transcribe_lang_hint.py" %}
```python
config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        language_codes=["es-ES"],
    ),
)
```
{% /tab %}
{% tab label="JavaScript" filename="live_transcribe_lang_hint.js" %}
```javascript
const config = {
  responseModalities: [Modality.TEXT],
  inputAudioTranscription: {
    languageCodes: ['es-ES'],
  },
};
```
{% /tab %}
{% tab label="WebSockets" filename="live_transcribe_lang_hint_ws.js" %}
```javascript
const setupMessage = {
  setup: {
    model: 'models/gemini-3.5-transcribe-live',
    generationConfig: {
      responseModalities: ['TEXT'],
    },
    inputAudioTranscription: {
      languageCodes: ['es-ES'],
    },
  },
};
websocket.send(JSON.stringify(setupMessage));
```
{% /tab %}
{% /tabs %}

### Custom vocabulary biasing {% id="custom-vocabulary-biasing" %}

Provide a list of up to 1,000 phrases, proper nouns, brand names, or technical terms in `custom_vocabulary` to bias speech recognition toward specific terminology (best results are typically achieved with up to 100 terms).

{% tabs %}
{% tab label="Python" filename="live_transcribe_custom_vocab.py" %}
```python
config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        language_codes=[],
        custom_vocabulary=["Gemini", "Kubernetes", "BigQuery"],
    ),
)
```
{% /tab %}
{% tab label="JavaScript" filename="live_transcribe_custom_vocab.js" %}
```javascript
const config = {
  responseModalities: [Modality.TEXT],
  inputAudioTranscription: {
    languageCodes: [],
    customVocabulary: ['Gemini', 'Kubernetes', 'BigQuery'],
  },
};
```
{% /tab %}
{% tab label="WebSockets" filename="live_transcribe_custom_vocab_ws.js" %}
```javascript
const setupMessage = {
  setup: {
    model: 'models/gemini-3.5-transcribe-live',
    generationConfig: {
      responseModalities: ['TEXT'],
    },
    inputAudioTranscription: {
      languageCodes: [],
      customVocabulary: ['Gemini', 'Kubernetes', 'BigQuery'],
    },
  },
};
websocket.send(JSON.stringify(setupMessage));
```
{% /tab %}
{% /tabs %}

### Smart transcription {% id="smart-transcription" %}

Configure transcription output formatting using the `mode` parameter in `input_audio_transcription`:

*   **`VERBATIM` (default)**: Produces an exact literal transcript of everything spoken, preserving raw filler words ("um", "uh", "like"), repetitions, and false starts.
*   **`SMART` (Smart transcription)**: Cleans up and structures the transcript for readability:
    *   **Disfluency removal**: Removes filler words, stuttering, and false starts.
    *   **Inline self-corrections**: Resolves spoken corrections naturally.
    *   **Structured formatting**: Automatically formats lists, bullet points, numbers, dates, and paragraph breaks.
    *   **Grammar & casing**: Applies natural capitalization and punctuation polish.

{% tabs %}
{% tab label="Python" filename="live_transcribe_smart_mode.py" %}
```python
config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        mode="SMART",
    ),
)
```
{% /tab %}
{% tab label="JavaScript" filename="live_transcribe_smart_mode.js" %}
```javascript
const config = {
  responseModalities: [Modality.TEXT],
  inputAudioTranscription: {
    mode: 'SMART',
  },
};
```
{% /tab %}
{% tab label="WebSockets" filename="live_transcribe_smart_mode_ws.js" %}
```javascript
const setupMessage = {
  setup: {
    model: 'models/gemini-3.5-transcribe-live',
    generationConfig: {
      responseModalities: ['TEXT'],
    },
    inputAudioTranscription: {
      mode: 'SMART',
    },
  },
};
websocket.send(JSON.stringify(setupMessage));
```
{% /tab %}
{% /tabs %}

## Voice Activity Detection (VAD) strategies {% id="voice-activity-detection-vad-strategies" %}

### Automatic VAD (Default) {% id="automatic-vad-default" %}

By default, server-side automatic Voice Activity Detection detects when a speaker begins and stops speaking.

### Hybrid VAD {% id="hybrid-vad" %}

[Hybrid VAD](/docs/live-api/capabilities#hybrid-vad) combines server-side automatic speech start detection with client-side speech end detection for zero-latency turn finalization:

1.  **Server-side automatic VAD remains enabled** to detect speech beginnings accurately with prefix audio padding, preventing front-word truncation.
2.  **Client-side VAD detects silence**: When a local on-device VAD detects that the speaker has stopped talking, the client sends an `audio_stream_end` signal immediately.
3.  **Fast finalization**: The server treats `audio_stream_end` as an immediate turn finalization prompt, bypassing the default server-side silence wait time and returning the finalized transcript with minimal latency.
4.  **Fallback**: If the client VAD fails to trigger, the server-side VAD acts as an automatic fallback.

{% tabs %}
{% tab label="Python" filename="live_transcribe_hybrid_vad.py" %}
```python
config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    input_audio_transcription=types.AudioTranscriptionConfig(),
)

async with client.aio.live.connect(model=model, config=config) as session:
    # Stream audio chunks...
    await session.send_realtime_input(
        audio=types.Blob(data=chunk, mime_type="audio/pcm;rate=16000")
    )

    # When client-side VAD detects end of speech, send audio_stream_end:
    await session.send_realtime_input(audio_stream_end=True)
```
{% /tab %}
{% tab label="JavaScript" filename="live_transcribe_hybrid_vad.js" %}
```javascript
const config = {
  responseModalities: [Modality.TEXT],
  inputAudioTranscription: {},
};

// Stream audio...
session.sendRealtimeInput({
  audio: { data: chunkBase64, mimeType: 'audio/pcm;rate=16000' }
});

// When client VAD detects end of speech, send audioStreamEnd:
session.sendRealtimeInput({
  audioStreamEnd: true
});
```
{% /tab %}
{% tab label="WebSockets" filename="live_transcribe_hybrid_vad_ws.js" %}
```javascript
const setupMessage = {
  setup: {
    model: 'models/gemini-3.5-transcribe-live',
    generationConfig: {
      responseModalities: ['TEXT'],
    },
    inputAudioTranscription: {},
  },
};
websocket.send(JSON.stringify(setupMessage));

// Stream audio...
websocket.send(JSON.stringify({
  realtimeInput: {
    audio: { data: chunkBase64, mimeType: 'audio/pcm;rate=16000' }
  }
}));

// When client VAD detects end of speech, send audioStreamEnd:
websocket.send(JSON.stringify({
  realtimeInput: {
    audioStreamEnd: true
  }
}));
```
{% /tab %}
{% /tabs %}

### Manual VAD (Push-to-Talk) {% id="manual-vad-push-to-talk" %}

For walkie-talkie interfaces or push-to-talk buttons, disable automatic VAD entirely and control turn boundaries explicitly using `activity_start` and `activity_end`:

{% tabs %}
{% tab label="Python" filename="live_transcribe_manual_vad.py" %}
```python
config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    realtime_input_config=types.RealtimeInputConfig(
        automatic_activity_detection=types.AutomaticActivityDetection(
            disabled=True
        )
    ),
    input_audio_transcription=types.AudioTranscriptionConfig(),
)

async with client.aio.live.connect(model=model, config=config) as session:
    # Button pressed: signal speech start
    await session.send_realtime_input(activity_start=types.ActivityStart())

    # Stream audio chunks...
    await session.send_realtime_input(audio=types.Blob(data=chunk, mime_type="audio/pcm;rate=16000"))

    # Button released: signal speech end
    await session.send_realtime_input(activity_end=types.ActivityEnd())
```
{% /tab %}
{% tab label="JavaScript" filename="live_transcribe_manual_vad.js" %}
```javascript
const config = {
  responseModalities: [Modality.TEXT],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: true,
    },
  },
  inputAudioTranscription: {},
};

// Signal speech start
session.sendRealtimeInput({ activityStart: {} });

// Stream audio...

// Signal speech end
session.sendRealtimeInput({ activityEnd: {} });
```
{% /tab %}
{% tab label="WebSockets" filename="live_transcribe_manual_vad_ws.js" %}
```javascript
const setupMessage = {
  setup: {
    model: 'models/gemini-3.5-transcribe-live',
    generationConfig: {
      responseModalities: ['TEXT'],
    },
    realtimeInputConfig: {
      automaticActivityDetection: {
        disabled: true,
      },
    },
    inputAudioTranscription: {},
  },
};
websocket.send(JSON.stringify(setupMessage));

// Button pressed: signal speech start
websocket.send(JSON.stringify({
  realtimeInput: {
    activityStart: {},
  },
}));

// Stream audio...
websocket.send(JSON.stringify({
  realtimeInput: {
    audio: { data: chunkBase64, mimeType: 'audio/pcm;rate=16000' },
  },
}));

// Button released: signal speech end
websocket.send(JSON.stringify({
  realtimeInput: {
    activityEnd: {},
  },
}));
```
{% /tab %}
{% /tabs %}

## Ephemeral tokens in client applications {% id="ephemeral-tokens-in-client-applications" %}

For client-to-server applications (such as mobile or web apps streaming directly from a microphone), use [ephemeral tokens](/docs/live-api/ephemeral-tokens) to avoid exposing your API key in client code.

Create a constrained ephemeral token on your server before initiating the client connection:

{% tabs %}
{% tab label="Python" filename="live_transcribe_ephemeral_token.py" %}
```python
import datetime
from google import genai

client = genai.Client()
expire_time = datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(minutes=30)

token = client.auth_tokens.create(
    config={
        "uses": 1,
        "expire_time": expire_time,
        "live_connect_constraints": {
            "model": "gemini-3.5-transcribe-live",
            "config": {
                "response_modalities": ["TEXT"],
                "input_audio_transcription": {
                    "language_codes": [],
                },
            },
        },
    }
)
```
{% /tab %}
{% tab label="JavaScript" filename="live_transcribe_ephemeral_token.js" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();

const token = await client.authTokens.create({
  config: {
    uses: 1,
    expireTime: expireTime,
    liveConnectConstraints: {
      model: 'gemini-3.5-transcribe-live',
      config: {
        responseModalities: ['TEXT'],
        inputAudioTranscription: {
          languageCodes: [],
        },
      },
    },
  },
});
```
{% /tab %}
{% tab label="REST" filename="live_transcribe_ephemeral_token.sh" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uses": 1,
    "expireTime": "YYYY-MM-DDTHH:MM:SSZ",
    "liveConnectConstraints": {
      "model": "models/gemini-3.5-transcribe-live",
      "config": {
        "responseModalities": ["TEXT"],
        "inputAudioTranscription": {
          "languageCodes": []
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## Supported languages {% id="supported-languages" %}

The following languages and BCP-47 language codes are supported for Gemini 3.5 Transcribe Live:

| Language | BCP-47 Code | Language | BCP-47 Code |
| :--- | :--- | :--- | :--- |
| Afrikaans | `af-ZA` | Japanese | `ja-JP` |
| Amharic | `am-ET` | Javanese | `jv-ID` |
| Arabic (Egypt) | `ar-EG` | Kabuverdianu | `kea-CV` |
| Armenian | `hy-AM` | Kannada | `kn-IN` |
| Assamese | `as-IN` | Kazakh | `kk-KZ` |
| Azerbaijani | `az-AZ` | Korean | `ko-KR` |
| Belarusian | `be-BY` | Kyrgyz | `ky-KG` |
| Bengali (Bangladesh) | `bn-BD` | Latvian | `lv-LV` |
| Bengali (India) | `bn-IN` | Lingala | `ln-CD` |
| Bosnian | `bs-BA` | Lithuanian | `lt-LT` |
| Bulgarian | `bg-BG` | Macedonian | `mk-MK` |
| Bulgarian (Aromanian) | `rup-BG` | Malay | `ms-MY` |
| Burmese | `my-MM` | Malayalam | `ml-IN` |
| Cantonese (Traditional) | `yue-Hant-HK` | Maltese | `mt-MT` |
| Catalan | `ca-ES` | Mandarin Chinese (Simplified) | `cmn-Hans-CN` |
| Cebuano | `ceb` | Marathi | `mr-IN` |
| Central Khmer | `km-KH` | Mongolian | `mn-MN` |
| Croatian | `hr-HR` | Nepali | `ne-NP` |
| Czech | `cs-CZ` | Norwegian | `nb-NO` |
| Danish | `da-DK` | Oriya | `or-IN` |
| Dutch | `nl-NL` | Polish | `pl-PL` |
| English (Great Britain) | `en-GB` | Portuguese (Brazil) | `pt-BR` |
| English (India) | `en-IN` | Portuguese (Portugal) | `pt-PT` |
| English (United States) | `en-US` | Punjabi | `pa-IN` |
| Estonian | `et-EE` | Punjabi (Gurmukhi script) | `pa-Guru-IN` |
| Farsi | `fa-IR` | Romanian | `ro-RO` |
| Filipino | `fil-PH` | Russian | `ru-RU` |
| Finnish | `fi-FI` | Serbian | `sr-RS` |
| French | `fr-FR` | Sindhi (Arabic script) | `sd-Arab-IN` |
| Galician | `gl-ES` | Slovak | `sk-SK` |
| Georgian | `ka-GE` | Slovenian | `sl-SI` |
| German | `de-DE` | Spanish (Latin America) | `es-419` |
| Greek | `el-GR` | Spanish (United States) | `es-US` |
| Gujarati | `gu-IN` | Swahili (Kenya) | `sw-KE` |
| Hausa | `ha-NG` | Swedish | `sv-SE` |
| Hebrew | `he-IL` | Tajik | `tg-TJ` |
| Hindi | `hi-IN` | Telugu | `te-IN` |
| Hungarian | `hu-HU` | Thai | `th-TH` |
| Icelandic | `is-IS` | Turkish | `tr-TR` |
| Indian English | `en-IN` | Ukrainian | `uk-UA` |
| Indonesian | `id-ID` | Uzbek | `uz-UZ` |
| Italian | `it-IT` | Vietnamese | `vi-VN` |

## Parameter reference {% id="parameter-reference" %}

Configure live transcription using fields in `input_audio_transcription` and `realtime_input_config`:

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `language_codes` | Array of strings | BCP-47 language codes (e.g., `["en-US"]`). If omitted or empty (`[]`), the model automatically detects the language and handles multilingual speech. |
| `custom_vocabulary` | Array of strings | Up to 1,000 custom terms, acronyms, brand names, or proper nouns to bias speech recognition. |
| `mode` | String | Transcription mode: `"VERBATIM"` (default) or `"SMART"` (Smart transcription). When set to `"SMART"`, the model removes filler words, formats lists, and corrects disfluencies. |
| `automatic_activity_detection.disabled` | Boolean | Set to `true` to disable automatic voice activity detection and manually send `activityStart` and `activityEnd` signals. |

### Server response fields {% id="server-response-fields" %}

| Field | Description |
| :--- | :--- |
| `server_content.interim_input_transcription` | Low-latency, interim partial transcription hypothesis emitted continuously while the user is actively speaking. |
| `server_content.input_transcription` | Finalized, authoritative input transcript emitted when a speech turn finishes. |

## Limitations {% id="limitations" %}

*   **Session duration:** Live transcription sessions support continuous streaming for up to 10 minutes.
*   **Speaker diarization:** Speaker diarization is not supported in live streaming sessions. For speaker diarization, use the non-streaming [Audio transcription](/docs/transcribe#speaker-diarization) endpoint.
*   **Word-level timestamps:** Word-level timestamps are not supported over the Live API. The Live API emits utterance-level timestamps (`interim_input_transcription` and `input_transcription`).
*   **Custom vocabulary:** You can provide up to 1,000 terms in `custom_vocabulary`, but best results are typically achieved with up to 100 terms.
*   **Mode compatibility:** Smart transcription (`"mode": "SMART"`) removes filler words and formats intent-aware text, but cannot be combined with word annotations.

## What's next {% id="whats-next" %}

*   Read the [Gemini Transcribe documentation](/docs/transcribe) for non-streaming audio files.
*   Read the [Live API overview](/docs/live-api) for conversational voice agents.
*   Read the [Live translation guide](/docs/live-api/live-translate) for real-time speech-to-speech translation.
*   Check the [Pricing page](/docs/pricing#gemini-3.5-transcribe-live) for Live API streaming pricing.
*   Explore the [Live API capabilities guide](/docs/live-api/capabilities).

# Tool use with Live API
Source: https://aistudio.google.com/docs/live-api/tools
Description: Use tools with the Gemini Live API to enable external actions in real time.

Tool use allows Live API to go beyond just conversation by enabling it to
perform actions in the real-world and pull in external context while maintaining
a real time connection. You can define tools such as
[Function calling](/docs/function-calling) and [Google Search](/docs/google-search)
with the Live API.

## Overview of supported tools {% id="tools-overview" %}

{% table %}

*   Tool
*   Gemini 3.8 Live
*   Gemini 3.8 Live Extended Thinking
*   Gemini 3.1 Flash Live Preview
*   Gemini 2.5 Flash Live Preview
---

*   **Search**
*   Supported
*   Supported
*   Supported
*   Supported
---

*   **Function calling**
*   Supported (synchronous and [asynchronous](/docs/live-api/tools#async-function-calling))
*   Supported ([asynchronous only](/docs/live-api/tools#async-function-calling))
*   Supported (synchronous only)
*   Supported (synchronous and [asynchronous](/docs/live-api/tools#async-function-calling))
---

*   **Google Maps**
*   Not supported
*   Not supported
*   Not supported
*   Not supported
---

*   **Code execution**
*   Not supported
*   Not supported
*   Not supported
*   Not supported
---

*   **URL context**
*   Not supported
*   Not supported
*   Not supported
*   Not supported
{% /table %}
## Function calling {% id="function-calling" %}

Live API supports function calling, just like regular content generation
requests. Function calling lets the Live API interact with external data and
programs, greatly increasing what your applications can accomplish.

You can define function declarations as part of the session configuration.
After receiving tool calls, the client should respond with a list of
`FunctionResponse` objects using the `session.send_tool_response` method.

See the [Function calling tutorial](/docs/function-calling) to learn
more.

{% callout type="note" %}
Unlike the `generateContent` API, the Live API
doesn't support automatic tool response handling. You must handle tool responses
manually in your client code.
{% /callout %}

{% tabs %}
{% tab label="Python" %}

```python
import asyncio
import wave
from google import genai
from google.genai import types

client = genai.Client()

model = "gemini-3.8-live"

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["AUDIO"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000) # Output is 24kHz

        async for response in session.receive():
            if response.data is not None:
                wf.writeframes(response.data)
            elif response.tool_call:
                print("The tool was called")
                function_responses = []
                for fc in response.tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        id=fc.id,
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())
```

{% /tab %}
{% tab label="JavaScript" %}

```js
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
import pkg from 'wavefile'; // npm install wavefile
const { WaveFile } = pkg;

const ai = new GoogleGenAI({});
const model = 'gemini-3.8-live';

// Simple function definitions
const turn_on_the_lights = { name: "turn_on_the_lights" } // , description: '...', parameters: { ... }
const turn_off_the_lights = { name: "turn_off_the_lights" }

const tools = [{ functionDeclarations: [turn_on_the_lights, turn_off_the_lights] }]

const config = {
  responseModalities: [Modality.AUDIO],
  tools: tools
}

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      } else if (message.toolCall) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  const inputTurns = 'Turn on the lights please';
  session.sendClientContent({ turns: inputTurns });

  let turns = await handleTurn();

  for (const turn of turns) {
    if (turn.toolCall) {
      console.debug('A tool was called');
      const functionResponses = [];
      for (const fc of turn.toolCall.functionCalls) {
        functionResponses.push({
          id: fc.id,
          name: fc.name,
          response: { result: "ok" } // simple, hard-coded function response
        });
      }

      console.debug('Sending tool response...\n');
      session.sendToolResponse({ functionResponses: functionResponses });
    }
  }

  // Check again for new messages
  turns = await handleTurn();

  // Combine audio data strings and save as wave file
  const combinedAudio = turns.reduce((acc, turn) => {
      if (turn.data) {
          const buffer = Buffer.from(turn.data, 'base64');
          const intArray = new Int16Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / Int16Array.BYTES_PER_ELEMENT);
          return acc.concat(Array.from(intArray));
      }
      return acc;
  }, []);

  const audioBuffer = new Int16Array(combinedAudio);

  const wf = new WaveFile();
  wf.fromScratch(1, 24000, '16', audioBuffer); // output is 24kHz
  fs.writeFileSync('audio.wav', wf.toBuffer());

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

await main();
```

{% /tab %}
{% /tabs %}

From a single prompt, the model can generate multiple function calls and the
code necessary to chain their outputs. This code executes in a sandbox
environment, generating subsequent [BidiGenerateContentToolCall](https://ai.google.dev/api/live#bidigeneratecontenttoolcall) messages.

## Asynchronous function calling {% id="async-function-calling" %}

Function calling executes sequentially by default, meaning execution pauses
until the results of each function call are available. This ensures sequential
processing, which means you won't be able to continue interacting with the model
while the functions are being run.

{% callout type="note" %} Asynchronous function calling is supported on
`gemini-3.8-live` and required on `gemini-3.8-live-extended-thinking`. It is not
supported on `gemini-3.1-flash-live-preview`; for that model, execution pauses
until you send the tool response. {% /callout %}

If you don't want to block the conversation, you can tell the model to run the
functions asynchronously. To do so, you first need to add a `behavior` to the
function definitions:

{% tabs %}
{% tab label="Python" %}

```python
# Non-blocking function definitions
turn_on_the_lights = {"name": "turn_on_the_lights", "behavior": "NON_BLOCKING"} # turn_on_the_lights will run asynchronously
turn_off_the_lights = {"name": "turn_off_the_lights"} # turn_off_the_lights will still pause all interactions with the model
```
{% /tab %}
{% tab label="JavaScript" %}

```js
import { GoogleGenAI, Modality, Behavior } from '@google/genai';

// Non-blocking function definitions
const turn_on_the_lights = {name: "turn_on_the_lights", behavior: Behavior.NON_BLOCKING}

// Blocking function definitions
const turn_off_the_lights = {name: "turn_off_the_lights"}

const tools = [{ functionDeclarations: [turn_on_the_lights, turn_off_the_lights] }]
```
{% /tab %}
{% /tabs %}

`NON-BLOCKING` ensures the function runs asynchronously while you can
continue interacting with the model.

Then you need to tell the model how to behave when it receives the
`FunctionResponse` using the `scheduling` parameter. It can either:

* Interrupt what it's doing and tell you about the response it got right away
(`scheduling="INTERRUPT"`),

* Wait until it's finished with what it's currently doing
(`scheduling="WHEN_IDLE"`),

* Or do nothing and use that knowledge later on in the discussion
(`scheduling="SILENT"`)

{% tabs %}
{% tab label="Python" %}

```python
# for a non-blocking function definition, apply scheduling in the function response:
  function_response = types.FunctionResponse(
      id=fc.id,
      name=fc.name,
      response={
          "result": "ok",
          "scheduling": "INTERRUPT" # Can also be WHEN_IDLE or SILENT
      }
  )
```
{% /tab %}
{% tab label="JavaScript" %}

```js
import { GoogleGenAI, Modality, Behavior, FunctionResponseScheduling } from '@google/genai';

// for a non-blocking function definition, apply scheduling in the function response:
const functionResponse = {
  id: fc.id,
  name: fc.name,
  response: {
    result: "ok",
    scheduling: FunctionResponseScheduling.INTERRUPT // Can also be WHEN_IDLE or SILENT
  }
}
```
{% /tab %}
{% /tabs %}

## Grounding with Google Search {% id="google-search" %}

You can enable Grounding with Google Search as part of the session
configuration. This increases the Live API's accuracy and prevents
hallucinations. See the [Grounding tutorial](/docs/google-search) to
learn more.

{% tabs %}
{% tab label="Python" %}

```python
import asyncio
import wave
from google import genai
from google.genai import types

client = genai.Client()

model = "gemini-3.8-live"

tools = [{'google_search': {}}]
config = {"response_modalities": ["AUDIO"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000) # Output is 24kHz

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.data is not None:
                    wf.writeframes(chunk.data)

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                        if part.executable_code is not None:
                            print(part.executable_code.code)

                        if part.code_execution_result is not None:
                            print(part.code_execution_result.output)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())
```

{% /tab %}
{% tab label="JavaScript" %}

```js
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
import pkg from 'wavefile'; // npm install wavefile
const { WaveFile } = pkg;

const ai = new GoogleGenAI({});
const model = 'gemini-3.8-live';

const tools = [{ googleSearch: {} }]
const config = {
  responseModalities: [Modality.AUDIO],
  tools: tools
}

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      } else if (message.toolCall) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  const inputTurns = 'When did the last Brazil vs. Argentina soccer match happen?';
  session.sendClientContent({ turns: inputTurns });

  let turns = await handleTurn();

  let combinedData = '';
  for (const turn of turns) {
    if (turn.serverContent && turn.serverContent.modelTurn && turn.serverContent.modelTurn.parts) {
      for (const part of turn.serverContent.modelTurn.parts) {
        if (part.executableCode) {
          console.debug('executableCode: %s\n', part.executableCode.code);
        }
        else if (part.codeExecutionResult) {
          console.debug('codeExecutionResult: %s\n', part.codeExecutionResult.output);
        }
        else if (part.inlineData && typeof part.inlineData.data === 'string') {
          combinedData += atob(part.inlineData.data);
        }
      }
    }
  }

  // Convert the base64-encoded string of bytes into a Buffer.
  const buffer = Buffer.from(combinedData, 'binary');

  // The buffer contains raw bytes. For 16-bit audio, we need to interpret every 2 bytes as a single sample.
  const intArray = new Int16Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / Int16Array.BYTES_PER_ELEMENT);

  const wf = new WaveFile();
  // The API returns 16-bit PCM audio at a 24kHz sample rate.
  wf.fromScratch(1, 24000, '16', intArray);
  fs.writeFileSync('audio.wav', wf.toBuffer());

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

await main();
```

{% /tab %}
{% /tabs %}

## Combining multiple tools {% id="combine-tools" %}

You can combine multiple tools within the Live API,
increasing your application's capabilities even more:

{% tabs %}
{% tab label="Python" %}

```python
prompt = """
Hey, I need you to do two things for me.

1. Use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
2. Then turn on the lights

Thanks!
"""

tools = [
    {"google_search": {}},
    {"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]

config = {"response_modalities": ["AUDIO"], "tools": tools}

# ... remaining model call
```
{% /tab %}
{% tab label="JavaScript" %}

```js
const prompt = `Hey, I need you to do two things for me.

1. Use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
2. Then turn on the lights

Thanks!
`

const tools = [
  { googleSearch: {} },
  { functionDeclarations: [turn_on_the_lights, turn_off_the_lights] }
]

const config = {
  responseModalities: [Modality.AUDIO],
  tools: tools
}

// ... remaining model call
```
{% /tab %}
{% /tabs %}

## What's next {% id="whats-next" %}

* Check out more examples of using tools with the Live API in the
   [Tool use cookbook](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_LiveAPI_tools.ipynb).

* Get the full story on features and configurations from the
   [Live API Capabilities guide](/docs/live-api/capabilities).

# Session management with Live API
Source: https://aistudio.google.com/docs/live-api/session-management
Description: Manage real-time persistent sessions and connection states in the Live API.

In the Live API, a session refers to a persistent
connection where input and output are streamed continuously over the same
connection (read more about [how it works](/docs/live-api)).
This unique session design enables low latency and supports unique features, but
can also introduce challenges, like session time limits, and early termination.
This guide covers strategies for overcoming the session management challenges
that can arise when using the Live API.

## Session lifetime {% id="maximum-session-duration" %}

Without compression, audio-only sessions are limited to 15 minutes,
and audio-video sessions are limited to 2 minutes. Exceeding these limits
will terminate the session (and therefore, the connection), but you can use
[context window compression](/docs/live-api/session-management#context-window-compression) to extend sessions to
an unlimited amount of time.

The lifetime of a connection is limited as well, to around 10 minutes. When the
connection terminates, the session terminates as well. In this case, you can
configure a single session to stay active over multiple connections using
[session resumption](/docs/live-api/session-management#session-resumption).
You'll also receive a [GoAway message](/docs/live-api/session-management#goaway-message) before the
connection ends, allowing you to take further actions.

## Context window compression {% id="context-window-compression" %}

To enable longer sessions, and avoid abrupt connection termination, you can
enable context window compression by setting the [contextWindowCompression](https://ai.google.dev/api/live#BidiGenerateContentSetup.FIELDS.ContextWindowCompressionConfig.BidiGenerateContentSetup.context_window_compression)
field as part of the session configuration.

In the [ContextWindowCompressionConfig](https://ai.google.dev/api/live#contextwindowcompressionconfig), you can configure a
[sliding-window mechanism](https://ai.google.dev/api/live#ContextWindowCompressionConfig.FIELDS.ContextWindowCompressionConfig.SlidingWindow.ContextWindowCompressionConfig.sliding_window)
and the [number of tokens](https://ai.google.dev/api/live#ContextWindowCompressionConfig.FIELDS.int64.ContextWindowCompressionConfig.trigger_tokens)
that triggers compression.

{% tabs %}
{% tab label="Python" %}

```python
from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)
```
{% /tab %}
{% tab label="JavaScript" %}

```js
const config = {
  responseModalities: [Modality.AUDIO],
  contextWindowCompression: { slidingWindow: {} }
};
```
{% /tab %}
{% /tabs %}

## Session resumption {% id="session-resumption" %}

To prevent session termination when the server periodically resets the WebSocket
connection, configure the [sessionResumption](https://ai.google.dev/api/live#BidiGenerateContentSetup.FIELDS.SessionResumptionConfig.BidiGenerateContentSetup.session_resumption)
field within the [setup configuration](https://ai.google.dev/api/live#BidiGenerateContentSetup).

Passing this configuration causes the
server to send [SessionResumptionUpdate](https://ai.google.dev/api/live#SessionResumptionUpdate)
messages, which can be used to resume the session by passing the last resumption
token as the [`SessionResumptionConfig.handle`](https://ai.google.dev/api/live#SessionResumptionConfig.FIELDS.string.SessionResumptionConfig.handle)
of the subsequent connection.

Resumption tokens are valid for 2 hr after the last sessions termination.

{% tabs %}
{% tab label="Python" %}

```python
import asyncio
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.8-live"

async def main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=model,
        config=types.LiveConnectConfig(
            response_modalities=["AUDIO"],
            session_resumption=types.SessionResumptionConfig(
                # The handle of the session to resume is passed here,
                # or else None to start a new session.
                handle=previous_session_handle
            ),
        ),
    ) as session:
        while True:
            await session.send_client_content(
                turns=types.Content(
                    role="user", parts=[types.Part(text="Hello world!")]
                )
            )
            async for message in session.receive():
                # Periodically, the server will send update messages that may
                # contain a handle for the current state of the session.
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        # The handle should be retained and linked to the session.
                        return update.new_handle

                # For the purposes of this example, placeholder input is continually fed
                # to the model. In non-sample code, the model inputs would come from
                # the user.
                if message.server_content and message.server_content.turn_complete:
                    break

if __name__ == "__main__":
    asyncio.run(main())
```

{% /tab %}
{% tab label="JavaScript" %}

```js
import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.8-live';

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

console.debug('Connecting to the service with handle %s...', previousSessionHandle)
const session = await ai.live.connect({
  model: model,
  callbacks: {
    onopen: function () {
      console.debug('Opened');
    },
    onmessage: function (message) {
      responseQueue.push(message);
    },
    onerror: function (e) {
      console.debug('Error:', e.message);
    },
    onclose: function (e) {
      console.debug('Close:', e.reason);
    },
  },
  config: {
    responseModalities: [Modality.AUDIO],
    sessionResumption: { handle: previousSessionHandle }
    // The handle of the session to resume is passed here, or else null to start a new session.
  }
});

const inputTurns = 'Hello how are you?';
session.sendClientContent({ turns: inputTurns });

const turns = await handleTurn();
for (const turn of turns) {
  if (turn.sessionResumptionUpdate) {
    if (turn.sessionResumptionUpdate.resumable && turn.sessionResumptionUpdate.newHandle) {
      let newHandle = turn.sessionResumptionUpdate.newHandle
      // ...Store newHandle and start new session with this handle here
    }
  }
}

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

await main();
```

{% /tab %}
{% /tabs %}

## Receiving a message before the session disconnects {% id="goaway-message" %}

The server sends a [GoAway](https://ai.google.dev/api/live#GoAway) message that signals that the current
connection will soon be terminated. This message includes the [timeLeft](https://ai.google.dev/api/live#GoAway.FIELDS.google.protobuf.Duration.GoAway.time_left),
indicating the remaining time and lets you take further action before the
connection will be terminated as ABORTED.

{% tabs %}
{% tab label="Python" %}

```python
async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)
```
{% /tab %}
{% tab label="JavaScript" %}

```js
const turns = await handleTurn();

for (const turn of turns) {
  if (turn.goAway) {
    console.debug('Time left: %s\n', turn.goAway.timeLeft);
  }
}
```
{% /tab %}
{% /tabs %}

## Receiving a message when the generation is complete {% id="generation-complete-message" %}

The server sends a [generationComplete](https://ai.google.dev/api/live#BidiGenerateContentServerContent.FIELDS.bool.BidiGenerateContentServerContent.generation_complete)
message that signals that the model finished generating the response.

{% tabs %}
{% tab label="Python" %}

```python
async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete
```
{% /tab %}
{% tab label="JavaScript" %}

```js
const turns = await handleTurn();

for (const turn of turns) {
  if (turn.serverContent && turn.serverContent.generationComplete) {
    // The generation is complete
  }
}
```
{% /tab %}
{% /tabs %}

## What's next {% id="whats-next" %}

Explore more ways to work with the Live API in the full
[Capabilities](/docs/live-api) guide,
the [Tool use](/docs/live-api/tools) page, or the
[Live API cookbook](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_LiveAPI.ipynb).

# Ephemeral tokens in Live API
Source: https://aistudio.google.com/docs/live-api/ephemeral-tokens
Description: Learn how to generate short-lived ephemeral tokens for client-side authentication in the Live API.

{% callout type="note" %}
This feature is in [preview](/docs/models#preview).
{% /callout %}

Ephemeral tokens are short-lived authentication tokens for accessing the Gemini
API through [WebSockets][websocket]. They are designed to enhance security when
you are connecting directly from a user's device to the API (a
[client-to-server](/docs/live-api#implementation-approach)
implementation). Like standard API keys, ephemeral tokens can be extracted from
client-side applications such as web browsers or mobile apps. But because
ephemeral tokens expire quickly and can be restricted, they significantly reduce
the security risks in a production environment. You should use them when
accessing the Live API directly from client-side applications to enhance API
key security.

{% callout type="note" %}
At this time, ephemeral tokens are only compatible with [Live API][live].
{% /callout %}

## How ephemeral tokens work {% id="how-it-works" %}

Here's how ephemeral tokens work at a high level:

1.  Your client (e.g. web app) authenticates with your backend.
2.  Your backend requests an ephemeral token from Gemini API's provisioning
    service.
3.  Gemini API issues a short-lived token.
4.  Your backend sends the token to the client for WebSocket connections to Live
    API. You can do this by swapping your API key with an ephemeral token.
5.  The client then uses the token as if it were an API key.

![Ephemeral tokens overview](/googledevai/static/gemini-api/docs/images/Live_API_01.png)

This enhances security because even if extracted, the token is short-lived,
unlike a long-lived API key deployed client-side. Since the client sends data
directly to Gemini, this also improves latency and avoids your backends needing
to proxy the real time data.

## Create an ephemeral token {% id="create-a-token" %}

Here is a simplified example of how to get an ephemeral token from Gemini.
By default, you'll have 1 minute to start new Live API sessions using the token
from this request (`newSessionExpireTime`), and 30 minutes to send messages over
that connection (`expireTime`).

{% tabs %}
{% tab label="Python" %}

```python
import datetime
from google import genai

now = datetime.datetime.now(tz=datetime.timezone.utc)

client = genai.Client()

token = client.auth_tokens.create(
    config = {
    'uses': 1, # The ephemeral token can only be used to start a single session
    'expire_time': now + datetime.timedelta(minutes=30), # Default is 30 minutes in the future
    # 'expire_time': '2025-05-17T00:00:00Z',   # Accepts isoformat.
    'new_session_expire_time': now + datetime.timedelta(minutes=1), # Default 1 minute in the future
  }
)

# You'll need to pass the value under token.name back to your client to use it
```
{% /tab %}
{% tab label="JavaScript" %}

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

const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();

const token = await client.authTokens.create({
    config: {
      uses: 1, // The default
      expireTime: expireTime, // Default is 30 mins
      newSessionExpireTime: new Date(Date.now() + (1 * 60 * 1000)), // Default 1 minute in the future
    },
  });
```
{% /tab %}
{% tab label="REST" %}

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uses": 1,
    "expireTime": "YYYY-MM-DDTHH:MM:SSZ",
    "newSessionExpireTime": "YYYY-MM-DDTHH:MM:SSZ"
  }'
```
{% /tab %}
{% /tabs %}

For `expireTime` value constraints, defaults, and other field specs, see the
[API reference](https://ai.google.dev/api/live#ephemeral-auth-tokens).
Within the `expireTime` timeframe, you'll need
[`sessionResumption`](/docs/live-api/session-management#session-resumption) to
reconnect the call every 10 minutes (this can be done with the same token even
if `uses: 1`).

It's also possible to lock an ephemeral token to a set of configurations. This
might be useful to further improve security of your application and keep your
system instructions on the server side.

{% tabs %}
{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

token = client.auth_tokens.create(
    config = {
    'uses': 1,
    'live_connect_constraints': {
        'model': 'gemini-3.8-live',
        'config': {
            'session_resumption':{},
            'response_modalities':['AUDIO']
        }
    },
    }
)

# You'll need to pass the value under token.name back to your client to use it
```

{% /tab %}
{% tab label="JavaScript" %}

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

const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();

const token = await client.authTokens.create({
    config: {
        uses: 1, // The default
        expireTime: expireTime,
        liveConnectConstraints: {
            model: 'gemini-3.8-live',
            config: {
                sessionResumption: {},
                responseModalities: ['AUDIO']
            }
        },
    }
});

// You'll need to pass the value under token.name back to your client to use it
```

{% /tab %}
{% tab label="REST" %}

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uses": 1,
    "expireTime": "YYYY-MM-DDTHH:MM:SSZ",
    "liveConnectConstraints": {
      "model": "models/gemini-3.8-live",
      "config": {
        "sessionResumption": {},
        "responseModalities": ["AUDIO"]
      }
    }
  }'
```

{% /tab %}
{% /tabs %}

You can also lock a subset of fields, see the
[SDK documentation](https://googleapis.github.io/python-genai/genai.html#genai.types.CreateAuthTokenConfig.lock_additional_fields)
for more info.

## Connect to Live API with an ephemeral token {% id="connect-live-api" %}

Once you have an ephemeral token, you use it as if it were an API key (but
remember, it only works for the live API, and only with the `v1beta` version of
the API).

The use of ephemeral tokens only adds value when deploying applications that
follow the
[client-to-server implementation](/docs/live-api#implementation-approach)
approach.

{% tabs %}
{% tab label="JavaScript" %}

```javascript
import { GoogleGenAI, Modality } from '@google/genai';

// Use the token generated in the "Create an ephemeral token" section here
const ai = new GoogleGenAI({
  apiKey: token.name
});
const model = 'gemini-3.8-live';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: { ... },
  });

  // Send content...

  session.close();
}

await main();
```

{% /tab %}
{% /tabs %}

{% callout type="note" %}
If not using the SDK, note that ephemeral tokens must either be passed in
an `access_token` query parameter, or in an HTTP `Authorization` prefixed by the
[auth-scheme](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1)
`Token`.
{% /callout %}

See [Get started with Live API](/docs/live-api) for more examples.

## Best practices {% id="best-practices" %}

*   Set a short expiration duration using the `expire_time` parameter.
*   Tokens expire, requiring re-initiation of the provisioning process.
*   Verify secure authentication for your own backend. Ephemeral tokens will
    only be as secure as your backend authentication method.
*   Generally, avoid using ephemeral tokens for backend-to-Gemini connections,
    as this path is typically considered secure.

## Limitations {% id="limitations" %}

Ephemeral tokens are only compatible with [Live API][live] at this time.

## What's next {% id="whats-next" %}

*   Read the Live API [reference](https://ai.google.dev/api/live#ephemeral-auth-tokens)
on ephemeral tokens for more information.

[live]: /docs/live-api
[WebSocket]: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API

# Live API best practices
Source: https://aistudio.google.com/docs/live-api/best-practices
Description: Learn best practices to optimize your use of the Gemini Live API.

This guide covers best practices you can follow to
optimize your use of the Live API.
See [Get started with Live API](/docs/live-api)
page for an overview and sample code for common use cases.

## Design clear system instructions {% id="system-instruction-guidelines" %}

To get the best performance out of Live API, we recommend having a
clearly-defined set of system instructions (SIs) that defines the agent persona,
conversational rules, and guardrails, in this order.

For best results, separate each agent into a distinct SI.

1. **Specify the agent persona:** Provide detail on the agent's name, role, and
any preferred characteristics. If you want to specify the accent, be sure to
also specify the preferred output language (such as a British accent for an
English speaker).

1. **Specify the conversational rules:** Put these rules in the order you expect
the model to follow. Delineate between one-time elements of the conversation
and conversational loops. For example:
    * **One-time element:** Gather a customer's details once (such as name,
    location, loyalty card number).
    * **Conversational loop:** The user can discuss recommendations, pricing,
    returns, and delivery, and may want to go from topic to topic. Let the
    model know that it's OK to engage in this conversational loop for as
    long as the user wants.

1. **Specify tool calls within a flow in distinct sentences:** For example, if a
one-time step to gather a customer's details requires invoking a `get_user_info`
function, you might say: *Your first step is to gather user information. First,
ask the user to provide their name, location, and loyalty card number. Then
invoke `get_user_info` with these details.*

1. **Add any necessary guardrails:** Provide any general conversational
guardrails you don't want the model to do. Feel free to provide specific
examples of if *x* happens, you want the model to do *y*. If you're still not
getting the preferred level of precision, use the word
*unmistakably* to guide the model to be precise.

## Define tools precisely {% id="tool-definitions" %}

When using tools with Live API, be specific in your tool definitions.
Be sure to tell Gemini under what conditions a tool call should be
invoked. For more details, see [Tool definitions](/docs/live-api/best-practices#tool-definitions-example) in
the example section.

## Craft effective prompts {% id="prompt-design" %}

* **Use clear prompts:** Provide examples of what the models should and
shouldn't do in the prompts, and try to limit prompts to one prompt per persona
or role at a time. Instead of lengthy, multi-page prompts, consider using prompt
chaining instead. The model performs best on tasks with single function calls.

* **Provide starting commands and information:** Live API expects
user input before it responds. To have Live API initiate the
conversation, include a prompt asking it to greet the user or begin the
conversation. Include information about the user to have Live API
personalize that greeting.

## Specify language {% id="language-guidelines" %}

If you want the model to respond in a specific language, include the following
instruction in your system instructions:

```none
RESPOND IN {OUTPUT_LANGUAGE}. YOU MUST RESPOND UNMISTAKABLY IN {OUTPUT_LANGUAGE}.
```

## Streaming {% id="streaming-guidelines" %}

When implementing real-time audio, follow these best practices:

*   **Chunk Size and Latency**: Send audio in chunks of 20ms to 40ms.
*   **Interruption Handling**: When the user speaks while the model is replying,
    the server sends a `server_content` message with `"interrupted": true`. You
    must immediately discard your client-side audio buffer to prevent the agent
    from continuing to talk over the user.

## Context management {% id="context-management" %}

Use `ContextWindowCompressionConfig` for long sessions, as native audio tokens
accumulate rapidly (approximately 25 tokens per sec of audio).

## Client buffering {% id="client-buffering" %}

Don't buffer input audio significantly (such as 1 second) before sending. Send
small chunks (20ms - 100ms) to minimize latency.

## Resampling {% id="resampling" %}

Ensure your client application resamples microphone input (often 44.1kHz or
48kHz) to 16kHz before transmission.

## Session management {% id="session-management" %}

Follow these guidelines to handle session lifecycle and ensure a reliable user
experience:

*   **Enable context window compression:** Audio tokens accumulate at
    approximately 25 tokens per second. Without compression, audio-only sessions
    are limited to 15 minutes and audio-video sessions to 2 minutes. Enable
    [context window compression](/docs/live-api/session-management#context-window-compression)
    to extend sessions to an unlimited duration.
*   **Implement session resumption:** The server may periodically reset the
    WebSocket connection. Use
    [session resumption](/docs/live-api/session-management#session-resumption)
    to seamlessly reconnect without losing context. Retain the latest resumption
    token from `SessionResumptionUpdate` messages and pass it as the handle when
    reconnecting. Resumption tokens are valid for 2 hours after the last session
    terminates.
*   **Handle GoAway messages:** The server sends a
    [GoAway](/docs/live-api/session-management#goaway-message) message
    before terminating a connection. Listen for this message and use the
    `timeLeft` field to gracefully wrap up or reconnect before the connection
    closes.
*   **Handle generationComplete signals:** Use the
    [`generationComplete`](/docs/live-api/session-management#generation-complete-message)
    message to know when the model has finished generating a response, so your
    application can update its UI or proceed with the next action.

For implementation details, see
[Session management](/docs/live-api/session-management).

## Examples {% id="best-practices-example" %}

This example combines both the best practices and
[guidelines for system instruction design](/docs/live-api/best-practices#system-instruction-guidelines) to
guide the model's performance as a career coach.

```none
**Persona:**
You are Laura, a career coach from Brooklyn, NY. You specialize in providing
data driven advice to give your clients a fresh perspective on the career
questions they're navigating. Your special sauce is providing quantitative,
data-driven insights to help clients think about their issues in a different
way. You leverage statistics, research, and psychology as much as possible.
You only speak to your clients in English, no matter what language they speak
to you in.

**Conversational Rules:**

1. **Introduce yourself:** Warmly greet the client.

2. **Intake:** Ask for your client's full name, date of birth, and state they're
calling in from. Call `create_client_profile` to create a new patient profile.

3. **Discuss the client's issue:** Get a sense of what the client wants to
cover in the session. DO NOT repeat what the client is saying back to them in
your response. Don't ask more than a few questions here.

4. **Reframe the client's issue with real data:** NO PLATITUDES. Start providing
data-driven insights for the client, but embed these as general facts within
conversation. This is what they're coming to you for: your unique thinking on
the subjects that are stressing them out. Show them a new way of thinking about
something. Let this step go on for as long as the client wants. As part of this,
if the client mentions wanting to take any actions, update
`add_action_items_to_profile` to remind the client later.

5. **Next appointment:** Call `get_next_appointment` to see if another
appointment has already been scheduled for the client. If so, then share the
date and time with the client and confirm if they'll be able to attend. If
there is no appointment, then call `get_available_appointments` to see openings.
Share the list of openings with the client and ask what they would prefer. Save
their preference with `schedule_appointment`. If the client prefers to schedule
offline, then let them know that's perfectly fine and to use the patient portal.

**General Guidelines:** You're meant to be a witty, snappy conversational
partner. Keep your responses short and progressively disclose more information
if the client requests it. Don't repeat back what the client says back to them.
Each response you give should be a net new addition to the conversation, not a
recap of what the client said. Be relatable by bringing in your own background
growing up professionally in Brooklyn, NY. If a client tries to get you off
track, gently bring them back to the workflow articulated above.

**Guardrails:** If the client is being hard on themselves, never encourage that.
Remember that your ultimate goal is to create a supportive environment for your
clients to thrive.
```

### Tool definitions {% id="tool-definitions-example" %}

This JSON defines the relevant functions called in the career coach example.
For best results when defining functions, include their names, descriptions,
parameters, and invocation conditions.

```json
[
 {
   "name": "create_client_profile",
   "description": "Creates a new client profile with their personal details. Returns a unique client ID. \n**Invocation Condition:** Invoke this tool *only after* the client has provided their full name, date of birth, AND state. This should only be called once at the beginning of the 'Intake' step.",
   "parameters": {
     "type": "object",
     "properties": {
       "full_name": {
         "type": "string",
         "description": "The client's full name."
       },
       "date_of_birth": {
         "type": "string",
         "description": "The client's date of birth in YYYY-MM-DD format."
       },
       "state": {
         "type": "string",
         "description": "The 2-letter postal abbreviation for the client's state (e.g., 'NY', 'CA')."
       }
     },
     "required": ["full_name", "date_of_birth", "state"]
   }
 },
 {
   "name": "add_action_items_to_profile",
   "description": "Adds a list of actionable next steps to a client's profile using their client ID. \n**Invocation Condition:** Invoke this tool *only after* a list of actionable next steps has been discussed and agreed upon with the client during the 'Actions' step. Requires the `client_id` obtained from the start of the session.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client, obtained from create_client_profile."
       },
       "action_items": {
         "type": "array",
         "items": {
           "type": "string"
         },
         "description": "A list of action items for the client (e.g., ['Update resume', 'Research three companies'])."
       }
     },
     "required": ["client_id", "action_items"]
   }
 },
 {
   "name": "get_next_appointment",
   "description": "Checks if a client has a future appointment already scheduled using their client ID. Returns the appointment details or null. \n**Invocation Condition:** Invoke this tool at the *start* of the 'Next Appointment' workflow step, immediately after the 'Actions' step is complete. This is used to check if an appointment *already exists*.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       }
     },
     "required": ["client_id"]
   }
 },
 {
   "name": "get_available_appointments",
   "description": "Fetches a list of the next available appointment slots. \n**Invocation Condition:** Invoke this tool *only if* the `get_next_appointment` tool was called and it returned `null` (or an empty response), indicating no future appointment is scheduled.",
   "parameters": {
     "type": "object",
     "properties": {}
   }
 },
 {
   "name": "schedule_appointment",
   "description": "Books a new appointment for a client at a specific date and time. \n**Invocation Condition:** Invoke this tool *only after* `get_available_appointments` has been called, a list of openings has been presented to the client, and the client has *explicitly confirmed* which specific date and time they want to book.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       },
       "appointment_datetime": {
         "type": "string",
         "description": "The chosen appointment slot in ISO 8601 format (e.g., '2025-10-30T14:30:00')."
       }
     },
     "required": ["client_id", "appointment_datetime"]
   }
 }
]
```

## Pricing and billing {% id="pricing-billing" %}

The Gemini Live API bills strictly by token usage. Because the Live API maintains a persistent WebSocket session, billing follows a compounding model based on the active context window.

### The session context window (compounding costs) {% id="session-context-window" %}

The API charges you per turn for all tokens present in the session context window. A "turn" is defined as one user input and the model's corresponding response.

*   **Accumulation:** The context window includes new tokens from the current turn plus all accumulated tokens from previous turns.
*   **Re-billing:** Past tokens are re-processed and accounted for in each new turn, up to your configured context window size. As a session lengthens, the cost per turn increases because the conversational history is re-processed.

### Audio tokens and transcriptions {% id="audio-tokens-and-transcriptions" %}

The Live API is natively multimodal. It retains conversational history as raw audio tokens to preserve acoustic nuance and tone.

*   **Audio billing:** The API bills you for the accumulated native audio tokens at the standard audio input rate on every turn.
*   **Transcription surcharge:** When audio-to-text transcription is enabled (`inputAudioTranscription` or `outputAudioTranscription`), the API charges for all text tokens generated for transcription at the text token output rate in addition to the standard audio token costs.

### Managing costs with context limits {% id="managing-costs" %}

To prevent unbounded cost growth in long sessions, configure your context window size using `contextWindowCompression`.

By setting a compression trigger (e.g., 25,000 tokens) and a sliding window (e.g., 8,000 tokens), the API automatically evicts older tokens once the threshold is reached. The API then bills subsequent turns only for the retained history plus any new tokens.

### Proactive audio mode {% id="proactive-audio-mode" %}

When Proactive Audio Mode is enabled, input tokens are charged the entire time the Live API is listening, while output tokens are only charged when the API responds.

*   **Note for Gemini 3.8 and 3.1:** Proactive Audio Mode is supported on
    `gemini-3.8-live` and `gemini-3.8-live-extended-thinking`. It is not
    supported on `gemini-3.1-flash-live-preview`; for that model, you are only
    billed for audio when actively streaming input.

For detailed pricing information, see the [Gemini API pricing page](/docs/pricing).

# Gemini API optimization and inference
Source: https://aistudio.google.com/docs/optimization
Description: Learn about the different inference and optimization options from the Gemini API.

The Gemini API offers a variety of optimization mechanisms to help you balance
speed, cost, and reliability based on your specific workload needs.
Whether you're building real-time conversational bots or running heavy offline
data-processing pipelines, choosing the right paradigm can significantly cut
costs or boost performance.

| Feature | Standard | Flex | Priority | Batch | Caching |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Pricing** | Full Price | 50% discount | 75% to 100% more than standard | 50% discount | 90% discount + Prorated token storage |
| **Latency** | Seconds to minutes | Minutes (1–15 min target) | Seconds | Up to 24 hours | Faster time-to-first-token |
| **Reliability** | High / Medium-high | Best-effort (Sheddable) | High (Non-sheddable) | High (for throughput) | N/A |
| **Interface** | Synchronous | Synchronous | Synchronous | Asynchronous | Saved state |
| **Best use case** | General application workflows | Non-urgent sequential chains | Production, user-facing apps | Massive datasets, offline evals | Recurring queries over same file |

## Inference service tiers (Synchronous) {% id="inference-tiers" %}

You can shift between reliability-optimized and cost-optimized synchronous
traffic by passing the `service_tier` parameter in your standard generation
calls.

### Standard inference (Default) {% id="standard" %}

The standard tier is the default option for sequential content generation.
It provides normal response times without extra premiums or heavy queuing.

* **Reliability:** Standard criticality
* **Price:** Standard pricing.
* **Best For:** Most interactive day-to-day applications.

### Priority inference (Latency-optimized) {% id="priority" %}

[Priority](/docs/priority-inference) processing routes your requests
to high-criticality compute queues.
This traffic is strictly non-sheddable (never preempted by other tiers) and
offers the highest reliability. If you exceed dynamic Priority limits,
the system will gracefully downgrade the request to Standard processing instead
of failing with an error.

* **Reliability:** Highest criticality
* **Price:** 75% to 100% over Standard rates.
* **Best for:** Customer chatbots, real-time fraud detection, and
business-critical copilots.

### Flex inference (Cost-optimized) {% id="flex" %}

[Flex inference](/docs/flex-inference) offers a 50% discount
compared to standard rates by utilizing
opportunistic, off-peak compute capacity. Requests are processed
synchronously, meaning you don't need to rewrite code to manage batch objects.
Because it is "sheddable" traffic, requests may be preempted if the system
experiences standard traffic spikes.

* **Reliability:** Non-guaranteed, sheddable criticality
* **Price:** 50% of Standard Pricing (billed per token).
* **Best for:** Multi-step agentic workflows where call N+1 depends on the
output of call N, background CRM updates, and offline evaluations.

## Batch API (Bulk, asynchronous) {% id="batch" %}

[The Batch API](/docs/batch-api) is designed to process large volumes
of requests asynchronously at
50% of the standard cost. You can submit requests either as in-line dictionaries
or using a JSONL input file (up to 2GB). It processes requests using background
throughput queues with a target turnaround time of 24 hours.

* **Reliability:** Sheddable but with 24h automated retries and queuing system
* **Price:** 50% of Standard pricing.
* **Best for:** Pre-processing massive datasets, running periodic regression
test suites, and high-volume image or embedding generations.

## Context caching (Input savings) {% id="caching" %}

[Context caching](/docs/caching) is used when a substantial initial
context is referenced repeatedly by shorter requests.

* **Implicit caching:** Automatically enabled on Gemini 2.5 and newer models.
The system passes on cost savings if your request hits existing caches based on
common prompt prefixes.

* **Explicit Caching:** You can manually create a cache object with a specific
Time-To-Live (TTL). Once created, you refer to the cached tokens for subsequent
requests to avoid passing the same corpus payload repeatedly. Explicit caching
is not supported for Gemini 4 Argon and onward.

* **Price:** Billed based on cache token count and storage duration (TTL).
* **Best For:** Chatbots with extensive system instructions, repetitive analysis
of lengthy video files, or queries against large document sets.

## Reduce video input costs with agentic processing {% id="agentic-video-processing" %}

For long-form video content (over 5–10 minutes) or targeted queries, agentic processing can reduce input token costs by
up to 88% while improving response quality. By default, all models (including Gemini 4) use [static processing](/docs/video-understanding#agentic-video-understanding) to extract frames at 1 FPS. With agentic video understanding, the model inspects the video transcript first and dynamically loads visual segments at higher frame rates and resolutions only where needed. For
short clips (under 5 minutes) or broad full-video summaries, keep the default static processing mode
for a faster Time to First Token (TTFT) and lower token overhead. Agentic mode incurs internal reasoning (`total_thought_tokens`) and tool round-trips (`total_tool_use_tokens`) during timeline navigation.

To use agentic processing with Gemini 4 Argon, 3.8 Flash, 3.6 Flash, or 3.5 Flash Lite,
set `processing: "agentic"` (Interactions API) or
`media_processing: "AGENTIC"` (GenerateContent API) on your video input. If the
model does not support agentic processing, it will return an error.

For more information, see
[Agentic video understanding](/docs/video-understanding#agentic-video-understanding).

# Batch API
Source: https://aistudio.google.com/docs/batch-api
Description: Get started building with the Batch API

{% callout type="note" %}
This feature is currently only available with the generateContent API.
Please follow the content on this page for more information.
{% /callout %}

The Gemini Batch API is designed to process large volumes of requests
asynchronously at [50% of the standard cost](/docs/pricing).
The target turnaround time is 24 hours, but in majority of cases, it is much
quicker.

Use Batch API for large-scale, non-urgent tasks such as data
pre-processing or running evaluations where an immediate response is not
required.

## Creating a batch job {% id="create-batch-job" %}

You have two ways to submit your requests in Batch API:

* **[Inline requests](/docs/batch-api#inline-requests):** A list of
    [`GenerateContentRequest`](https://ai.google.dev/api/batch-mode#GenerateContentRequest) objects
    directly included in your batch creation request. This is suitable for
    smaller batches that keep the total request size under 20MB. The **output**
    returned from the model is a list of `inlineResponse` objects.

* **[Input file](/docs/batch-api#input-file):** A [JSON Lines (JSONL)](https://jsonlines.org/)
    file where each line contains a complete
    [`GenerateContentRequest`](https://ai.google.dev/api/batch-mode#GenerateContentRequest) object.
    This method is recommended for larger requests. The **output**
    returned from the model is a JSONL file where each line is either a
    `GenerateContentResponse` or a status object.

### Inline requests {% id="inline-requests" %}

For a small number of requests, you can directly embed the
[`GenerateContentRequest`](https://ai.google.dev/api/batch-mode#GenerateContentRequest) objects
within your [`BatchGenerateContentRequest`](https://ai.google.dev/api/batch-mode#request-body). The
following example calls the
[`BatchGenerateContent`](https://ai.google.dev/api/batch-mode#google.ai.generativelanguage.v1beta.BatchService.BatchGenerateContent)
method with inline requests:

{% tabs %}
{% tab label="Python" %}
```python

from google import genai
from google.genai import types

client = genai.Client()

# A list of dictionaries, where each is a GenerateContentRequest
inline_requests = [
    {
        'contents': [{
            'parts': [{'text': 'Tell me a one-sentence joke.'}],
            'role': 'user'
        }]
    },
    {
        'contents': [{
            'parts': [{'text': 'Why is the sky blue?'}],
            'role': 'user'
        }]
    }
]

inline_batch_job = client.batches.create(
    model="gemini-3.8-flash",
    src=inline_requests,
    config={
        'display_name': "inlined-requests-job-1",
    },
)

print(f"Created batch job: {inline_batch_job.name}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript

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

const ai = new GoogleGenAI({});

const inlinedRequests = [
    {
        contents: [{
            parts: [{text: 'Tell me a one-sentence joke.'}],
            role: 'user'
        }]
    },
    {
        contents: [{
            parts: [{'text': 'Why is the sky blue?'}],
            role: 'user'
        }]
    }
]

const response = await ai.batches.create({
    model: 'gemini-3.8-flash',
    src: inlinedRequests,
    config: {
        displayName: 'inlined-requests-job-1',
    }
});

console.log(response);
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.BatchJob;
import com.google.genai.types.BatchJobSource;
import com.google.genai.types.Content;
import com.google.genai.types.CreateBatchJobConfig;
import com.google.genai.types.InlinedRequest;
import com.google.genai.types.Part;
import java.util.List;

Client client = new Client();

// A list of InlinedRequest objects
List<InlinedRequest> inlineRequests =
    Arrays.asList(
        InlinedRequest.builder()
            .contents(
                Arrays.asList(
                    Content.builder()
                        .role("user")
                        .parts(Arrays.asList(Part.fromText("Tell me a one-sentence joke.")))
                        .build()))
            .build(),
        InlinedRequest.builder()
            .contents(
                Arrays.asList(
                    Content.builder()
                        .role("user")
                        .parts(Arrays.asList(Part.fromText("Why is the sky blue?")))
                        .build()))
            .build());

BatchJobSource src = BatchJobSource.builder().inlinedRequests(inlineRequests).build();
CreateBatchJobConfig config =
    CreateBatchJobConfig.builder().displayName("inlined-requests-job-1").build();

BatchJob inlineBatchJob = client.batches.create("gemini-3.8-flash", src, config);

System.out.println("Created batch job: " + inlineBatchJob.name().orElse(""));
```
{% /tab %}

{% tab label="REST" %}
```bash
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:batchGenerateContent \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-X POST \
-H "Content-Type:application/json" \
-d '{
    "batch": {
        "display_name": "my-batch-requests",
        "input_config": {
            "requests": {
                "requests": [
                    {
                        "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]},
                        "metadata": {
                            "key": "request-1"
                        }
                    },
                    {
                        "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]},
                        "metadata": {
                            "key": "request-2"
                        }
                    }
                ]
            }
        }
    }
}'
```
{% /tab %}
{% /tabs %}

### Input file {% id="input-file" %}

For larger sets of requests, prepare a JSON Lines (JSONL) file. Each line in
this file must be a JSON object containing a user-defined key and a request
object, where the request is a valid
[`GenerateContentRequest`](https://ai.google.dev/api/batch-mode#GenerateContentRequest) object. The
user-defined key is used in the response to indicate which output is the result
of which request. For example, the request with the key defined as `request-1`
will have its response annotated with the same key name.

This file is uploaded using the [File API](/docs/files). The maximum
allowed file size for an input file is 2GB.

The following is an example of a JSONL file. You can save it in a file named
`my-batch-requests.json`:

```json
{"key": "request-1", "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}], "generation_config": {"temperature": 0.7}}}
{"key": "request-2", "request": {"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}}
```

Similarly to inline requests, you can specify other parameters like system
instructions, tools or other configurations in each request JSON.

You can upload this file using the [File API](/docs/files) as
shown in the following example. If
you are working with multimodal input, you can reference other uploaded files
within your JSONL file.

{% tabs %}
{% tab label="Python" %}
```python

import json
from google import genai
from google.genai import types

client = genai.Client()

# Create a sample JSONL file
with open("my-batch-requests.jsonl", "w") as f:
    requests = [
        {"key": "request-1", "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]}},
        {"key": "request-2", "request": {"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}}
    ]
    for req in requests:
        f.write(json.dumps(req) + "\n")

# Upload the file to the File API
uploaded_file = client.files.upload(
    file='my-batch-requests.jsonl',
    config=types.UploadFileConfig(display_name='my-batch-requests', mime_type='jsonl')
)

print(f"Uploaded file: {uploaded_file.name}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript

import {GoogleGenAI} from '@google/genai';
import * as fs from "fs";
import * as path from "path";

const ai = new GoogleGenAI({});
const fileName = "my-batch-requests.jsonl";

// Define the requests
const requests = [
    { "key": "request-1", "request": { "contents": [{ "parts": [{ "text": "Describe the process of photosynthesis." }] }] } },
    { "key": "request-2", "request": { "contents": [{ "parts": [{ "text": "What are the main ingredients in a Margherita pizza?" }] }] } }
];

// Construct the path to file
const filePath = fileName;

async function writeBatchRequestsToFile(requests = [{ key: '', request: {} }], filePath = '') {
    try {
        // Use a writable stream for efficiency, especially with larger files.
        const writeStream = fs.createWriteStream(filePath, { flags: 'w' });

        writeStream.on('error', (err = null) => {
            console.error(`Error writing to file ${filePath}:`, err);
        });

        for (const req of requests) {
            writeStream.write(JSON.stringify(req) + '\n');
        }

        writeStream.end();

        console.log(`Successfully wrote batch requests to ${filePath}`);

    } catch (error) {
        // This catch block is for errors that might occur before stream setup,
        // stream errors are handled by the 'error' event.
        console.error(`An unexpected error occurred:`, error);
    }
}

// Write to a file.
await writeBatchRequestsToFile(requests, filePath);

// Upload the file to the File API.
const uploadedFile = await ai.files.upload({file: 'my-batch-requests.jsonl', config: {
    mimeType: 'jsonl',
}});
console.log(uploadedFile.name);
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;

Client client = new Client();

// Create a sample JSONL file
List<String> requests =
    Arrays.asList(
        "{\"key\": \"request-1\", \"request\": {\"contents\": [{\"parts\": [{\"text\": \"Describe the process of photosynthesis.\"}]}]}}",
        "{\"key\": \"request-2\", \"request\": {\"contents\": [{\"parts\": [{\"text\": \"What are the main ingredients in a Margherita pizza?\"}]}]}}");
Files.write(Paths.get("my-batch-requests.jsonl"), requests);

// Upload the file to the File API
UploadFileConfig uploadConfig =
    UploadFileConfig.builder()
        .displayName("my-batch-requests")
        .mimeType("jsonl")
        .build();
File uploadedFile = client.files.upload("my-batch-requests.jsonl", uploadConfig);

System.out.println("Uploaded file: " + uploadedFile.name().orElse(""));
```
{% /tab %}

{% tab label="REST" %}
```bash
tmp_batch_input_file=batch_input.tmp
echo -e '{"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}], "generationConfig": {"temperature": 0.7}}\n{"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}' > batch_input.tmp
MIME_TYPE=$(file -b --mime-type "${tmp_batch_input_file}")
NUM_BYTES=$(wc -c < "${tmp_batch_input_file}")
DISPLAY_NAME=BatchInput

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
-D "${tmp_header_file}" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/jsonl" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${tmp_batch_input_file}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
```
{% /tab %}
{% /tabs %}

The following example calls the
[`BatchGenerateContent`](https://ai.google.dev/api/batch-mode#google.ai.generativelanguage.v1beta.BatchService.BatchGenerateContent)
method with the input file uploaded using File API:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

# Assumes `uploaded_file` is the file object from the previous step
client = genai.Client()
file_batch_job = client.batches.create(
    model="gemini-3.8-flash",
    src=uploaded_file.name,
    config={
        'display_name': "file-upload-job-1",
    },
)

print(f"Created batch job: {file_batch_job.name}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// Assumes `uploadedFile` is the file object from the previous step
const fileBatchJob = await ai.batches.create({
    model: 'gemini-3.8-flash',
    src: uploadedFile.name,
    config: {
        displayName: 'file-upload-job-1',
    }
});

console.log(fileBatchJob);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.BatchJob;
import com.google.genai.types.BatchJobSource;
import com.google.genai.types.CreateBatchJobConfig;

Client client = new Client();

// Assumes `uploadedFileName` is the file name from the previous step
String uploadedFileName = "files/my-batch-requests-id";

BatchJobSource src = BatchJobSource.builder().fileName(uploadedFileName).build();
CreateBatchJobConfig config =
    CreateBatchJobConfig.builder().displayName("file-upload-job-1").build();

BatchJob fileBatchJob = client.batches.create("gemini-3.8-flash", src, config);

System.out.println("Created batch job: " + fileBatchJob.name().orElse(""));
```
{% /tab %}

{% tab label="REST" %}
```bash
# Set the File ID taken from the upload response.
BATCH_INPUT_FILE='files/123456'
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:batchGenerateContent \
-X POST \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type:application/json" \
-d "{
    'batch': {
        'display_name': 'my-batch-requests',
        'input_config': {
            'file_name': '${BATCH_INPUT_FILE}'
        }
    }
}"
```
{% /tab %}
{% /tabs %}

When you create a batch job, you will get a job name returned. Use this name
for [monitoring](/docs/batch-api#batch-job-status) the job status as well as
[retrieving the results](/docs/batch-api#retrieve-batch-results) once the job completes.

The following is an example output that contains a job name:

```none

Created batch job from file: batches/123456789

```

### Batch embedding support {% id="batch-embedding" %}

You can use the Batch API to interact with the
[Embeddings model](/docs/embeddings) for higher throughput.
To create an embeddings batch job with either [inline requests](/docs/batch-api#inline-requests)
or [input files](/docs/batch-api#input-file), use the `batches.create_embeddings` API and
specify the embeddings model.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

# Creating an embeddings batch job with an input file request:
file_job = client.batches.create_embeddings(
    model="gemini-embedding-2",
    src={'file_name': uploaded_batch_requests.name},
    config={'display_name': "Input embeddings batch"},
)

# Creating an embeddings batch job with an inline request:
batch_job = client.batches.create_embeddings(
    model="gemini-embedding-2",
    # For a predefined list of requests `inlined_requests`
    src={'inlined_requests': inlined_requests},
    config={'display_name': "Inlined embeddings batch"},
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// Creating an embeddings batch job with an input file request:
let fileJob;
fileJob = await client.batches.createEmbeddings({
    model: 'gemini-embedding-2',
    src: {fileName: uploadedBatchRequests.name},
    config: {displayName: 'Input embeddings batch'},
});
console.log(`Created batch job: ${fileJob.name}`);

// Creating an embeddings batch job with an inline request:
let batchJob;
batchJob = await client.batches.createEmbeddings({
    model: 'gemini-embedding-2',
    // For a predefined a list of requests `inlinedRequests`
    src: {inlinedRequests: inlinedRequests},
    config: {displayName: 'Inlined embeddings batch'},
});
console.log(`Created batch job: ${batchJob.name}`);
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.BatchJob;
import com.google.genai.types.Content;
import com.google.genai.types.CreateEmbeddingsBatchJobConfig;
import com.google.genai.types.EmbedContentBatch;
import com.google.genai.types.EmbeddingsBatchJobSource;
import com.google.genai.types.Part;
import java.util.List;

Client client = new Client();

String uploadedFileName = "files/my-embedding-requests-id";

// Creating an embeddings batch job with an input file request:
BatchJob fileJob =
    client.batches.createEmbeddings(
        "gemini-embedding-2",
        EmbeddingsBatchJobSource.builder().fileName(uploadedFileName).build(),
        CreateEmbeddingsBatchJobConfig.builder().displayName("Input embeddings batch").build());
System.out.println("Created batch job: " + fileJob.name().orElse(""));

// Creating an embeddings batch job with an inline request:
EmbedContentBatch inlinedRequests =
    EmbedContentBatch.builder()
        .contents(Arrays.asList(Content.fromParts(Part.fromText("What is the meaning of life?"))))
        .build();
BatchJob batchJob =
    client.batches.createEmbeddings(
        "gemini-embedding-2",
        EmbeddingsBatchJobSource.builder().inlinedRequests(inlinedRequests).build(),
        CreateEmbeddingsBatchJobConfig.builder().displayName("Inlined embeddings batch").build());
System.out.println("Created batch job: " + batchJob.name().orElse(""));
```
{% /tab %}

{% /tabs %}

Read the Embeddings section in the [Batch API cookbook](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Batch_mode.ipynb)
for more examples.

### Request configuration {% id="request-config" %}

You can include any request configurations you would use in a standard non-batch
request. For example, you could specify the temperature, system instructions or
even pass in other modalities. The following example shows an example inline
request that contains a system instruction for one of the requests:

{% tabs %}
{% tab label="Python" %}
```python
inline_requests_list = [
    {'contents': [{'parts': [{'text': 'Write a short poem about a cloud.'}]}]},
    {'contents': [{
        'parts': [{
            'text': 'Write a short poem about a cat.'
            }]
        }],
    'config': {
        'system_instruction': {'parts': [{'text': 'You are a cat. Your name is Neko.'}]}}
    }
]
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
inlineRequestsList = [
    {contents: [{parts: [{text: 'Write a short poem about a cloud.'}]}]},
    {contents: [{parts: [{text: 'Write a short poem about a cat.'}]}],
     config: {systemInstruction: {parts: [{text: 'You are a cat. Your name is Neko.'}]}}}
]
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.InlinedRequest;
import com.google.genai.types.Part;
import java.util.List;

List<InlinedRequest> inlineRequestsList =
    Arrays.asList(
        InlinedRequest.builder()
            .contents(Arrays.asList(Content.fromParts(Part.fromText("Write a short poem about a cloud."))))
            .build(),
        InlinedRequest.builder()
            .contents(Arrays.asList(Content.fromParts(Part.fromText("Write a short poem about a cat."))))
            .config(
                GenerateContentConfig.builder()
                    .systemInstruction(
                        Content.fromParts(Part.fromText("You are a cat. Your name is Neko.")))
                    .build())
            .build());
```
{% /tab %}

{% /tabs %}

Similarly can specify tools to use for a request. The following example
shows a request that enables the [Google Search tool](/docs/google-search):

{% tabs %}
{% tab label="Python" %}
```python
inlined_requests = [
{'contents': [{'parts': [{'text': 'Who won the euro 1998?'}]}]},
{'contents': [{'parts': [{'text': 'Who won the euro 2025?'}]}],
 'config':{'tools': [{'google_search': {}}]}}]
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
inlineRequestsList = [
    {contents: [{parts: [{text: 'Who won the euro 1998?'}]}]},
    {contents: [{parts: [{text: 'Who won the euro 2025?'}]}],
     config: {tools: [{googleSearch: {}}]}}
]
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GoogleSearch;
import com.google.genai.types.InlinedRequest;
import com.google.genai.types.Part;
import com.google.genai.types.Tool;
import java.util.List;

List<InlinedRequest> inlinedRequests =
    Arrays.asList(
        InlinedRequest.builder()
            .contents(Arrays.asList(Content.fromParts(Part.fromText("Who won the euro 1998?"))))
            .build(),
        InlinedRequest.builder()
            .contents(Arrays.asList(Content.fromParts(Part.fromText("Who won the euro 2025?"))))
            .config(
                GenerateContentConfig.builder()
                    .tools(Tool.builder().googleSearch(GoogleSearch.builder().build()).build())
                    .build())
            .build());
```
{% /tab %}

{% /tabs %}

You can specify [structured output](/docs/structured-output) as well.
The following example shows how to specify for your batch requests.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai
from pydantic import BaseModel, TypeAdapter

class Recipe(BaseModel):
    recipe_name: str
    ingredients: list[str]

client = genai.Client()

# A list of dictionaries, where each is a GenerateContentRequest
inline_requests = [
    {
        'contents': [{
            'parts': [{'text': 'List a few popular cookie recipes, and include the amounts of ingredients.'}],
            'role': 'user'
        }],
        'config': {
            'response_mime_type': 'application/json',
            'response_schema': list[Recipe]
        }
    },
    {
        'contents': [{
            'parts': [{'text': 'List a few popular gluten free cookie recipes, and include the amounts of ingredients.'}],
            'role': 'user'
        }],
        'config': {
            'response_mime_type': 'application/json',
            'response_schema': list[Recipe]
        }
    }
]

inline_batch_job = client.batches.create(
    model="gemini-3.8-flash",
    src=inline_requests,
    config={
        'display_name': "structured-output-job-1"
    },
)

# wait for the job to finish
job_name = inline_batch_job.name
print(f"Polling status for job: {job_name}")

while True:
    batch_job_inline = client.batches.get(name=job_name)
    if batch_job_inline.state.name in ('JOB_STATE_SUCCEEDED', 'JOB_STATE_FAILED', 'JOB_STATE_CANCELLED', 'JOB_STATE_EXPIRED'):
        break
    print(f"Job not finished. Current state: {batch_job_inline.state.name}. Waiting 30 seconds...")
    time.sleep(30)

print(f"Job finished with state: {batch_job_inline.state.name}")

# print the response
for i, inline_response in enumerate(batch_job_inline.dest.inlined_responses, start=1):
    print(f"\n--- Response {i} ---")

    # Check for a successful response
    if inline_response.response:
        # The .text property is a shortcut to the generated text.
        print(inline_response.response.text)

```
{% /tab %}
{% tab label="JavaScript" %}
```javascript

import {GoogleGenAI, Type} from '@google/genai';

const ai = new GoogleGenAI({});

const inlinedRequests = [
    {
        contents: [{
            parts: [{text: 'List a few popular cookie recipes, and include the amounts of ingredients.'}],
            role: 'user'
        }],
        config: {
            responseMimeType: 'application/json',
            responseSchema: {
            type: Type.ARRAY,
            items: {
                type: Type.OBJECT,
                properties: {
                'recipeName': {
                    type: Type.STRING,
                    description: 'Name of the recipe',
                    nullable: false,
                },
                'ingredients': {
                    type: Type.ARRAY,
                    items: {
                    type: Type.STRING,
                    description: 'Ingredients of the recipe',
                    nullable: false,
                    },
                },
                },
                required: ['recipeName'],
            },
            },
        }
    },
    {
        contents: [{
            parts: [{text: 'List a few popular gluten free cookie recipes, and include the amounts of ingredients.'}],
            role: 'user'
        }],
        config: {
            responseMimeType: 'application/json',
            responseSchema: {
            type: Type.ARRAY,
            items: {
                type: Type.OBJECT,
                properties: {
                'recipeName': {
                    type: Type.STRING,
                    description: 'Name of the recipe',
                    nullable: false,
                },
                'ingredients': {
                    type: Type.ARRAY,
                    items: {
                    type: Type.STRING,
                    description: 'Ingredients of the recipe',
                    nullable: false,
                    },
                },
                },
                required: ['recipeName'],
            },
            },
        }
    }
]

const inlinedBatchJob = await ai.batches.create({
    model: 'gemini-3.8-flash',
    src: inlinedRequests,
    config: {
        displayName: 'inlined-requests-job-1',
    }
});
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.HashMap;
import java.util.HashSet;
import java.util.Arrays;
import java.util.Collections;
import com.google.genai.Client;
import com.google.genai.types.BatchJob;
import com.google.genai.types.BatchJobSource;
import com.google.genai.types.Content;
import com.google.genai.types.CreateBatchJobConfig;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.InlinedRequest;
import com.google.genai.types.InlinedResponse;
import com.google.genai.types.JobState;
import com.google.genai.types.Part;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;
import java.util.List;
import java.util.Map;
import java.util.Set;

Client client = new Client();

Map<String, Schema> properties = new HashMap<>();
properties.put("recipeName", Schema.builder().type(Type.Known.STRING).build());
properties.put(
    "ingredients",
    Schema.builder()
        .type(Type.Known.ARRAY)
        .items(Schema.builder().type(Type.Known.STRING).build())
        .build());

Schema recipeSchema =
    Schema.builder()
        .type(Type.Known.ARRAY)
        .items(
            Schema.builder()
                .type(Type.Known.OBJECT)
                .properties(
properties)
                .required("recipeName")
                .build())
        .build();

GenerateContentConfig jsonConfig =
    GenerateContentConfig.builder()
        .responseMimeType("application/json")
        .responseSchema(recipeSchema)
        .build();

List<InlinedRequest> inlineRequests =
    Arrays.asList(
        InlinedRequest.builder()
            .contents(
                Arrays.asList(
                    Content.builder()
                        .role("user")
                        .parts(
                            Arrays.asList(
                                Part.fromText(
                                    "List a few popular cookie recipes, and include the amounts of ingredients.")))
                        .build()))
            .config(jsonConfig)
            .build(),
        InlinedRequest.builder()
            .contents(
                Arrays.asList(
                    Content.builder()
                        .role("user")
                        .parts(
                            Arrays.asList(
                                Part.fromText(
                                    "List a few popular gluten free cookie recipes, and include the amounts of ingredients.")))
                        .build()))
            .config(jsonConfig)
            .build());

BatchJob inlineBatchJob =
    client.batches.create(
        "gemini-3.8-flash",
        BatchJobSource.builder().inlinedRequests(inlineRequests).build(),
        CreateBatchJobConfig.builder().displayName("structured-output-job-1").build());

// Wait for the job to finish
String jobName = inlineBatchJob.name().get();
System.out.println("Polling status for job: " + jobName);

Set<JobState.Known> completedStates =
    new HashSet<>(Arrays.asList(
        JobState.Known.JOB_STATE_SUCCEEDED,
        JobState.Known.JOB_STATE_FAILED,
        JobState.Known.JOB_STATE_CANCELLED,
        JobState.Known.JOB_STATE_EXPIRED));

BatchJob batchJobInline = client.batches.get(jobName, null);
while (!completedStates.contains(batchJobInline.state().get().knownEnum())) {
  System.out.println(
      "Job not finished. Current state: " + batchJobInline.state().get() + ". Waiting 30 seconds...");
  Thread.sleep(30000);
  batchJobInline = client.batches.get(jobName, null);
}

System.out.println("Job finished with state: " + batchJobInline.state().get());

// Print the response
List<InlinedResponse> responses = batchJobInline.dest().get().inlinedResponses().orElse(Collections.emptyList());
for (int i = 0; i < responses.size(); i++) {
  System.out.println("\n--- Response " + (i + 1) + " ---");
  InlinedResponse inlineResponse = responses.get(i);
  if (inlineResponse.response().isPresent()) {
    System.out.println(inlineResponse.response().get().text());
  }
}
```
{% /tab %}

{% /tabs %}

The following shows an example output of this job:

```json
--- Response 1 ---
[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed light brown sugar",
      "1 large egg",
      "1 teaspoon vanilla extract",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1/2 teaspoon salt",
      "1 1/2 cups chocolate chips"
    ]
  },
  {
    "recipe_name": "Oatmeal Raisin Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "1 cup packed light brown sugar",
      "1/2 cup granulated sugar",
      "2 large eggs",
      "1 teaspoon vanilla extract",
      "1 1/2 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon ground cinnamon",
      "1/2 teaspoon salt",
      "3 cups old-fashioned rolled oats",
      "1 cup raisins"
    ]
  },
  {
    "recipe_name": "Sugar Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "1 1/2 cups granulated sugar",
      "1 large egg",
      "1 teaspoon vanilla extract",
      "2 3/4 cups all-purpose flour",
      "1 teaspoon baking powder",
      "1/2 teaspoon salt"
    ]
  }
]

--- Response 2 ---
[
  {
    "recipe_name": "Gluten-Free Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed light brown sugar",
      "2 large eggs",
      "1 teaspoon vanilla extract",
      "2 1/4 cups gluten-free all-purpose flour blend (with xanthan gum)",
      "1 teaspoon baking soda",
      "1/2 teaspoon salt",
      "1 1/2 cups chocolate chips"
    ]
  },
  {
    "recipe_name": "Gluten-Free Peanut Butter Cookies",
    "ingredients": [
      "1 cup (250g) creamy peanut butter",
      "1/2 cup (100g) granulated sugar",
      "1/2 cup (100g) packed light brown sugar",
      "1 large egg",
      "1 teaspoon vanilla extract",
      "1/2 teaspoon baking soda",
      "1/4 teaspoon salt"
    ]
  },
  {
    "recipe_name": "Gluten-Free Oatmeal Raisin Cookies",
    "ingredients": [
      "1/2 cup (1 stick) unsalted butter, softened",
      "1/2 cup granulated sugar",
      "1/2 cup packed light brown sugar",
      "1 large egg",
      "1 teaspoon vanilla extract",
      "1 cup gluten-free all-purpose flour blend",
      "1/2 teaspoon baking soda",
      "1/2 teaspoon ground cinnamon",
      "1/4 teaspoon salt",
      "1 1/2 cups gluten-free rolled oats",
      "1/2 cup raisins"
    ]
  }
]
```

## Monitoring job status {% id="batch-job-status" %}

Use the operation name obtained when creating the batch job to poll its status.
The state field of the batch job will indicate its current status. A batch job
can be in one of the following states:

* `JOB_STATE_PENDING`: The job has been created and is waiting to be processed by the service.
* `JOB_STATE_RUNNING`: The job is in progress.
* `JOB_STATE_SUCCEEDED`: The job completed successfully. You can now retrieve the results.
* `JOB_STATE_FAILED`: The job failed. Check the error details for more information.
* `JOB_STATE_CANCELLED`: The job was cancelled by the user.
* `JOB_STATE_EXPIRED`: The job has expired because it was running or pending
    for more than 48 hours. The job will not have any results to retrieve.
    You can try submitting the job again or splitting up
    the requests into smaller batches.

You can poll the job status periodically to check for completion.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

# Use the name of the job you want to check
# e.g., inline_batch_job.name from the previous step
job_name = "YOUR_BATCH_JOB_NAME" # (e.g. 'batches/your-batch-id')
batch_job = client.batches.get(name=job_name)

completed_states = set([
    'JOB_STATE_SUCCEEDED',
    'JOB_STATE_FAILED',
    'JOB_STATE_CANCELLED',
    'JOB_STATE_EXPIRED',
])

print(f"Polling status for job: {job_name}")
batch_job = client.batches.get(name=job_name) # Initial get
while batch_job.state.name not in completed_states:
  print(f"Current state: {batch_job.state.name}")
  time.sleep(30) # Wait for 30 seconds before polling again
  batch_job = client.batches.get(name=job_name)

print(f"Job finished with state: {batch_job.state.name}")
if batch_job.state.name == 'JOB_STATE_FAILED':
    print(f"Error: {batch_job.error}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// Use the name of the job you want to check
// e.g., inlinedBatchJob.name from the previous step
let batchJob;
const completedStates = new Set([
    'JOB_STATE_SUCCEEDED',
    'JOB_STATE_FAILED',
    'JOB_STATE_CANCELLED',
    'JOB_STATE_EXPIRED',
]);

try {
    batchJob = await ai.batches.get({name: inlinedBatchJob.name});
    while (!completedStates.has(batchJob.state || '')) {
        console.log(`Current state: ${batchJob.state}`);
        // Wait for 30 seconds before polling again
        await new Promise(resolve => setTimeout(resolve, 30000));
        batchJob = await client.batches.get({ name: batchJob.name });
    }
    console.log(`Job finished with state: ${batchJob.state}`);
    if (batchJob.state === 'JOB_STATE_FAILED') {
        // The exact structure of `error` might vary depending on the SDK
        // This assumes `error` is an object with a `message` property.
        console.error(`Error: ${batchJob.state}`);
    }
} catch (error) {
    console.error(`An error occurred while polling job ${batchJob.name}:`, error);
}
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.HashSet;
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.BatchJob;
import com.google.genai.types.JobState;
import java.util.Set;

Client client = new Client();

// Use the name of the job you want to check
String jobName = "batches/your-batch-id";

Set<JobState.Known> completedStates =
    new HashSet<>(Arrays.asList(
        JobState.Known.JOB_STATE_SUCCEEDED,
        JobState.Known.JOB_STATE_FAILED,
        JobState.Known.JOB_STATE_CANCELLED,
        JobState.Known.JOB_STATE_EXPIRED));

System.out.println("Polling status for job: " + jobName);
BatchJob batchJob = client.batches.get(jobName, null);
while (!completedStates.contains(batchJob.state().get().knownEnum())) {
  System.out.println("Current state: " + batchJob.state().get());
  Thread.sleep(30000); // Wait for 30 seconds before polling again
  batchJob = client.batches.get(jobName, null);
}

System.out.println("Job finished with state: " + batchJob.state().get());
if (batchJob.state().get().knownEnum() == JobState.Known.JOB_STATE_FAILED) {
  System.out.println("Error: " + batchJob.error().orElse(null));
}
```
{% /tab %}

{% /tabs %}

### Polling and webhooks {% id="webhooks" %}

**Tired of polling?** Gemini now supports
[Webhooks](/docs/webhooks) for processing completions asynchronously.
Instead of continuously calling `GET / operations`, subscribe to
`batch.succeeded` directly to allow the Gemini API to push real-time
notifications to your server when asynchronous or long-running operations
complete.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

webhook = client.webhooks.create(
    name="MyBatchWebhook",
    subscribed_events=["batch.succeeded", "batch.failed"],
    uri="https://my-api.com/gemini-callback",
)

print(f"Created webhook: {webhook.name}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

async function createWebhook() {
  const webhook = await client.webhooks.create({
    name: "MyBatchWebhook",
    subscribed_events: ["batch.succeeded", "batch.failed"],
    uri: "https://my-api.com/gemini-callback",
  });

  console.log(`Created webhook: ${webhook.name}`);
}

await createWebhook();
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.gaos.models.webhooks.Webhook;
import com.google.genai.gaos.models.webhooks.WebhookInput;
import com.google.genai.gaos.models.webhooks.WebhookSubscribedEvent;
import java.util.List;

Client client = new Client();

WebhookInput input =
    WebhookInput.builder()
        .name("MyBatchWebhook")
        .subscribedEvents(
            Arrays.asList(
                WebhookSubscribedEvent.BATCH_SUCCEEDED,
                WebhookSubscribedEvent.BATCH_FAILED))
        .uri("https://my-api.com/gemini-callback")
        .build();

Webhook webhook = client.webhooks.create(input).webhook().get();
System.out.println("Created webhook: " + webhook.name().orElse(""));
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST \
  "https://generativelanguage.googleapis.com/v1/webhooks?webhook_id=my-example-webhook-123" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GOOGLE_API_KEY" \
  -d '{
    "name": "My Example Webhook",
    "uri": "https://my-api.com/gemini-callback",
    "subscribed_events": ["batch.succeeded", "batch.failed"]
  }'
```
{% /tab %}
{% /tabs %}

## Retrieving results {% id="retrieve-batch-results" %}

Once the job status indicates your batch job has succeeded, the results are
available in the `response` field.

{% tabs %}
{% tab label="Python" %}
```python
import json
from google import genai

client = genai.Client()

# Use the name of the job you want to check
# e.g., inline_batch_job.name from the previous step
job_name = "YOUR_BATCH_JOB_NAME"
batch_job = client.batches.get(name=job_name)

if batch_job.state.name == 'JOB_STATE_SUCCEEDED':

    # If batch job was created with a file
    if batch_job.dest and batch_job.dest.file_name:
        # Results are in a file
        result_file_name = batch_job.dest.file_name
        print(f"Results are in file: {result_file_name}")

        print("Downloading result file content...")
        file_content = client.files.download(file=result_file_name)
        # Process file_content (bytes) as needed
        print(file_content.decode('utf-8'))

    # If batch job was created with inline request
    # (for embeddings, use batch_job.dest.inlined_embed_content_responses)
    elif batch_job.dest and batch_job.dest.inlined_responses:
        # Results are inline
        print("Results are inline:")
        for i, inline_response in enumerate(batch_job.dest.inlined_responses):
            print(f"Response {i+1}:")
            if inline_response.response:
                # Accessing response, structure may vary.
                try:
                    print(inline_response.response.text)
                except AttributeError:
                    print(inline_response.response) # Fallback
            elif inline_response.error:
                print(f"Error: {inline_response.error}")
    else:
        print("No results found (neither file nor inline).")
else:
    print(f"Job did not succeed. Final state: {batch_job.state.name}")
    if batch_job.error:
        print(f"Error: {batch_job.error}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// Use the name of the job you want to check
// e.g., inlinedBatchJob.name from the previous step
const jobName = "YOUR_BATCH_JOB_NAME";

try {
    const batchJob = await ai.batches.get({ name: jobName });

    if (batchJob.state === 'JOB_STATE_SUCCEEDED') {
        console.log('Found completed batch:', batchJob.displayName);
        console.log(batchJob);

        // If batch job was created with a file destination
        if (batchJob.dest?.fileName) {
            const resultFileName = batchJob.dest.fileName;
            console.log(`Results are in file: ${resultFileName}`);

            console.log("Downloading result file content...");
            const fileContentBuffer = await ai.files.download({ file: resultFileName });

            // Process fileContentBuffer (Buffer) as needed
            console.log(fileContentBuffer.toString('utf-8'));
        }

        // If batch job was created with inline responses
        else if (batchJob.dest?.inlinedResponses) {
            console.log("Results are inline:");
            for (let i = 0; i < batchJob.dest.inlinedResponses.length; i++) {
                const inlineResponse = batchJob.dest.inlinedResponses[i];
                console.log(`Response ${i + 1}:`);
                if (inlineResponse.response) {
                    // Accessing response, structure may vary.
                    if (inlineResponse.response.text !== undefined) {
                        console.log(inlineResponse.response.text);
                    } else {
                        console.log(inlineResponse.response); // Fallback
                    }
                } else if (inlineResponse.error) {
                    console.error(`Error: ${inlineResponse.error}`);
                }
            }
        }

        // If batch job was an embedding batch with inline responses
        else if (batchJob.dest?.inlinedEmbedContentResponses) {
            console.log("Embedding results found inline:");
            for (let i = 0; i < batchJob.dest.inlinedEmbedContentResponses.length; i++) {
                const inlineResponse = batchJob.dest.inlinedEmbedContentResponses[i];
                console.log(`Response ${i + 1}:`);
                if (inlineResponse.response) {
                    console.log(inlineResponse.response);
                } else if (inlineResponse.error) {
                    console.error(`Error: ${inlineResponse.error}`);
                }
            }
        } else {
            console.log("No results found (neither file nor inline).");
        }
    } else {
        console.log(`Job did not succeed. Final state: ${batchJob.state}`);
        if (batchJob.error) {
            console.error(`Error: ${typeof batchJob.error === 'string' ? batchJob.error : batchJob.error.message || JSON.stringify(batchJob.error)}`);
        }
    }
} catch (error) {
    console.error(`An error occurred while processing job ${jobName}:`, error);
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.BatchJob;
import com.google.genai.types.BatchJobDestination;
import com.google.genai.types.InlinedEmbedContentResponse;
import com.google.genai.types.InlinedResponse;
import com.google.genai.types.JobState;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;

Client client = new Client();

// Use the name of the job you want to check
String jobName = "batches/your-batch-id";
BatchJob batchJob = client.batches.get(jobName, null);

if (batchJob.state().get().knownEnum() == JobState.Known.JOB_STATE_SUCCEEDED) {
  BatchJobDestination dest = batchJob.dest().orElse(null);

  // If batch job was created with a file destination
  if (dest != null && dest.fileName().isPresent()) {
    String resultFileName = dest.fileName().get();
    System.out.println("Results are in file: " + resultFileName);

    System.out.println("Downloading result file content...");
    client.files.download(resultFileName, "batch_results.jsonl", null);
    String fileContent = Files.readString(Paths.get("batch_results.jsonl"));
    System.out.println(fileContent);
  }
  // If batch job was created with inline requests
  else if (dest != null && dest.inlinedResponses().isPresent()) {
    System.out.println("Results are inline:");
    List<InlinedResponse> responses = dest.inlinedResponses().get();
    for (int i = 0; i < responses.size(); i++) {
      System.out.println("Response " + (i + 1) + ":");
      InlinedResponse inlineResponse = responses.get(i);
      if (inlineResponse.response().isPresent()) {
        System.out.println(inlineResponse.response().get().text());
      } else if (inlineResponse.error().isPresent()) {
        System.out.println("Error: " + inlineResponse.error().get());
      }
    }
  }
  // If batch job was an embedding batch with inline responses
  else if (dest != null && dest.inlinedEmbedContentResponses().isPresent()) {
    System.out.println("Embedding results found inline:");
    List<InlinedEmbedContentResponse> responses = dest.inlinedEmbedContentResponses().get();
    for (int i = 0; i < responses.size(); i++) {
      System.out.println("Response " + (i + 1) + ":");
      InlinedEmbedContentResponse inlineResponse = responses.get(i);
      if (inlineResponse.response().isPresent()) {
        System.out.println(inlineResponse.response().get());
      } else if (inlineResponse.error().isPresent()) {
        System.out.println("Error: " + inlineResponse.error().get());
      }
    }
  } else {
    System.out.println("No results found (neither file nor inline).");
  }
} else {
  System.out.println("Job did not succeed. Final state: " + batchJob.state().get());
  batchJob.error().ifPresent(err -> System.out.println("Error: " + err));
}
```
{% /tab %}

{% tab label="REST" %}
```bash
BATCH_NAME="batches/123456" # Your batch job name

curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type:application/json" 2> /dev/null > batch_status.json

if jq -r '.done' batch_status.json | grep -q "false"; then
    echo "Batch has not finished processing"
fi

batch_state=$(jq -r '.metadata.state' batch_status.json)
if [[ $batch_state = "JOB_STATE_SUCCEEDED" ]]; then
    if [[ $(jq '.response | has("inlinedResponses")' batch_status.json) = "true" ]]; then
        jq -r '.response.inlinedResponses' batch_status.json
        exit
    fi
    responses_file_name=$(jq -r '.response.responsesFile' batch_status.json)
    curl https://generativelanguage.googleapis.com/download/v1beta/$responses_file_name:download?alt=media \
    -H "x-goog-api-key: $GEMINI_API_KEY" 2> /dev/null
elif [[ $batch_state = "JOB_STATE_FAILED" ]]; then
    jq '.error' batch_status.json
elif [[ $batch_state == "JOB_STATE_CANCELLED" ]]; then
    echo "Batch was cancelled by the user"
elif [[ $batch_state == "JOB_STATE_EXPIRED" ]]; then
    echo "Batch expired after 48 hours"
fi
```
{% /tab %}
{% /tabs %}

## Listing batch jobs {% id="listing-batch-jobs" %}

You can list your recent batch jobs.

{% tabs %}
{% tab label="Python" %}
```python
batch_jobs = client.batches.list()

# Optional query config:
# batch_jobs = client.batches.list(config={'page_size': 5})

for batch_job in batch_jobs:
    print(batch_job)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const batchJobs = await ai.batches.list();

// Optional query config:
// const batchJobs = await ai.batches.list({config: {'pageSize': 5}});

for await (const batchJob of batchJobs) {
    console.log(batchJob);
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.Pager;
import com.google.genai.types.BatchJob;
import com.google.genai.types.ListBatchJobsConfig;

Client client = new Client();

Pager<BatchJob> batchJobs = client.batches.list(null);

// Optional query config:
// Pager<BatchJob> batchJobs = client.batches.list(ListBatchJobsConfig.builder().pageSize(5).build());

for (BatchJob batchJob : batchJobs) {
  System.out.println(batchJob);
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl https://generativelanguage.googleapis.com/v1beta/batches \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## Cancelling a batch job {% id="canceling-batch-job" %}

You can cancel an ongoing batch job using its name. When a job is
canceled, it stops processing new requests.

{% tabs %}
{% tab label="Python" %}
```python
client.batches.cancel(name=batch_job_to_cancel.name)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
await ai.batches.cancel({name: batchJobToCancel.name});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;

Client client = new Client();

String batchJobToCancelName = "batches/your-batch-id";
client.batches.cancel(batchJobToCancelName, null);
```
{% /tab %}

{% tab label="REST" %}
```bash
BATCH_NAME="batches/123456" # Your batch job name

# Cancel the batch
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME:cancel \
-H "x-goog-api-key: $GEMINI_API_KEY" \

# Confirm that the status of the batch after cancellation is JOB_STATE_CANCELLED
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type:application/json" 2> /dev/null | jq -r '.metadata.state'
```
{% /tab %}
{% /tabs %}

## Deleting a batch job {% id="delete-batch-job" %}

You can delete an existing batch job using its name. When a job is
deleted, it stops processing new requests and is removed from the list of
batch jobs.

{% tabs %}
{% tab label="Python" %}
```python
client.batches.delete(name=batch_job_to_delete.name)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
await ai.batches.delete({name: batchJobToDelete.name});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;

Client client = new Client();

String batchJobToDeleteName = "batches/your-batch-id";
client.batches.delete(batchJobToDeleteName, null);
```
{% /tab %}

{% tab label="REST" %}
```bash
BATCH_NAME="batches/123456" # Your batch job name

# Delete the batch job
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME" \
-H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## Generating images in batch {% id="image-generation" %}

If you're using [Gemini Nano Banana](/docs/image-generation) and need to generate a lot
of images, you can use the Batch API to get higher
[rate limits](/docs/rate-limits) in exchange for a turnaround of up
to 24 hours.

You can either use [inline requests](/docs/batch-api#inline-requests-images) for small batches of requests (under 20MB) or
a [JSONL input file](/docs/batch-api#input-file-images) for large batches (recommended for image generation):

### Inline requests for images {% id="inline-requests-images" %}

{% tabs %}
{% tab label="Python" %}
```python
import time
import base64
import json
from google import genai
from google.genai import types
from PIL import Image

client = genai.Client()

# 1. Create batch job with inline requests
inline_requests = [
    {
        'contents': [{'parts': [{'text': 'A big letter A surrounded by animals starting with the A letter'}]}],
        'config': {'response_modalities': ['TEXT', 'IMAGE']}
    },
    {
        'contents': [{'parts': [{'text': 'A big letter B surrounded by animals starting with the B letter'}]}],
        'config': {'response_modalities': ['TEXT', 'IMAGE']}
    }
]

inline_batch_job = client.batches.create(
    model="gemini-3-pro-image-preview",
    src=inline_requests,
    config={
        'display_name': "inlined-image-requests-job-1",
    },
)

print(f"Created batch job: {inline_batch_job.name}")

# 2. Monitor job status
job_name = inline_batch_job.name
print(f"Polling status for job: {job_name}")

completed_states = set([
    'JOB_STATE_SUCCEEDED',
    'JOB_STATE_FAILED',
    'JOB_STATE_CANCELLED',
    'JOB_STATE_EXPIRED',
])

batch_job = client.batches.get(name=job_name) # Initial get
while batch_job.state.name not in completed_states:
  print(f"Current state: {batch_job.state.name}")
  time.sleep(10) # Wait for 10 seconds before polling again
  batch_job = client.batches.get(name=job_name)

print(f"Job finished with state: {batch_job.state.name}")

# 3. Retrieve results
if batch_job.state.name == 'JOB_STATE_SUCCEEDED':
    print("Results are inline:")
    for i, inline_response in enumerate(batch_job.dest.inlined_responses):
        print(f"Response {i+1}:")
        if inline_response.response:
            for part in inline_response.response.candidates[0].content.parts:
                if part.text:
                    print(part.text)
                elif part.inline_data:
                    print(f"Image mime type: {part.inline_data.mime_type}")
                    image = part.as_image()
                    image.save(f"image_{i+1}.png")
        elif inline_response.error:
            print(f"Error: {inline_response.error}")
elif batch_job.state.name == 'JOB_STATE_FAILED':
    print(f"Error: {batch_job.error}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

async function run() {
    // 1. Create batch job with inline requests
    const inlinedRequests = [
        {
            contents: [{parts: [{text: 'A big letter A surrounded by animals starting with the A letter'}]}],
            config: {responseModalities: ['TEXT', 'IMAGE']}
        },
        {
            contents: [{parts: [{text: 'A big letter B surrounded by animals starting with the B letter'}]}],
            config: {responseModalities: ['TEXT', 'IMAGE']}
        }
    ]

    const inlineBatchJob = await ai.batches.create({
        model: 'gemini-3-pro-image-preview',
        src: inlinedRequests,
        config: {
            displayName: 'inlined-image-requests-job-1',
        }
    });

    console.log(inlineBatchJob);

    // 2. Monitor job status
    let batchJob;
    const completedStates = new Set([
        'JOB_STATE_SUCCEEDED',
        'JOB_STATE_FAILED',
        'JOB_STATE_CANCELLED',
        'JOB_STATE_EXPIRED',
    ]);

    try {
        batchJob = await ai.batches.get({name: inlineBatchJob.name || ''});
        while (!completedStates.has(batchJob.state || '')) {
            console.log(`Current state: ${batchJob.state}`);
            // Wait for 10 seconds before polling again
            await new Promise(resolve => setTimeout(resolve, 10000));
            batchJob = await ai.batches.get({ name: batchJob.name || '' });
        }
        console.log(`Job finished with state: ${batchJob.state}`);
    } catch (error) {
        console.error(`An error occurred while polling job ${inlineBatchJob.name}:`, error);
        return;
    }

    // 3. Retrieve results
    if (batchJob.state === 'JOB_STATE_SUCCEEDED') {
        if (batchJob.dest?.inlinedResponses) {
            console.log("Results are inline:");
            for (let i = 0; i < batchJob.dest.inlinedResponses.length; i++) {
                const inlineResponse = batchJob.dest.inlinedResponses[i];
                console.log(`Response ${i + 1}:`);
                if (inlineResponse.response) {
                    for (const part of inlineResponse.response?.candidates?.[0]?.content?.parts || []) {
                        if (part.text) {
                            console.log(part.text);
                        } else if (part.inlineData) {
                            console.log(`Image mime type: ${part.inlineData.mimeType}`);
                        }
                    }
                } else if (inlineResponse.error) {
                    console.error(`Error: ${inlineResponse.error}`);
                }
            }
        } else {
            console.log("No inline results found.");
        }
    } else if (batchJob.state === 'JOB_STATE_FAILED') {
         console.error(`Error: ${typeof batchJob.error === 'string' ? batchJob.error : batchJob.error?.message || JSON.stringify(batchJob.error)}`);
    }
}
await run();
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.HashSet;
import java.util.Arrays;
import java.util.Collections;
import com.google.genai.Client;
import com.google.genai.types.BatchJob;
import com.google.genai.types.BatchJobSource;
import com.google.genai.types.Content;
import com.google.genai.types.CreateBatchJobConfig;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.InlinedRequest;
import com.google.genai.types.InlinedResponse;
import com.google.genai.types.JobState;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;
import java.util.Set;

Client client = new Client();

// 1. Create batch job with inline requests
GenerateContentConfig imageConfig =
    GenerateContentConfig.builder().responseModalities("TEXT", "IMAGE").build();

List<InlinedRequest> inlineRequests =
    Arrays.asList(
        InlinedRequest.builder()
            .contents(
                Arrays.asList(
                    Content.fromParts(
                        Part.fromText(
                            "A big letter A surrounded by animals starting with the A letter"))))
            .config(imageConfig)
            .build(),
        InlinedRequest.builder()
            .contents(
                Arrays.asList(
                    Content.fromParts(
                        Part.fromText(
                            "A big letter B surrounded by animals starting with the B letter"))))
            .config(imageConfig)
            .build());

BatchJob inlineBatchJob =
    client.batches.create(
        "gemini-3-pro-image-preview",
        BatchJobSource.builder().inlinedRequests(inlineRequests).build(),
        CreateBatchJobConfig.builder().displayName("inlined-image-requests-job-1").build());

System.out.println("Created batch job: " + inlineBatchJob.name().orElse(""));

// 2. Monitor job status
String jobName = inlineBatchJob.name().get();
System.out.println("Polling status for job: " + jobName);

Set<JobState.Known> completedStates =
    new HashSet<>(Arrays.asList(
        JobState.Known.JOB_STATE_SUCCEEDED,
        JobState.Known.JOB_STATE_FAILED,
        JobState.Known.JOB_STATE_CANCELLED,
        JobState.Known.JOB_STATE_EXPIRED));

BatchJob batchJob = client.batches.get(jobName, null);
while (!completedStates.contains(batchJob.state().get().knownEnum())) {
  System.out.println("Current state: " + batchJob.state().get());
  Thread.sleep(10000); // Wait for 10 seconds before polling again
  batchJob = client.batches.get(jobName, null);
}

System.out.println("Job finished with state: " + batchJob.state().get());

// 3. Retrieve results
if (batchJob.state().get().knownEnum() == JobState.Known.JOB_STATE_SUCCEEDED) {
  System.out.println("Results are inline:");
  List<InlinedResponse> responses = batchJob.dest().get().inlinedResponses().orElse(Collections.emptyList());
  for (int i = 0; i < responses.size(); i++) {
    System.out.println("Response " + (i + 1) + ":");
    InlinedResponse inlineResponse = responses.get(i);
    if (inlineResponse.response().isPresent()) {
      for (Part part : inlineResponse.response().get().parts()) {
        if (part.text().isPresent()) {
          System.out.println(part.text().get());
        } else if (part.inlineData().isPresent()) {
          System.out.println("Image mime type: " + part.inlineData().get().mimeType().orElse(""));
          Files.write(
              Paths.get("image_" + (i + 1) + ".png"),
              part.inlineData().get().data().get());
        }
      }
    } else if (inlineResponse.error().isPresent()) {
      System.out.println("Error: " + inlineResponse.error().get());
    }
  }
} else if (batchJob.state().get().knownEnum() == JobState.Known.JOB_STATE_FAILED) {
  System.out.println("Error: " + batchJob.error().orElse(null));
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# 1. Create batch job
printf -v request_data '{
    "batch": {
        "display_name": "my-batch-image-requests",
        "input_config": {
            "requests": {
                "requests": [
                    {
                        "request": {
                            "contents": [{"parts": [{"text": "A big letter A surrounded by animals starting with the A letter"}]}],
                            "generation_config": {"responseModalities": ["TEXT", "IMAGE"]}
                        },
                        "metadata": { "key": "request-1" }
                    },
                    {
                        "request": {
                            "contents": [{"parts": [{"text": "A big letter B surrounded by animals starting with the B letter"}]}],
                            "generation_config": {"responseModalities": ["TEXT", "IMAGE"]}
                        },
                        "metadata": { "key": "request-2" }
                    }
                ]
            }
        }
    }
}'
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:batchGenerateContent \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -H "Content-Type:application/json" \
  -d "$request_data" > created_batch.json

BATCH_NAME=$(jq -r '.name' created_batch.json)
echo "Created batch job: $BATCH_NAME"

# 2. Poll job status until completion by repeating the following command
# Replace $BATCH_NAME with the name returned above.
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type:application/json" > batch_status.json

echo "Current status:"
jq '.' batch_status.json

# 3. If state is JOB_STATE_SUCCEEDED, retrieve results from batch_status.json
batch_state=$(jq -r '.state' batch_status.json)
if [[ $batch_state = "JOB_STATE_SUCCEEDED" ]]; then
    echo "Job succeeded. Results:"
    jq -r '.dest.inlinedResponses' batch_status.json
fi
```
{% /tab %}
{% /tabs %}

### Input file for images {% id="input-file-images" %}

{% tabs %}
{% tab label="Python" %}
```python
import json
import time
import base64
from google import genai
from google.genai import types
from PIL import Image

client = genai.Client()

# 1. Create and upload file
file_name = "my-batch-image-requests.jsonl"
with open(file_name, "w") as f:
    requests = [
        {"key": "request-1", "request": {"contents": [{"parts": [{"text": "A big letter A surrounded by animals starting with the A letter"}]}], "generation_config": {"responseModalities": ["TEXT", "IMAGE"]}}},
        {"key": "request-2", "request": {"contents": [{"parts": [{"text": "A big letter B surrounded by animals starting with the B letter"}]}], "generation_config": {"responseModalities": ["TEXT", "IMAGE"]}}}
    ]
    for req in requests:
        f.write(json.dumps(req) + "\n")

uploaded_file = client.files.upload(
    file=file_name,
    config=types.UploadFileConfig(display_name='my-batch-image-requests', mime_type='jsonl')
)
print(f"Uploaded file: {uploaded_file.name}")

# 2. Create batch job
file_batch_job = client.batches.create(
    model="gemini-3-pro-image-preview",
    src=uploaded_file.name,
    config={
        'display_name': "file-image-upload-job-1",
    },
)
print(f"Created batch job: {file_batch_job.name}")

# 3. Monitor job status
job_name = file_batch_job.name
print(f"Polling status for job: {job_name}")

completed_states = set([
    'JOB_STATE_SUCCEEDED',
    'JOB_STATE_FAILED',
    'JOB_STATE_CANCELLED',
    'JOB_STATE_EXPIRED',
])

batch_job = client.batches.get(name=job_name) # Initial get
while batch_job.state.name not in completed_states:
  print(f"Current state: {batch_job.state.name}")
  time.sleep(10) # Wait for 10 seconds before polling again
  batch_job = client.batches.get(name=job_name)

print(f"Job finished with state: {batch_job.state.name}")

# 4. Retrieve results
if batch_job.state.name == 'JOB_STATE_SUCCEEDED':
    result_file_name = batch_job.dest.file_name
    print(f"Results are in file: {result_file_name}")
    print("Downloading result file content...")
    file_content_bytes = client.files.download(file=result_file_name)
    file_content = file_content_bytes.decode('utf-8')
    # The result file is also a JSONL file. Parse and print each line.
    for line in file_content.splitlines():
      if line:
        parsed_response = json.loads(line)
        if 'response' in parsed_response and parsed_response['response']:
            for part in parsed_response['response']['candidates'][0]['content']['parts']:
              if part.get('text'):
                print(part['text'])
              elif part.get('inlineData'):
                print(f"Image mime type: {part['inlineData']['mimeType']}")
                data = base64.b64decode(part['inlineData']['data'])
        elif 'error' in parsed_response:
            print(f"Error: {parsed_response['error']}")
elif batch_job.state.name == 'JOB_STATE_FAILED':
    print(f"Error: {batch_job.error}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';
import * as fs from "fs";
import * as path from "path";

const ai = new GoogleGenAI({});

async function run() {
    // 1. Create and upload file
    const fileName = "my-batch-image-requests.jsonl";
    const requests = [
        { "key": "request-1", "request": { "contents": [{ "parts": [{ "text": "A big letter A surrounded by animals starting with the A letter" }] }], "generation_config": {"responseModalities": ["TEXT", "IMAGE"]} } },
        { "key": "request-2", "request": { "contents": [{ "parts": [{ "text": "A big letter B surrounded by animals starting with the B letter" }] }], "generation_config": {"responseModalities": ["TEXT", "IMAGE"]} } }
    ];
    const filePath = fileName;

    try {
        const writeStream = fs.createWriteStream(filePath, { flags: 'w' });
        for (const req of requests) {
            writeStream.write(JSON.stringify(req) + '\n');
        }
        writeStream.end();
        console.log(`Successfully wrote batch requests to ${filePath}`);
    } catch (error) {
        console.error(`An unexpected error occurred writing file:`, error);
        return;
    }

    const uploadedFile = await ai.files.upload({file: fileName, config: { mimeType: 'jsonl' }});
    console.log(`Uploaded file: ${uploadedFile.name}`);

    // 2. Create batch job
    const fileBatchJob = await ai.batches.create({
        model: 'gemini-3-pro-image-preview',
        src: uploadedFile.name || '',
        config: {
            displayName: 'file-image-upload-job-1',
        }
    });
    console.log(fileBatchJob);

    // 3. Monitor job status
    let batchJob;
    const completedStates = new Set([
        'JOB_STATE_SUCCEEDED',
        'JOB_STATE_FAILED',
        'JOB_STATE_CANCELLED',
        'JOB_STATE_EXPIRED',
    ]);

    try {
        batchJob = await ai.batches.get({name: fileBatchJob.name || ''});
        while (batchJob.state && !completedStates.has(batchJob.state)) {
            console.log(`Current state: ${batchJob.state}`);
            // Wait for 10 seconds before polling again
            await new Promise(resolve => setTimeout(resolve, 10000));
            batchJob = await ai.batches.get({ name: batchJob.name || '' });
        }
        console.log(`Job finished with state: ${batchJob.state}`);
    } catch (error) {
        console.error(`An error occurred while polling job ${fileBatchJob.name}:`, error);
        return;
    }

    // 4. Retrieve results
    if (batchJob.state === 'JOB_STATE_SUCCEEDED') {
        if (batchJob.dest?.fileName) {
            const resultFileName = batchJob.dest.fileName;
            console.log(`Results are in file: ${resultFileName}`);
            console.log("Downloading result file content...");
            await ai.files.download({ file: resultFileName, downloadPath: 'result.jsonl' });
            const fileContent = fs.readFileSync('result.jsonl', 'utf-8');
            for (const line of fileContent.split('\n')) {
                if (line) {
                    const parsedResponse = JSON.parse(line);
                    if (parsedResponse.response) {
                        for (const part of parsedResponse.response.candidates[0].content.parts) {
                            if (part.text) {
                                console.log(part.text);
                            } else if (part.inlineData) {
                                console.log(`Image mime type: ${part.inlineData.mimeType}`);
                            }
                        }
                    } else if (parsedResponse.error) {
                        console.error(`Error: ${parsedResponse.error}`);
                    }
                }
            }
        } else {
            console.log("No result file found.");
        }
    } else if (batchJob.state === 'JOB_STATE_FAILED') {
         console.error(`Error: ${typeof batchJob.error === 'string' ? batchJob.error : batchJob.error?.message || JSON.stringify(batchJob.error)}`);
    }
}
await run();
```
{% /tab %}
{% tab label="Java" %}
```java
import java.util.HashSet;
import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.BatchJob;
import com.google.genai.types.BatchJobSource;
import com.google.genai.types.CreateBatchJobConfig;
import com.google.genai.types.File;
import com.google.genai.types.JobState;
import com.google.genai.types.UploadFileConfig;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;
import java.util.Set;

Client client = new Client();

// 1. Create and upload file
String fileName = "my-batch-image-requests.jsonl";
List<String> requests =
    Arrays.asList(
        "{\"key\": \"request-1\", \"request\": {\"contents\": [{\"parts\": [{\"text\": \"A big letter A surrounded by animals starting with the A letter\"}]}], \"generation_config\": {\"responseModalities\": [\"TEXT\", \"IMAGE\"]}}}",
        "{\"key\": \"request-2\", \"request\": {\"contents\": [{\"parts\": [{\"text\": \"A big letter B surrounded by animals starting with the B letter\"}]}], \"generation_config\": {\"responseModalities\": [\"TEXT\", \"IMAGE\"]}}}");
Files.write(Paths.get(fileName), requests);

File uploadedFile =
    client.files.upload(
        fileName,
        UploadFileConfig.builder()
            .displayName("my-batch-image-requests")
            .mimeType("jsonl")
            .build());
System.out.println("Uploaded file: " + uploadedFile.name().orElse(""));

// 2. Create batch job
BatchJob fileBatchJob =
    client.batches.create(
        "gemini-3-pro-image-preview",
        BatchJobSource.builder().fileName(uploadedFile.name().get()).build(),
        CreateBatchJobConfig.builder().displayName("file-image-upload-job-1").build());
System.out.println("Created batch job: " + fileBatchJob.name().orElse(""));

// 3. Monitor job status
String jobName = fileBatchJob.name().get();
System.out.println("Polling status for job: " + jobName);

Set<JobState.Known> completedStates =
    new HashSet<>(Arrays.asList(
        JobState.Known.JOB_STATE_SUCCEEDED,
        JobState.Known.JOB_STATE_FAILED,
        JobState.Known.JOB_STATE_CANCELLED,
        JobState.Known.JOB_STATE_EXPIRED));

BatchJob batchJob = client.batches.get(jobName, null);
while (!completedStates.contains(batchJob.state().get().knownEnum())) {
  System.out.println("Current state: " + batchJob.state().get());
  Thread.sleep(10000); // Wait for 10 seconds before polling again
  batchJob = client.batches.get(jobName, null);
}

System.out.println("Job finished with state: " + batchJob.state().get());

// 4. Retrieve results
if (batchJob.state().get().knownEnum() == JobState.Known.JOB_STATE_SUCCEEDED) {
  String resultFileName = batchJob.dest().get().fileName().get();
  System.out.println("Results are in file: " + resultFileName);
  System.out.println("Downloading result file content...");
  client.files.download(resultFileName, "batch_image_results.jsonl", null);
  for (String line : Files.readAllLines(Paths.get("batch_image_results.jsonl"))) {
    if (!line.isEmpty()) {
      System.out.println(line);
    }
  }
} else if (batchJob.state().get().knownEnum() == JobState.Known.JOB_STATE_FAILED) {
  System.out.println("Error: " + batchJob.error().orElse(null));
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# 1. Create and upload file
echo '{"key": "request-1", "request": {"contents": [{"parts": [{"text": "A big letter A surrounded by animals starting with the A letter"}]}], "generation_config": {"responseModalities": ["TEXT", "IMAGE"]}}}' > my-batch-image-requests.jsonl
echo '{"key": "request-2", "request": {"contents": [{"parts": [{"text": "A big letter B surrounded by animals starting with the B letter"}]}], "generation_config": {"responseModalities": ["TEXT", "IMAGE"]}}}' >> my-batch-image-requests.jsonl

# Follow File API guide to upload: https://ai.google.dev/docs/files#upload_a_file
# This example assumes you have uploaded the file and set BATCH_INPUT_FILE to its name (e.g., files/abcdef123)
BATCH_INPUT_FILE="files/your-uploaded-file-name"

# 2. Create batch job
printf -v request_data '{
    "batch": {
        "display_name": "my-batch-file-image-requests",
        "input_config": { "file_name": "%s" }
    }
}' "$BATCH_INPUT_FILE"
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:batchGenerateContent \
  -X POST \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type:application/json" \
  -d "$request_data" > created_batch.json

BATCH_NAME=$(jq -r '.name' created_batch.json)
echo "Created batch job: $BATCH_NAME"

# 3. Poll job status until completion by repeating the following command:
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type:application/json" > batch_status.json

echo "Current status:"
jq '.' batch_status.json

# 4. If state is JOB_STATE_SUCCEEDED, download results file
batch_state=$(jq -r '.state' batch_status.json)
if [[ $batch_state = "JOB_STATE_SUCCEEDED" ]]; then
    responses_file_name=$(jq -r '.dest.fileName' batch_status.json)
    echo "Job succeeded. Downloading results from $responses_file_name..."
    curl https://generativelanguage.googleapis.com/download/v1beta/$responses_file_name:download?alt=media \
      -H "x-goog-api-key: $GEMINI_API_KEY" > batch_results.jsonl
    echo "Results saved to batch_results.jsonl"
fi
```
{% /tab %}
{% /tabs %}

## Technical details {% id="technical-details" %}

* **Supported models:** Batch API supports a range of Gemini models.
    Refer to the [Models page](/docs/models) for each model's support
    of Batch API. The supported modalities for Batch API are the same
    as what's supported on the interactive (or non-batch) API.

* **Pricing:** Batch API usage is priced at 50% of the standard interactive
    API cost for the equivalent model. See the [pricing page](/docs/pricing)
    for details. Refer to the [rate limits page](/docs/rate-limits#batch-api)
    for details on rate limits for this feature.

* **Service level objective (SLO):** Batch jobs are designed to complete
    within a 24-hour turnaround time. Many jobs may complete much faster
    depending on their size and current system load.

* **Caching:** [Context caching](/docs/caching) is supported
    for batch requests. Reuse cached content by specifying the `cached_content`
    resource name in the configuration of individual requests within your batch.
    If a request in your batch results in a cache hit, you pay the
    [standard context caching rates](/docs/pricing).

## Best practices {% id="best-practices" %}

* **Use input files for large requests:** For a large number of requests,
    always use the file input
    method for better manageability and to avoid hitting request size limits for
    the [`BatchGenerateContent`](https://ai.google.dev/api/batch-mode#google.ai.generativelanguage.v1beta.BatchService.BatchGenerateContent)
    call itself. Note that there's a 2GB file size limit per input file.

* **Error handling:** Check the `batchStats` for `failedRequestCount` after a
    job completes. If using file output, parse each line to check if it's a
    `GenerateContentResponse` or a status object indicating an error for that
    specific request. See the [troubleshooting
    guide](/docs/troubleshooting#error-codes) for a complete set of
    error codes.

* **Submit jobs once:** The creation of a batch job is not idempotent.
    If you send the same creation request twice, two separate batch jobs will
    be created.

* **Break up very large batches:** While the target turnaround time is 24
    hours, actual processing time can vary based on system load and job size.
    For large jobs, consider breaking them into smaller
    batches if intermediate results are needed sooner.

## What's next {% id="whats-next" %}

* Check out the [Batch API notebook](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Batch_mode.ipynb)
for more examples.

* The OpenAI compatibility layer supports Batch API. Read the examples on the
    [OpenAI Compatibility](/docs/openai#batch) page.

# Webhooks
Source: https://aistudio.google.com/docs/webhooks
Description: Learn how to use webhooks in the Gemini API.

{% callout type="note" %}
This feature is in [preview](/docs/models#preview).
{% /callout %}

Webhooks allow the Gemini API to push real-time notifications to your server
when asynchronous or Long-Running Operations (LROs) complete. This replaces the
need to poll the API for status updates, reducing latency and overhead.

Webhooks are available for operations like [Batch](/docs/batch-api) jobs,
[Interactions](/docs/interactions-overview) and [video generation](/docs/video).

## How it works {% id="how-it-works" %}

Instead of polling `GET /operations` repeatedly to check if a job is finished,
you can configure Gemini API Webhooks to send an HTTP POST request to your
listener URL immediately upon an event trigger.

The Gemini API supports two ways to configure webhooks:

* [**Static webhooks**](/docs/webhooks#static-webhooks): Project-level endpoints configured
  with the Gemini [WebhookService API](https://ai.google.dev/api/). Good for global integrations
  (e.g., notifying Slack, syncing a database).

* [**Dynamic webhooks**](/docs/webhooks#dynamic-webhooks): Request-level overrides passing a
webhook URL in the configuration payload of a specific jobs call. Ideal for
routing specific jobs to dedicated endpoints.

## Static webhooks {% id="static-webhooks" %}

Static webhooks are registered for a whole [project](/docs/api-key#google-cloud-projects) and trigger for any matching
event.

### Create a webhook {% id="create-webhook" %}

You can create endpoints using the SDK or REST API.

**IMPORTANT**: When creating a webhook, the API returns a **signing secret**
**only once**. You must store this securely (e.g. in your environment variables)
to verify signatures later. If you lose the signing secret, you'll have to
[rotate](/docs/webhooks#rotate-signing-secret) it.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

webhook = client.webhooks.create(
    name="MyBatchWebhook",
    subscribed_events=["batch.succeeded", "batch.failed"],
    uri="https://my-api.com/gemini-callback",
)

# Store webhook.new_signing_secret securely
webhook_secret = webhook.new_signing_secret
print(f"Created webhook: {webhook.name}, {webhook.id}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

async function createWebhook() {
  const webhook = await client.webhooks.create({
    name: "MyBatchWebhook",
    subscribed_events: ["batch.succeeded", "batch.failed"],
    uri: "https://my-api.com/gemini-callback",
  });

  // Store webhook.signingSecret securely
  const webhookSecret = webhook.new_signing_secret;
  console.log(`Created webhook: ${webhook.name}, ${webhook.id}`);
}

await createWebhook();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.webhooks.Webhook;
import com.google.genai.gaos.models.webhooks.WebhookInput;
import com.google.genai.gaos.models.webhooks.WebhookSubscribedEvent;
import java.util.Arrays;

Client client = new Client();

WebhookInput input =
    WebhookInput.builder()
        .name("MyBatchWebhook")
        .subscribedEvents(
            Arrays.asList(
                WebhookSubscribedEvent.BATCH_SUCCEEDED, WebhookSubscribedEvent.BATCH_FAILED))
        .uri("https://my-api.com/gemini-callback")
        .build();

Webhook webhook = client.webhooks.create(input).webhook().get();

// Store webhook.newSigningSecret() securely
String webhookSecret = webhook.newSigningSecret().orElse("");
System.out.println(
    "Created webhook: " + webhook.name().orElse("") + ", " + webhook.id().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
    "google.golang.org/genai/interactions/models/webhooks"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Webhooks.Create(ctx, operations.CreateWebhookRequest{
        Body: webhooks.WebhookInput{
            Name: genai.Ptr("MyBatchWebhook"),
            SubscribedEvents: []webhooks.WebhookSubscribedEvent{
                webhooks.WebhookSubscribedEventBatchSucceeded,
                webhooks.WebhookSubscribedEventBatchFailed,
            },
            URI: "https://my-api.com/gemini-callback",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    webhook := res.Webhook
    // Store webhook.GetNewSigningSecret() securely
    _ = webhook.GetNewSigningSecret()
    fmt.Printf("Created webhook: %v, %v\n", webhook.GetName(), webhook.GetID())
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST \
  "https://generativelanguage.googleapis.com/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "name": "MyBatchWebhook",
    "uri": "https://my-api.com/gemini-callback",
    "subscribed_events": ["batch.succeeded", "batch.failed"]
  }'
```
{% /tab %}
{% /tabs %}

For details on setting up your server to receive data, see the
[Handle webhook requests](/docs/webhooks#handle-webhook-requests) section.

### Get a webhook {% id="get-webhook" %}

Retrieve details about a specific webhook by its resource name.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

webhook = client.webhooks.get(id="")

print(f"Webhook: {webhook.name}")
print(f"URI: {webhook.uri}")
print(f"Events: {webhook.subscribed_events}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI(); // Assumes process.env.GEMINI_API_KEY is set

async function getWebhook() {
  const webhook = await client.webhooks.get("");

  console.log(`Webhook: ${webhook.name}`);
  console.log(`URI: ${webhook.uri}`);
  console.log(`Events: ${webhook.subscribed_events}`);
}

await getWebhook();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.webhooks.Webhook;
import java.util.Collections;

Client client = new Client();

Webhook webhook = client.webhooks.get("<your_webhook_id>").webhook().get();

System.out.println("Webhook: " + webhook.name().orElse(""));
System.out.println("URI: " + webhook.uri().orElse(""));
System.out.println("Events: " + webhook.subscribedEvents().orElse(Collections.emptyList()));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Webhooks.Get(ctx, operations.GetWebhookRequest{
        ID: "<your_webhook_id>",
    })
    if err != nil {
        log.Fatal(err)
    }

    webhook := res.Webhook
    if webhook.Name != nil {
        fmt.Printf("Webhook: %s\n", *webhook.Name)
    }
    fmt.Printf("URI: %s\n", webhook.URI)
    fmt.Printf("Events: %v\n", webhook.SubscribedEvents)
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X GET \
  "https://generativelanguage.googleapis.com/v1/webhooks/" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

### List webhooks {% id="list-webhooks" %}

List all configured webhooks for the current project, with optional pagination.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

webhooks = client.webhooks.list()

for wh in webhooks:
    print(f"{wh.id}: {wh.name} -> {wh.uri}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

async function listWebhooks() {
  const webhooks = await client.webhooks.list();

  for (const wh of webhooks.webhooks || []) {
    console.log(`${wh.id}: ${wh.name} -> ${wh.uri}`);
  }
}

await listWebhooks();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.webhooks.Webhook;
import com.google.genai.gaos.models.webhooks.WebhookListResponse;
import java.util.Collections;

Client client = new Client();

WebhookListResponse response =
    client.webhooks.listDirect().webhookListResponse().orElse(new WebhookListResponse());

for (Webhook wh : response.webhooks().orElse(Collections.emptyList())) {
  System.out.println(
      wh.id().orElse("") + ": " + wh.name().orElse("") + " -> " + wh.uri().orElse(""));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Webhooks.List(ctx, operations.ListWebhooksRequest{})
    if err != nil {
        log.Fatal(err)
    }

    if res.WebhookListResponse != nil {
        for _, wh := range res.WebhookListResponse.Webhooks {
            fmt.Printf("%v: %v -> %s\n", wh.GetID(), wh.GetName(), wh.URI)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X GET \
  "https://generativelanguage.googleapis.com/v1/webhooks" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

### Update a webhook {% id="update-webhook" %}

Update an existing webhook's properties such as the display name, target URI, or
subscribed events.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

updated_webhook = client.webhooks.update(
    id="",
    subscribed_events=["batch.succeeded", "batch.failed", "batch.cancelled"],
)

print(f"Updated webhook: {updated_webhook.name}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

async function updateWebhook() {
  const updatedWebhook = await client.webhooks.update(
    "",
    {
      subscribed_events: ["batch.succeeded", "batch.failed", "batch.cancelled"],
    }
  );

  console.log(`Updated webhook: ${updatedWebhook.name}`);
}

await updateWebhook();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.webhooks.Webhook;
import com.google.genai.gaos.models.webhooks.WebhookUpdate;
import com.google.genai.gaos.models.webhooks.WebhookUpdateSubscribedEvent;
import java.util.Arrays;

Client client = new Client();

WebhookUpdate updateBody =
    WebhookUpdate.builder()
        .subscribedEvents(
            Arrays.asList(
                WebhookUpdateSubscribedEvent.BATCH_SUCCEEDED,
                WebhookUpdateSubscribedEvent.BATCH_FAILED,
                WebhookUpdateSubscribedEvent.of("batch.cancelled")))
        .build();

Webhook updatedWebhook =
    client.webhooks
        .update()
        .id("<your_webhook_id>")
        .updateMask("subscribed_events")
        .body(updateBody)
        .call()
        .webhook()
        .get();

System.out.println("Updated webhook: " + updatedWebhook.name().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
    "google.golang.org/genai/interactions/models/webhooks"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Webhooks.Update(ctx, operations.UpdateWebhookRequest{
        ID:         "<your_webhook_id>",
        UpdateMask: genai.Ptr("subscribed_events"),
        Body: &webhooks.WebhookUpdate{
            SubscribedEvents: []webhooks.WebhookUpdateSubscribedEvent{
                webhooks.WebhookUpdateSubscribedEventBatchSucceeded,
                webhooks.WebhookUpdateSubscribedEventBatchFailed,
                webhooks.WebhookUpdateSubscribedEvent("batch.cancelled"),
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Webhook.Name != nil {
        fmt.Printf("Updated webhook: %s\n", *res.Webhook.Name)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X PATCH \
  "https://generativelanguage.googleapis.com/v1/webhooks/" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "subscribed_events": ["batch.succeeded", "batch.failed", "batch.cancelled"]
  }'
```
{% /tab %}
{% /tabs %}

### Delete a webhook {% id="delete-webhook" %}

Remove a webhook endpoint from the project. This stops future event deliveries
to that endpoint.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

client.webhooks.delete(id="")

print("Webhook deleted.")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

async function deleteWebhook() {
  await client.webhooks.delete("");

  console.log("Webhook deleted.");
}

await deleteWebhook();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;

Client client = new Client();

client.webhooks.delete("<your_webhook_id>");

System.out.println("Webhook deleted.");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Webhooks.Delete(ctx, operations.DeleteWebhookRequest{
        ID: "<your_webhook_id>",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Webhook deleted.")
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X DELETE \
  "https://generativelanguage.googleapis.com/v1/webhooks/" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

### Rotate a signing secret {% id="rotate-signing-secret" %}

Rotate the signing secret for a webhook. You can configure whether previously
active secrets are revoked immediately or after a 24-hour grace period.

**IMPORTANT**: The new signing secret is returned **only once** at rotation
time. Store it securely before updating your verification logic.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

response = client.webhooks.rotate_signing_secret(
    id="",
    revocation_behavior="REVOKE_PREVIOUS_SECRETS_AFTER_H24",
)

# Store response.secret securely, then update your server's verification config
print("New signing secret generated. Update your server configuration.")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

async function rotateSigningSecret() {
  const response = await client.webhooks.rotateSigningSecret(
    "",
    {
      revocation_behavior: "revoke_previous_secrets_after_h24",
    }
  );

  // Store response.secret securely, then update your server's verification config
  console.log("New signing secret generated. Update your server configuration.");
}

await rotateSigningSecret();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.webhooks.RevocationBehavior;
import com.google.genai.gaos.models.webhooks.RotateSigningSecretRequest;
import com.google.genai.gaos.models.webhooks.WebhookRotateSigningSecretResponse;

Client client = new Client();

RotateSigningSecretRequest requestBody =
    RotateSigningSecretRequest.builder()
        .revocationBehavior(RevocationBehavior.REVOKE_PREVIOUS_SECRETS_AFTER_H24)
        .build();

WebhookRotateSigningSecretResponse response =
    client.webhooks
        .rotateSigningSecret()
        .id("<your_webhook_id>")
        .body(requestBody)
        .call()
        .webhookRotateSigningSecretResponse()
        .get();

// Store response.secret() securely, then update your server's verification config
String newSecret = response.secret().orElse("");
System.out.println("New signing secret generated. Update your server configuration.");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
    "google.golang.org/genai/interactions/models/webhooks"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Webhooks.RotateSigningSecret(ctx, operations.RotateSigningSecretRequest{
        ID: "<your_webhook_id>",
        Body: &webhooks.RotateSigningSecretRequest{
            RevocationBehavior: webhooks.RevocationBehaviorRevokePreviousSecretsAfterH24.ToPointer(),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // Store res.WebhookRotateSigningSecretResponse.GetSecret() securely, then update your server's verification config
    _ = res.WebhookRotateSigningSecretResponse.GetSecret()
    fmt.Println("New signing secret generated. Update your server configuration.")
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST \
  "https://generativelanguage.googleapis.com/v1/webhooks//rotate_secret" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "revocation_behavior": "REVOKE_PREVIOUS_SECRETS_AFTER_H24"
  }'
```
{% /tab %}
{% /tabs %}

### Handle webhook requests on a server {% id="handle-webhook-requests" %}

When an event happens that you're subscribed to, your webhook URL will receive
an HTTP POST request. Your endpoint must respond with a 2xx status
code within a few seconds to avoid a retry. To ensure delivery, the Gemini API
automatically retries failed requests for 24 hours using exponential backoff.

Gemini strictly follows the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks) specification for
security headers. Verify the payload on your server using the signed header
signatures and your stored static signing secret. See the [Webhook envelope](/docs/webhooks#webhook-envelope) section for the payload information.

Here is an example using Flask for the HTTP listener:

{% tabs %}
{% tab label="Python" %}
```python
# pip install flask standardwebhooks
import os
from flask import Flask, request, jsonify
# Standard verification wrapper for Standard Webhook Headers
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)

SIGNING_SECRET = os.environ.get('WEBHOOK_SIGNING_SECRET')

@app.route('/gemini-callback', methods=['POST'])
def gemini_callback():
    payload = request.get_data(as_text=True)
    headers = request.headers

    try:
        wh = Webhook(SIGNING_SECRET)
        event = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        return jsonify({"error": "Signature invalid"}), 400

    # Process thin payload contents
    if event.get("type") == "batch.succeeded":
        print(f"Batch completed! ID: {event['data']['id']}")
        if event["data"].get("output_file_uri"):
            # For batch jobs with input file
            print(f"Batch file: {event['data']['output_file_uri']}")
    elif event.get("type") == "interaction.completed":
        print(f"Interaction completed! ID: {event['data']['id']}")
    elif event.get("type") == "video.generated":
        print(f"Video generated! URI: {event['data']['output_file_uri']}")

    return jsonify({"status": "received"}), 200

if __name__ == "__main__":
    app.run(port=8000)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// npm install standardwebhooks
import { GoogleGenAI } from "@google/genai";
import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
const client = new GoogleGenAI();

// Don't use express.json() because signature verification needs the raw text body
app.use(express.text({ type: "application/json" }));

app.post("/gemini-callback", async (req, res) => {
  const payload = req.body;
  const headers = req.headers;

  try {
    const wh = new Webhook(process.env.WEBHOOK_SIGNING_SECRET || "");
    const event = wh.verify(payload, headers);
    console.log(`Event type: ${event.type}, data: ${JSON.stringify(event.data)}`);

          // Process thin payload contents
          if (event.type === "batch.succeeded") {
              console.log(`Batch completed! ID: ${event.data.id}`);
              if (event.data.output_file_uri) {
                  // For batch jobs with input file
                  console.log(`Batch file: ${event.data.output_file_uri}`);
              }
          } else if (event.type === "interaction.completed") {
              console.log(`Interaction completed! ID: ${event.data.id}`);
          } else if (event.type === "video.generated") {
              console.log(`Video generated! URI: ${event.data.output_file_uri}`);
          }

          res.status(200).json({ status: "received" });
      } catch (e) {
          console.error("Webhook verification failed:", e);
          res.status(400).send("Invalid signature");
      }
});

app.listen(8000, () => {
  console.log("Webhook server is running on port 8000");
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.sun.net.httpserver.HttpServer;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

String signingSecret = System.getenv("WEBHOOK_SIGNING_SECRET");

HttpServer server = HttpServer.create(new InetSocketAddress(8000), 0);
server.createContext(
    "/gemini-callback",
    exchange -> {
      String payload =
          new String(exchange.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);
      String msgId = exchange.getRequestHeaders().getFirst("webhook-id");
      String msgTimestamp = exchange.getRequestHeaders().getFirst("webhook-timestamp");
      String msgSignature = exchange.getRequestHeaders().getFirst("webhook-signature");

      try {
        String toSign = msgId + "." + msgTimestamp + "." + payload;
        Mac mac = Mac.getInstance("HmacSHA256");
        byte[] secretBytes =
            Base64.getDecoder().decode(signingSecret.replaceFirst("^whsec_", ""));
        mac.init(new SecretKeySpec(secretBytes, "HmacSHA256"));
        String expectedSig =
            "v1,"
                + Base64.getEncoder()
                    .encodeToString(mac.doFinal(toSign.getBytes(StandardCharsets.UTF_8)));

        if (msgSignature == null || !msgSignature.contains(expectedSig)) {
          byte[] resp = "{\"error\": \"Signature invalid\"}".getBytes(StandardCharsets.UTF_8);
          exchange.sendResponseHeaders(400, resp.length);
          try (OutputStream os = exchange.getResponseBody()) {
            os.write(resp);
          }
          return;
        }

        Matcher typeMatcher = Pattern.compile("\"type\"\\s*:\\s*\"([^\"]+)\"").matcher(payload);
        String type = typeMatcher.find() ? typeMatcher.group(1) : "";

        Matcher idMatcher = Pattern.compile("\"id\"\\s*:\\s*\"([^\"]+)\"").matcher(payload);
        String id = idMatcher.find() ? idMatcher.group(1) : "";

        Matcher uriMatcher =
            Pattern.compile("\"output_file_uri\"\\s*:\\s*\"([^\"]+)\"").matcher(payload);
        String outputFileUri = uriMatcher.find() ? uriMatcher.group(1) : "";

        if ("batch.succeeded".equals(type)) {
          System.out.println("Batch completed! ID: " + id);
          if (!outputFileUri.isEmpty()) {
            System.out.println("Batch file: " + outputFileUri);
          }
        } else if ("interaction.completed".equals(type)) {
          System.out.println("Interaction completed! ID: " + id);
        } else if ("video.generated".equals(type)) {
          System.out.println("Video generated! URI: " + outputFileUri);
        }

        byte[] resp = "{\"status\": \"received\"}".getBytes(StandardCharsets.UTF_8);
        exchange.sendResponseHeaders(200, resp.length);
        try (OutputStream os = exchange.getResponseBody()) {
          os.write(resp);
        }
      } catch (Exception e) {
        exchange.sendResponseHeaders(400, -1);
      }
    });
server.start();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "encoding/json"
    "fmt"
    "io"
    "log"
    "net/http"
    "os"
    "strings"

)

func main() {
    signingSecret := os.Getenv("WEBHOOK_SIGNING_SECRET")

    http.HandleFunc("/gemini-callback", func(w http.ResponseWriter, r *http.Request) {
        payloadBytes, err := io.ReadAll(r.Body)
        if err != nil {
            http.Error(w, `{"error": "Failed to read body"}`, http.StatusBadRequest)
            return
        }
        payload := string(payloadBytes)
        msgID := r.Header.Get("webhook-id")
        msgTimestamp := r.Header.Get("webhook-timestamp")
        msgSignature := r.Header.Get("webhook-signature")

        secretBytes, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(signingSecret, "whsec_"))
        if err != nil {
            http.Error(w, `{"error": "Invalid secret"}`, http.StatusBadRequest)
            return
        }

        toSign := fmt.Sprintf("%s.%s.%s", msgID, msgTimestamp, payload)
        mac := hmac.New(sha256.New, secretBytes)
        mac.Write([]byte(toSign))
        expectedSig := "v1," + base64.StdEncoding.EncodeToString(mac.Sum(nil))

        if msgSignature == "" || !strings.Contains(msgSignature, expectedSig) {
            http.Error(w, `{"error": "Signature invalid"}`, http.StatusBadRequest)
            return
        }

        var event struct {
            Type string `json:"type"`
            Data struct {
                ID            string `json:"id"`
                OutputFileURI string `json:"output_file_uri"`
            } `json:"data"`
        }
        _ = json.Unmarshal(payloadBytes, &event)

        switch event.Type {
        case "batch.succeeded":
            fmt.Printf("Batch completed! ID: %s\n", event.Data.ID)
            if event.Data.OutputFileURI != "" {
                fmt.Printf("Batch file: %s\n", event.Data.OutputFileURI)
            }
        case "interaction.completed":
            fmt.Printf("Interaction completed! ID: %s\n", event.Data.ID)
        case "video.generated":
            fmt.Printf("Video generated! URI: %s\n", event.Data.OutputFileURI)
        }

        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte(`{"status": "received"}`))
    })

    log.Fatal(http.ListenAndServe(":8000", nil))
}
```
{% /tab %}

{% /tabs %}

## Dynamic webhooks {% id="dynamic-webhooks" %}

Dynamic webhooks allow you to bind a webhook endpoint to a **specific request
configuration**, ideal for agent-orchestration queues. Dynamic webhooks leverage
asymmetric public-key JWKS signatures instead of symmetric secrets.

### Submit a dynamic request {% id="submit-dynamic-request" %}

Add a `webhook_config` when triggering an asynchronous job (e.g., creating a
Batch).

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

response = client.interactions.create(
    model='gemini-3.8-flash',
    input='Tell me a short joke about programming.',
    background=True, # Required when webhook_config is specified
    webhook_config={
        'uris': ["https://my-api.com/gemini-webhook-dynamic"],
        'user_metadata': {"job_group": "nightly-eval", "priority": "high"}
    }
)

print(f"Interaction created! ID: {response.id}")
print(f"Status: {response.status}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

async function createInteractionWithWebhook() {
  const response = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Tell me a short joke about programming.",
    background: true, // Required when webhook_config is specified
    webhook_config: {
      uris: ["https://my-api.com/gemini-webhook-dynamic"],
      user_metadata: { job_group: "nightly-eval", priority: "high" },
    },
  });

  console.log(`Interaction created! ID: ${response.id}`);
  console.log(`Status: ${response.status}`);
}

await createInteractionWithWebhook();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.WebhookConfig;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> userMetadata = new HashMap<>();
userMetadata.put("job_group", "nightly-eval");
userMetadata.put("priority", "high");

WebhookConfig webhookConfig =
    WebhookConfig.builder()
        .uris(Arrays.asList("https://my-api.com/gemini-webhook-dynamic"))
        .userMetadata(userMetadata)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(InteractionsInput.of("Tell me a short joke about programming."))
        .background(true) // Required when webhookConfig is specified
        .webhookConfig(webhookConfig)
        .build();

Interaction response =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println("Interaction created! ID: " + response.id().orElse(""));
System.out.println(
    "Status: " + response.status().map(InteractionStatus::value).orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:      interactions.Model("gemini-3.8-flash"),
            Input:      interactions.NewInteractionsInput("Tell me a short joke about programming."),
            Background: genai.Ptr(true), // Required when WebhookConfig is specified
            WebhookConfig: &interactions.WebhookConfig{
                Uris: []string{"https://my-api.com/gemini-webhook-dynamic"},
                UserMetadata: map[string]any{
                    "job_group": "nightly-eval",
                    "priority":  "high",
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.ID != nil {
        fmt.Printf("Interaction created! ID: %s\n", *res.Interaction.ID)
    }
    fmt.Printf("Status: %s\n", res.Interaction.Status)
}
```
{% /tab %}

{% tab label="REST" %}
```shell
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short joke about programming.",
    "background": true,
    "webhook_config": {
      "uris": ["https://my-api.com/gemini-webhook-dynamic"],
      "user_metadata": {"job_group": "nightly-eval", "priority": "high"}
    }
  }'
```
{% /tab %}
{% /tabs %}

### Verify dynamic signatures (JWKS) {% id="verify-dynamic-signatures" %}

Dynamic webhook requests emit a JSON Web Token (JWT) signature. Your listener
must extract the signature and verify it using [Google's public certificate
endpoints](https://www.googleapis.com/oauth2/v3/certs).

{% tabs %}
{% tab label="Python" %}
```python
import jwt
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

# Google public cert list endpoint
JWKS_URI = "https://generativelanguage.googleapis.com/.well-known/jwks.json"

def load_google_public_key(kid):
    response = requests.get(JWKS_URI).json()
    for key_item in response.get('keys', []):
        if key_item.get('kid') == kid:
            # Convert JWK to Cert wrapper
            return jwt.algorithms.RSAAlgorithm.from_jwk(key_item)
    return None

@app.route('/gemini-webhook-dynamic', methods=['POST'])
def dynamic_handler():
    payload = request.get_data(as_text=True)
    headers = request.headers

    token = headers.get('Webhook-Signature')
    if not token:
        return jsonify({"error": "No signature header"}), 400

    try:
        # Extract kid from JWT header
        unverified_headers = jwt.get_unverified_header(token)
        pub_key = load_google_public_key(unverified_headers.get('kid'))

        if not pub_key:
            return jsonify({"error": "Key cert not found"}), 400

        # Verify Signature against expected audience (e.g., your project client ID)
        event = jwt.decode(
            token,
            pub_key,
            algorithms=["RS256"],
            audience="your-configured-audience"
        )
    except Exception as e:
        return jsonify({"error": "Invalid Dynamic signature", "details": str(e)}), 400

    print("Verified Dynamic payload success.")
    return jsonify({"status": "received"}), 200
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import express from "express";
import jwt from "jsonwebtoken";
import jwksClient from "jwks-rsa";

const app = express();
app.use(express.text({ type: 'application/json' }));

const client = jwksClient({
  jwksUri: "https://generativelanguage.googleapis.com/.well-known/jwks.json"
});

function getKey(header = { kid: "" }, callback = (err = null, key = "") => {}) {
  client.getSigningKey(header.kid, (err, key) => {
    const signingKey = key?.getPublicKey();
    callback(null, signingKey);
  });
}

app.post('/gemini-webhook-dynamic', (req, res) => {
  const token = req.headers['webhook-signature'];

  if (!token) {
    res.status(400).json({ error: "No signature header" });
    return;
  }

  jwt.verify(
    token,
    getKey,
    {
      algorithms: ["RS256"],
      audience: "your-configured-audience"
    },
    (err, decoded) => {
      if (err) {
        res.status(400).json({ error: "Invalid Dynamic signature", details: err.message });
        return;
      }

      console.log("Verified Dynamic payload success.");
      res.status(200).json({ status: "received" });
    }
  );
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.sun.net.httpserver.HttpServer;
import java.io.InputStream;
import java.io.OutputStream;
import java.math.BigInteger;
import java.net.InetSocketAddress;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.security.KeyFactory;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.RSAPublicKeySpec;
import java.util.Base64;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

String jwksUri = "https://generativelanguage.googleapis.com/.well-known/jwks.json";

HttpServer server = HttpServer.create(new InetSocketAddress(8000), 0);
server.createContext(
    "/gemini-webhook-dynamic",
    exchange -> {
      String token = exchange.getRequestHeaders().getFirst("Webhook-Signature");
      if (token == null || token.split("\\.").length != 3) {
        byte[] resp = "{\"error\": \"No signature header\"}".getBytes(StandardCharsets.UTF_8);
        exchange.sendResponseHeaders(400, resp.length);
        try (OutputStream os = exchange.getResponseBody()) {
          os.write(resp);
        }
        return;
      }

      try {
        String[] parts = token.split("\\.");
        String headerJson =
            new String(Base64.getUrlDecoder().decode(parts[0]), StandardCharsets.UTF_8);
        Matcher kidMatcher = Pattern.compile("\"kid\"\\s*:\\s*\"([^\"]+)\"").matcher(headerJson);
        String kid = kidMatcher.find() ? kidMatcher.group(1) : "";

        PublicKey pubKey = null;
        try (InputStream in = URI.create(jwksUri).toURL().openStream()) {
          String jwksJson = new String(in.readAllBytes(), StandardCharsets.UTF_8);
          Matcher keyBlockMatcher =
              Pattern.compile(
                      "\\{[^}]*\"kid\"\\s*:\\s*\"" + Pattern.quote(kid) + "\"[^}]*\\}")
                  .matcher(jwksJson);
          if (keyBlockMatcher.find()) {
            String keyBlock = keyBlockMatcher.group(0);
            Matcher nMatcher = Pattern.compile("\"n\"\\s*:\\s*\"([^\"]+)\"").matcher(keyBlock);
            Matcher eMatcher = Pattern.compile("\"e\"\\s*:\\s*\"([^\"]+)\"").matcher(keyBlock);
            if (nMatcher.find() && eMatcher.find()) {
              BigInteger n =
                  new BigInteger(1, Base64.getUrlDecoder().decode(nMatcher.group(1)));
              BigInteger e =
                  new BigInteger(1, Base64.getUrlDecoder().decode(eMatcher.group(1)));
              pubKey =
                  KeyFactory.getInstance("RSA").generatePublic(new RSAPublicKeySpec(n, e));
            }
          }
        }

        Signature sig = Signature.getInstance("SHA256withRSA");
        sig.initVerify(pubKey);
        sig.update((parts[0] + "." + parts[1]).getBytes(StandardCharsets.UTF_8));
        boolean verified = sig.verify(Base64.getUrlDecoder().decode(parts[2]));

        if (!verified) {
          throw new SecurityException("Signature verification failed");
        }

        System.out.println("Verified Dynamic payload success.");
        byte[] resp = "{\"status\": \"received\"}".getBytes(StandardCharsets.UTF_8);
        exchange.sendResponseHeaders(200, resp.length);
        try (OutputStream os = exchange.getResponseBody()) {
          os.write(resp);
        }
      } catch (Exception e) {
        byte[] resp =
            ("{\"error\": \"Invalid Dynamic signature\", \"details\": \""
                    + e.getMessage()
                    + "\"}")
                .getBytes(StandardCharsets.UTF_8);
        exchange.sendResponseHeaders(400, resp.length);
        try (OutputStream os = exchange.getResponseBody()) {
          os.write(resp);
        }
      }
    });
server.start();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "crypto"
    "crypto/rsa"
    "crypto/sha256"
    "encoding/base64"
    "encoding/json"
    "fmt"
    "io"
    "log"
    "math/big"
    "net/http"
    "strings"

)

func main() {
    jwksURI := "https://generativelanguage.googleapis.com/.well-known/jwks.json"

    http.HandleFunc("/gemini-webhook-dynamic", func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Webhook-Signature")
        parts := strings.Split(token, ".")
        if len(parts) != 3 {
            http.Error(w, `{"error": "No signature header"}`, http.StatusBadRequest)
            return
        }

        headerBytes, err := base64.RawURLEncoding.DecodeString(parts[0])
        if err != nil {
            http.Error(w, `{"error": "Invalid header"}`, http.StatusBadRequest)
            return
        }
        var header struct {
            Kid string `json:"kid"`
        }
        _ = json.Unmarshal(headerBytes, &header)

        resp, err := http.Get(jwksURI)
        if err != nil {
            http.Error(w, `{"error": "Failed to fetch JWKS"}`, http.StatusBadRequest)
            return
        }
        defer resp.Body.Close()
        jwksBytes, _ := io.ReadAll(resp.Body)

        var jwks struct {
            Keys []struct {
                Kid string `json:"kid"`
                N   string `json:"n"`
                E   string `json:"e"`
            } `json:"keys"`
        }
        _ = json.Unmarshal(jwksBytes, &jwks)

        var pubKey *rsa.PublicKey
        for _, k := range jwks.Keys {
            if k.Kid == header.Kid {
                nBytes, _ := base64.RawURLEncoding.DecodeString(k.N)
                eBytes, _ := base64.RawURLEncoding.DecodeString(k.E)
                pubKey = &rsa.PublicKey{
                    N: new(big.Int).SetBytes(nBytes),
                    E: int(new(big.Int).SetBytes(eBytes).Int64()),
                }
                break
            }
        }
        if pubKey == nil {
            http.Error(w, `{"error": "Matching key not found"}`, http.StatusBadRequest)
            return
        }

        sigBytes, _ := base64.RawURLEncoding.DecodeString(parts[2])
        hashed := sha256.Sum256([]byte(parts[0] + "." + parts[1]))
        if err := rsa.VerifyPKCS1v15(pubKey, crypto.SHA256, hashed[:], sigBytes); err != nil {
            http.Error(w, `{"error": "Invalid Dynamic signature"}`, http.StatusBadRequest)
            return
        }

        fmt.Println("Verified Dynamic payload success.")
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte(`{"status": "received"}`))
    })

    log.Fatal(http.ListenAndServe(":8000", nil))
}
```
{% /tab %}

{% /tabs %}

## Webhook envelope {% id="webhook-envelope" %}

To avoid bandwidth congestion, Gemini webhooks use a **thin payload** model to
deliver data.
deliveries send a snapshot containing status details and pointers to results,
rather than the raw output file itself.

Here is an example payload format:

```json
{
  "type": "batch.succeeded",
  "version": "v1",
  "timestamp": "2026-01-22T12:00:00Z",
  "data": {
    "id": "batch_123456",
    "output_file_uri": "gs://my-bucket/results.jsonl"
  }
}
```

## Event catalog reference {% id="event-catalog" %}

The following events are triggered for supporting jobs:

| Event type | Trigger | Payload item (`data`) |
| :--- | :--- | :--- |
| `batch.succeeded` | Processing finished successfully. | `id`, `output_file_uri` |
| `batch.cancelled` | User cancelled request | `id` |
| `batch.expired` | Batch has not been processed (finished) in 24h timeframe | `id` |
| `batch.failed` | Batch job failed (system or validation error). | `id`, `error_code`, `error_message` |
| `interaction.requires_action` | Function call, user needs to do something | `id` |
| `interaction.completed` | LRO in interactions API succeeded | `id` |
| `interaction.failed` | LRO in interactions API failed (system or validation error). | `id`, `error_code`, `error_message` |
| `interaction.cancelled` | LRO in interactions API cancelled | `id` |
| `video.generated` | Video generation LRO completed. | `id`, `output_file_uri`, `file_name` |

## Best practices {% id="best-practices" %}

To ensure reliable, scalable operation:

* **Strict replay protection check**: All requests carry a `webhook-timestamp`
header. Always validate this timestamp on your server configuration layer to
reject payloads older than **5 minutes** (to mitigate replay attacks).

* **Process asynchronously**: Respond with `2xx OK` immediately upon valid
signature detection, and queue parsing operations internally. Prolonged listener
hold times will trigger a delivery retry cycle.

* **Deduplication handling**: Standard webhooks deliver "At-least-once". Use the
consistent `webhook-id` header to handle potential duplicates in higher
congestion flows.

## What's next? {% id="whats-next" %}

* [Batch API](/docs/batch-api): Utilize webhooks to automate high volume endpoints.

# Flex inference
Source: https://aistudio.google.com/docs/flex-inference
Description: Learn how to optimize costs with the Flex inference tier in the Interactions API

{% callout type="note" %}
This feature is in [preview](/docs/models#preview).
{% /callout %}

The Gemini Flex API is an inference tier that offers a 50% cost reduction
compared to standard rates, in exchange for variable latency and best-effort
availability. It's designed for latency-tolerant workloads that require
synchronous processing but don't need the real-time performance of the standard
API.

## How to use Flex {% id="how-to-use-flex" %}

To use the Flex tier, specify the `service_tier` as `flex` in your request. By
default, requests use the standard tier if this field is omitted.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Analyze this dataset for trends...",
    service_tier='flex'
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

async function main() {
    const interaction = await client.interactions.create({
        model: 'gemini-3.8-flash',
        input: 'Analyze this dataset for trends...',
        service_tier: 'flex'
    });
    console.log(interaction.output_text);
}
await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ServiceTier;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Analyze this dataset for trends..."))
        .serviceTier(ServiceTier.FLEX)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:       interactions.Model("gemini-3.8-flash"),
            Input:       interactions.NewInteractionsInput("Analyze this dataset for trends..."),
            ServiceTier: interactions.ServiceTierFlex.ToPointer(),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.8-flash",
      "input": "Analyze this dataset for trends...",
      "service_tier": "flex"
  }'
```
{% /tab %}
{% /tabs %}

## How Flex inference works {% id="how-it-works" %}

Gemini Flex inference bridges the gap between the standard API and the 24-hour
turnaround of the [Batch API](/docs/batch-api). It utilizes off-peak,
"sheddable" compute capacity to provide a cost-effective solution for background
tasks and sequential workflows.

| Feature | Flex | Priority | Standard | Batch |
| :--- | :--- | :--- | :--- | :--- |
| **Pricing** | 50% discount | 75-100% more than Standard | Full price | 50% discount |
| **Latency** | Minutes (1-15 min target) | Low (Seconds) | Seconds to minutes | Up to 24 hours |
| **Reliability** | Best-effort (Sheddable) | High (Non-sheddable) | High / Medium-high | High (for throughput) |
| **Interface** | Synchronous | Synchronous | Synchronous | Asynchronous |

### Key benefits {% id="benefits" %}

* **Cost efficiency**: Substantial savings for non-production evals, background agents, and data enrichment.
* **Low friction**: Simply add a single parameter to your existing requests.
* **Synchronous workflows**: Ideal for sequential API chains where the next request depends on the output of the previous one, making it more flexible than Batch for agentic workflows.

### Use cases {% id="use-cases" %}

* **Offline evaluations**: Running "LLM-as-a-judge" regression tests or leaderboards.
* **Background agents**: Sequential tasks like CRM updates, profile building, or content moderation where minutes of delay are acceptable.
* **Budget-constrained research**: Academic experiments that require high token volume on a limited budget.

### Rate limits {% id="quota" %}

Flex inference traffic counts towards your general [rate limits](https://aistudio.google.com/rate-limit); it doesn't
offer extended rate limits like the [Batch API](/docs/batch-api).

### Sheddable capacity {% id="capacity" %}

Flex traffic is treated with lower priority. If there is a spike in
standard traffic, Flex requests may be preempted or evicted to ensure capacity
for high-priority users. If you're looking for high-priority inference, check
[Priority inference](/docs/priority-inference)

### Error codes {% id="error-codes" %}

When Flex capacity is unavailable or the system is congested, the API will
return standard error codes:

* **503 Service Unavailable**: The system is currently at capacity.
* **429 Too Many Requests**: Rate limits or resource exhaustion.

### Client responsibility {% id="client" %}

* **No server-side fallback**: To prevent unexpected charges, the system won't
  automatically upgrade a Flex request to the Standard tier if Flex capacity is
  full.

* **Retries**: You must implement your own client-side retry logic with
  exponential backoff.

* **Timeouts**: Because Flex requests may sit in a queue, we recommend
  increasing client-side timeouts to 10 minutes or more to avoid premature
  connection closure.

## Adjust timeout windows {% id="timeout" %}

You can configure per-request timeouts for the REST API and client libraries.
Always ensure your client-side timeout covers the intended server patience
window (e.g., 600s+ for Flex wait queues). The SDKs expect timeout values in
milliseconds.

### Per-request timeouts {% id="per-request-timeout" %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client(http_options={"timeout": 900000})

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="why is the sky blue?",
    service_tier="flex",
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

async function main() {
    const interaction = await client.interactions.create({
        model: "gemini-3.8-flash",
        input: "why is the sky blue?",
        service_tier: "flex",
    }, {timeout: 900000});
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ServiceTier;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.HttpOptions;

Client client =
    Client.builder()
        .httpOptions(HttpOptions.builder().timeout(900000).build())
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("why is the sky blue?"))
        .serviceTier(ServiceTier.FLEX)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        HTTPOptions: genai.HTTPOptions{
            Timeout: genai.Ptr(15 * time.Minute),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:       interactions.Model("gemini-3.8-flash"),
            Input:       interactions.NewInteractionsInput("why is the sky blue?"),
            ServiceTier: interactions.ServiceTierFlex.ToPointer(),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}

{% /tabs %}

## Implement retries {% id="retries" %}

Because Flex is sheddable and fails with 503 errors, here is an example of
optionally implementing retry logic to continue with failed requests:

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

def call_with_retry(max_retries=3, base_delay=5):
    for attempt in range(max_retries):
        try:
            return client.interactions.create(
                model="gemini-3.8-flash",
                input="Analyze this batch statement.",
                service_tier="flex",
            )
        except Exception as e:
            if attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt) # Exponential Backoff
                print(f"Flex busy, retrying in {delay}s...")
                time.sleep(delay)
            else:
                print("Flex exhausted, falling back to Standard...")
                return client.interactions.create(
                    model="gemini-3.8-flash",
                    input="Analyze this batch statement."
                )

interaction = call_with_retry()
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function sleep(ms = 1000) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function callWithRetry(maxRetries = 3, baseDelay = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      console.log(`Attempt ${attempt + 1}: Calling Flex tier...`);
      const interaction = await ai.interactions.create({
        model: "gemini-3.8-flash",
        input: "Analyze this batch statement.",
        service_tier: 'flex',
      });
      return interaction;
    } catch (e) {
      if (attempt < maxRetries - 1) {
        const delay = baseDelay * (2 ** attempt);
        console.log(`Flex busy, retrying in ${delay}s...`);
        await sleep(delay * 1000);
      } else {
        console.log("Flex exhausted, falling back to Standard...");
        return await ai.interactions.create({
          model: "gemini-3.8-flash",
          input: "Analyze this batch statement.",
        });
      }
    }
  }
  throw new Error("Failed to complete request with retry.");
}

async function main() {
    const interaction = await callWithRetry();
    console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ServiceTier;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

int maxRetries = 3;
int baseDelay = 5;
Interaction interaction = null;

for (int attempt = 0; attempt < maxRetries; attempt++) {
  try {
    CreateModelInteraction flexParams =
        CreateModelInteraction.builder()
            .model(Model.of("gemini-3.8-flash"))
            .input(InteractionsInput.of("Analyze this batch statement."))
            .serviceTier(ServiceTier.FLEX)
            .build();
    interaction =
        client.interactions.create(CreateInteractionRequestBody.of(flexParams)).interaction().get();
    break;
  } catch (Exception e) {
    if (attempt < maxRetries - 1) {
      int delay = baseDelay * (1 << attempt); // Exponential Backoff
      System.out.println("Flex busy, retrying in " + delay + "s...");
      Thread.sleep(delay * 1000L);
    } else {
      System.out.println("Flex exhausted, falling back to Standard...");
      CreateModelInteraction standardParams =
          CreateModelInteraction.builder()
              .model(Model.of("gemini-3.8-flash"))
              .input(InteractionsInput.of("Analyze this batch statement."))
              .build();
      interaction =
          client
              .interactions
              .create(CreateInteractionRequestBody.of(standardParams))
              .interaction()
              .get();
    }
  }
}

if (interaction != null) {
  System.out.println(interaction.outputText().orElse(""));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    maxRetries := 3
    baseDelay := 5
    var interaction *interactions.Interaction

    for attempt := 0; attempt < maxRetries; attempt++ {
        res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
            Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
                Model:       interactions.Model("gemini-3.8-flash"),
                Input:       interactions.NewInteractionsInput("Analyze this batch statement."),
                ServiceTier: interactions.ServiceTierFlex.ToPointer(),
            }),
        })
        if err == nil {
            interaction = res.Interaction
            break
        }

        if attempt < maxRetries-1 {
            delay := baseDelay * (1 << attempt) // Exponential Backoff
            fmt.Printf("Flex busy, retrying in %ds...\n", delay)
            time.Sleep(time.Duration(delay) * time.Second)
        } else {
            fmt.Println("Flex exhausted, falling back to Standard...")
            stdRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
                Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
                    Model: interactions.Model("gemini-3.8-flash"),
                    Input: interactions.NewInteractionsInput("Analyze this batch statement."),
                }),
            })
            if err != nil {
                log.Fatal(err)
            }
            interaction = stdRes.Interaction
        }
    }

    if interaction != nil && interaction.OutputText != nil {
        fmt.Println(*interaction.OutputText)
    }
}
```
{% /tab %}

{% /tabs %}

## Pricing {% id="pricing" %}

Flex inference is priced at 50% of the [standard API](/docs/pricing)
and billed per token.

## Supported models {% id="supported-models" %}

The following models support Flex inference:

| Model | Flex inference |
| ------------------ | :--------------------------: |
| [Gemini 4 Argon](/docs/models/gemini-4-argon) | ✔️ |
| [Gemini 3.8 Flash](/docs/models/gemini-3.8-flash) | ✔️ |
| [Gemini 3.6 Flash](/docs/models/gemini-3.6-flash) | ✔️ |
| [Gemini 3.5 Flash-Lite](/docs/models/gemini-3.5-flash-lite) | ✔️ |
| [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite) | ✔️ |
| [Gemini 3.1 Pro Preview](/docs/models/gemini-3.1-pro-preview) | ✔️ |
| [Gemini 3 Flash Preview](/docs/models/gemini-3-flash-preview) | ✔️ |
| [Gemini 2.5 Pro](/docs/models/gemini-2.5-pro) | ✔️ |
| [Gemini 2.5 Flash](/docs/models/gemini-2.5-flash) | ✔️ |
| [Gemini 2.5 Flash-Lite](/docs/models/gemini-2.5-flash-lite) | ✔️ |

## What's next {% id="whats-next" %}

* [Priority inference](/docs/priority-inference) for ultra-low latency.
* [Tokens](/docs/tokens): Understand tokens.

# Priority inference
Source: https://aistudio.google.com/docs/priority-inference
Description: Learn how to use Gemini Priority inference for business-critical workloads requiring lower latency.

{% callout type="note" %}
This feature is in [preview](/docs/models#preview).
{% /callout %}

The Gemini Priority API is a premium inference tier designed for
business-critical workloads that require lower latency and the highest
reliability at a premium price point. Priority tier traffic is prioritized above
standard API and Flex tier traffic.

Priority inference is available across the Interactions API endpoints.

## How to use Priority {% id="how-to-use" %}

To use the Priority tier, set the `service_tier` field in your request to
`priority`. The default tier is standard if the field is omitted.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Triage this critical customer support ticket immediately.",
    service_tier='priority'
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function main() {
    const interaction = await ai.interactions.create({
        model: "gemini-3.8-flash",
        input: "Triage this critical customer support ticket immediately.",
        service_tier: "priority"
    });
    console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ServiceTier;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Perform a priority inference task."))
        .serviceTier(ServiceTier.PRIORITY)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:       interactions.Model("gemini-3.8-flash"),
            Input:       interactions.NewInteractionsInput("Perform a priority inference task."),
            ServiceTier: interactions.ServiceTierPriority.ToPointer(),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Triage this critical customer support ticket immediately.",
    "service_tier": "priority"
  }'
```
{% /tab %}
{% /tabs %}

## How Priority inference works {% id="how-it-works" %}

Priority inference routes requests to high-criticality compute queues, offering
predictable, fast performance for user-facing applications. Its primary
mechanism is a graceful server-side downgrade to standard processing for traffic
that exceeds dynamic limits, ensuring application stability instead of failing
the request.

| Feature | Priority | Standard | Flex | Batch |
| :--- | :--- | :--- | :--- | :--- |
| **Pricing** | 75-100% more than Standard | Full price | 50% discount | 50% discount |
| **Latency** | Seconds | Seconds to minutes | Minutes (1-15 min target) | Up to 24 hours |
| **Reliability** | High (Non-sheddable) | High / Medium-high | Best-effort (Sheddable) | High (for throughput) |
| **Interface** | Synchronous | Synchronous | Synchronous | Asynchronous |

### Key benefits {% id="benefits" %}

* **Low latency**: Designed for second response times for interactive,
user-facing AI tools.

* **High reliability**: Traffic is treated with the highest criticality and is
strictly non-sheddable.

* **Graceful degradation**: Traffic spikes exceeding dynamic limits are
automatically downgraded to the Standard tier for processing instead of failing,
preventing service outages.

* **Low friction**: Uses the same synchronous `create` method as the
standard and Flex tiers.

### Use cases {% id="use-cases" %}

Priority processing is ideal for business-critical workflows where performance
and reliability are paramount.

* **Interactive AI applications**: Customer service chatbots and copilots where
users pay a premium and expect fast, consistent responses.

* **Real-time decision engines**: Systems requiring highly reliable, low-latency
outcomes, such as live ticket triaging or fraud detection.

* **Premium customer features**: Developers who need to guarantee higher service
level objectives (SLOs) for paying customers.

### Rate limits {% id="rate-limits" %}

Priority consumption holds its own rate limits even though consumption is
counted towards [overall interactive traffic rate limits](https://aistudio.google.com/rate-limit). The default rate limits
for Priority inference are **0.3x standard rate limit for Model / Tier**

### Graceful downgrade logic {% id="downgrade" %}

If Priority limits are exceeded due to congestion, overflow requests are
**automatically and gracefully** downgraded to Standard processing instead of
failing with a 503 or 429 error. Downgraded requests are billed at the standard
rate, not the Priority premium rate.

### Client responsibility {% id="client" %}

* **Response monitoring**: Developers should monitor the `x-gemini-service-tier`
  header in the API response to detect if requests are being frequently
  downgraded to `standard`.

* **Retries**: Clients must implement retry logic/exponential backoff for
standard errors, such as `DEADLINE_EXCEEDED`.

## Pricing {% id="pricing" %}

Priority inference is priced at 75-100% more than the
[standard API](/docs/pricing) and billed per token.

## Supported models {% id="supported-models" %}

The following models support Priority inference:

| Model | Priority inference |
| ------------------ | :--------------------------: |
| [Gemini 4 Argon](/docs/models/gemini-4-argon) | ✔️ |
| [Gemini 3.8 Flash](/docs/models/gemini-3.8-flash) | ✔️ |
| [Gemini 3.6 Flash](/docs/models/gemini-3.6-flash) | ✔️ |
| [Gemini 3.5 Flash-Lite](/docs/models/gemini-3.5-flash-lite) | ✔️ |
| [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite) | ✔️ |
| [Gemini 3.1 Pro Preview](/docs/models/gemini-3.1-pro-preview) | ✔️ |
| [Gemini 3 Flash Preview](/docs/models/gemini-3-flash-preview) | ✔️ |
| [Gemini 2.5 Pro](/docs/models/gemini-2.5-pro) | ✔️ |
| [Gemini 2.5 Flash](/docs/models/gemini-2.5-flash) | ✔️ |
| [Gemini 2.5 Flash-Lite](/docs/models/gemini-2.5-flash-lite) | ✔️ |

## What's next {% id="whats-next" %}

* [Flex inference](/docs/flex-inference) for cost reduction.
* [Tokens](/docs/tokens): Understand tokens.

# Context caching
Source: https://aistudio.google.com/docs/caching
Description: Learn how to use Context Caching in the Interactions API

In a typical AI workflow, you might pass the same input tokens over and over to
a model. The Gemini API offers implicit caching to optimize performance and
costs.

{% callout type="note" %}
The **Interactions API** only supports implicit caching. Explicit caching
(manually creating and managing cache objects) is not supported in the
Interactions API, or for Gemini 4 Argon and onward. To use explicit caching on
supported Gemini 3 and 2.5 models, switch to the
[generateContent API](/docs/caching?generate-content=true).
{% /callout %}

## Implicit caching {% id="implicit-caching" %}

Implicit caching is enabled by default for all Gemini 2.5 and newer models. It is
supported for both [stateful](/docs/text-generation#multi-turn-conversations) (using `previous_interaction_id`)
and [stateless](/docs/text-generation#stateless-conversations) conversation modes.
We automatically pass on cost savings if your request hits caches. You don't need to configure anything to turn it on. The following table lists the minimum input token count for each model:

| Model | Min token limit |
| :---- | :---- |
| Gemini 4 Argon | 4,096 |
| Gemini 3.8 Flash | 4,096 |
| Gemini 3.6 Flash | 4,096 |
| Gemini 3.1 Pro Preview | 4,096 |
| Gemini 2.5 Flash | 2,048 |
| Gemini 2.5 Pro | 2,048 |

To increase the chance of an implicit cache hit:

- Try putting large and common contents at the beginning of your prompt
- Try to send requests with similar prefix in a short amount of time

{% callout type="note" %}
**Multi-turn and agent loops on Gemini 4 (Argon and newer):** Gemini caches the
full previous request only if the new request adds at least 2,050 tokens. Model
output, thought, and function results all count toward this total. For smaller
additions, Gemini re-processes the last 2,050 tokens of the previous request at
the standard input rate. Most agent turns exceed this threshold.
{% /callout %}

You can see the number of tokens which were cache hits in the response object's
`usage.total_cached_tokens` (Python and JavaScript) field.

# Interactions API
Source: https://aistudio.google.com/docs/interactions-overview
Description: The Interactions API is the simplest and recommended way to build with Gemini models and agents.

The Interactions API is our new interface and the most straightforward way to
build with Gemini models and agents. As of June 2026, it is Generally Available
and the recommended interface for all new projects.

While it is now considered legacy, the original
[`generateContent`](/docs/text-generation?generate-content=true) API remains fully
supported.

## Why use the Interactions API? {% id="why-interactions" %}

*   **New capabilities out of the box**: Optional server-side conversation state
    using `previous_interaction_id`, observable execution steps for debugging
    and UI rendering, and background execution for long-running tasks using
    `background=true`.

*   **Lower cost with higher cache hit rates**: Server-side state management
    enables more efficient context caching across turns, reducing token costs
    for multi-turn conversations.

*   **Built for frontier models and agents**: Purpose-built for thinking models,
    multi-step tool use, and complex reasoning flows — simplifying the process
    of building, debugging, and orchestrating agentic applications.

*   **Single API for models and agents**: One unified interface for calling
    Gemini models and agents directly such as Deep Research and custom managed
    agents — no separate endpoints or patterns to learn.

*   **Where new things launch**: Going forward, new models and capabilities
    beyond the core mainline family, along with new agentic capabilities and
    tools, will launch on the Interactions API.

By default, the Interactions API stores requests so you can leverage the
server-side state management features by using `previous_interaction_id`. You
can opt into stateless behavior by setting `store=false`. See the [data
retention](/docs/interactions-overview#data-storage-retention) section for
details.

## Get started {% id="get-started" %}

*   **Set up your coding agent**: Connect to the **Gemini Docs MCP** and install
    the `gemini-api-dev` skill to give your assistant direct access to the
    latest developer docs and best practices. [Set up your coding agent
    →](/docs/coding-agents)

*   **Migrate from `generateContent`**: If you have an existing integration,
    follow the [Migration Guide](/docs/migrate-to-interactions) to transition to
    the Interactions API.

*   **Get started**: Get started in the [Interactions API Get started
    guide](/docs/get-started).

### Feature Guides {% id="feature-guides" %}

Explore the specific capabilities of the Interactions API through these guides.
You can use the toggle on these pages to switch between generateContent and
Interactions API:

*   [Text generation](/docs/text-generation)
*   [Image generation](/docs/image-generation)
*   [Image understanding](/docs/image-understanding)
*   [Audio understanding](/docs/audio)
*   [Video understanding](/docs/video-understanding)
*   [Document processing](/docs/document-processing)
*   [Function calling](/docs/function-calling)
*   [Structured output](/docs/structured-output)
*   [Deep Research agent](/docs/deep-research)
*   [Flex inference](/docs/flex-inference)
*   [Priority inference](/docs/priority-inference)

## How the Interactions API works {% id="how-it-works" %}

The Interactions API centers around a core resource: the
[**`Interaction`**](https://ai.google.dev/api/interactions-api#Resource:Interaction).
An `Interaction` represents a complete turn in a conversation or task. It acts
as a session record, containing the entire history of an interaction as a
chronological sequence of **execution steps**. These steps include model
thoughts, server-side or client-side tool calls and results (like
`function_call` and `function_result`), and the final `model_output`. The stored
resource (retrieved via `interactions.get`) also includes `user_input` steps for
full context, though the `interactions.create` response only returns
model-generated steps.

When you make a call to
[`interactions.create`](https://ai.google.dev/api/interactions-api#CreateInteraction),
you are creating a new `Interaction` resource:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'
```
{% /tab %}
{% /tabs %}

### Server-side state management {% id="server-side-state" %}

You can use the `id` of a completed interaction in a subsequent call using the
`previous_interaction_id` parameter to continue the conversation. The server
uses this ID to retrieve the conversation history, saving you from having to
resend the entire chat history:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}
```
{% /tab %}
{% tab label="REST" %}
```bash
# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID"
  }'
```
{% /tab %}
{% /tabs %}

The `previous_interaction_id` parameter preserves only the conversation history
(inputs and outputs) using `previous_interaction_id`. The other parameters are
**interaction-scoped** and apply only to the specific interaction you are
currently generating:

-   `tools`
-   `system_instruction`
-   `generation_config` (including `thinking_level`, `temperature`, etc.)

This means you must re-specify these parameters in each new interaction if you
want them to apply. This server-side state management is optional; you can also
operate in stateless mode by sending the full conversation history in each
request.

### Data storage and retention {% id="data-storage-retention" %}

By default, the API stores all Interaction objects (`store=true`) in order to
simplify use of server-side state management features (with
`previous_interaction_id`), background execution (using `background=true`) and
observability purposes.

-   **Paid Tier**: The system retains interactions for **55 days**.
-   **Free Tier**: The system retains interactions for **1 day**.

If you don't want this, you can set `store=false` in your request. This control
is separate from state management; you can opt out of storage for any
interaction. However, note that `store=false` is incompatible with [background
execution](/docs/background-execution) and prevents using
`previous_interaction_id` for subsequent turns.

For Paid Tier projects, you can configure the retention window in [AI
Studio](https://aistudio.google.com/logs) to automatically mark logs for
deletion from project storage after 7, 14, 28, or 55 days. A shorter retention
may affect retrieval of past conversations.

You can delete stored interactions at any time using the [`delete`](https://ai.google.dev/api/interactions-api#deleteInteraction) method programmatically, which
requires the interaction ID. You can also view and manage stored interactions
logs, including deletion from project storage, in [AI
Studio](https://aistudio.google.com/logs).

After the retention period expires, your data will be deleted automatically.

Interactions objects are processed according to the [terms](/docs/terms).

### View interactions in AI Studio {% id="viewing-interactions-in-ai-studio" %}

The API stores Interactions API requests executed with `store=true` for projects
on the Paid Tier. You can view them directly from the [Logs page in Google AI
Studio](https://aistudio.google.com/logs). See the [Logs
guide](/docs/logs-datasets) for more.

## Best practices {% id="best-practices" %}

*   **Cache hit rate**: Implicit caching is supported in both stateful and
    stateless modes (see
    [Quickstart](/docs/get-started#4-multi-turn-conversations)). Using
    `previous_interaction_id` (stateful) to continue conversations allows the
    system to more easily utilize implicit caching for the conversation history,
    which improves performance and reduces costs.
*   **Mixing interactions**: You have the flexibility to mix and match Agent and
    Model interactions within a conversation. For example, you can use a
    specialized agent, like the Deep Research agent, for initial data
    collection, and then use a standard Gemini model for follow-up tasks such as
    summarizing or reformatting, linking these steps with the
    `previous_interaction_id`.

## Supported models & agents {% id="supported-models-agents" %}

| Model Name | Type | Model ID |
| :--- | :--- | :--- |
| Gemini 4 Argon | Model | `gemini-4-argon` |
| Gemini 3.8 Flash | Model | `gemini-3.8-flash` |
| Gemini 3.6 Flash | Model | `gemini-3.6-flash` |
| Gemini 3.1 Pro Preview | Model | `gemini-3.1-pro-preview` |
| Gemini 3.5 Flash-Lite | Model | `gemini-3.5-flash-lite` |
| Gemini 3.1 Flash-Lite | Model | `gemini-3.1-flash-lite` |
| Gemini 3 Flash Preview | Model | `gemini-3-flash-preview` |
| Gemini 2.5 Pro | Model | `gemini-2.5-pro` |
| Gemini 2.5 Flash | Model | `gemini-2.5-flash` |
| Gemini 2.5 Flash-lite | Model | `gemini-2.5-flash-lite` |
| Gemini 3 Pro Image | Model | `gemini-3-pro-image` |
| Gemini 3.1 Flash Image | Model | `gemini-3.1-flash-image` |
| Gemini 3.1 Flash TTS Preview | Model | `gemini-3.1-flash-tts-preview` |
| Gemma 4 31B IT | Model | `gemma-4-31b-it` |
| Gemma 4 26B MoE IT | Model | `gemma-4-26b-a4b-it` |
| Lyria 3.5 | Model | `lyria-3.5` |
| Lyria 3 Clip Preview | Model | `lyria-3-clip-preview` |
| Lyria 3 Pro Preview | Model | `lyria-3-pro-preview` |
| Deep Research Preview | Agent | `deep-research-preview-04-2026` |
| Deep Research Preview | Agent | `deep-research-max-preview-04-2026` |
| Antigravity Preview | Agent | `antigravity-preview-09-2026` |

## SDKs {% id="sdk" %}

You can use latest version of the Google GenAI SDKs in order to access
Interactions API.

*   On Python, this is `google-genai` package from `2.3.0` version onwards.
*   On JavaScript, this is `@google/genai` package from `2.3.0` version onwards.
*   On Go, this is `google.golang.org/genai` package.
*   On Java, this is `com.google.genai:google-genai` package.

You can learn more about how to install the SDKs on [Libraries](/docs/libraries)
page.

## Limitations {% id="limitations" %}

*   **Remote MCP**: Gemini 3 does not support remote MCP, this is coming soon.
*   **Multi-turn model compatibility**: When mixing different models in a
    conversation (either stateful or stateless), subsequent models must support
  the output modalities of the previous models as input. For example, if you
    generate an image using `gemini-3.1-flash-image`, you cannot continue that
    conversation with a model that doesn't accept image inputs (such as a
    text-only model or a music-generation model like Lyria).

The following features are supported by the
[`generateContent`](/docs/text-generation?generate-content=true) API but are **not
yet available** in the Interactions API:

*   **[Batch API](/docs/batch-api)**
*   **[Automatic function calling
    (Python)](/docs/function-calling?example=meeting&generate-content=true#automatic_function_calling_python_only)**
    *   **[Explicit caching](/docs/caching)**: Note that server-side implicit
        caching is available in the Interactions API via
        `previous_interaction_id`.

## Feedback {% id="feedback" %}

Your feedback is critical to the development of the Interactions API. Share your
thoughts, report bugs, or request features on our [Google AI Developer Community
Forum](https://discuss.ai.google.dev/c/gemini-api/4).

## What's next {% id="whats-next" %}

*   Try the [Interactions API quickstart
    notebook](https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_interactions_api.ipynb).
    *   Learn more about the [Gemini Deep Research agent](/docs/deep-research).

# Streaming interactions
Source: https://aistudio.google.com/docs/streaming
Description: Learn how to stream responses, tool calls, thinking, and images in real time with the Interactions API.

When creating an Interaction, you can set `stream: true` to incrementally stream the response using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) (SSE).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Count from 1 to 25.",
    stream=True,
)
for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Count from 1 to 25.",
    stream: true,
});
for await (const event of stream) {
    if (event.event_type === "step.delta") {
        if (event.delta.type === "text") {
            process.stdout.write(event.delta.text);
        }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Count from 1 to 25."))
        .stream(true)
        .build();

CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));

try (EventStream<InteractionSSEStreamEvent> events = response.events()) {
  for (InteractionSSEStreamEvent streamEvent : events) {
    InteractionSSEEvent event = streamEvent.data().orElse(null);
    if (event instanceof StepDelta stepDelta) {
      StepDeltaData data = stepDelta.delta().orElse(null);
      if (data instanceof TextDelta textDelta) {
        textDelta.text().ifPresent(System.out::print);
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:  interactions.Model("gemini-3.8-flash"),
            Input:  interactions.NewInteractionsInput("Explain quantum computing in simple terms."),
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

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

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

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

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

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

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

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

event: step.delta
data: {"index":1,"delta":{"text":"1, 2, 3, 4, 5, 6, ","type":"text"},"event_type":"step.delta"}

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

...

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

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

event: done
data: [DONE]
```

## Event types {% id="event-types" %}

Each server-sent event includes a named `event_type` and associated JSON data. The Interactions API uses a symmetric streaming model where all content—text, tool calls, thinking—flows through a consistent **step-based** event.

Each stream follows this event flow:

1. `interaction.created`: The interaction is created, includes metadata (ID, model, status).
2. A series of **steps**, each consisting of:
   - A `step.start` event, indicating the step type (e.g., `model_output`, `thought`, `function_call`).
   - One or more `step.delta` events with incremental data for that step.
   - A `step.stop` event marking the step as complete.
3. An `interaction.completed` event with final `usage` statistics.

When you set `stream: false`, the API returns a single `interaction` object with a `steps` array. Each element in `steps` is the fully assembled version of one `step.start` → `step.delta`(s) → `step.stop` cycle.

### `interaction.created` {% id="event-interaction-created" %}

Sent when the interaction is first created. Contains the interaction ID, model, and initial status.

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

### `interaction.status_update` {% id="event-interaction-status-update" %}

Signals an interaction-level status transition. May appear between steps.

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

### `step.start` {% id="event-step-start" %}

Marks the beginning of a new step. Contains the step `type` and `index`. The step type determines which delta types to expect and how the step appears in a non-streaming response:

| Step Type | Expected Delta Types | Description |
|---|---|---|---|
| `model_output` | `text`, `image`, `audio` | The model's final response content. |
| `thought` | `thought_signature`, `thought_summary` | Chain-of-thought reasoning. `summary` is only present when `thinking_summaries` is enabled. |
| `function_call` | `arguments_delta` | A request for the client to execute a function. Sets interaction status to `requires_action`. |
| Server-side tools | Varies by tool | Tools executed by the API (e.g., `google_search_call`, `google_search_result`, `code_execution_call`, `code_execution_result`). |

See the [Interactions API reference](https://ai.google.dev/api/interactions-api) for the full list.

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

For function calls, the step includes the function name, id and empty arguments `{}`.

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

### `step.delta` {% id="event-step-delta" %}

Incremental data for the current step. The `delta` object contains a `type` field that determines its shape.

**Examples:**

**`text`:** Incremental text token from a `model_output` step:

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

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

**`image`:** Base64-encoded image data from a `model_output` step:

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

**`thought_summary`:** Thinking summary content from a `thought` step:

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

**`arguments_delta`:** (Partial) JSON string for function call arguments. Must be accumulated across deltas:

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

These are some of the most common delta types. For the complete list of all delta types, see the [Interactions API reference](https://ai.google.dev/api/interactions-api).

### `step.stop` {% id="event-step-stop" %}

Marks the end of a step. Contains the step `index`.

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

When using the [Antigravity Agent](/docs/antigravity-agent), the
`step.stop` event may also include usage statistics:

*   **`usage`**: The accumulated usage (running total) since the start of the interaction.
*   **`step_usage`**: The usage of this specific step.

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

### `interaction.completed` {% id="event-interaction-completed" %}

Sent when the interaction is finished. Contains the final interaction object with `usage` statistics. In non-streaming mode, this is the top-level response object itself. Does not include `steps` in the response.

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

### `error` {% id="event-error" %}

Sent when an error occurs during the interaction. Contains an error object with a message and code.

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

## Streaming with tools {% id="streaming-with-tools" %}

The Interactions API supports streaming with both client-side tools (function
calling) and server-side tools (Google Search, Code Execution, etc.) in a single
request. During streaming, tool invocations appear as typed steps in the event
stream. For function calls, the `step.start` event delivers the function name,
and `step.delta` events stream the arguments as JSON strings
(`arguments_delta`). You must accumulate these deltas to get the full arguments.
Server-side tools like Google Search are executed automatically by the API,
producing `google_search_call` and `google_search_result` steps.

### Streaming with function calling {% id="streaming-with-function-calling" %}

To perform function calling with streaming, the client must handle a multi-turn
conversation:

1. **Turn 1 (Function Request):** Call `interactions.create` with `stream: true`
   and your defined `tools`. The API will stream a `function_call` step. You
   must accumulate the incremental argument JSON strings (`arguments_delta`) from
   `step.delta` events until the interaction completes with the status
   `requires_action`.
2. **Turn 2 (Sending Result):** Call `interactions.create` again, passing the
   `previous_interaction_id` (matching the ID of the first interaction) and
   sending a `function_result` block within the `input` array. This resumes the
   stream, allowing the model to generate its final response.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

weather_tool = {
    "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"]
    }
}

# Turn 1: Request function call
stream = client.interactions.create(
    model="gemini-3.8-flash",
    tools=[weather_tool],
    input="What is the weather in Paris right now?",
    stream=True,
)

first_interaction_id = None
func_call_id = None
func_call_name = None
func_args_accumulated = ""

for event in stream:
    if event.event_type == "interaction.created":
        first_interaction_id = event.interaction.id
    elif event.event_type == "step.start":
        step = event.step
        if step.type == "function_call":
            func_call_id = step.id
            func_call_name = step.name
    elif event.event_type == "step.delta":
        if event.delta.type == "arguments_delta":
            func_args_accumulated += event.delta.arguments

# Turn 2: Execute tool and send the result back to resume stream
if func_call_id:
    # Execute weather_tool using accumulated arguments
    dummy_result = {
        "content": [{"type": "text", "text": '{"weather": "Sunny and 22°C"}'}]
    }

    stream2 = client.interactions.create(
        model="gemini-3.8-flash",
        previous_interaction_id=first_interaction_id,
        input=[{
            "type": "function_result",
            "name": func_call_name,
            "call_id": func_call_id,
            "result": dummy_result
        }],
        stream=True,
    )

    for event in stream2:
        if event.event_type == "step.delta":
            if event.delta.type == "text":
                print(event.delta.text, end="", flush=True)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const weatherTool = {
    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"]
    }
};

// Turn 1: Request function call
const stream = await client.interactions.create({
    model: "gemini-3.8-flash",
    tools: [
    {
      type: "function",
      name: "get_current_weather",
      description: "Get the current weather for a given location",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string" },
        },
        required: ["location"],
      },
    },
  ],
    input: "What is the weather in Paris right now?",
    stream: true,
});

let firstInteractionId = null;
let funcCallId = null;
let funcCallName = null;
let funcArgsAccumulated = "";

for await (const event of stream) {
    if (event.event_type === "interaction.created") {
        firstInteractionId = event.interaction.id;
    } else if (event.event_type === "step.start") {
        const step = event.step;
        if (step.type === "function_call") {
            funcCallId = step.id;
            funcCallName = step.name;
        }
    } else if (event.event_type === "step.delta") {
        if (event.delta.type === "arguments_delta") {
            funcArgsAccumulated += event.delta.arguments;
        }
    }
}

// Turn 2: Execute tool and send the result back to resume stream
if (funcCallId && firstInteractionId && funcCallName) {
    const dummyResult = {
        content: [{ type: "text", text: '{"weather": "Sunny and 22°C"}' }]
    };

    const stream2 = await client.interactions.create({
        model: "gemini-3.8-flash",
        previous_interaction_id: firstInteractionId,
        input: [{
            type: "function_result",
            name: funcCallName,
            call_id: funcCallId,
            result: dummyResult
        }],
        stream: true,
    });

    for await (const event of stream2) {
        if (event.event_type === "step.delta") {
            if (event.delta.type === "text") {
                process.stdout.write(event.delta.text);
            }
        }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ArgumentsDelta;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.FunctionResultStep;
import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;
import com.google.genai.gaos.models.interactions.InteractionCreatedEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionSseEventInteraction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.StepStart;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> locationProp = new HashMap<>();
locationProp.put("type", "string");
locationProp.put("description", "The city and state, e.g. San Francisco, CA");

Map<String, Object> properties = new HashMap<>();
properties.put("location", locationProp);

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");
parameters.put("properties", properties);
parameters.put("required", Arrays.asList("location"));

Function weatherTool =
    Function.builder()
        .name("get_weather")
        .description("Get the current weather in a given location")
        .parameters(parameters)
        .build();

// Turn 1: Request function call
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .tools(Arrays.asList(weatherTool))
        .input(InteractionsInput.of("What is the weather in Paris right now?"))
        .stream(true)
        .build();

CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));

String firstInteractionId = null;
String funcCallId = null;
String funcCallName = null;
StringBuilder funcArgsAccumulated = new StringBuilder();

try (EventStream<InteractionSSEStreamEvent> stream = response.events()) {
  for (InteractionSSEStreamEvent streamEvent : stream) {
    InteractionSSEEvent event = streamEvent.data().orElse(null);
    if (event instanceof InteractionCreatedEvent createdEvent) {
      firstInteractionId =
          createdEvent.interaction().flatMap(InteractionSseEventInteraction::id).orElse(null);
    } else if (event instanceof StepStart stepStart) {
      Step step = stepStart.step().orElse(null);
      if (step instanceof FunctionCallStep fcStep) {
        funcCallId = fcStep.id().orElse(null);
        funcCallName = fcStep.name().orElse(null);
      }
    } else if (event instanceof StepDelta stepDelta) {
      StepDeltaData delta = stepDelta.delta().orElse(null);
      if (delta instanceof ArgumentsDelta argsDelta) {
        funcArgsAccumulated.append(argsDelta.arguments().orElse(""));
      }
    }
  }
}

// Turn 2: Execute tool and send the result back to resume stream
if (funcCallId != null && firstInteractionId != null && funcCallName != null) {
  FunctionResultStep resultStep =
      FunctionResultStep.builder()
          .name(funcCallName)
          .callId(funcCallId)
          .result(
              FunctionResultStepResultUnion.of(
                  Arrays.asList(TextContent.builder().text("{\"weather\": \"Sunny and 22°C\"}").build())))
          .build();

  CreateModelInteraction params2 =
      CreateModelInteraction.builder()
          .model(Model.of("gemini-3.8-flash"))
          .previousInteractionId(firstInteractionId)
          .input(InteractionsInput.ofStep(Arrays.asList(resultStep)))
          .stream(true)
          .build();

  CreateInteractionResponse response2 =
      client.interactions.create(CreateInteractionRequestBody.of(params2));

  try (EventStream<InteractionSSEStreamEvent> stream2 = response2.events()) {
    for (InteractionSSEStreamEvent streamEvent : stream2) {
      InteractionSSEEvent event = streamEvent.data().orElse(null);
      if (event instanceof StepDelta stepDelta) {
        StepDeltaData delta = stepDelta.delta().orElse(null);
        if (delta instanceof TextDelta textDelta) {
          textDelta.text().ifPresent(System.out::print);
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-pro"),
            Input: interactions.NewInteractionsInput("Solve the Monty Hall problem step-by-step."),
            GenerationConfig: &interactions.GenerationConfig{
                ThinkingLevel:     interactions.ThinkingLevelHigh.ToPointer(),
                ThinkingSummaries: interactions.ThinkingSummariesAuto.ToPointer(),
            },
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if thoughtDelta := stepDelta.GetDeltaThoughtSummary(); thoughtDelta != nil {
                if textContent := thoughtDelta.GetContentText(); textContent != nil {
                    fmt.Printf("[Thought] %s\n", textContent.Text)
                }
            }
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}

    **Turn 1:** Request function call

    ```bash
    curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
      -H "x-goog-api-key: $GEMINI_API_KEY" \
      -H "Content-Type: application/json" \
      --no-buffer \
      -d '{
        "model": "gemini-3.8-flash",
        "input": "What is the weather in Paris right now?",
        "stream": true,
        "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"]
            }
          }
        ]
      }'
    ```

    **Turn 2:** Send the function result using the `previous_interaction_id` and `call_id` from Turn 1

    ```bash
    curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
      -H "x-goog-api-key: $GEMINI_API_KEY" \
      -H "Content-Type: application/json" \
      --no-buffer \
      -d '{
        "model": "gemini-3.8-flash",
        "previous_interaction_id": "v1_ChdGUVFJYXBXVUdLVEF4TjhQ...",
        "stream": true,
        "input": [
          {
            "type": "function_result",
            "name": "get_weather",
            "call_id": "CALL_ID",
            "result": {
              "content": [
                {
                  "type": "text",
                  "text": "{\"weather\": \"Sunny and 22°C\"}"
                }
              ]
            }
          }
        ]
      }'
    ```

{% /tab %}
{% /tabs %}

### Streaming with multiple tools {% id="streaming-with-multiple-tools" %}

The following example uses both a `function` tool and `google_search` in one request:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

tools = [
    {"type": "google_search"},
    {
        "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"]
        }
    }
]

stream = client.interactions.create(
    model="gemini-3.8-flash",
    tools=tools,
    input="Search what is the largest mountain in Europe and what the weather is there right now?",
    stream=True,
)
for event in stream:
    if event.event_type == "step.start":
        step = event.step
        print(f"\n--- Step {event.index}: {step.type} ---")
        # Show details for tool steps
        if step.type == "google_search_call":
            print(f"  Search ID: {step.id}")
        elif step.type == "google_search_result":
            print(f"  Result for: {step.call_id}")
        elif step.type == "function_call":
            print(f"  Function: {step.name}({step.arguments})")
    elif event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)
        elif event.delta.type == "google_search_call":
            print(f"  Queries: {event.delta.arguments}")
        elif event.delta.type == "arguments_delta":
            print(f"  Args chunk: {event.delta.arguments}", end="", flush=True)
    elif event.event_type == "interaction.completed":
        print(f"\n\nStatus: {event.interaction.status}")
        if event.interaction.status == "requires_action":
            print("Action required: provide function call results to continue.")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    model: "gemini-3.8-flash",
    tools: [
        { type: "google_search" },
        {
            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: "Search what is the largest mountain in Europe and what the weather is there right now?",
    stream: true,
});
for await (const event of stream) {
    if (event.event_type === "step.start") {
        const step = event.step;
        console.log(`\n--- Step ${event.index}: ${step.type} ---`);
        // Show details for tool steps
        if (step.type === "google_search_call") {
            console.log(`  Search ID: ${step.id}`);
        } else if (step.type === "google_search_result") {
            console.log(`  Result for: ${step.call_id}`);
        } else if (step.type === "function_call") {
            console.log(`  Function: ${step.name}(${JSON.stringify(step.arguments)})`);
        }
    } else if (event.event_type === "step.delta") {
        if (event.delta.type === "text") {
            process.stdout.write(event.delta.text);
        } else if (event.delta.type === "google_search_call") {
            console.log(`  Queries: ${JSON.stringify(event.delta.arguments?.queries)}`);
        } else if (event.delta.type === "arguments_delta") {
            process.stdout.write(`  Args chunk: ${event.delta.arguments}`);
        }
    } else if (event.event_type === "interaction.completed") {
        console.log(`\n\nStatus: ${event.interaction.status}`);
        if (event.interaction.status === "requires_action") {
            console.log("Action required: provide function call results to continue.");
        }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ArgumentsDelta;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.GoogleSearchCallDelta;
import com.google.genai.gaos.models.interactions.GoogleSearchCallStep;
import com.google.genai.gaos.models.interactions.GoogleSearchResultStep;
import com.google.genai.gaos.models.interactions.InteractionCompletedEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionSseEventInteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.StepStart;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.interactions.Tool;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

Client client = new Client();

Map<String, Object> locationProp = new HashMap<>();
locationProp.put("type", "string");
locationProp.put("description", "The city and state, e.g. San Francisco, CA");

Map<String, Object> properties = new HashMap<>();
properties.put("location", locationProp);

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");
parameters.put("properties", properties);
parameters.put("required", Arrays.asList("location"));

List<Tool> tools =
    Arrays.asList(
        new GoogleSearch(),
        Function.builder()
            .name("get_weather")
            .description("Get the current weather in a given location")
            .parameters(parameters)
            .build());

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .tools(tools)
        .input(
            InteractionsInput.of(
                "Search what is the largest mountain in Europe and what the weather is there right now?"))
        .stream(true)
        .build();

CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));

try (EventStream<InteractionSSEStreamEvent> stream = response.events()) {
  for (InteractionSSEStreamEvent streamEvent : stream) {
    InteractionSSEEvent event = streamEvent.data().orElse(null);
    if (event instanceof StepStart stepStart) {
      Step step = stepStart.step().orElse(null);
      if (step != null) {
        System.out.printf("%n--- Step %d: %s ---%n", stepStart.index().orElse(0), step.type());
        if (step instanceof GoogleSearchCallStep searchCall) {
          System.out.println("  Search ID: " + searchCall.id().orElse(""));
        } else if (step instanceof GoogleSearchResultStep searchResult) {
          System.out.println("  Result for: " + searchResult.callId().orElse(""));
        } else if (step instanceof FunctionCallStep fcStep) {
          System.out.printf(
              "  Function: %s(%s)%n",
              fcStep.name().orElse(""), fcStep.arguments().orElse(Collections.emptyMap()));
        }
      }
    } else if (event instanceof StepDelta stepDelta) {
      StepDeltaData delta = stepDelta.delta().orElse(null);
      if (delta instanceof TextDelta textDelta) {
        textDelta.text().ifPresent(System.out::print);
      } else if (delta instanceof GoogleSearchCallDelta searchDelta) {
        System.out.println("  Queries: " + searchDelta.arguments().orElse(null));
      } else if (delta instanceof ArgumentsDelta argsDelta) {
        System.out.print("  Args chunk: " + argsDelta.arguments().orElse(""));
      }
    } else if (event instanceof InteractionCompletedEvent completedEvent) {
      completedEvent
          .interaction()
          .ifPresent(
              interaction -> {
                String status =
                    interaction
                        .status()
                        .map(InteractionSseEventInteractionStatus::value)
                        .orElse("");
                System.out.println("\n\nStatus: " + status);
                if ("requires_action".equals(status)) {
                  System.out.println("Action required: provide function call results to continue.");
                }
              });
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    weatherTool := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Gets the current weather for a given location."),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{"type": "string"},
            },
            "required": []string{"location"},
        },
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:  interactions.Model("gemini-3.8-flash"),
            Input:  interactions.NewInteractionsInput("What is the weather in Tokyo and Paris?"),
            Tools:  []interactions.Tool{weatherTool},
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepStart := event.GetDataStepStart(); stepStart != nil {
            if call := stepStart.GetStepFunctionCall(); call != nil {
                fmt.Printf("\n[Function Call Started] %s (id: %s)\n", call.Name, call.ID)
            }
        }
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if argsDelta := stepDelta.GetDeltaArgumentsDelta(); argsDelta != nil && argsDelta.Arguments != nil {
                fmt.Printf("[Args Delta] %s\n", *argsDelta.Arguments)
            }
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
        if completed := event.GetDataInteractionCompleted(); completed != nil {
            interaction := completed.Interaction
            if interaction.Status == interactions.InteractionSseEventInteractionStatusRequiresAction {
                fmt.Printf("\nStream paused: Waiting for tool outputs for interaction %s\n", interaction.ID)
            }
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Search what is the largest mountain in Europe and what the weather is there right now?",
    "stream": true,
    "tools": [
      { "type": "google_search" },
      {
        "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"]
        }
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

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

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

event: step.start
data: {"index":0,"step":{"id":"mkutnkgn","signature":"","type":"google_search_call"},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"signature":"...","type":"google_search_call","arguments":{"queries":["largest mountain in Europe"]}},"event_type":"step.delta"}

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

event: step.start
data: {"index":1,"step":{"call_id":"mkutnkgn","signature":"","type":"google_search_result"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"signature":"...","type":"google_search_result","is_error":false},"event_type":"step.delta"}

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

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

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

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

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

event: step.delta
data: {"index":3,"delta":{"arguments":"{\"location\":\"Mount Elbrus, Russia\"}","type":"arguments_delta"},"event_type":"step.delta"}

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

event: interaction.completed
data: {"interaction":{"id":"v1_...","status":"requires_action","usage":{"total_tokens":299,"total_input_tokens":138,"input_tokens_by_modality":[{"modality":"text","tokens":138}],"total_cached_tokens":0,"total_output_tokens":20,"total_tool_use_tokens":0,"total_thought_tokens":141},"created":"2026-05-12T17:24:26Z","updated":"2026-05-12T17:24:26Z","service_tier":"standard","object":"interaction","model":"gemini-3.8-flash"},"event_type":"interaction.completed"}

event: done
data: [DONE]
```

## Streaming with thinking {% id="streaming-with-thinking" %}

When the model uses thinking, you'll receive `thought` steps with two distinct delta types: `thought_summary` (incremental text or image summary content), and `thought_signature` (an encrypted representation of the model's internal reasoning, sent as the last delta before `step.stop`). If `thinking_summaries` is enabled, `thought_summary` deltas stream a summary of the model's reasoning. For more details on thinking, see the [Thinking guide](/docs/thinking).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the greatest common divisor of 1071 and 462?",
    generation_config={
        "thinking_summaries": "auto"
    },
    stream=True,
)
for event in stream:
    if event.event_type == "step.start":
        print(f"\n--- Step: {event.step.type} ---")
    elif event.event_type == "step.delta":
        if event.delta.type == "thought_summary":
            if event.delta.content.type == "text":
                print(event.delta.content.text, end="", flush=True)
        elif event.delta.type == "text":
            print(event.delta.text, end="", flush=True)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the greatest common divisor of 1071 and 462?",
    generation_config: {
        thinking_summaries: "auto",
    },
    stream: true,
});
for await (const event of stream) {
    if (event.event_type === "step.start") {
        console.log(`\n--- Step: ${event.step.type} ---`);
    } else if (event.event_type === "step.delta") {
        if (event.delta.type === "thought_summary") {
            if (event.delta.content?.type === "text") {
                process.stdout.write(event.delta.content.text);
            }
        } else if (event.delta.type === "text") {
            process.stdout.write(event.delta.text);
        }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GenerationConfig;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.StepStart;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.interactions.ThoughtSummaryDelta;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("What is the greatest common divisor of 1071 and 462?"))
        .generationConfig(
            GenerationConfig.builder().thinkingSummaries(ThinkingSummaries.AUTO).build())
        .stream(true)
        .build();

CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));

try (EventStream<InteractionSSEStreamEvent> stream = response.events()) {
  for (InteractionSSEStreamEvent streamEvent : stream) {
    InteractionSSEEvent event = streamEvent.data().orElse(null);
    if (event instanceof StepStart stepStart) {
      Step step = stepStart.step().orElse(null);
      if (step != null) {
        System.out.printf("%n--- Step: %s ---%n", step.type());
      }
    } else if (event instanceof StepDelta stepDelta) {
      StepDeltaData delta = stepDelta.delta().orElse(null);
      if (delta instanceof ThoughtSummaryDelta thoughtDelta) {
        Content content = thoughtDelta.content().orElse(null);
        if (content instanceof TextContent textContent) {
          textContent.text().ifPresent(System.out::print);
        }
      } else if (delta instanceof TextDelta textDelta) {
        textDelta.text().ifPresent(System.out::print);
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("What are the top news stories in AI today, and calculate 2^64 - 1?"),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.GoogleSearch{}),
                interactions.NewTool(interactions.CodeExecution{}),
            },
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepStart := event.GetDataStepStart(); stepStart != nil {
            step := stepStart.Step
            if searchCall := step.GoogleSearchCallStep; searchCall != nil {
                fmt.Printf("[Google Search Started] id: %s\n", searchCall.ID)
            } else if searchRes := step.GoogleSearchResultStep; searchRes != nil {
                fmt.Printf("[Google Search Results Received] for call_id: %s\n", searchRes.CallID)
            } else if codeCall := step.CodeExecutionCallStep; codeCall != nil {
                fmt.Printf("[Code Execution Started] id: %s\n", codeCall.ID)
            } else if codeRes := step.CodeExecutionResultStep; codeRes != nil {
                fmt.Printf("[Code Execution Finished] output: %s\n", codeRes.Result)
            }
        }
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if searchDelta := stepDelta.GetDeltaGoogleSearchCall(); searchDelta != nil {
                fmt.Printf("[Search Queries] %v\n", searchDelta.Arguments.Queries)
            }
            if codeDelta := stepDelta.GetDeltaCodeExecutionCall(); codeDelta != nil {
                fmt.Printf("[Code Delta] %s\n", codeDelta.Arguments.Code)
            }
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is the greatest common divisor of 1071 and 462?",
    "stream": true,
    "generation_config": {
      "thinking_summaries": "auto"
    }
  }'
```
{% /tab %}
{% /tabs %}

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

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

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

event: step.delta
data: {"index":0,"delta":{"content":{"text":"**Implementing Euclidean Algorithm**\n\nI've just worked through a detailed example applying the Euclidean algorithm to find the GCD of 1071 and 462, confirming its step-by-step nature. The calculations went smoothly, tracking the remainders until zero. My focus is now solidifying the implementation logic, ensuring accuracy and considering potential edge cases. I'll translate this example into code.\n\n\n","type":"text"},"type":"thought_summary"},"event_type":"step.delta"}

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

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

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

...
```

## Streaming with agents {% id="streaming-with-agents" %}

The Interactions API supports agents like Deep Research. Agents use `background=True` and return results asynchronously, but you can also stream agent interactions to receive progress updates and intermediate steps as they happen. For more details, see the [Background execution guide](/docs/background-execution) and the [Deep Research guide](/docs/deep-research).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

stream = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Research the latest advances in quantum computing.",
    stream=True,
    background=True,
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto"
    }
)
for event in stream:
    if event.event_type == "step.start":
        print(f"\n--- Step: {event.step.type} ---")
    elif event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)
        elif event.delta.type == "thought_summary":
            if event.delta.content.type == "text":
                print(event.delta.content.text, end="", flush=True)
    elif event.event_type == "interaction.completed":
        print(f"\n\nTotal Tokens: {event.interaction.usage.total_tokens}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    agent: "deep-research-preview-04-2026",
    input: "Research the latest advances in quantum computing.",
    stream: true,
    background: true,
    agent_config: {
        type: "deep-research",
        thinking_summaries: "auto"
    }
});
for await (const event of stream) {
    if (event.event_type === "step.start") {
        console.log(`\n--- Step: ${event.step.type} ---`);
    } else if (event.event_type === "step.delta") {
        if (event.delta.type === "text") {
            process.stdout.write(event.delta.text);
        } else if (event.delta.type === "thought_summary") {
            if (event.delta.content?.type === "text") {
                process.stdout.write(event.delta.content.text);
            }
        }
    } else if (event.event_type === "interaction.completed") {
        if (event.interaction?.usage?.total_tokens) { console.log(`\n\nTotal Tokens: ${event.interaction.usage.total_tokens}`); }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.DeepResearchAgentConfig;
import com.google.genai.gaos.models.interactions.InteractionCompletedEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionSseEventInteraction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.StepStart;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.interactions.ThinkingSummaries;
import com.google.genai.gaos.models.interactions.ThoughtSummaryDelta;
import com.google.genai.gaos.models.interactions.Usage;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;

Client client = new Client();

CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent("deep-research-preview-04-2026")
        .input(InteractionsInput.of("Research the latest advances in quantum computing."))
        .stream(true)
        .background(true)
        .agentConfig(
            DeepResearchAgentConfig.builder()
                .thinkingSummaries(ThinkingSummaries.AUTO)
                .build())
        .build();

CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));

try (EventStream<InteractionSSEStreamEvent> stream = response.events()) {
  for (InteractionSSEStreamEvent streamEvent : stream) {
    InteractionSSEEvent event = streamEvent.data().orElse(null);
    if (event instanceof StepStart stepStart) {
      Step step = stepStart.step().orElse(null);
      if (step != null) {
        System.out.printf("%n--- Step: %s ---%n", step.type());
      }
    } else if (event instanceof StepDelta stepDelta) {
      StepDeltaData delta = stepDelta.delta().orElse(null);
      if (delta instanceof TextDelta textDelta) {
        textDelta.text().ifPresent(System.out::print);
      } else if (delta instanceof ThoughtSummaryDelta thoughtDelta) {
        Content content = thoughtDelta.content().orElse(null);
        if (content instanceof TextContent textContent) {
          textContent.text().ifPresent(System.out::print);
        }
      }
    } else if (event instanceof InteractionCompletedEvent completedEvent) {
      completedEvent
          .interaction()
          .flatMap(InteractionSseEventInteraction::usage)
          .flatMap(Usage::totalTokens)
          .ifPresent(tokens -> System.out.println("\n\nTotal Tokens: " + tokens));
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.1-flash-image-preview"),
            Input: interactions.NewInteractionsInput("Generate a watercolor illustration of a lighthouse at sunset and describe the scene."),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat([]interactions.ResponseFormat{
                interactions.NewResponseFormat(interactions.TextResponseFormat{}),
                interactions.NewResponseFormat(interactions.ImageResponseFormat{}),
            })),
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
            if imgDelta := stepDelta.GetDeltaImage(); imgDelta != nil && imgDelta.Data != nil {
                imageBytes, err := base64.StdEncoding.DecodeString(*imgDelta.Data)
                if err != nil {
                    log.Fatal(err)
                }
                if err := os.WriteFile("lighthouse.png", imageBytes, 0644); err != nil {
                    log.Fatal(err)
                }
                fmt.Println("\n[Saved lighthouse.png]")
            }
        }
        if completed := event.GetDataInteractionCompleted(); completed != nil {
            // You can also access the final image using interaction.GetOutputImage() on a non-streamed or retrieved interaction
            fmt.Println("\nGeneration complete!")
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "agent": "deep-research-preview-04-2026",
    "input": "Research the latest advances in quantum computing.",
    "stream": true,
    "background": true,
    "agent_config": {
      "type": "deep-research",
      "thinking_summaries": "auto"
    }
  }'
```
{% /tab %}
{% /tabs %}

```none
event: interaction.created
data: {"interaction":{"id":"v1_...","status":"in_progress","object":"interaction","agent":"deep-research-preview-04-2026"},"event_type":"interaction.created"}

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

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

event: step.delta
data: {"index":0,"delta":{"content":{"text":"***Generating research plan***\n\nTo best answer your request, I'm starting by constructing a comprehensive research plan. This will outline the key areas I need to investigate and the strategy I'll use to connect them."},"type":"thought_summary"},"event_type":"step.delta"}

... (additional thought steps) ...

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

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

event: step.delta
data: {"index":1,"delta":{"text":"# The Quantum Inflection Point: Exhaustive Analysis of Hardware, Algorithms, and Market Dynamics in 2026\n\n## Executive Summary\n\n..."},"event_type":"step.delta"}

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

event: interaction.completed
data: {"interaction":{"id":"v1_...","status":"completed","usage":{"total_tokens":1117031,"total_input_tokens":428865,"total_output_tokens":22294,"total_thought_tokens":26213},"created":"2026-05-12T17:24:27Z","updated":"2026-05-12T17:24:27Z","object":"interaction","agent":"deep-research-preview-04-2026"},"event_type":"interaction.completed"}

event: done
data: [DONE]
```

## Streaming image generation {% id="streaming-image-generation" %}

The Interactions API supports streaming multiple output modalities simultaneously. By requesting both `text` and `image` in the `response_format`, you can receive interleaved text and generated images in the same stream.

The following example uses `gemini-3.1-flash-image` (Nano Banana 2) to search for information and generate a story with interleaved illustrations.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.1-flash-image",
    tools=[{"type": "google_search", "search_types": ["web_search", "image_search"]}],
    input="Search for the history of the Colosseum and write a short illustrated story about a gladiator named Marcus. Interleave text and generated images.",
    response_format=[
        {"type": "text"},
        {"type": "image"}
    ],
    stream=True,
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)
        elif event.delta.type == "image":
            print(f"\n[Image chunk: {len(event.delta.data)} bytes]", end="", flush=True)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    model: "gemini-3.1-flash-image",
    tools: [{ type: "google_search", search_types: ["web_search", "image_search"] }],
    input: "Search for the history of the Colosseum and write a short illustrated story about a gladiator named Marcus. Interleave text and generated images.",
    response_format: [
        { type: "text" },
        { type: "image" }
    ],
    stream: true,
});

for await (const event of stream) {
    if (event.event_type === "step.delta") {
        if (event.delta.type === "text") {
            process.stdout.write(event.delta.text);
        } else if (event.delta.type === "image") {
            if (event.delta?.data) { console.log(`\n[Image chunk: ${event.delta.data.length} bytes]`); }
        }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.GoogleSearchSearchType;
import com.google.genai.gaos.models.interactions.ImageDelta;
import com.google.genai.gaos.models.interactions.ImageResponseFormat;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.utils.EventStream;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.1-flash-image"))
        .tools(
            Arrays.asList(
                GoogleSearch.builder()
                    .searchTypes(
                        Arrays.asList(
                            GoogleSearchSearchType.of("web_search"),
                            GoogleSearchSearchType.of("image_search")))
                    .build()))
        .input(
            InteractionsInput.of(
                "Search for the history of the Colosseum and write a short illustrated story about a gladiator named Marcus. Interleave text and generated images."))
        .responseFormat(
            CreateModelInteractionResponseFormat.of(
                Arrays.asList(
                    ResponseFormat.of(TextResponseFormat.builder().build()),
                    ResponseFormat.of(ImageResponseFormat.builder().build()))))
        .stream(true)
        .build();

CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));

try (EventStream<InteractionSSEStreamEvent> stream = response.events()) {
  for (InteractionSSEStreamEvent streamEvent : stream) {
    InteractionSSEEvent event = streamEvent.data().orElse(null);
    if (event instanceof StepDelta stepDelta) {
      StepDeltaData delta = stepDelta.delta().orElse(null);
      if (delta instanceof TextDelta textDelta) {
        textDelta.text().ifPresent(System.out::print);
      } else if (delta instanceof ImageDelta imageDelta) {
        imageDelta
            .data()
            .ifPresent(data -> System.out.printf("%n[Image chunk: %d bytes]", data.length()));
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    var interactionID string
    var lastEventID *string

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:  interactions.Model("gemini-3.8-pro"),
            Input:  interactions.NewInteractionsInput("Write a detailed 5-section guide to distributed consensus algorithms."),
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if created := event.GetDataInteractionCreated(); created != nil {
            interactionID = created.Interaction.ID
            if created.EventID != nil {
                lastEventID = created.EventID
            }
        }
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if stepDelta.EventID != nil {
                lastEventID = stepDelta.EventID
            }
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
    }

    if err := stream.Err(); err != nil {
        fmt.Printf("\nStream interrupted (%v). Resuming...\n", err)
        if interactionID != "" && lastEventID != nil {
            resumedRes, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
                ID:          interactionID,
                Stream:      genai.Ptr(true),
                LastEventID: lastEventID,
            })
            if err != nil {
                log.Fatal(err)
            }
            resumedStream := resumedRes.InteractionSSEStreamEvent
            defer resumedStream.Close()

            for resumedStream.Next() {
                event := resumedStream.Value()
                if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
                    if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                        fmt.Print(textDelta.GetText())
                    }
                }
            }
            if err := resumedStream.Err(); err != nil {
                log.Fatal(err)
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-3.1-flash-image",
    "input": "Search for the history of the Colosseum and write a short illustrated story about a gladiator named Marcus. Interleave text and generated images.",
    "stream": true,
    "tools": [
      { "type": "google_search",
        "search_types": ["web_search", "image_search"]
      }
    ],
    "generation_config": {
      "thinking_summaries": "auto"
    },
    "response_format": [
      { "type": "text" }, { "type": "image"}
    ]
  }'
```
{% /tab %}
{% /tabs %}

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

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

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

event: step.delta
data: {"index":0,"delta":{"text":"Here is a short illustrated story about the Colosseum...\n\n### Part 1: The New Flavian Amphitheater\n\n...","type":"text"},"event_type":"step.delta"}

...

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

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

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

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

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

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

event: step.delta
data: {"index":2,"delta":{"text":"### Part 2: The Hypogeum and the Wait\n\n...","type":"text"},"event_type":"step.delta"}

...

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

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

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

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

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

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

event: step.delta
data: {"index":4,"delta":{"text":"### Part 3: The Moment of Spectacle\n\n...","type":"text"},"event_type":"step.delta"}

...

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

event: interaction.completed
data: {"interaction":{"id":"v1_...","status":"completed","usage":{"total_tokens":6128,"total_input_tokens":29,"total_output_tokens":6099,"output_tokens_by_modality":[{"modality":"image","tokens":4480}]}},"event_type":"interaction.completed"}

event: done
data: [DONE]
```

## Handling unknown events {% id="handling-unknown-events" %}

In accordance with the API's versioning policy, new event types and delta types may be added over time. Your code should handle unknown event types gracefully—log and skip any events you don't recognize rather than throwing an error.

## What's next {% id="whats-next" %}

*   Learn more about the [Interactions API](/docs/interactions-overview).
*   Explore [Function calling](/docs/function-calling) with tools.
*   Learn about [Thinking](/docs/thinking) for enhanced reasoning.
*   Try the [Deep Research agent](/docs/deep-research) for long-running tasks.
*   See the [Interactions API reference](https://ai.google.dev/api/interactions-api) for all event types and delta types.

# Background execution
Source: https://aistudio.google.com/docs/background-execution
Description: Run long-running background tasks and agents using background=true in the Interactions API.

For long-running tasks like deep research, complex reasoning, or multi-step agent executions, connection timeouts can interrupt standard HTTP requests (which typically close after 60 seconds). The [Interactions API](/docs/interactions-overview) provides **background execution** to run these tasks asynchronously.

To let the interaction run until it completes the task on the server, set `"background": true` when creating the interaction. The API immediately returns an interaction ID, which client applications can use to poll for status, stream progress, or reconnect to a disconnected stream.

Background execution is supported for standard Gemini models (such as `gemini-4-argon` and `gemini-3.8-flash`) and Managed Agents (such as `antigravity-preview-09-2026`).

## Create a background interaction {% id="create-a-background-interaction" %}

To start a background interaction, set the `background` parameter to `true` when creating the resource.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Write a guide on space exploration.",
    background=True,
)
print(f"Created background interaction ID: {interaction.id}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Write a guide on space exploration.",
    background: true,
});
console.log(`Created background interaction ID: ${interaction.id}`);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-3.8-flash")
        .input(InteractionsInput.of("Write a guide on space exploration."))
        .background(true)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Created background interaction ID: " + interaction.id().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:      interactions.Model("gemini-3.8-flash"),
            Input:      interactions.NewInteractionsInput("Write a guide on space exploration."),
            Background: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.ID != nil {
        fmt.Printf("Created background interaction ID: %s\n", *res.Interaction.ID)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Write a guide on space exploration.",
    "background": true
  }'
```
{% /tab %}
{% /tabs %}

## How background execution works {% id="how-background-execution-works" %}

When you create a background interaction, the task runs asynchronously on the server. The interaction transitions through various execution states:

*   `in_progress`: The server is actively executing the interaction (such as running code or researching).
*   `requires_action`: The interaction has paused and is waiting for client input (such as confirming a tool execution or answering a question).
*   `completed`: The interaction finished successfully and the output is available.
*   `failed`: An error occurred during execution (such as tool failure or rate limits).
*   `cancelled`: A client request stopped the execution.

{% callout type="note" %}
For the complete list of interaction states, see the [Interactions API Reference](https://ai.google.dev/api/interactions-api#Resource:Interaction).
{% /callout %}

### Use cases {% id="use-cases" %}

Use background execution for:

*   **Agent executions:** Tasks requiring code execution, web browsing, or sub-agent orchestration (such as `antigravity-preview-09-2026`).
*   **Deep research:** Runs using `deep-research-preview-04-2026` or `deep-research-max-preview-04-2026` which take several minutes.
*   **Long reasoning:** Tasks where extended model thinking steps exceed standard HTTP connection limits.
*   **Long decode (Gemini 4):** Tasks that generate extended completions beyond `65,536` tokens. On `gemini-4-argon`, you can set `max_output_tokens` up to `1,048,576` tokens using [long decode](/docs/long-decode).

{% callout type="note" %}
When `background=False` (default), a single foreground hop is capped at 65,536 output tokens for streaming and 32,768 output tokens for non-streaming. To generate beyond 65,536 tokens with `background=False`, use [client-side continuation](/docs/long-decode#client-side-continuation).
{% /callout %}

### Data retention for background execution {% id="data-retention" %}

Background execution (`background=True`) requires `store=True` (the default) so the server can store the interaction while you poll or stream results. Passing `background=True` with `store=False` returns a `400` error.

Stored background interactions follow the standard [Interactions API data storage and retention](/docs/interactions-overview#data-storage-retention) policy:

*   **Paid tier:** Retained for **55 days** (configurable to 7, 14, 28, or 55 days in [Google AI Studio](https://aistudio.google.com/logs)).
*   **Free tier:** Retained for **1 day**.

To remove a background interaction earlier, [delete the interaction](/docs/background-execution#cancellation-and-deletion) after retrieving the result.

## Retrieve results {% id="retrieve-results" %}

Obtain background interaction results using either **polling** or **streaming**.

### Polling pattern (non-blocking) {% id="polling-pattern-non-blocking" %}

Polling checks the interaction status periodically using non-blocking GET requests until it reaches a terminal state.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

interaction = client.interactions.get(id="YOUR_INTERACTION_ID")

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

if interaction.status == "completed":
    print(interaction.output_text)
else:
    print(f"Finished with status: {interaction.status}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

let interaction = await client.interactions.get("YOUR_INTERACTION_ID");

while (interaction.status === "in_progress") {
    await new Promise(resolve => setTimeout(resolve, 5000));
    interaction = await client.interactions.get(interaction.id);
}

if (interaction.status === "completed") {
    console.log(interaction.output_text);
} else {
    console.log(`Finished with status: ${interaction.status}`);
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;

Client client = new Client();

Interaction interaction =
    client.interactions
        .get(GetInteractionByIdRequest.builder().id("YOUR_INTERACTION_ID").build())
        .interaction()
        .get();

while (InteractionStatus.IN_PROGRESS.equals(interaction.status().orElse(null))) {
  Thread.sleep(5000);
  interaction =
      client.interactions
          .get(GetInteractionByIdRequest.builder().id(interaction.id().get()).build())
          .interaction()
          .get();
}

if (InteractionStatus.COMPLETED.equals(interaction.status().orElse(null))) {
  System.out.println(interaction.outputText().orElse(""));
} else {
  System.out.println(
      "Finished with status: " + interaction.status().map(InteractionStatus::value).orElse(""));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
        ID: "YOUR_INTERACTION_ID",
    })
    if err != nil {
        log.Fatal(err)
    }
    interaction := res.Interaction

    for interaction.Status == interactions.InteractionStatusInProgress {
        time.Sleep(5 * time.Second)
        res, err = client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        interaction = res.Interaction
    }

    if interaction.Status == interactions.InteractionStatusCompleted {
        if interaction.OutputText != nil {
            fmt.Println(*interaction.OutputText)
        }
    } else {
        fmt.Printf("Finished with status: %s\n", interaction.Status)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20"
```
{% /tab %}
{% /tabs %}

### Streaming pattern {% id="streaming-pattern" %}

If a network interruption disconnects a stream, streaming can resume from the last received event. Each delta contains a unique `event_id` in its payload. Passing this ID as `last_event_id` resumes the stream from that event.

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()
interaction_id = "YOUR_INTERACTION_ID"

def stream_with_reconnect(interaction_id: str):
    last_event_id = None
    while True:
        try:
            # Retrieve the stream. If resuming, pass last_event_id
            stream = client.interactions.get(
                id=interaction_id,
                stream=True,
                last_event_id=last_event_id
            )

            for event in stream:
                # Log event updates and capture event_id if present
                if event.event_id:
                    last_event_id = event.event_id

                if event.event_type == "step.delta" and event.delta.type == "text":
                    print(event.delta.text, end="", flush=True)

                if event.event_type == "interaction.completed":
                    return

        except Exception as e:
            print(f"\n[Connection lost: {e}. Reconnecting in 3s...]")
            time.sleep(3)

stream_with_reconnect(interaction_id)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const interactionId = "YOUR_INTERACTION_ID";

async function streamWithReconnect(id = interactionId) {
    let lastEventId = "";
    while (true) {
        try {
            // Retrieve the stream. If resuming, pass last_event_id in options
            const eventStream = await client.interactions.get(id, {
                stream: true,
                last_event_id: lastEventId
            });

            for await (const event of eventStream) {
                if (event.event_id) {
                    lastEventId = event.event_id;
                }

                if (event.event_type === "step.delta" && event.delta?.type === "text") {
                    process.stdout.write(event.delta.text);
                }

                if (event.event_type === "interaction.completed") {
                    return;
                }
            }
        } catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            console.log(`\n[Connection lost: ${message}. Reconnecting in 3s...]`);
            await new Promise(resolve => setTimeout(resolve, 3000));
        }
    }
}

await streamWithReconnect(interactionId);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.InteractionCompletedEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import com.google.genai.gaos.utils.EventStream;

Client client = new Client();
String interactionId = "YOUR_INTERACTION_ID";
String lastEventId = null;
boolean completed = false;

while (!completed) {
  try (EventStream<InteractionSSEStreamEvent> stream =
      client.interactions
          .get(
              GetInteractionByIdRequest.builder()
                  .id(interactionId)
                  .stream(true)
                  .lastEventId(lastEventId)
                  .build())
          .events()) {
    for (InteractionSSEStreamEvent streamEvent : stream) {
      InteractionSSEEvent event = streamEvent.data().orElse(null);
      if (event instanceof StepDelta) {
        StepDelta stepDelta = (StepDelta) event;
        if (stepDelta.eventId().isPresent()) {
          lastEventId = stepDelta.eventId().get();
        }
        if (stepDelta.delta().isPresent() && stepDelta.delta().get() instanceof TextDelta) {
          System.out.print(((TextDelta) stepDelta.delta().get()).text().orElse(""));
          System.out.flush();
        }
      } else if (event instanceof InteractionCompletedEvent) {
        completed = true;
        break;
      }
    }
  } catch (Exception e) {
    System.out.println("\n[Connection lost: " + e.getMessage() + ". Reconnecting in 3s...]");
    Thread.sleep(3000);
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    interactionID := "YOUR_INTERACTION_ID"
    var lastEventID *string
    completed := false

    for !completed {
        res, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID:          interactionID,
            Stream:      genai.Ptr(true),
            LastEventID: lastEventID,
        })
        if err != nil {
            fmt.Printf("\n[Connection lost: %v. Reconnecting in 3s...]\n", err)
            time.Sleep(3 * time.Second)
            continue
        }

        stream := res.InteractionSSEStreamEvent
        for stream.Next() {
            event := stream.Value()
            if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
                if stepDelta.EventID != nil {
                    lastEventID = stepDelta.EventID
                }
                if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                    fmt.Print(textDelta.GetText())
                }
            } else if event.GetDataInteractionCompleted() != nil {
                completed = true
                break
            }
        }
        if err := stream.Err(); err != nil {
            fmt.Printf("\n[Stream error: %v. Reconnecting in 3s...]\n", err)
            _ = stream.Close()
            time.Sleep(3 * time.Second)
            continue
        }
        _ = stream.Close()
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -N -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID?stream=true&last_event_id=YOUR_LAST_EVENT_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20"
```
{% /tab %}
{% /tabs %}

## Multi-turn conversations {% id="multi-turn-conversations" %}

Subsequent interactions can chain to a background conversation using `previous_interaction_id`, subject to these constraints:

1.  **Active executions are blocked:** Chaining a subsequent interaction to one with `in_progress` status returns a `400 Bad Request` error. Wait for the interaction to reach the `completed` state before starting the next one.
2.  **Environment Parameter for Managed Agents:** When chaining interactions for Managed Agents (such as `antigravity-preview-09-2026`), requests must include both `previous_interaction_id` and `environment`.

The following examples show how to chain interactions:

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()
agent_model = "antigravity-preview-09-2026"

# First interaction: Provision sandbox environment and execute first instruction
interaction1 = client.interactions.create(
    agent=agent_model,
    input="Create a folder named project/ and write hello.py inside.",
    environment="remote",
    background=True
)

# Wait for completion
while True:
    check = client.interactions.get(id=interaction1.id)
    if check.status != "in_progress":
        break
    time.sleep(2)

# Second interaction: Chain using previous_interaction_id and environment
interaction2 = client.interactions.create(
    agent=agent_model,
    input="List all files in the project/ directory.",
    previous_interaction_id=interaction1.id,
    environment="remote",
    background=True
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const agentModel = "antigravity-preview-09-2026";

// First interaction: Provision sandbox environment and execute first instruction
const interaction1 = await client.interactions.create({
    agent: agentModel,
    input: "Create a folder named project/ and write hello.py inside.",
    environment: "remote",
    background: true
});

// Wait for completion
while (true) {
    const check = await client.interactions.get(interaction1.id);
    if (check.status !== "in_progress") {
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 2000));
}

// Second interaction: Chain using previous_interaction_id and environment
const interaction2 = await client.interactions.create({
    agent: agentModel,
    input: "List all files in the project/ directory.",
    previous_interaction_id: interaction1.id,
    environment: "remote",
    background: true
});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;

Client client = new Client();
String agentModel = "antigravity-preview-09-2026";

// First interaction: Provision sandbox environment and execute first instruction
CreateModelInteraction params1 =
    CreateModelInteraction.builder()
        .model(agentModel)
        .input(InteractionsInput.of("Create a folder named project/ and write hello.py inside."))
        .environment(CreateModelInteractionEnvironment.of("remote"))
        .background(true)
        .build();

Interaction interaction1 =
    client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();

// Wait for completion
while (true) {
  Interaction check =
      client.interactions
          .get(GetInteractionByIdRequest.builder().id(interaction1.id().get()).build())
          .interaction()
          .get();
  if (!InteractionStatus.IN_PROGRESS.equals(check.status().orElse(null))) {
    break;
  }
  Thread.sleep(2000);
}

// Second interaction: Chain using previousInteractionId and environment
CreateModelInteraction params2 =
    CreateModelInteraction.builder()
        .model(agentModel)
        .input(InteractionsInput.of("List all files in the project/ directory."))
        .previousInteractionId(interaction1.id().get())
        .environment(CreateModelInteractionEnvironment.of("remote"))
        .background(true)
        .build();

Interaction interaction2 =
    client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    agentModel := interactions.Model("antigravity-preview-09-2026")
    remoteEnv := interactions.NewCreateModelInteractionEnvironment("remote")

    // First interaction: Provision sandbox environment and execute first instruction
    res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:       agentModel,
            Input:       interactions.NewInteractionsInput("Create a folder named project/ and write hello.py inside."),
            Environment: &remoteEnv,
            Background:  genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Wait for completion
    for {
        check, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
            ID: *res1.Interaction.ID,
        })
        if err != nil {
            log.Fatal(err)
        }
        if check.Interaction.Status != interactions.InteractionStatusInProgress {
            break
        }
        time.Sleep(2 * time.Second)
    }

    // Second interaction: Chain using PreviousInteractionID and Environment
    _, err = client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 agentModel,
            Input:                 interactions.NewInteractionsInput("List all files in the project/ directory."),
            PreviousInteractionID: res1.Interaction.ID,
            Environment:           &remoteEnv,
            Background:            genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# Chain second interaction (Make sure FIRST_INTERACTION_ID has status 'completed')
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "agent": "antigravity-preview-09-2026",
    "input": "List all files in the project/ directory.",
    "previous_interaction_id": "FIRST_INTERACTION_ID",
    "environment": "remote",
    "background": true
  }'
```
{% /tab %}
{% /tabs %}

## Cancellation and deletion {% id="cancellation-and-deletion" %}

Control running executions and manage storage using cancel and delete requests:

*   **Cancel (`POST /interactions/{id}/cancel`):** Stops the running task. The status transitions to `cancelled`. Clean-up actions on the server can cause a slight delay before the status updates in GET requests.
*   **Delete (`DELETE /interactions/{id}`):** Removes the interaction records from the server. Subsequent GET requests return a `404 Not Found` error.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

# Cancel a running interaction
client.interactions.cancel(id="YOUR_INTERACTION_ID")

# Delete the interaction record entirely
client.interactions.delete(id="YOUR_INTERACTION_ID")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

// Cancel a running interaction
await client.interactions.cancel("YOUR_INTERACTION_ID");

// Delete the interaction record entirely
await client.interactions.delete("YOUR_INTERACTION_ID");
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;

Client client = new Client();

// Cancel a running interaction
client.interactions.cancel("YOUR_INTERACTION_ID");

// Delete the interaction record entirely
client.interactions.delete("YOUR_INTERACTION_ID");
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Cancel a running interaction
    _, err = client.Interactions.Cancel(ctx, operations.CancelInteractionByIDRequest{
        ID: "YOUR_INTERACTION_ID",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Delete the interaction record entirely
    _, err = client.Interactions.Delete(ctx, operations.DeleteInteractionRequest{
        ID: "YOUR_INTERACTION_ID",
    })
    if err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# Cancel the interaction
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID/cancel" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20"

# Delete the interaction
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/interactions/YOUR_INTERACTION_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20"
```
{% /tab %}
{% /tabs %}

## Next steps {% id="next-steps" %}

*   Read the [Interactions API overview](/docs/interactions-overview) to understand session and state management.
*   See the [Streaming interactions](/docs/streaming) guide for details on real-time event updates.
*   Explore the [Managed agents quickstart](/docs/managed-agents-quickstart) to build stateful multi-turn agents.

# File input methods
Source: https://aistudio.google.com/docs/file-input-methods
Description: Get started building with Gemini's multimodal capabilities in the Gemini API

This guide explains the different ways you can include media files such as
images, audio, video, and documents when making requests to the Gemini API.
The new methods are supported in all of the Gemini API endpoints, including
Batch, Interactions and Live API.
Choosing the right method depends on the size of your file, where your data is
stored, and how frequently you plan to use the file.

The simplest way to include a file as your input is to read a local file and
include it in a prompt. The following example shows how to read a local PDF
file. PDFs are limited to 50MB for this method. See the
[Input method comparison table](/docs/file-input-methods#method-comparison) for a complete list of file
input types and limits.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import pathlib
import base64

client = genai.Client()

filepath = pathlib.Path('my_local_file.pdf')

prompt = "Summarize this document"
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": prompt},
        {"type": "document", "data": base64.b64encode(filepath.read_bytes()).decode('utf-8'), "mime_type": "application/pdf"}
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from 'node:fs';

const client = new GoogleGenAI({});
const prompt = "Summarize this document";

async function main() {
    const filePath = 'my_local_file.pdf';

    const interaction = await client.interactions.create({
        model: "gemini-3.8-flash",
        input: [
            { type: "text", text: prompt },
            {
                type: "document",
                data: fs.readFileSync(filePath).toString("base64"),
                mime_type: "application/pdf"
            }
        ]
    });
    console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] pdfBytes = Files.readAllBytes(Paths.get("my_local_file.pdf"));
String base64Pdf = Base64.getEncoder().encodeToString(pdfBytes);

String prompt = "Summarize this document";

Content textContent = TextContent.builder().text(prompt).build();
Content docContent =
    DocumentContent.builder()
        .data(base64Pdf)
        .mimeType(DocumentContentMimeType.APPLICATION_PDF)
        .build();

List<Content> contents = Arrays.asList(textContent, docContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    pdfBytes, err := os.ReadFile("my_local_file.pdf")
    if err != nil {
        log.Fatal(err)
    }
    base64Pdf := base64.StdEncoding.EncodeToString(pdfBytes)

    prompt := "Summarize this document"

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
                interactions.NewContent(interactions.DocumentContent{
                    Data:     genai.Ptr(base64Pdf),
                    MimeType: interactions.DocumentContentMimeTypeApplicationPdf.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# Encode the local file to base64
B64_CONTENT=$(base64 -w 0 my_local_file.pdf)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Summarize this document"},
      {
        "type": "document",
        "data": "'${B64_CONTENT}'",
        "mime_type": "application/pdf"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

## Input method comparison {% id="method-comparison" %}

The following table compares each input method with file limits and best use
cases. Note that the file size limit may vary depending on the file type and
model or tokenizer used to process the file.

{% table %}
* Method
* Best for
* Max file size
* Persistence
---

* **Inline data**
* Quick testing, small files, real-time applications.
* 100 MB per request or payload
     (**50 MB for PDFs**)

* None (sent with every request)
---

* **File API upload**
* Large files, files used multiple times.
* 2 GB per file,
     up to 20GB per project

* 48 Hours
---

* **File API GCS URI registration**
* Large files already in Google Cloud Storage, files used multiple times.
* 2 GB per file, no overall storage limits
* None (fetched per request). One time registration can give access for up to 30 days.
---

* **External URLs**
* Public data or data in cloud buckets (AWS, Azure, GCS) without re-uploading.
* 15 MB per file
* None (fetched per request)
{% /table %}

## Inline data {% id="inline-data" %}

For smaller files (under 100MB, or 50MB for PDFs), you can pass the data
directly in the request payload. This is the simplest method for quick tests or
applications handling real-time, transient data. You can provide data as
base64 encoded strings or by reading local files directly.

For an example of reading from a local file, see the example at the beginning of
this page.

### Fetch from a URL {% id="fetch-from-a-url" %}

You can also fetch a file from a URL, convert it to bytes, and include it in the
input.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import httpx

client = genai.Client()

doc_url = "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
doc_data = httpx.get(doc_url).content

prompt = "Summarize this document"

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "document", "data": base64.b64encode(doc_data).decode('utf-8'), "mime_type": "application/pdf"},
        {"type": "text", "text": prompt}
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const docUrl = 'https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf';
const prompt = "Summarize this document";

async function main() {
    const pdfResp = await fetch(docUrl)
      .then((response) => response.arrayBuffer());

    const interaction = await client.interactions.create({
        model: "gemini-3.8-flash",
        input: [
            { type: "text", text: prompt },
            {
                type: "document",
                data: Buffer.from(pdfResp).toString("base64"),
                mime_type: "application/pdf"
            }
        ]
    });
    console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

String docUrl = "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf";
HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder().uri(URI.create(docUrl)).build();
byte[] docData = httpClient.send(request, HttpResponse.BodyHandlers.ofByteArray()).body();
String base64Pdf = Base64.getEncoder().encodeToString(docData);

String prompt = "Summarize this document";

Content docContent =
    DocumentContent.builder()
        .data(base64Pdf)
        .mimeType(DocumentContentMimeType.APPLICATION_PDF)
        .build();
Content textContent = TextContent.builder().text(prompt).build();

List<Content> contents = Arrays.asList(docContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "io"
    "log"
    "net/http"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    docURL := "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
    resp, err := http.Get(docURL)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    docData, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    base64Pdf := base64.StdEncoding.EncodeToString(docData)

    prompt := "Summarize this document"

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    Data:     genai.Ptr(base64Pdf),
                    MimeType: interactions.DocumentContentMimeTypeApplicationPdf.ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
  DOC_URL="https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
  PROMPT="Summarize this document"
  DISPLAY_NAME="base64_pdf"

  # Download the PDF
  wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"

  # Check for FreeBSD base64 and set flags accordingly
  if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
    B64FLAGS="--input"
  else
    B64FLAGS="-w0"
  fi

  # Base64 encode the PDF
  ENCODED_PDF=$(base64 $B64FLAGS "${DISPLAY_NAME}.pdf")

  # Create JSON payload file
  cat <payload.json
{
  "model": "gemini-3.8-flash",
  "input": [
    {"type": "document", "data": "${ENCODED_PDF}", "mime_type": "application/pdf"},
    {"type": "text", "text": "${PROMPT}"}
  ]
}
EOF

    # Generate content using interactions
    curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
        -H "x-goog-api-key: $GEMINI_API_KEY" \
        -H 'Content-Type: application/json' \
        -H "Api-Revision: 2026-05-20" \
        -d @payload.json 2> /dev/null > response.json

    cat response.json
    echo

    jq ".outputs[] | select(.type == \"text\") | .text" response.json
```
{% /tab %}
{% /tabs %}

## Gemini File API {% id="file-api" %}

The File API is designed for larger files (up to 2GB) or files you intend to
use in multiple requests.

### Standard file upload {% id="standard-file-upload" %}

Upload a local file to the Gemini API. Files uploaded this way are stored
temporarily (48 hours) and processed for efficient retrieval by the model.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

doc_file = client.files.upload(file="path/to/your/sample.pdf")
prompt = "Summarize this document"

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": prompt},
        {"type": "document", "uri": doc_file.uri, "mime_type": doc_file.mime_type}
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const prompt = "Summarize this document";

async function main() {
  const filePath = "path/to/your/sample.pdf";

  const myfile = await client.files.upload({
    file: filePath,
    config: { mimeType: "application/pdf" },
  });

  const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
        { type: "text", text: prompt },
        { type: "document", uri: myfile.uri, mime_type: myfile.mimeType }
    ]
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File docFile =
    client.files.upload(
        new java.io.File("path/to/your/sample.pdf"),
        UploadFileConfig.builder().mimeType("application/pdf").build());

String prompt = "Summarize this document";

Content textContent = TextContent.builder().text(prompt).build();
Content docContent =
    DocumentContent.builder()
        .uri(docFile.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(docFile.mimeType().orElse("application/pdf")))
        .build();

List<Content> contents = Arrays.asList(textContent, docContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    docFile, err := client.Files.UploadFromPath(ctx, "path/to/your/sample.pdf", &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Summarize this document"

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(docFile.URI),
                    MimeType: interactions.DocumentContentMimeType(docFile.MIMEType).ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
FILE_PATH="path/to/sample.pdf"
MIME_TYPE=$(file -b --mime-type "${FILE_PATH}")
NUM_BYTES=$(wc -c < "${FILE_PATH}")
DISPLAY_NAME=DOCUMENT

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -D "${tmp_header_file}" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${FILE_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)

# Now use in an interaction
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Summarize this document"},
        {"type": "document", "uri": '$file_uri', "mime_type": "'${MIME_TYPE}'"}
      ]
    }'
```
{% /tab %}
{% /tabs %}

### Register Google Cloud Storage files {% id="registration" %}

If your data is already in Google Cloud Storage, you don't need to
download and re-upload it. You can register it directly with the File API.

1. Grant **Service Agent** access to each bucket

  1. Enable the Gemini API in your Google Cloud project.

  1. Create the Service Agent:

`gcloud beta services identity create --service=generativelanguage.googleapis.com --project=<your_project>`
  1. **Grant the Gemini API Service Agent permissions** to read your storage
     buckets.

     The user needs to assign the `Storage Object Viewer`
     [IAM role](https://docs.cloud.google.com/storage/docs/access-control/iam-roles#storage.objectViewer)
     to this service agent on the specific storage buckets they intend to use.

  This access doesn't expire by default, but can be changed at any time. You can
  also use the
  [Google Cloud Storage IAM SDK](https://cloud.google.com/iam/docs/write-policy-client-libraries)
  commands to grant permissions.

1. Authenticate your service

   **Prerequisites**

   * Enable API
   * Create a service account or agent with appropriate permissions.

  You first need to authenticate as the service that has storage object viewer
  permissions. How this happens depends on the environment in which your file
  management code will be running.

  **Outside of Google Cloud**

  If your code is running from outside of Google Cloud, such as your desktop,
  download the account credentials from the Google Cloud Console with the
  following steps:

  1. Browse to the [Service Account console](https://console.cloud.google.com/iam-admin/serviceaccounts)
  1. Select the relevant service account
  1. Select the **Keys** tab and choose **Add key, Create new key**
  1. Choose the **JSON** key type, and note where the file was downloaded to on
     your machine.

  For more details, see the official Google Cloud documentation on
  [service account key management](https://docs.cloud.google.com/iam/docs/keys-create-delete).

  Then use the following commands to authenticate. These commands assume your
  service account file is in the current directory, named
  `service-account.json`.

{% tabs %}
{% tab label="Python" %}
```python
from google.oauth2.service_account import Credentials

GCS_READ_SCOPES = [
  'https://www.googleapis.com/auth/devstorage.read_only',
  'https://www.googleapis.com/auth/cloud-platform'
]

SERVICE_ACCOUNT_FILE = 'service-account.json'

credentials = Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE,
    scopes=GCS_READ_SCOPES
)
```
{% /tab %}
{% tab label="Javascript" %}
```javascript
const { GoogleAuth } = require('google-auth-library');

const GCS_READ_SCOPES = [
  'https://www.googleapis.com/auth/devstorage.read_only',
  'https://www.googleapis.com/auth/cloud-platform'
];

const SERVICE_ACCOUNT_FILE = 'service-account.json';

const auth = new GoogleAuth({
  keyFile: SERVICE_ACCOUNT_FILE,
  scopes: GCS_READ_SCOPES
});
```
{% /tab %}
{% tab label="CLI" %}
```bash
gcloud auth application-default login \
  --client-id-file=service-account.json \
  --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only'
```

**On Google Cloud**

If you are running directly in Google Cloud, for example by using [Cloud
Run functions](https://cloud.google.com/functions) or a
[Compute Engine instance](https://cloud.google.com/products/compute), you will
have implicit credentials but will need to re-authenticate to grant the
appropriate scopes.
{% /tab %}
{% tab label="Python" %}
This code expects that the service is running in an environment where
    [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials)
    can be obtained automatically, such as Cloud Run or Compute Engine.

    ```python
import google.auth

GCS_READ_SCOPES = [
  'https://www.googleapis.com/auth/devstorage.read_only',
  'https://www.googleapis.com/auth/cloud-platform'
]

credentials, project = google.auth.default(scopes=GCS_READ_SCOPES)
    ```
{% /tab %}
{% tab label="JavaScript" %}
This code expects that the service is running in an environment where
    [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials)
    can be obtained automatically, such as Cloud Run or Compute Engine.

    ```javascript
const { GoogleAuth } = require('google-auth-library');

const auth = new GoogleAuth({
  scopes: [
    'https://www.googleapis.com/auth/devstorage.read_only',
    'https://www.googleapis.com/auth/cloud-platform'
  ]
});
    ```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.auth.oauth2.GoogleCredentials;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.List;

List<String> gcsReadScopes =
    Arrays.asList(
        "https://www.googleapis.com/auth/devstorage.read_only",
        "https://www.googleapis.com/auth/cloud-platform");

String serviceAccountFile = "service-account.json";

GoogleCredentials credentials =
    GoogleCredentials.fromStream(new FileInputStream(serviceAccountFile))
        .createScoped(gcsReadScopes);
```
{% /tab %}

{% tab label="CLI" %}
This is an interactive command. For services like Compute Engine you can attach
scopes to the running service at the config level. See the
[user-managed service docs](https://docs.cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances#using)
for an example.

    ```bash
gcloud auth application-default login \
--scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only"
    ```
{% /tab %}
{% /tabs %}

1. File registration (Files API)

   Use the Files API to register files and produce a Files API path that can
   directly be used in the Gemini API.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client(credentials=credentials)

registered_gcs_files = client.files.register_files(
    uris=["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"]
)
prompt = "Summarize this file."

for f in registered_gcs_files.files:
  print(f.name)
  interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
      {"type": "text", "text": prompt},
      {"type": "document", "uri": f.uri, "mime_type": f.mime_type}
    ],
  )
  print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
    const registeredGcsFiles = await ai.files.registerFiles({
        uris: ["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"]
    });

    const prompt = "Summarize this file.";

    for (const file of registeredGcsFiles.files || []) {
        console.log(file.name);
        const interaction = await ai.interactions.create({
            model: "gemini-3.8-flash",
            input: [
                { type: "text", text: prompt },
                { type: "document", uri: file.uri, mime_type: file.mimeType }
            ]
        });

        console.log(interaction.output_text);
    }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.auth.oauth2.GoogleCredentials;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.RegisterFilesResponse;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

GoogleCredentials credentials =
    GoogleCredentials.fromStream(new FileInputStream("service-account.json"))
        .createScoped(
            Arrays.asList(
                "https://www.googleapis.com/auth/devstorage.read_only",
                "https://www.googleapis.com/auth/cloud-platform"));

Client client = Client.builder().credentials(credentials).build();

RegisterFilesResponse registeredGcsFiles =
    client.files.registerFiles(
        credentials,
        Arrays.asList("gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"),
        null);

String prompt = "Summarize this file.";

for (File f : registeredGcsFiles.files().orElse(Collections.emptyList())) {
  System.out.println(f.name().orElse(""));

  Content textContent = TextContent.builder().text(prompt).build();
  Content docContent =
      DocumentContent.builder()
          .uri(f.uri().orElse(""))
          .mimeType(DocumentContentMimeType.of(f.mimeType().orElse("application/pdf")))
          .build();

  CreateModelInteraction params =
      CreateModelInteraction.builder()
          .model(Model.of("gemini-3.8-flash"))
          .input(InteractionsInput.ofContent(Arrays.asList(textContent, docContent)))
          .build();

  Interaction interaction =
      client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
  System.out.println(interaction.outputText().orElse(""));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "log"

    "google.golang.org/genai"
)

func main() {
    cc := &genai.ClientConfig{}
    if err := cc.UseDefaultCredentials(); err != nil {
        log.Fatal(err)
    }
    _ = cc.Credentials
}
```
{% /tab %}

{% tab label="CLI" %}
```bash
access_token=$(gcloud auth application-default print-access-token)
project_id=$(gcloud config get-value project)
curl -X POST https://generativelanguage.googleapis.com/v1beta/files:register \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ${access_token}" \
    -H "x-goog-user-project: ${project_id}" \
    -d '{"uris": ["gs://bucket/object1", "gs://bucket/object2"]}'
```
{% /tab %}
{% /tabs %}

## External HTTP / Signed URLs {% id="external-urls" %}

You can pass publicly accessible HTTPS URLs or pre-signed URLs directly in your
request. The Gemini API will fetch the content securely during processing.
This is ideal for files that you don't want to re-upload. Each file can be up
to 15 MB. For larger files, use the
[File API](/docs/file-input-methods#file-api).

{% callout type="note" %}
Gemini 2.0 family of models are not supported
{% /callout %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf"
prompt = "Summarize this file"

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "document", "uri": uri, "mime_type": "application/pdf"},
        {"type": "text", "text": prompt}
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

String uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf";
String prompt = "Summarize this file";

Client client = new Client();

Content docContent =
    DocumentContent.builder()
        .uri(uri)
        .mimeType(DocumentContentMimeType.APPLICATION_PDF)
        .build();
Content textContent = TextContent.builder().text(prompt).build();

List<Content> contents = Arrays.asList(docContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    cc := &genai.ClientConfig{}
    if err := cc.UseDefaultCredentials(); err != nil {
        log.Fatal(err)
    }
    client, err := genai.NewClient(ctx, cc)
    if err != nil {
        log.Fatal(err)
    }

    registeredGcsFiles, err := client.Files.RegisterFiles(
        ctx,
        []string{"gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"},
        cc.Credentials,
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Summarize this file."

    for _, f := range registeredGcsFiles.Files {
        fmt.Println(f.Name)
        res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
            Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput([]interactions.Content{
                    interactions.NewContent(interactions.TextContent{
                        Text: prompt,
                    }),
                    interactions.NewContent(interactions.DocumentContent{
                        URI:      genai.Ptr(f.URI),
                        MimeType: interactions.DocumentContentMimeType(f.MIMEType).ToPointer(),
                    }),
                }),
            }),
        })
        if err != nil {
            log.Fatal(err)
        }
        if res.Interaction.OutputText != nil {
            fmt.Println(*res.Interaction.OutputText)
        }
    }
}
```
{% /tab %}

{% tab label="Javascript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf";

async function main() {
  const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: [
      { type: "document", uri: uri, mime_type: "application/pdf" },
      { type: "text", text: "summarize this file" }
    ]
  });

  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
      -H 'x-goog-api-key: $GEMINI_API_KEY' \
      -H 'Content-Type: application/json' \
      -H "Api-Revision: 2026-05-20" \
      -d '{
          "model": "gemini-3.8-flash",
          "input": [
            {"type": "text", "text": "Summarize this pdf"},
            {
              "type": "document",
              "uri": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf",
              "mime_type": "application/pdf"
            }
          ]
        }'
```
{% /tab %}
{% /tabs %}

### Accessibility {% id="accessibility" %}

Verify that the URLs you provide don't lead to pages that require a login or
are behind a paywall. For private databases, ensure you create a signed URL
with the correct access permissions and expiry.

### Safety checks {% id="safety-checks" %}

The system performs a content moderation check on the URL to confirm they meet
safety and policy standards. If the URL fails this check, you will get an
`url_retrieval_status` of `URL_RETRIEVAL_STATUS_UNSAFE`.

### Supported content types {% id="supported-content-types" %}

This list of supported file types and limitations is intended as initial
guidance and is not comprehensive. The effective
set of supported types is subject to change and can vary based on the specific
model and tokenizer version in use. Unsupported types will result in an error.
Additionally, content retrieval for these file types
only supports publicly accessible URLs.

#### Text file types {% id="text-file-types" %}

* `text/html`
* `text/css`
* `text/plain`
* `text/xml`
* `text/csv`
* `text/rtf`
* `text/javascript`

#### Application file types {% id="application-file-types" %}

* `application/json`
* `application/pdf`

#### Image file types {% id="image-file-types" %}

* `image/bmp`
* `image/jpeg`
* `image/png`
* `image/webp`

#### Video file types {% id="video-file-types" %}

* `video/mp4`
* `video/mpeg`
* `video/quicktime`
* `video/avi`
* `video/x-flv`
* `video/mpg`
* `video/webm`
* `video/wmv`
* `video/3gpp`

## Best practices {% id="best-practices" %}

* **Choose the right method:** Use inline data for small, transient files.
    Use the File API for larger or frequently used files. Use external URLs
    for data already hosted online.

* **Specify MIME Types:** Always provide the correct MIME type for the file
    data to ensure proper processing.

* **Handle Errors:** Implement error handling in your code to manage
    potential issues like network failures, file access problems, or API
    errors.

## Limitations {% id="limitations" %}

* File size limits vary by method (see [comparison table](/docs/file-input-methods#method-comparison))
    and file type.

* Inline data increases request payload size.
* File API uploads are temporary and expire after 48 hours.
* External URL fetching is limited to 15 MB per file and supports specific
    content types.

## What's next {% id="whats-next" %}

* Try writing your own multimodal prompts using
    [Google AI Studio](http://aistudio.google.com/).

* For information on including files in your prompts, see the
    [Vision](/docs/image-understanding),
    [Audio](/docs/audio), and
    [Document processing](/docs/document-processing)
    guides.

# Files API
Source: https://aistudio.google.com/docs/files
Description: Learn how to upload, manage, and process media files using the Gemini Interactions API.

Gemini can handle various types of input data, including text, images, and
audio, at the same time.

This guide shows you how to work with media files using the Files API. The
basic operations are the same for audio files, images, videos, documents, and
other supported file types.

For file prompting guidance, check out the [File prompt guide](/docs/files#prompt-guide) section.

## Upload a file {% id="upload-audio" %}

You can use the Files API to upload a media file. Always use the Files API when
the total request size (including the files, text prompt, system instructions,
etc.) is larger than 100&nbsp;MB. For PDF files, the limit is 50&nbsp;MB.

The following code uploads a file and then uses the file in a call to
`interactions.create`.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

myfile = client.files.upload(file="path/to/sample.mp3")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this audio clip"},
        {"type": "audio", "uri": myfile.uri, "mime_type": myfile.mime_type}
    ]
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const myfile = await client.files.upload({
    file: "path/to/sample.mp3",
    config: { mimeType: "audio/mpeg" },
  });

  const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "text", text: "Describe this audio clip" },
      { type: "audio", uri: myfile.uri, mime_type: myfile.mimeType }
    ]
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AudioContent;
import com.google.genai.gaos.models.interactions.AudioContentMimeType;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File myFile =
    client.files.upload(
        new java.io.File("path/to/sample.mp3"),
        UploadFileConfig.builder().mimeType("audio/mp3").build());

Content textContent = TextContent.builder().text("Describe this audio clip").build();
Content audioContent =
    AudioContent.builder()
        .uri(myFile.uri().orElse(""))
        .mimeType(AudioContentMimeType.of(myFile.mimeType().orElse("audio/mp3")))
        .build();

List<Content> contents = Arrays.asList(textContent, audioContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    myFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", &genai.UploadFileConfig{
        MIMEType: "audio/mp3",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Describe this audio clip",
                }),
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(myFile.URI),
                    MimeType: interactions.AudioContentMimeType(myFile.MIMEType).ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
AUDIO_PATH="path/to/sample.mp3"
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D "${tmp_header_file}" \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now create an interaction using the Interactions API
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Describe this audio clip"},
        {"type": "audio", "uri": '$file_uri', "mime_type": "'${MIME_TYPE}'"}
      ]
    }' 2> /dev/null > response.json

cat response.json
echo

jq ".outputs[] | select(.type == \"text\") | .text" response.json
```
{% /tab %}
{% /tabs %}

## Get metadata for a file {% id="get-metadata" %}

You can verify that the API successfully stored the uploaded file and get its
metadata by calling `files.get`.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

myfile = client.files.upload(file='path/to/sample.mp3')
file_name = myfile.name
myfile = client.files.get(name=file_name)
print(myfile)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {
  GoogleGenAI,
} from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const myfile = await client.files.upload({
    file: "path/to/sample.mp3",
    config: { mimeType: "audio/mpeg" },
  });

  const fileName = myfile.name;
  const fetchedFile = await client.files.get({ name: fileName || '' });
  console.log(fetchedFile);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;

Client client = new Client();

File myFile =
    client.files.upload(
        new java.io.File("path/to/sample.mp3"),
        UploadFileConfig.builder().mimeType("audio/mp3").build());

String fileName = myFile.name().orElse("");
File fileMetadata = client.files.get(fileName, null);
System.out.println(fileMetadata);
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    myFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", &genai.UploadFileConfig{
        MIMEType: "audio/mp3",
    })
    if err != nil {
        log.Fatal(err)
    }

    fileMetadata, err := client.Files.Get(ctx, myFile.Name, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(fileMetadata)
}
```
{% /tab %}

{% tab label="REST" %}
```shell
# file_info.json was created in the upload example
name=$(jq -r ".file.name" file_info.json)
# Get the file of interest to check state
curl https://generativelanguage.googleapis.com/v1beta/$name \
-H "x-goog-api-key: $GEMINI_API_KEY" > file_info.json
# Print some information about the file you got
name=$(jq -r ".name" file_info.json)
echo name=$name
file_uri=$(jq -r ".uri" file_info.json)
echo file_uri=$file_uri
```
{% /tab %}
{% /tabs %}

## List uploaded files {% id="list-uploaded" %}

The following code gets a list of all the files uploaded:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

print('My files:')
for f in client.files.list():
    print(' ', f.name)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {
  GoogleGenAI,
} from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const listResponse = await client.files.list({ config: { pageSize: 10 } });
  for await (const file of listResponse) {
    console.log(file.name);
  }
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.File;

Client client = new Client();

System.out.println("My files:");
for (File f : client.files.list(null)) {
  System.out.println("  " + f.name().orElse(""));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("My files:")
    for f, err := range client.Files.All(ctx) {
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println(" ", f.Name)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
echo "My files: "

curl "https://generativelanguage.googleapis.com/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## Delete uploaded files {% id="delete-uploaded" %}

Files are automatically deleted after 48 hours. You can also manually delete an
uploaded file:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

myfile = client.files.upload(file='path/to/sample.mp3')
client.files.delete(name=myfile.name)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {
  GoogleGenAI,
} from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const myfile = await client.files.upload({
    file: "path/to/sample.mp3",
    config: { mimeType: "audio/mpeg" },
  });

  const fileName = myfile.name;
  await client.files.delete({ name: fileName || '' });
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;

Client client = new Client();

File myFile =
    client.files.upload(
        new java.io.File("path/to/sample.mp3"),
        UploadFileConfig.builder().mimeType("audio/mp3").build());

client.files.delete(myFile.name().orElse(""), null);
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    myFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", &genai.UploadFileConfig{
        MIMEType: "audio/mp3",
    })
    if err != nil {
        log.Fatal(err)
    }

    if _, err := client.Files.Delete(ctx, myFile.Name, nil); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl --request "DELETE" https://generativelanguage.googleapis.com/v1beta/$name \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## Usage information {% id="usage-info" %}

You can use the Files API to upload and interact with media files. The Files API
lets you store up to 20&nbsp;GB of files per project, with a per-file maximum
size of 2&nbsp;GB. Files are stored for 48 hours.

During that time, you can use the API to get metadata about the files. However,
you can't download user-uploaded files. You can download files generated by
models, such as videos, using the `files.download` method. The Files API is
available at no cost in all regions where the Gemini API is available.

## File prompting strategies {% id="prompt-guide" %}

This section provides guidance and best practices for using media files with
prompts for the Gemini API.

Being able to use various types of data in your prompts gives you more
flexibility in terms of what tasks you can tackle with the Gemini API. For
example, you can send the model a photo of a delicious meal and ask it to write
a short blog about the meal.

{% table %}
* **Prompt**
* **Response**
---

* Write a short, engaging blog post based on this picture. It should
  include a description of the meal in the photo and talk about my journey
  meal prepping.

    ![Glass containers full of rice, bellpeppers, carrots and broccoli](/googledevai/static/gemini-api/docs/images/image_prompt.png)

* Meal prepping is a great way to save time and money, and it can also
  help you to eat healthier. This meal is a great example of a healthy
  and delicious meal that can be prepped ahead of time.
  This meal features brown rice, roasted vegetables, and chicken teriyaki.
  The brown rice is a healthy and complex carbohydrate that will give you
  sustained energy. The roasted vegetables are a great way to get your daily
  dose of vitamins and minerals, and the chicken teriyaki is a delicious and
  protein-rich option.
  This meal is also straightforward to prepare. Simply cook the brown rice,
  roast the vegetables, and cook the chicken teriyaki. Once everything is
  cooked, divide it into meal prep containers and store them in the
  refrigerator. You can then grab a container and go on busy mornings!
  If you're looking for a healthy and delicious meal that can be
  prepped ahead of time, this meal is a great option. It's packed with
  nutrients and flavor, and it's sure to keep you feeling full and satisfied.
  Here's to healthy and delicious meal prepping!
{% /table %}

If you are having trouble getting the output you want from prompts that use
media files, there are some strategies that can help you get the results you
want. The following sections provide design approaches and troubleshooting
tips for improving prompts that use multimodal input.

You can improve your multimodal prompts by following these best practices:

* **[Prompt design fundamentals](/docs/files#specific-instructions)**
    * **Be specific in your instructions**: Craft clear and concise instructions
      that leave minimal room for misinterpretation.
    * **Add a few examples to your prompt**: Use realistic few-shot examples to
      illustrate what you want to achieve.
    * **Break it down step-by-step**: Divide complex tasks into manageable
      sub-goals, guiding the model through the process.
    * **Specify the output format**: In your prompt, ask for the output to be in
      the format you want, like Markdown, JSON, HTML and more.
    * **Put your image first for single-image prompts**: While Gemini can handle
      image and text inputs in any order, for prompts containing a single image,
      it might perform better if that image is placed before the text prompt.
* **[Troubleshooting your multimodal prompt](/docs/files#troubleshooting)**
    * **If the model is not drawing information from the relevant part of the
      image**: Drop hints with which aspects of the image you want the prompt to
      draw information from.
    * **If the model output is too generic (not tailored enough to the image)**:
      At the start of the prompt, try asking the model to describe the image(s)
      before providing the task instruction, or try asking the model to refer to
      what's in the image.

### Be specific in your instructions {% id="specific-instructions" %}

Prompts have the most success when they are clear and detailed. If you have a
specific output in mind, it's better to include that requirement in the prompt
to ensure you get the output you want.

For this image of an airport board, asking the model to just "describe this
image" could generate a general description. If you need the model to parse the
time and city from the image, you can include that request directly in your
prompt.

{% table %}
* Prompt
* Model response
---

* ![A flight display board showing estimated times of arrival for multiple locations](/googledevai/static/gemini-api/docs/images/timetable.png)
* The image shows an airport arrivals and departures board.
{% /table %}

{% table %}
* **Updated prompt**
* **Improved response**
---

* ![A flight display board showing estimated times of arrival for multiple locations](/googledevai/static/gemini-api/docs/images/timetable.png)
  Parse the time and city from the airport board shown in this image into a
  list.
* 10:50 Moscow  \
  11:05 Edinburgh  \
  11:05 London  \
  11:10 Bucharest  \
  11:30 Kiev  \
  11:35 Dublin  \
  11:45 East Midlands  \
  12:15 Sofia  \
  12:30 London  \
  12:30 Newcastle  \
  12:40 St Petersburg  \
  12:40 London  \
  12:45 Manchester
{% /table %}

### Add a few examples {% id="add-a-few-examples" %}

The Gemini model can accept multiple inputs which it can use as examples to
understand the output you want. Adding these examples can help the model
identify the patterns and apply the relationship between the given images and
responses to the new example. This is also called "few-shot" learning.

In the following example, the initial output is written in sentence form,
and also contains the country (Brazil). Suppose you want the output in a
different format or style, and you want only the city, not the country. Adding
few-shot examples to your prompt can steer the model to respond in the way you
want.

{% table %}
* **Prompt**
* **Model response**
---

* ![Christ the Redeemer statue in Rio de Janeiro, Brazil](/googledevai/static/gemini-api/docs/images/redeemer.png)Determine the city along with the landmark.
* The landmark is the Christ the Redeemer statue in Rio de Janeiro, Brazil.
{% /table %}

{% table %}
* **Updated prompt**
* **Improved response**
---

* Determine the city along with the landmark.
    ![The Colosseum in Rome](/googledevai/static/gemini-api/docs/images/colosseum.png)

* city: Rome, landmark: the Colosseum.
---

* ![The Forbidden city in Beijing](/googledevai/static/gemini-api/docs/images/forbidden-city.png)
* city: Beijing, landmark: Forbidden City
---

* ![Christ the Redeemer statue in Rio de Janeiro, Brazil](/googledevai/static/gemini-api/docs/images/redeemer.png)
* city: Rio de Janeiro, landmark: Christ the Redeemer statue
{% /table %}

### Break it down step-by-step {% id="break-it-down-step-by-step" %}

For complex tasks like the ones that require both visual understanding and
reasoning, it can be helpful to split the task into smaller, more
straightforward steps. Alternatively, it could also be effective if you
directly ask the model to "think step by step" in your prompt.

{% table %}
* Prompt
* Model response
---

* ![Three rolls of toilet paper](/googledevai/static/gemini-api/docs/images/toilet-paper.jpg)
    When will I run out of toilet paper?

* Soon, you only have 3 rolls left.
{% /table %}

{% table %}
* **Updated prompt**
* **Improved response**
---

* ![Three rolls of toilet paper](/googledevai/static/gemini-api/docs/images/toilet-paper.jpg)
    First, count how many toilet paper rolls are in this picture.
    Then, determine how much toilet paper a typical person uses per day.
    Calculate how long these rolls of toilet paper will last.

* There are 3 rolls of toilet paper in this picture.
    A typical person uses about 20 sheets of toilet paper per day.
    If each roll contains 200 sheets, then each roll will last for about 10
    days. Therefore, the 3 rolls will last for about a month.
{% /table %}

Math problems or other types of word problems are great candidates for asking
the model to think step-by-step.

{% table %}
* **Prompt**
* **Response**
---

* ![A math equation describing a sequence of numbers](/googledevai/static/gemini-api/docs/images/math.jpg)
    What is the 4th term in the sequence?

* -135
{% /table %}

The response from the model is incorrect. Some ways to improve this is to ask
the model to parse the problem before answering the prompt.

{% table %}
* **Prompt**
* **Response**
---

* ![A math equation describing a sequence of numbers](/googledevai/static/gemini-api/docs/images/math.jpg)
    Parse the formula in the image first.
    Then based on the formula, answer "what's the 4th term in the sequence?".

* *Click to expand the result*
    $$ b(n) = b(n-1) * (-3) $$
    $$ b(1) = 15 $$
    Substitute n = 4 into the formula:
    $$ b(4) = b(4-1) * (-3) $$
    $$ b(4) = b(3) * (-3) $$
    We don't know the value of b(3), so substitute n = 3 into the formula:
    $$ b(3) = b(3-1) * (-3) $$
    $$ b(3) = b(2) * (-3) $$
    We don't know the value of b(2), so substitute n = 2 into the formula:
    $$ b(2) = b(2-1) * (-3) $$
    $$ b(2) = b(1) * (-3) $$
    We know the value of b(1) is 15, so substitute it into the formula:
    $$ b(2) = 15 * (-3) $$
    $$ b(2) = -45 $$
    Now that we know the value of b(2), substitute it into the formula for b(3):
    $$ b(3) = b(2) * (-3) $$
    $$ b(3) = -45 * (-3) $$
    $$ b(3) = 135 $$
    Now that we know the value of b(3), substitute it into the formula for b(4):
    $$ b(4) = b(3) * (-3) $$
    $$ b(4) = 135 * (-3) $$
    $$ b(4) = -405 $$
    Therefore, the 4th term in the sequence is -405.
{% /table %}

This model response is correct - now to make the response even more streamlined,
you can ask the model to think step-by-step.

{% table %}
* **Updated prompt**
* **Improved response**
---

* ![A math equation describing a sequence of numbers](/googledevai/static/gemini-api/docs/images/math.jpg)
    What is the 4th term in the sequence? Think step by step.

* The first term is 15.
    The second term is b(1) * (-3) = 15 * (-3) = -45.
    The third term is b(2) * (-3) = -45 * (-3) = 135.
    The fourth term is b(3) * (-3) = 135 * (-3) = -405.
{% /table %}

### Specify the output format {% id="specify-the-output-format" %}

A common problem is the need for model output to be in a certain format
(e.g. Markdown, JSON, HTML), especially if the model output needs to
be ingested by a downstream task. You can try to produce output in that format
by instructing the model to do so within the prompt. The following are two
examples:

{% table %}
* Prompt
* Model response
---

* ![An excel spreadsheet of subjects and their due dates](/googledevai/static/gemini-api/docs/images/excel-example.png)
    Parse the table in this image into Markdown format

* ```none
    | Subject | Status | Time | Start date | Due on |
    | ------- | ------ | ---- | ---------- | ------ |
    | Math | Done | 1.5 hrs | 11/29/2023 | 12/1/2023 |
    | Geography | Done | 30 min | 12/2/2023 | 12/4/2023 |
    | Physics | In progress | 2 hrs | 12/3/2023 | 12/5/2023 |
    | Biology | Not started | 6 hrs | 11/2/2016 | 12/6/2023 |
    ```
{% /table %}

{% table %}
* **Prompt**
* **Model response**
---

* ![A paella dish with shrimp](/googledevai/static/gemini-api/docs/images/spanish-meal.png)
    Provide a list of all the following attributes:
    ingredients, type of cuisine, vegetarian or not, in JSON format

* ```json
    {
    "ingredients": [
    "rice",
    "shrimp",
    "clams",
    "mussels",
    "peas",
    "tomatoes",
    "onions",
    "garlic",
    "olive oil",
    "paprika",
    "salt",
    "pepper"
    ],
    "type of cuisine": "Spanish",
    "vegetarian": false
    }
    ```
{% /table %}

### Put your image first for single-image prompts {% id="single-image-prompts" %}

While Gemini can interpret image and text in any order within a prompt, placing
a single image before the text prompt might lead to better results.
In the following samples, you'll notice the image comes first before the text in
each prompt.

### Troubleshooting your multimodal prompt {% id="troubleshooting" %}

You might need to troubleshoot your prompt if you are not getting a helpful
response. Here are a few strategies you could try.

#### If the model is not drawing information from the relevant part of the image {% id="if-the-model-is-not-drawing-information-from-the-relevant-part-of-the-image" %}

To get a more specific response, you can point out which aspects of the image
you want the prompt to draw information from to inform its response.

{% table %}
* Prompt
* Model response
---

* ![A box of baby diapers that specifies the amount and other information about the diapers](/googledevai/static/gemini-api/docs/images/diapers.png)
    How many days will these diapers last a baby?

* The diapers will last for 198 days before they run out.
{% /table %}

{% table %}
* **Updated prompt**
* **Improved response**
---

* ![A box of baby diapers that specifies the amount and other information about the diapers](/googledevai/static/gemini-api/docs/images/diapers.png)
    How long will these diapers last before I run out?
    Use the weight shown on the box to determine the child's age, and use the
    total number of diapers in the box. Divide the total number by how many
    diapers the child goes through per day.

* The box contains 198 diapers. The box states the diapers are for a child
    weighing 22-37 lbs. The average child in this weight range is likely between
    1 and 2 years old. A 2-year-old typically goes through 6 diapers per day,
    therefore, the diapers will last around 33 days (198/6).
{% /table %}

#### If the model output is too generic and not tailored enough to the image input {% id="if-the-model-output-is-too-generic-and-not-tailored-enough-to-the-image-input" %}

To help the model tailor its response to the image(s), try asking it to describe
the images before performing its reasoning task.

{% table %}
* Prompt
* Model response
---

* ![A person putting clothing items into a suitcase](/googledevai/static/gemini-api/docs/images/packing.jpg)
    ![A row of shops in a mall](/googledevai/static/gemini-api/docs/images/mall.jpg)
    ![Three rolls of toilet paper](/googledevai/static/gemini-api/docs/images/toilet-paper.jpg)
    ![A view of the ocean, mountains and clouds](/googledevai/static/gemini-api/docs/images/ocean.jpg)
    What is in common between these images?

* All four images are examples of landscape photography.
{% /table %}

{% table %}
* **Updated prompt**
* **Improved response**
---

* ![A person putting clothing items into a suitcase](/googledevai/static/gemini-api/docs/images/packing.jpg)
    ![A row of shops in a mall](/googledevai/static/gemini-api/docs/images/mall.jpg)
    ![Three rolls of toilet paper](/googledevai/static/gemini-api/docs/images/toilet-paper.jpg)
    ![A view of the ocean, mountains and clouds](/googledevai/static/gemini-api/docs/images/ocean.jpg)
    First, describe what's in each image in detail. What's in common between these images?

* The first image shows a person packing a suitcase. The second image shows an
  empty hallway in a shopping mall. The third image shows a roll of toilet
  paper. The fourth image shows a dark and stormy sea.

  The commonality between these images is that they are all examples of liminal
  spaces. Liminal spaces are places or situations that are in between two other
  places or situations. They are often characterized by a sense of uncertainty
  or ambiguity.

  The first image shows the person in between being at home and being on a trip.
  The second image shows the hallway in between two stores. The third image is
  of toilet paper, which can represent a bathroom. A bathroom is a transitional
  space between private and public realms. It's a place where we prepare
  ourselves to enter or leave the outside world.

  The fourth image shows the sea in between being calm and being stormy.

  Liminal spaces can be both exciting and unsettling. They can be a place of
  new beginning or a place of endings. They can be a place of reflection or a
  place of action.
{% /table %}

You can also try explicitly asking the model to refer to what's in the image.

{% table %}
* **Updated prompt**
* **Improved response**
---

* ![A person putting clothing items into a suitcase](/googledevai/static/gemini-api/docs/images/packing.jpg)
    ![A row of shops in a mall](/googledevai/static/gemini-api/docs/images/mall.jpg)
    ![Three rolls of toilet paper](/googledevai/static/gemini-api/docs/images/toilet-paper.jpg)
    ![A view of the ocean, mountains and clouds](/googledevai/static/gemini-api/docs/images/ocean.jpg)
    What is in common between these images? Refer to what's in the images in
    your response.

* All of the images are related to travel. The first image shows a person
  packing a suitcase, the second image shows an empty hallway in a shopping
  mall, the third image shows a stack of toilet paper, and the fourth image
  shows a dark and stormy sea.

  These images are all related to travel because they are all things that
  people need or use when they travel. The first image shows a person packing a
  suitcase, which is something that people do when they are going on a trip.
  The second image shows an empty hallway in a shopping mall, which is a place
  where people often go to buy things for their trips. The third image shows a
  stack of toilet paper, which is something that people often use when they are
  traveling. The fourth image shows a dark and stormy sea, which is something
  that people often encounter when they are traveling.
{% /table %}

The same tips work for creative output from images. In the following example
with the rabbit, explicitly asking the model to include aspects from the image
can improve the output.

{% table %}
* Prompt
* Model response
---

* ![A rabbit on grass with water in the background](/googledevai/static/gemini-api/docs/images/rabbit.jpg)
    Can you write me a poem about this image?

* Little bunny, so soft and brown,
    Hopping through the field, up and down.
    Your ears so long, your tail so small,
    You're the cutest creature of them all.

    You nibble on the grass, so green and sweet,
    And hop away when you see me.
    But I'll always be your friend,
    Little bunny, until the very end.
{% /table %}

{% table %}
* **Updated prompt**
* **Improved response**
---

* ![A rabbit on grass with water in the background](/googledevai/static/gemini-api/docs/images/rabbit.jpg)
    Can you write me a descriptive and dramatic poem about this image and
    include the location?

* Little bunny on the green,
              Ears so long, so keen.
              What do you see out there,
              In the distance, where you stare?

    Is it the ocean blue,
              Sparkling in the sun's hue?
              Or the waves that crash and roar,
              A rhythm that you adore?

    Little bunny, tell me true,
              What captures your attention so?
              Is it the salty breeze,
              Or the seagulls' cries that please?

    Perhaps it's the vastness of it all,
              A world so big and small.
              A place where dreams can roam,
              And adventures can be sown.

    Little bunny, I wonder what you dream,
    As you sit on the grass, so serene.
    Do you yearn to explore the deep,
    Or stay on land, where you can leap?

    Whatever it may be, little bunny,
    Keep that spark of wonder burning brightly.
    For in your dreams and aspirations,
    Lies a world waiting for your creation.
{% /table %}

#### Troubleshooting which part of the prompt failed {% id="troubleshooting-which-part-of-the-prompt-failed" %}

It can be hard to know whether a prompt failed because the model
didn't **understand the image** to begin with, or if it did understand the image
but did not perform the correct **reasoning steps** afterward. To disambiguate
between those reasons, ask the model to describe what's in the image.

In the following example, if the model responds with a snack that seems
surprising when paired with tea (e.g. popcorn), you can first troubleshoot to
determine whether the model correctly recognized that the image contains tea.

{% table %}
* Prompt
* Prompt for troubleshooting
---

* ![A tea set with four cups and a kettle](/googledevai/static/gemini-api/docs/images/tea-set.png)
    What's a snack I can make in 1 minute that would go well with this?

* ![A tea set with four cups and a kettle](/googledevai/static/gemini-api/docs/images/tea-set.png)
    Describe what's in this image.
{% /table %}

Another strategy is to ask the model to explain its reasoning. That can help you
narrow down which part of the reasoning broke down, if any.

{% table %}
* Prompt
* Prompt for troubleshooting
---

* ![A tea set with four cups and a kettle](/googledevai/static/gemini-api/docs/images/tea-set.png)
    What's a snack I can make in 1 minute that would go well with this?

* ![A tea set with four cups and a kettle](/googledevai/static/gemini-api/docs/images/tea-set.png)
    What's a snack I can make in 1 minute that would go well with this? Please
    explain why.
{% /table %}

## What's next {% id="whats-next" %}

- Try writing your own multimodal prompts using [Google AI
    Studio](http://aistudio.google.com).

- For information on using the Gemini Files API for
    uploading media files and including them in your prompts, see the
    [Vision][vision-interactions], [Audio][audio-interactions], and
    [Document processing][document-processing-interactions] guides.

- For more guidance on prompt design, like tuning sampling parameters, see the
    [Prompt strategies](/docs/prompting-strategies) page.

[vision-interactions]: /docs/image-understanding
[audio-interactions]: /docs/audio
[document-processing-interactions]: /docs/document-processing

# OpenAI compatibility
Source: https://aistudio.google.com/docs/openai
Description: Call Gemini models directly using standard OpenAI SDKs and REST endpoints.

Gemini models are accessible using the OpenAI libraries (Python and TypeScript /
Javascript) along with the REST API, by updating three lines of code
and using your [Gemini API key](https://aistudio.google.com/apikey). If you
aren't already using the OpenAI libraries, we recommend that you call the
[Gemini API directly](https://ai.google.dev/docs/get-started).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[
        {   "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Explain to me how AI works"
        }
    ]
)

print(response.choices[0].message)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

const response = await openai.chat.completions.create({
    model: "gemini-3.8-flash",
    messages: [
        {   role: "system",
            content: "You are a helpful assistant."
        },
        {
            role: "user",
            content: "Explain to me how AI works",
        },
    ],
});

console.log(response.choices[0].message);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [
      {
        "role": "user",
        "content": "Explain to me how AI works"
      }
    ]
  }'
```

What changed? Just three lines!

* **`api_key="GEMINI_API_KEY"`**: Replace "`GEMINI_API_KEY`" with your actual Gemini
API key, which you can get in [Google AI Studio](https://aistudio.google.com).

* **`base_url="https://generativelanguage.googleapis.com/v1beta/openai/"`:** This
tells the OpenAI library to send requests to the Gemini API endpoint instead of
the default URL.

* **`model="gemini-3.8-flash"`**: Choose a compatible Gemini model

{% /tab %}
{% /tabs %}
## Thinking {% id="thinking" %}

Gemini models are trained to think through complex problems, leading
to significantly improved reasoning. The Gemini API comes with [thinking
parameters](/docs/thinking) which give fine grain
control over how much the model will think.

Different Gemini models have different reasoning configurations, you can see how
they map to OpenAI's reasoning efforts as follows:

| reasoning_effort (OpenAI) | thinking_level (Gemini 4 Argon) | thinking_level (Gemini 3.1 Flash-Lite) | thinking_level (Gemini 3 Flash) | thinking_budget (Gemini 2.5) |
| :--- | :--- | :--- | :--- | :--- |
| `minimal` | `low` | `minimal` | `minimal` | `1,024` |
| `low` | `low` | `low` | `low` | `1,024` |
| `medium` | `medium` | `medium` | `medium` | `8,192` |
| `high` | `high` | `high` | `high` | `24,576` |

If no `reasoning_effort` is specified, Gemini uses the model's
default [level or budget](/docs/thinking#thinking-levels).

If you want to disable thinking, you can set `reasoning_effort` to `"none"` for
2.5 models. Reasoning cannot be turned off for Gemini 2.5 Pro or 3 models.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    reasoning_effort="low",
    messages=[
        {   "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Explain to me how AI works"
        }
    ]
)

print(response.choices[0].message)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

const response = await openai.chat.completions.create({
    model: "gemini-3.8-flash",
    reasoning_effort: "low",
    messages: [
        {   role: "system",
            content: "You are a helpful assistant."
        },
        {
            role: "user",
            content: "Explain to me how AI works",
        },
    ],
});

console.log(response.choices[0].message);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "reasoning_effort": "low",
    "messages": [
      {
        "role": "user",
        "content": "Explain to me how AI works"
      }
    ]
  }'
```

Gemini thinking models also produce [thought summaries](/docs/thinking#summaries).
You can use the [`extra_body`](/docs/openai#extra-body) field to include Gemini fields
in your request.

Note that `reasoning_effort` and `thinking_level`/`thinking_budget` overlap
functionality, so they can't be used at the same time.

{% /tab %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "Explain to me how AI works"}],
    extra_body={
      'extra_body': {
        "google": {
          "thinking_config": {
            "thinking_level": "low",
            "include_thoughts": True
          }
        }
      }
    }
)

print(response.choices[0].message)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

const response = await openai.chat.completions.create({
    model: "gemini-3.8-flash",
    messages: [{role: "user", content: "Explain to me how AI works",}],
    extra_body: {
      "google": {
        "thinking_config": {
          "thinking_level": "low",
          "include_thoughts": true
        }
      }
    }
});

console.log(response.choices[0].message);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```shell
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer GEMINI_API_KEY" \
  -d '{
      "model": "gemini-3.8-flash",
        "messages": [{"role": "user", "content": "Explain to me how AI works"}],
        "extra_body": {
          "google": {
            "thinking_config": {
              "thinking_level": "low",
              "include_thoughts": true
            }
          }
        }
      }'
```

Gemini 3 supports OpenAI compatibility for thought signatures in chat completion
APIs. You can find the full example on the [thought signatures](/docs/thought-signatures?generate-content=true#openai) page.

{% /tab %}
{% /tabs %}
## Streaming {% id="streaming" %}

The Gemini API supports [streaming responses](/docs/text-generation#streaming-responses).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
  model="gemini-3.8-flash",
  messages=[
    {
        "role": "system",
        "content": "You are a helpful assistant."
    },
    {   "role": "user",
        "content": "Hello!"
    }
  ],
  stream=True
)

for chunk in response:
    print(chunk.choices[0].delta)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: "gemini-3.8-flash",
    messages: [
      {
          "role": "system",
          "content": "You are a helpful assistant."
      },
      {
          "role": "user",
          "content": "Hello!"
      }
    ],
    stream: true,
  });

  for await (const chunk of completion) {
    console.log(chunk.choices[0].delta.content);
  }
}

await main();
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer GEMINI_API_KEY" \
  -d '{
      "model": "gemini-3.8-flash",
      "messages": [
          {"role": "user", "content": "Explain to me how AI works"}
      ],
      "stream": true
    }'
```

{% /tab %}
{% /tabs %}
## Function calling {% id="function-calling" %}

Function calling makes it easier for you to get structured data outputs from
generative models and is [supported in the Gemini API](/docs/function-calling).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

tools = [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the weather in a given location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. Chicago, IL",
          },
          "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        },
        "required": ["location"],
      },
    }
  }
]

messages = [{"role": "user", "content": "What's the weather like in Chicago today?"}]
response = client.chat.completions.create(
  model="gemini-3.8-flash",
  messages=messages,
  tools=tools,
  tool_choice="auto"
)

print(response)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

async function main() {
  const messages = [{"role": "user", "content": "What's the weather like in Chicago today?"}];
  const tools = [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. Chicago, IL",
              },
              "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["location"],
          },
        }
      }
  ];

  const response = await openai.chat.completions.create({
    model: "gemini-3.8-flash",
    messages: messages,
    tools: tools,
    tool_choice: "auto",
  });

  console.log(response);
}

await main();
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
  "model": "gemini-3.8-flash",
  "messages": [
    {
      "role": "user",
      "content": "What'\''s the weather like in Chicago today?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "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. Chicago, IL"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}'
```

{% /tab %}
{% /tabs %}
## Image understanding {% id="image-understanding" %}

Gemini models are natively multimodal and provide best in class performance on
[many common vision tasks](/docs/image-understanding).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import base64
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

# Function to encode the image
def encode_image(image_path):
  with open(image_path, "rb") as image_file:
    return base64.b64encode(image_file.read()).decode('utf-8')

# Getting the base64 string
base64_image = encode_image("Path/to/agi/image.jpeg")

response = client.chat.completions.create(
  model="gemini-3.8-flash",
  messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is in this image?",
        },
        {
          "type": "image_url",
          "image_url": {
            "url":  f"data:image/jpeg;base64,{base64_image}"
          },
        },
      ],
    }
  ],
)

print(response.choices[0])
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";
import fs from 'fs';

const openai = new OpenAI({
  apiKey: "GEMINI_API_KEY",
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

function encodeImage(imagePath = '') {
  try {
    const imageBuffer = fs.readFileSync(imagePath);
    return imageBuffer.toString('base64');
  } catch (error) {
    console.error("Error encoding image:", error);
    return '';
  }
}

async function main() {
  const imagePath = "Path/to/agi/image.jpeg";
  const base64Image = await encodeImage(imagePath);

  const messages = [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is in this image?",
        },
        {
          "type": "image_url",
          "image_url": {
            "url": `data:image/jpeg;base64,${base64Image}`
          },
        },
      ],
    }
  ];

  try {
    const response = await openai.chat.completions.create({
      model: "gemini-3.8-flash",
      messages: messages,
    });

    console.log(response.choices[0]);
  } catch (error) {
    console.error("Error calling Gemini API:", error);
  }
}

await main();
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
bash -c '
  base64_image=$(base64 -i "Path/to/agi/image.jpeg");
  curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer GEMINI_API_KEY" \
    -d "{
      \"model\": \"gemini-3.8-flash\",
      \"messages\": [
        {
          \"role\": \"user\",
          \"content\": [
            { \"type\": \"text\", \"text\": \"What is in this image?\" },
            {
              \"type\": \"image_url\",
              \"image_url\": { \"url\": \"data:image/jpeg;base64,${base64_image}\" }
            }
          ]
        }
      ]
    }"
'
```

{% /tab %}
{% /tabs %}
## Generate an image {% id="generate-image" %}

Generate an image using `gemini-2.5-flash-image` or `gemini-3-pro-image-preview`. Supported parameters include `prompt`, `model`, `n`, `size`, and `response_format`. Any other parameters not listed here or in the [`extra_body`](/docs/openai#extra-body) section will be silently ignored by the compatibility layer.

{% callout type="note" %}
You can enable **Grounding with Google Search** and configure **safety settings**
using the `extra_body` parameter. See the [`extra_body`](/docs/openai#extra-body) section
for available parameters. Grounding with Google Search is only available on Gemini 3 and newer models.
{% /callout %}

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import base64
from openai import OpenAI
from PIL import Image
from io import BytesIO

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

response = client.images.generate(
    model="gemini-2.5-flash-image",
    prompt="a portrait of a sheepadoodle wearing a cape",
    response_format='b64_json',
    n=1,
)

for image_data in response.data:
  image = Image.open(BytesIO(base64.b64decode(image_data.b64_json)))
  image.show()
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "GEMINI_API_KEY",
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

async function main() {
  const image = await openai.images.generate(
    {
      model: "gemini-2.5-flash-image",
      prompt: "a portrait of a sheepadoodle wearing a cape",
      response_format: "b64_json",
      n: 1,
    }
  );

  console.log(image.data);
}

await main();
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer GEMINI_API_KEY" \
  -d '{
        "model": "gemini-2.5-flash-image",
        "prompt": "a portrait of a sheepadoodle wearing a cape",
        "response_format": "b64_json",
        "n": 1,
      }'
```

{% /tab %}
{% /tabs %}
## Generate a video {% id="generate-video" %}

{% callout type="warning" %} Veo 3.1 Preview (`veo-3.1-generate-preview`,
`veo-3.1-fast-generate-preview`, and `veo-3.1-lite-generate-preview`) in the
Gemini API was [shut down](/docs/deprecations) on **October 22, 2026**. Migrate
to [Gemini Omni Flash](/docs/omni) (`gemini-omni-1.1-flash`) using the native
Google GenAI SDK ([Interactions API](/docs/interactions-overview)) or the GA
models available through the
[Gemini Enterprise Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate)
to avoid service interruptions. Video generation with `gemini-omni-1.1-flash` is
not supported on the OpenAI-compatible `/v1/videos` endpoint. {% /callout %}

## Audio understanding {% id="audio-understanding" %}

Analyze audio input:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
import base64
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

with open("/path/to/your/audio/file.wav", "rb") as audio_file:
  base64_audio = base64.b64encode(audio_file.read()).decode('utf-8')

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Transcribe this audio",
        },
        {
              "type": "input_audio",
              "input_audio": {
                "data": base64_audio,
                "format": "wav"
          }
        }
      ],
    }
  ],
)

print(response.choices[0].message.content)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "GEMINI_API_KEY",
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const audioFile = fs.readFileSync("/path/to/your/audio/file.wav");
const base64Audio = audioFile.toString('base64');

async function main() {
  const response = await client.chat.completions.create({
    model: "gemini-3.8-flash",
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: "Transcribe this audio",
          },
          {
            type: "input_audio",
            input_audio: {
              data: base64Audio,
              format: "wav",
            },
          },
        ],
      },
    ],
  });

  console.log(response.choices[0].message.content);
}

await main();
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

Note: If you get an `Argument list too long` error, the encoding of your
audio file might be too long for curl.

```bash
bash -c '
  base64_audio=$(base64 -i "/path/to/your/audio/file.wav");
  curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer GEMINI_API_KEY" \
    -d "{
      \"model\": \"gemini-3.8-flash\",
      \"messages\": [
        {
          \"role\": \"user\",
          \"content\": [
            { \"type\": \"text\", \"text\": \"Transcribe this audio file.\" },
            {
              \"type\": \"input_audio\",
              \"input_audio\": {
                \"data\": \"${base64_audio}\",
                \"format\": \"wav\"
              }
            }
          ]
        }
      ]
    }"
'
```

{% /tab %}
{% /tabs %}
## Structured output {% id="structured-output" %}

Gemini models can output JSON objects in any [structure you define](/docs/structured-output).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from pydantic import BaseModel
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="gemini-3.8-flash",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "John and Susan are going to an AI conference on Friday."},
    ],
    response_format=CalendarEvent,
)

print(completion.choices[0].message.parsed)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai"
});

const CalendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const completion = await openai.chat.completions.parse({
  model: "gemini-3.8-flash",
  messages: [
    { role: "system", content: "Extract the event information." },
    { role: "user", content: "John and Susan are going to an AI conference on Friday" },
  ],
  response_format: zodResponseFormat(CalendarEvent, "event"),
});

const event = completion.choices[0].message.parsed;
console.log(event);
```

{% /tab %}
{% /tabs %}
## Embeddings {% id="embeddings" %}

Text embeddings measure the relatedness of text strings and can be generated
using the [Gemini API](/docs/embeddings). You can use
`gemini-embedding-2` for multimodal embeddings or
`gemini-embedding-001` for text-only embeddings.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.embeddings.create(
    input="Your text string goes here",
    model="gemini-embedding-2"
)

print(response.data[0].embedding)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

async function main() {
  const embedding = await openai.embeddings.create({
    model: "gemini-embedding-2",
    input: "Your text string goes here",
  });

  console.log(embedding);
}

await main();
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/embeddings" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
    "input": "Your text string goes here",
    "model": "gemini-embedding-2"
  }'
```

{% /tab %}
{% /tabs %}
## Batch API {% id="batch" %}

You can create [batch jobs](/docs/batch-api), submit them, and check
their status using the OpenAI library.

You'll need to prepare the JSONL file in OpenAI input format. For example:

```json
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "Tell me a one-sentence joke."}]}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "Why is the sky blue?"}]}}
```

OpenAI compatibility for Batch supports creating a batch,
monitoring job status, and viewing batch results.

Compatibility for upload and download is currently not supported. Instead, the
following example uses the `genai` client for uploading and downloading
[files](/docs/files), the same as when using the Gemini [Batch API](/docs/batch-api#input-file).

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

# Regular genai client for uploads & downloads
from google import genai
client = genai.Client()

openai_client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

# Upload the JSONL file in OpenAI input format, using regular genai SDK
uploaded_file = client.files.upload(
    file='my-batch-requests.jsonl',
    config=types.UploadFileConfig(display_name='my-batch-requests', mime_type='jsonl')
)

# Create batch
batch = openai_client.batches.create(
    input_file_id=batch_input_file_id,
    endpoint="/v1/chat/completions",
    completion_window="24h"
)

# Wait for batch to finish (up to 24h)
while True:
    batch = client.batches.retrieve(batch.id)
    if batch.status in ('completed', 'failed', 'cancelled', 'expired'):
        break
    print(f"Batch not finished. Current state: {batch.status}. Waiting 30 seconds...")
    time.sleep(30)
print(f"Batch finished: {batch}")

# Download results in OpenAI output format, using regular genai SDK
file_content = genai_client.files.download(file=batch.output_file_id).decode('utf-8')

# See batch_output JSONL in OpenAI output format
for line in file_content.splitlines():
    print(line)
```

The OpenAI SDK also supports [generating embeddings with the Batch API](/docs/batch-api#batch-embedding). To do so, switch out the
`create` method's `endpoint` field for an embeddings endpoint, as well as the
`url` and `model` keys in the JSONL file:

```python
# JSONL file using embeddings model and endpoint
# {"custom_id": "request-1", "method": "POST", "url": "/v1/embeddings", "body": {"model": "ggemini-embedding-001", "messages": [{"role": "user", "content": "Tell me a one-sentence joke."}]}}
# {"custom_id": "request-2", "method": "POST", "url": "/v1/embeddings", "body": {"model": "gemini-embedding-001", "messages": [{"role": "user", "content": "Why is the sky blue?"}]}}

# ...

# Create batch step with embeddings endpoint
batch = openai_client.batches.create(
input_file_id=batch_input_file_id,
endpoint="/v1/embeddings",
completion_window="24h"
)
```

See the [Batch embedding generation](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Get_started_OpenAI_Compatibility.ipynb)
section of the OpenAI compatibility cookbook for a complete example.

{% /tab %}
{% /tabs %}
## Flex and Priority inference {% id="inference" %}

The Gemini API matches OpenAI's `service_tier` parameter in name and logic,
enforcing limits and gracefully directing traffic for both the Flex and Priority
inference tiers.

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

client = OpenAI(
  api_key="GEMINI_API_KEY",
  base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

completion = client.chat.completions.create(
  model="gemini-3.8-flash",
  messages=[
    {"role": "user", "content": "Write a short poem about clouds."}
  ],
  service_tier="priority" # Or service_tier="flex"
)

print(completion)
```

When not explicitly assigned, `service_tier` defaults to `standard`, equivalent
to `default` for OpenAI.
Learn more about inference tiers in the [Optimization](/docs/optimization) documentation.

{% /tab %}
{% /tabs %}
## Enable Gemini features with `extra_body` {% id="extra-body" %}

There are several features supported by Gemini that are not available in OpenAI
models but can be enabled using the `extra_body` field.

| Parameter | Type | Endpoint | Description |
| :--- | :--- | :--- | :--- |
| **`cached_content`** | Text | Chat | Corresponds to Gemini's general content cache. |
| **`thinking_config`** | Object | Chat | Corresponds to Gemini's ThinkingConfig. |
| **`aspect_ratio`** | Text | Images | Output aspect ratio (e.g., `"16:9"`, `"1:1"`, `"9:16"`). |
| **`generation_config`** | Object | Images | Gemini generation config object (e.g., `{"responseModalities": ["IMAGE"], "candidateCount": 2}`). |
| **`safety_settings`** | List | Images | Custom safety threshold filters (e.g., `[{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"}]`). |
| **`tools`** | List | Images | Enables grounding (e.g., `[{"google_search": {}}]`). Only for `gemini-3-pro-image-preview`. |

### Example using `extra_body` {% id="extra-body-example" %}

Here's an example of using `extra_body` to set `cached_content`:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

client = OpenAI(
    api_key=MY_API_KEY,
    base_url="https://generativelanguage.googleapis.com/v1beta/"
)

stream = client.chat.completions.create(
    model="gemini-3.8-flash",
    n=1,
    messages=[
        {
            "role": "user",
            "content": "Summarize the video"
        }
    ],
    stream=True,
    stream_options={'include_usage': True},
    extra_body={
        'extra_body':
        {
            'google': {
              'cached_content': "cachedContents/0000aaaa1111bbbb2222cccc3333dddd4444eeee"
          }
        }
    }
)

for chunk in stream:
    print(chunk)
    print(chunk.usage.to_dict())
```

{% /tab %}
{% /tabs %}
## List models {% id="list-models" %}

Get a list of available Gemini models:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

client = OpenAI(
  api_key="GEMINI_API_KEY",
  base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

models = client.models.list()
for model in models:
  print(model.id)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "GEMINI_API_KEY",
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

async function main() {
  const list = await openai.models.list();

  for await (const model of list) {
    console.log(model);
  }
}
await main();
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl https://generativelanguage.googleapis.com/v1beta/openai/models \
-H "Authorization: Bearer GEMINI_API_KEY"
```

{% /tab %}
{% /tabs %}
## Retrieve a model {% id="retrieve-model" %}

Retrieve a Gemini model:

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
from openai import OpenAI

client = OpenAI(
  api_key="GEMINI_API_KEY",
  base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

model = client.models.retrieve("gemini-3.8-flash")
print(model.id)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "GEMINI_API_KEY",
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

async function main() {
  const model = await openai.models.retrieve("gemini-3.8-flash");
  console.log(model.id);
}

await main();
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl https://generativelanguage.googleapis.com/v1beta/openai/models/gemini-3.8-flash \
-H "Authorization: Bearer GEMINI_API_KEY"
```

{% /tab %}
{% /tabs %}
## Current limitations {% id="current-limitations" %}

Support for the OpenAI libraries is still in beta while we extend feature support.

If you have questions about supported parameters, upcoming features, or run into
any issues getting started with Gemini, join our [Developer Forum](https://discuss.ai.google.dev/c/gemini-api/4).

## What's next {% id="whats-next" %}

Try our [OpenAI Compatibility Colab][colab] to work through more detailed
examples.

[colab]: https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_OpenAI_Compatibility.ipynb

# Media resolution
Source: https://aistudio.google.com/docs/media-resolution
Description: Learn about how to use media resolutions with multimodal inputs in the Interactions API.

The `media_resolution` parameter controls how the Gemini API processes media
inputs like images, videos, audio, and PDF documents by determining the
**maximum number of tokens** allocated for media inputs, allowing you to
balance response quality against latency and cost. While visual and document
inputs scale token allocation based on the resolution setting, audio inputs
are tokenized at a fixed rate per second across all resolution levels. For
different settings, default values and how they correspond to tokens, see the
[Token counts](/docs/media-resolution#token-counts) section.

You can configure media resolution for individual media objects (content items)
within your request (Gemini 4 and Gemini 3 models).

## Per-content-item media resolution (Gemini 4 and Gemini 3 models) {% id="per-content-item-media-resolution" %}

Gemini 4 and Gemini 3 models allow you to set media resolution for individual media objects within
your request, offering fine-grained optimisation of token usage. You can mix
resolution levels in a single request. For example, using high resolution for a
complex diagram and low resolution for a simple contextual image.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

myfile = client.files.upload(file="path/to/image.jpg")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/image.jpg",
    config: { mimeType: "image/jpeg" },
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mime_type: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Describe the details in this high-resolution image.").build();
Content imageContent =
    ImageContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/image/scones.jpg")
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/image.jpg", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Describe the details in this high-resolution image.",
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:        genai.Ptr(uploadedFile.URI),
                    MimeType:   interactions.ImageContentMimeType(uploadedFile.MIMEType).ToPointer(),
                    Resolution: interactions.MediaResolutionHigh.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
# First upload the file using the Files API, then use the URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Describe this image:"},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg",
        "resolution": "high"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

## Available resolution values {% id="available-resolution-values" %}

The Gemini API defines the following levels for media resolution:

* `unspecified`: The default setting. The token count for this level varies significantly between Gemini 4/3 and earlier Gemini models.
* `low`: Lower token count, resulting in faster processing and lower cost, but with less detail.
* `medium`: A balance between detail, cost, and latency.
* `high`: Higher token count, providing more detail for the model to work with, at the expense of increased latency and cost.
* `ultra_high` (Per content item only): Highest token count, required for specific use cases such as [computer use](/docs/computer-use).

Note that `high` provides the optimal performance for most use cases.

The exact number of tokens generated for each of these levels depends on both
the **media type** (Image, Video, Audio, PDF) and the **model version**.

## Token counts {% id="token-counts" %}

The tables below summarize the approximate token counts for each
`media_resolution` value and media type per model family.

**Gemini 4 and Gemini 3 models**

| MediaResolution | Image | Video | Audio | PDF |
| :--- | :--- | :--- | :--- | :--- |
| `unspecified` (Default) | 1120 | 70 | 25 (per second) | 560 |
| `low` | 280 | 70 | 25 (per second) | 280 + Native Text |
| `medium` | 560 | 70 | 25 (per second) | 560 + Native Text |
| `high` | 1120 | 280 | 25 (per second) | 1120 + Native Text |
| `ultra_high` | 2240 | N/A | N/A | N/A |

## Choosing the right resolution {% id="choosing-the-right-resolution" %}

* **Default (`unspecified`):** Start with the default. It's tuned for a good balance of quality, latency, and cost for most common use cases.
* **`low`:** Use for scenarios where cost and latency are paramount, and fine-grained detail is less critical.
* **`medium` / `high`:** Increase the resolution when the task requires
  understanding intricate details within the media. This is often needed for
  complex visual analysis, chart reading, or dense document comprehension.
* **`ultra_high`** - Only available for per content item setting. Recommended
  for specific use cases such as computer use or where testing shows a clear
  enhancement over `high`.
* **Per-content-item control (Gemini 4 and Gemini 3):** Optimizes token usage. For example,
  in a prompt with multiple images, use `high` for a complex diagram and `low`
  or `medium` for simpler contextual images.

**Recommended settings**

The following lists the recommended media resolution settings for each supported
media type.

| Media Type | Recommended Setting | Max Tokens | Usage Guidance |
| :--- | :--- | :--- | :--- |
| **Images** | `high` | 1120 | Recommended for most image analysis tasks to ensure maximum quality. |
| **PDFs** | `medium` | 560 | Optimal for document understanding; quality typically saturates at `medium`. Increasing to `high` rarely improves OCR results for standard documents. |
| **Video** (General) | `low` (or `medium`) | 70 (per frame) | **Note:** For video, `low` and `medium` settings are treated identically (70 tokens) to optimize context usage. This is sufficient for most action recognition and description tasks. |
| **Video** (Text-heavy) | `high` | 280 (per frame) | Required only when the use case involves reading dense text (OCR) or small details within video frames. |
| **Audio** | `unspecified` (Default) | 25 (per second) | Audio is tokenized at a fixed rate of 25 tokens per second across all supported resolution settings (`unspecified`, `low`, `medium`, and `high`). |

Always test and evaluate the impact of different resolution settings on your
application to find the best trade-off between quality, latency, and cost.

## Relationship with video processing modes {% id="relationship-with-video-processing-modes" %}

For video content, `media_resolution` controls the token budget per frame, while
the `processing` mode controls *which* content from the video is loaded. These two settings
operate independently: you can use low, medium, or high resolution with either
static processing or agentic video understanding. For details, see
[Agentic video understanding](/docs/video-understanding#agentic-video-understanding).

## Version compatibility summary {% id="version-compatibility-summary" %}

* Setting the `resolution` on individual content items is **supported on Gemini 4 and Gemini 3 models**.

## Next steps {% id="next-steps" %}

* Learn more about the multimodal capabilities of Gemini API in the
    [image understanding](/docs/image-understanding),
    [video understanding](/docs/video-understanding),
    [audio understanding](/docs/audio), and
    [document understanding](/docs/document-processing) guides.

# Understand and count tokens
Source: https://aistudio.google.com/docs/tokens
Description: Understand and count tokens with the Gemini API

Gemini and other generative AI models process input and output at a granularity
called a _token_.

**For Gemini models, a token is equivalent to about 4 characters.
100 tokens is equal to about 60-80 English words.**

## About tokens {% id="about-tokens" %}

Tokens can be single characters like `z` or whole words like `cat`. Long words
are broken up into several tokens. The set of all tokens used by the model is
called the vocabulary, and the process of splitting text into tokens is called
_tokenization_.

When billing is enabled, the [cost of a call to the Gemini API](/docs/pricing) is
determined in part by the number of input and output tokens, so knowing how to
count tokens can be helpful.

## Count tokens {% id="count-tokens" %}

All input to and output from the Gemini API is tokenized, including text, image
files, and other non-text modalities.

You can count tokens in the following ways:

* **Call `count_tokens` with the input of the request.** Returns the total
    number of tokens in _the input only_. Make this call before sending input
    to check the size of your requests.

* **Use the `usage` on the interaction response.** Returns token
    counts for input (`total_input_tokens`), output (`total_output_tokens`),
    thinking (`total_thought_tokens`), cached content
    (`total_cached_tokens`), tool use (`total_tool_use_tokens`),
    and total (`total_tokens`).

### Count text tokens {% id="text-tokens" %}

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()
prompt = "The quick brown fox jumps over the lazy dog."

# Count tokens before sending
total_tokens = client.models.count_tokens(
    model="gemini-3.8-flash",
    contents=prompt
)
print("total_tokens:", total_tokens.total_tokens)

# Get usage from interaction
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=prompt
)
print(interaction.usage)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";

// Count tokens before sending
const countResponse = await client.models.countTokens({
    model: "gemini-3.8-flash",
    contents: prompt,
});
console.log(countResponse.totalTokens);

// Get usage from interaction
const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: prompt,
});
console.log(interaction.usage);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.CountTokensResponse;

Client client = new Client();
String prompt = "The quick brown fox jumps over the lazy dog.";

// Count tokens before sending
CountTokensResponse countResponse =
    client.models.countTokens("gemini-3.8-flash", prompt, null);
System.out.println("total_tokens: " + countResponse.totalTokens().orElse(0));

// Get usage from interaction
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of(prompt))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.usage().orElse(null));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    modelInfo, err := client.Models.Get(ctx, "gemini-3.8-flash", nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Input token limit: %d\n", modelInfo.InputTokenLimit)
    fmt.Printf("Output token limit: %d\n", modelInfo.OutputTokenLimit)
}
```
{% /tab %}

{% tab label="REST" %}
```shell
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:countTokens" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{"contents": [{"parts": [{"text": "The quick brown fox."}]}]}'
```
{% /tab %}
{% /tabs %}

### Count multi-turn tokens {% id="multi-turn-tokens" %}

Count tokens across conversation history using `previous_interaction_id`:

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
# First interaction
interaction1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Bob"
)

# Second interaction continues the conversation
interaction2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What's my name?",
    previous_interaction_id=interaction1.id
)

# Usage includes tokens from both turns
print(f"Input tokens: {interaction2.usage.total_input_tokens}")
print(f"Output tokens: {interaction2.usage.total_output_tokens}")
print(f"Total tokens: {interaction2.usage.total_tokens}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// This will only work for SDK newer than 2.0.0
// First interaction
const interaction1 = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Hi, my name is Bob"
});

// Second interaction continues the conversation
const interaction2 = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "What's my name?",
    previous_interaction_id: interaction1.id
});

console.log(`Input tokens: ${interaction2.usage.total_input_tokens}`);
console.log(`Output tokens: ${interaction2.usage.total_output_tokens}`);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Usage;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// First interaction
CreateModelInteraction params1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Hi, my name is Bob"))
        .build();

Interaction interaction1 =
    client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();

// Second interaction continues the conversation
CreateModelInteraction params2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("What's my name?"))
        .previousInteractionId(interaction1.id().orElse(""))
        .build();

Interaction interaction2 =
    client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();

// Usage includes tokens from both turns
if (interaction2.usage().isPresent()) {
  Usage usage = interaction2.usage().get();
  System.out.println("Input tokens: " + usage.totalInputTokens().orElse(0));
  System.out.println("Output tokens: " + usage.totalOutputTokens().orElse(0));
  System.out.println("Total tokens: " + usage.totalTokens().orElse(0));
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "The quick brown fox jumps over the lazy dog."

    // Count input tokens before sending
    totalTokens, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", genai.Text(prompt), nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("total_tokens: %d\n", totalTokens.TotalTokens)

    // Create the interaction and inspect the returned usage metadata
    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(prompt),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    interaction := res.Interaction
    if interaction.OutputText != nil {
        fmt.Println(*interaction.OutputText)
    }
    if interaction.Usage != nil {
        if interaction.Usage.TotalInputTokens != nil {
            fmt.Printf("Input tokens: %d\n", *interaction.Usage.TotalInputTokens)
        }
        if interaction.Usage.TotalOutputTokens != nil {
            fmt.Printf("Output tokens: %d\n", *interaction.Usage.TotalOutputTokens)
        }
        if interaction.Usage.TotalThoughtTokens != nil {
            fmt.Printf("Thought tokens: %d\n", *interaction.Usage.TotalThoughtTokens)
        }
        if interaction.Usage.TotalTokens != nil {
            fmt.Printf("Total tokens: %d\n", *interaction.Usage.TotalTokens)
        }
    }
}
```
{% /tab %}

{% /tabs %}

### Count multimodal tokens {% id="multimodal-tokens" %}

All input to the Gemini API is tokenized, including images, video, and audio.
Key points about tokenization:

* **Images**: Images ≤384 pixels in both dimensions count as 258 tokens. Larger
  images are tiled into 768x768 pixel tiles, each counting as 258 tokens.

* **Video**: 263 tokens per second (applies to static processing). For agentic
  processing, token usage varies. See
  [Video token usage by processing mode](/docs/tokens#video).
* **Audio**: 32 tokens per second

#### Image tokens {% id="images" %}

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
uploaded_file = client.files.upload(file="path/to/image.jpg")

# Count tokens for image + text
total_tokens = client.models.count_tokens(
    model="gemini-3.8-flash",
    contents=["Tell me about this image", uploaded_file]
)
print(f"Total tokens: {total_tokens}")

# Generate with image
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Tell me about this image"},
        {"type": "image", "uri": uploaded_file.uri, "mime_type": uploaded_file.mime_type}
    ]
)
print(interaction.usage)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// This will only work for SDK newer than 2.0.0
const uploadedFile = await client.files.upload({
    file: "path/to/image.jpg",
    config: { mimeType: "image/jpeg" }
});

// Count tokens
const countResponse = await client.models.countTokens({
    model: "gemini-3.8-flash",
    contents: [
        { text: "Tell me about this image" },
        { fileData: { fileUri: uploadedFile.uri, mimeType: uploadedFile.mimeType } }
    ]
});
console.log(countResponse.totalTokens);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.Content;
import com.google.genai.types.CountTokensResponse;
import com.google.genai.types.File;
import com.google.genai.types.Part;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;

Client client = new Client();

File uploadedFile =
    client.files.upload(
        new java.io.File("path/to/image.jpg"),
        UploadFileConfig.builder().mimeType("image/jpeg").build());

// Count tokens for image + text
CountTokensResponse countResponse =
    client.models.countTokens(
        "gemini-3.8-flash",
        Arrays.asList(
            Content.fromParts(
                Part.fromText("Tell me about this image"),
                Part.fromUri(
                    uploadedFile.uri().orElse(""), uploadedFile.mimeType().orElse("image/jpeg")))),
        null);
System.out.println("Total tokens: " + countResponse.totalTokens().orElse(0));

// Generate with image
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    TextContent.builder().text("Tell me about this image").build(),
                    ImageContent.builder()
                        .uri(uploadedFile.uri().orElse(""))
                        .mimeType(
                            ImageContentMimeType.of(uploadedFile.mimeType().orElse("image/jpeg")))
                        .build())))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.usage().orElse(null));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:  interactions.Model("gemini-3.8-flash"),
            Input:  interactions.NewInteractionsInput("Explain the history of the internet in 3 paragraphs."),
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        }
        if completed := event.GetDataInteractionCompleted(); completed != nil {
            usage := completed.Interaction.Usage
            if usage != nil && usage.TotalTokens != nil {
                fmt.Printf("\nTotal tokens: %d\n", *usage.TotalTokens)
            }
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% /tabs %}

**Inline data example:**

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
import base64

with open('image.jpg', 'rb') as f:
    image_bytes = f.read()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this image"},
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode('utf-8'),
            "mime_type": "image/jpeg"
        }
    ]
)
print(interaction.usage)
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("image.jpg"));
String base64Image = Base64.getEncoder().encodeToString(imageBytes);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    TextContent.builder().text("Describe this image").build(),
                    ImageContent.builder()
                        .data(base64Image)
                        .mimeType(ImageContentMimeType.IMAGE_JPEG)
                        .build())))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.usage().orElse(null));
```
{% /tab %}

{% /tabs %}

#### Video tokens {% id="video" %}

Token calculation for video depends on the processing mode:

| **Processing mode** | **Frames sampled** | **Tokens per second** | **Tokens for 60s video** |
| --- | --- | --- | --- |
| **Static** (default) | 1 FPS (all frames) | ~100 (default low resolution) / ~300 (high resolution) | ~6,000 (default) / ~18,000 (high) |
| **Agentic** | Dynamic (on demand) | Variable (up to 88% fewer) | Typically 1,500 to 3,000 |

For details on setting the processing mode, see
[Agentic video understanding](/docs/video-understanding#agentic-video-understanding).

{% callout type="note" %}
For static processing, token calculations assume the default sampling rate of
1 FPS. If you set a [custom frame rate](/docs/video-understanding?generate-content=true#custom-frame-rate)
in the GenerateContent API, token usage scales proportionally with the
configured FPS.
{% /callout %}

To check actual token usage for a request, inspect `interaction.usage`. Agentic video tokens are reported across the following fields:

* **Initial prompt** (video reference + user prompt): `total_input_tokens`
* **Navigation thinking**: `total_thought_tokens`
* **Transcript, frames, and audio loaded on demand**: `total_tool_use_tokens`
* **Final answer**: `total_output_tokens`

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
import time

video_file = client.files.upload(file="path/to/video.mp4")

while not video_file.state or video_file.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    video_file = client.files.get(name=video_file.name)

# A 60-second video is approximately 100 * 60 = 6,000 tokens
total_tokens = client.models.count_tokens(
    model="gemini-3.8-flash",
    contents=["Summarize this video", video_file]
)
print(f"Total tokens: {total_tokens}")

# Generate with video
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Summarize this video"},
        {"type": "video", "uri": video_file.uri, "mime_type": video_file.mime_type}
    ]
)
print(interaction.usage)
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.Content;
import com.google.genai.types.CountTokensResponse;
import com.google.genai.types.File;
import com.google.genai.types.FileState;
import com.google.genai.types.Part;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;

Client client = new Client();

File videoFile =
    client.files.upload(
        new java.io.File("path/to/video.mp4"),
        UploadFileConfig.builder().mimeType("video/mp4").build());

// Wait for processing
while (videoFile.state().isPresent()
    && videoFile.state().get().knownEnum() == FileState.Known.PROCESSING) {
  Thread.sleep(5000);
  videoFile = client.files.get(videoFile.name().orElse(""), null);
}

// A 60-second video is approximately 100 * 60 = 6,000 tokens
CountTokensResponse countResponse =
    client.models.countTokens(
        "gemini-3.8-flash",
        Arrays.asList(
            Content.fromParts(
                Part.fromText("Summarize this video"),
                Part.fromUri(
                    videoFile.uri().orElse(""), videoFile.mimeType().orElse("video/mp4")))),
        null);
System.out.println("Total tokens: " + countResponse.totalTokens().orElse(0));

// Generate with video
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    TextContent.builder().text("Summarize this video").build(),
                    VideoContent.builder()
                        .uri(videoFile.uri().orElse(""))
                        .mimeType(VideoContentMimeType.of(videoFile.mimeType().orElse("video/mp4")))
                        .build())))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.usage().orElse(null));
```
{% /tab %}

{% /tabs %}

#### Audio tokens {% id="audio" %}

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
audio_file = client.files.upload(file="path/to/audio.mp3")

# A 60-second audio clip is approximately 32 * 60 = 1,920 tokens
total_tokens = client.models.count_tokens(
    model="gemini-3.8-flash",
    contents=["Transcribe this audio", audio_file]
)
print(f"Total tokens: {total_tokens}")

# Generate with audio
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Transcribe this audio"},
        {"type": "audio", "uri": audio_file.uri, "mime_type": audio_file.mime_type}
    ]
)
print(interaction.usage)
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AudioContent;
import com.google.genai.gaos.models.interactions.AudioContentMimeType;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.Content;
import com.google.genai.types.CountTokensResponse;
import com.google.genai.types.File;
import com.google.genai.types.Part;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;

Client client = new Client();

File audioFile =
    client.files.upload(
        new java.io.File("path/to/audio.mp3"),
        UploadFileConfig.builder().mimeType("audio/mp3").build());

// A 60-second audio clip is approximately 32 * 60 = 1,920 tokens
CountTokensResponse countResponse =
    client.models.countTokens(
        "gemini-3.8-flash",
        Arrays.asList(
            Content.fromParts(
                Part.fromText("Transcribe this audio"),
                Part.fromUri(
                    audioFile.uri().orElse(""), audioFile.mimeType().orElse("audio/mp3")))),
        null);
System.out.println("Total tokens: " + countResponse.totalTokens().orElse(0));

// Generate with audio
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    TextContent.builder().text("Transcribe this audio").build(),
                    AudioContent.builder()
                        .uri(audioFile.uri().orElse(""))
                        .mimeType(AudioContentMimeType.of(audioFile.mimeType().orElse("audio/mp3")))
                        .build())))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.usage().orElse(null));
```
{% /tab %}

{% /tabs %}

### Count system instruction tokens {% id="system-instructions" %}

System instructions are counted as part of the input tokens:

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hello!",
    system_instruction="You are a helpful assistant who speaks like a pirate."
)

# system_instruction tokens included in total_input_tokens
print(f"Input tokens: {interaction.usage.total_input_tokens}")
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Hello!"))
        .systemInstruction("You are a helpful assistant who speaks like a pirate.")
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

// system_instruction tokens included in total_input_tokens
if (interaction.usage().isPresent()) {
  System.out.println(
      "Input tokens: " + interaction.usage().get().totalInputTokens().orElse(0));
}
```
{% /tab %}

{% /tabs %}

### Count tool tokens {% id="tools" %}

Tools (functions, code execution, Google Search) are also counted:

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string"}
            }
        }
    }
]

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What's the weather in Tokyo?",
    tools=tools
)

print(f"Input tokens: {interaction.usage.total_input_tokens}")
print(f"Tool use tokens: {interaction.usage.total_tool_use_tokens}")
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Tool;
import com.google.genai.gaos.models.interactions.Usage;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> locationProp = new HashMap<>();
locationProp.put("type", "string");

Map<String, Object> properties = new HashMap<>();
properties.put("location", locationProp);

Map<String, Object> schema = new HashMap<>();
schema.put("type", "object");
schema.put("properties", properties);

Tool weatherTool =
    Function.builder()
            .name("get_weather")
            .description("Get current weather")
            .parameters(schema)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("What's the weather in Tokyo?"))
        .tools(Arrays.asList(weatherTool))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.usage().isPresent()) {
  Usage usage = interaction.usage().get();
  System.out.println("Input tokens: " + usage.totalInputTokens().orElse(0));
  System.out.println("Tool use tokens: " + usage.totalToolUseTokens().orElse(0));
}
```
{% /tab %}

{% /tabs %}

## Context window {% id="context-window" %}

Each Gemini model has a maximum number of tokens it can handle.

* **Gemini 4 models (`gemini-4-argon`):** Share a single 1M-token context window (`1,048,576` tokens) across input, thinking, and output tokens. By default, synchronous responses (`background=False`, streaming or non-streaming) are capped at `65,536` output tokens, or you can generate up to `1,048,576` tokens using [long decode](/docs/long-decode). If your input tokens plus `max_output_tokens` exceed 1,048,576 tokens, the API automatically caps the output limit to the remaining space in the context window (`1,048,576` minus your input tokens).
* **Gemini 3 and 2.5 models:** Use separate input (`1,048,576` tokens) and output (`65,536` tokens) budgets.

### Get context window size programmatically {% id="get-context-window" %}

{% tabs %}
{% tab label="Python" %}
```python
# This will only work for SDK newer than 2.0.0
model_info = client.models.get(model="gemini-3.8-flash")
print(f"Input token limit: {model_info.input_token_limit}")
print(f"Output token limit: {model_info.output_token_limit}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
// This will only work for SDK newer than 2.0.0
const modelInfo = await client.models.get({ model: "gemini-3.8-flash" });
console.log(`Input token limit: ${modelInfo.inputTokenLimit}`);
console.log(`Output token limit: ${modelInfo.outputTokenLimit}`);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Model;

Client client = new Client();

Model modelInfo = client.models.get("gemini-3.8-flash", null);
System.out.println("Input token limit: " + modelInfo.inputTokenLimit().orElse(0));
System.out.println("Output token limit: " + modelInfo.outputTokenLimit().orElse(0));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Tell me about this instrument"
    imageBytes, err := os.ReadFile("/path/to/organ.jpg")
    if err != nil {
        log.Fatal(err)
    }
    base64Image := base64.StdEncoding.EncodeToString(imageBytes)

    // Count tokens before creating the interaction
    parts := []*genai.Part{
        genai.NewPartFromText(prompt),
        genai.NewPartFromBytes(imageBytes, "image/jpeg"),
    }
    totalTokens, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", []*genai.Content{
        genai.NewContentFromParts(parts, genai.RoleUser),
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Estimated input tokens: %d\n", totalTokens.TotalTokens)

    // Create the multimodal interaction and inspect the usage metadata
    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
                interactions.NewContent(interactions.ImageContent{
                    Data:     genai.Ptr(base64Image),
                    MimeType: interactions.ImageContentMimeTypeImageJpeg.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    interaction := res.Interaction
    if interaction.OutputText != nil {
        fmt.Println(*interaction.OutputText)
    }
    if interaction.Usage != nil && interaction.Usage.TotalTokens != nil {
        fmt.Printf("Total tokens billed: %d\n", *interaction.Usage.TotalTokens)
    }
}
```
{% /tab %}

{% /tabs %}

Find context window sizes on the [models](/docs/models) page.

## What's next {% id="whats-next" %}

* [Text generation](/docs/text-generation): Generation basics
* [Caching](/docs/caching): Reduce costs with caching
* [Pricing](/docs/pricing): Understand costs

# Prompt design strategies
Source: https://aistudio.google.com/docs/prompting-strategies
Description: Get started designing prompts for Gemini AI models.

*Prompt design* is the process of creating prompts, or natural language
requests, that elicit accurate, high quality responses from a language model.

This page introduces basic concepts, strategies, and best practices to get you
started designing prompts to get the most out of Gemini AI models.

{% callout type="note" %}
Note: Prompt engineering is iterative. These guidelines and templates are
starting points. Experiment and refine based on your specific use cases and
observed model responses.
{% /callout %}

## Topic-specific prompt guides {% id="additional-prompt-guides" %}

Looking for more specific prompt strategies? Check out our other prompting
guides on:

-  [Prompting with media files](/docs/files#prompt-guide)
-  [Prompting for image generation](/docs/image-generation#prompt-guide)
-  [Prompting for video generation](/docs/veo#prompt-guide)

You can find other sample prompts in the [prompt gallery](https://ai.google.dev/prompts)
meant to interactively showcase many of the concepts shared in this guide.

## Clear and specific instructions {% id="clear-and-specific-instructions" %}

An effective and efficient way to customize model behavior is to provide it with
clear and specific instructions. Instructions can be in the form of a question,
step-by-step tasks, or as complex as mapping out a user's experience and
mindset.

### Input {% id="input" %}

Input is the required text in the prompt that you want the model to provide a
response to. Inputs can be a question that the model
answers (question input), a task the model performs (task input), an entity the
model operates on (entity input), or partial input that the model completes or
continues (completion input).

#### Question input {% id="question" %}

**Prompt**
```none
What's a good name for a flower shop that specializes in selling bouquets of
dried flowers? Create a list of 5 options with just the names.
```

**Generated output**
```none
Here are 5 names for a flower shop specializing in dried flowers:

1. Everlasting Blooms
2. Dried & Delightful
3. The Petal Preserve
4. Whispers of Wildflowers
5. Forever Blooms
```

#### Task input {% id="task" %}

**Prompt**
```none
Give me a simple list of just the things that I must bring on a camping trip. The list should have 5 items.
```

**Generated output**
```none
1. **Tent:** Your shelter from the elements.
2. **Sleeping Bag:** Stay warm and comfortable.
3. **Sleeping Pad:** Insulation and cushioning for a good night's sleep.
4. **Headlamp or Flashlight:** Light for nighttime activities.
5. **First Aid Kit:** Be prepared for minor injuries.
```

#### Entity input {% id="entity" %}

**Prompt**
```none
Classify the following items as [large, small]:
Elephant
Mouse
Snail
```

**Generated output**
```none
Here's the classification:

* **Elephant:** Large
* **Mouse:** Small
* **Snail:** Small
```

#### Partial input completion {% id="completion" %}

Generative language models work like an advanced auto completion tool. When you
provide partial content, the model can provide the rest of the content or what
it thinks is a continuation of that content as a response. When doing so, if you
include any examples or context, the model can take those examples or context
into account.

The following example provides a prompt with an instruction and an entity input:

**Prompt:**
```none
For the given order, return a JSON object that has the fields cheeseburger, hamburger, fries, or
drink, with the value being the quantity.

Order: A burger and a drink.
```

**Response:**
```json
{
  "cheeseburger": 0,
  "hamburger": 1,
  "fries": 0,
  "drink": 1
}
```

_(gemini-2.5-flash)_

While the model did as prompted, writing out the instructions in natural
language can sometimes be challenging and it leaves a lot to the model's
interpretation. For example, a restaurants menu might contain many items. To
reduce the size of the JSON response, you probably want to omit the items that
weren't ordered. In this case, you can give an example and a response prefix and
let the model complete it:

**Prompt:**
````none
Valid fields are cheeseburger, hamburger, fries, and drink.
Order: Give me a cheeseburger and fries
Output:
```
{
  "cheeseburger": 1,
  "fries": 1
}
```
Order: I want two burgers, a drink, and fries.
Output:
````

**Response:**
```json
{
  "hamburger": 2,
  "drink": 1,
  "fries": 1
}
```

_(gemini-2.5-flash)_

Notice how "cheeseburger" was excluded from the output because it wasn't a part
of the order.

While you can specify the format of simple JSON response objects using prompts,
we recommend using Gemini API's
[structured output](/docs/structured-output) feature when specifying
a more complex JSON Schema for the response.

### Constraints {% id="constraints" %}

Specify any constraints on reading the prompt or generating a response. You can
tell the model what to do and not to do. For example, you can specify a
constraint in the prompt on how long you want a summary to be:

**Prompt:**
```none
Summarize this text in one sentence:
Text: A quantum computer exploits quantum mechanical phenomena to perform calculations exponentially
faster than any modern traditional computer. At very tiny scales, physical matter acts as both
particles and as waves, and quantum computing uses specialized hardware to leverage this behavior.
The operating principles of quantum devices is beyond the scope of classical physics. When deployed
at scale, quantum computers could be used in a wide variety of applications such as: in
cybersecurity to break existing encryption methods while helping researchers create new ones, in
meteorology to develop better weather forecasting etc. However, the current state of the art quantum
computers are still largely experimental and impractical.
```

**Response:**
```none
Exploiting quantum mechanical phenomena, quantum computers can perform calculations exponentially faster than traditional computers for potential applications like cybersecurity and meteorology, although they are currently largely experimental and impractical.
```

_(gemini-2.5-flash)_

### Response format {% id="response-format" %}

You can give instructions that specify the format of the response. For example,
you can ask for the response to be formatted as a table, bulleted list, elevator
pitch, keywords, sentence, or paragraph. The following system instruction tells
the model to be more conversational in its response:

**Prompt:**
```none
All questions should be answered comprehensively with details, unless the user requests a concise response specifically.
```

**Response:**
```none
What is a smart way to make a business that sells DVD's in 2026?
```

_(gemini-2.5-flash)_

#### Format responses with the completion strategy {% id="format-responses-with-the-completion-strategy" %}

The [completion strategy](/docs/prompting-strategies#completion) can also help format the response.
The following example prompts the model to create an essay outline:

**Prompt:**
```none
Create an outline for an essay about hummingbirds.
```

**Response:**
```none
Here is a possible outline for an essay about hummingbirds:

I. Introduction
A. Hook: Start with a captivating fact or description about hummingbirds (e.g., their speed, iridescent colors, or tiny size).
B. Background: Briefly introduce hummingbirds - where they are found (Americas), their reputation as unique birds.
C. Thesis Statement: State the main point of the essay, which could be about the remarkable adaptations, behaviors, and ecological importance of hummingbirds.

II. Appearance and Identification
.....
```

_(gemini-2.5-flash)_

The prompt didn't specify the format for the outline and the model chose a
format for you. To get the model to return an outline in a specific format, you
can add text that represents the start of the outline and let the model complete
it based on the pattern that you initiated.

**Prompt:**
```none
Create an outline for an essay about hummingbirds.
I. Introduction

   *
```

**Response:**
```none
Okay, here is an outline for an essay about hummingbirds, starting from the introduction you provided:

I. Introduction

* Hook: Start with a captivating fact or description about hummingbirds (e.g., their speed, iridescent colors, or tiny size).
* Background: Briefly introduce hummingbirds - where they are found (Americas), their reputation as unique birds, and their general characteristics.
* Thesis Statement: State the main point of the essay, focusing on the remarkable adaptations, behaviors, and ecological significance that make hummingbirds extraordinary.
.....
```

_(gemini-2.5-flash)_

## Zero-shot vs few-shot prompts {% id="few-shot" %}

You can include examples in the prompt that show the model what getting it right
looks like. The model attempts to identify patterns and relationships from the
examples and applies them when generating a response. Prompts that contain a few
examples are called *few-shot* prompts, while prompts that provide no
examples are called *zero-shot* prompts. Few-shot prompts are often used
to regulate the formatting, phrasing, scoping, or general patterning of model
responses. Use specific and varied examples to help the model narrow its focus
and generate more accurate results.

We recommend to always include few-shot examples in your prompts. Prompts
without few-shot examples are likely to be less effective. In fact, you can
remove instructions from your prompt if your examples are clear enough in
showing the task at hand.

The following zero-shot prompt asks the model to choose the best explanation.

**Prompt:**
```none
Please choose the best explanation to the question:

Question: How is snow formed?
Explanation1: Snow is formed when water vapor in the air freezes into ice
crystals in the atmosphere, which can combine and grow into snowflakes as they
fall through the atmosphere and accumulate on the ground.
Explanation2: Water vapor freezes into ice crystals forming snow.
Answer:
```

**Response:**
```none
Explanation1 is the better explanation because it provides more detail on the
process, including how ice crystals combine and grow into snowflakes as they
fall through the atmosphere.
```

_(gemini-2.5-flash)_

If your use case requires the model to produce concise responses, you can
include examples in the prompt that give preference to concise responses.

The following prompt provides two examples that show preference to the shorter
explanations. In the response, you can see that the examples guided the model to
choose the shorter explanation (`Explanation2`) as opposed to the longer
explanation (`Explanation1`) like it did previously.

**Prompt:**
```none
Below are some examples showing a question, explanation, and answer format:

Question: Why is the sky blue?
Explanation1: The sky appears blue because of Rayleigh scattering, which causes
shorter blue wavelengths of light to be scattered more easily than longer red
wavelengths, making the sky look blue.
Explanation2: Due to Rayleigh scattering effect.
Answer: Explanation2

Question: What is the cause of earthquakes?
Explanation1: Sudden release of energy in the Earth's crust.
Explanation2: Earthquakes happen when tectonic plates suddenly slip or break
apart, causing a release of energy that creates seismic waves that can shake the
ground and cause damage.
Answer: Explanation1

Now, Answer the following question given the example formats above:

Question: How is snow formed?
Explanation1: Snow is formed when water vapor in the air freezes into ice
crystals in the atmosphere, which can combine and grow into snowflakes as they
fall through the atmosphere and accumulate on the ground.
Explanation2: Water vapor freezes into ice crystals forming snow.
Answer:
```

**Response:**
```none
Answer: Explanation2
```

_(gemini-2.5-flash)_

### Optimal number of examples {% id="number-examples" %}

Models like Gemini can often pick up on patterns using a few examples, though
you may need to experiment with the number of examples to provide in the prompt
for the best results. At the same time, if you include too many examples,
the model may start to [overfit](https://developers.google.com/machine-learning/glossary#overfitting)
the response to the examples.

### Consistent formatting {% id="consistent-formatting" %}

Make sure that the structure and formatting of few-shot examples are the same to
avoid responses with undesired formats. One of the primary objectives of adding
few-shot examples in prompts is to show the model the response format.
Therefore, it is essential to ensure a consistent format across all examples,
especially paying attention to XML tags, white spaces, newlines, and example
splitters.

## Add context {% id="context" %}

You can include instructions and information in a prompt that the model needs
to solve a problem, instead of assuming that the model has all of the required
information. This contextual information helps the model understand the
constraints and details of what you're asking for it to do.

The following example asks the model to give troubleshooting guidance for a
router:

**Prompt:**
```none
What should I do to fix my disconnected wifi? The light on my Google
Wifi router is yellow and blinking slowly.
```

**Response:**
```none
A yellow blinking light on your Google Wifi router usually indicates a problem
  with the internet connection. Here are some steps to troubleshoot and fix the
  issue:

  1. Restart your router and modem:
    - Unplug your modem from the power outlet and wait for 30 seconds.
    - Plug your modem back in and wait for it to fully boot up.
    - Unplug your Google Wifi router and wait for 30 seconds.
    - Plug your Google Wifi router back in and wait for it to fully boot up.
.....
```

_(gemini-2.5-flash)_

The response looks like generic troubleshooting information that's not specific
to the router or the status of the LED indicator lights.

To customize the response for the specific router, you can add to the prompt
the router's troubleshooting guide as context for it to refer to when providing
a response.

**Prompt:**
```none
Answer the question using the text below. Respond with only the text provided.
Question: What should I do to fix my disconnected wifi? The light on my Google Wifi router is yellow and blinking slowly.

Text:
Color: Slowly pulsing yellow
What it means: There is a network error.
What to do:
Check that the Ethernet cable is connected to both your router and your modem and both devices are turned on. You might need to unplug and plug in each device again.

Color: Fast blinking yellow
What it means: You are holding down the reset button and are factory resetting this device.
What to do:
If you keep holding down the reset button, after about 12 seconds, the light will turn solid yellow. Once it is solid yellow, let go of the factory reset button.

Color: Solid yellow
What it means: Router is factory resetting.
What to do:
This can take up to 10 minutes. When it's done, the device will reset itself and start pulsing white, letting you know it's ready for setup.

Color: Solid red
What it means: Something is wrong.
What to do:
Critical failure. Factory reset the router. If the light stays red, contact Wifi customer support.
```

**Response:**
```none
Check that the Ethernet cable is connected to both your router and your modem and both devices are turned on. You might need to unplug and plug in each device again.
```

_(gemini-2.5-flash)_

## Break down prompts into components {% id="prompt-components" %}

For use cases that require complex prompts, you can help the model manage this
complexity by breaking things down into simpler components.

1.  **Break down instructions:** Instead of having many instructions in one
    prompt, create one prompt per instruction. You can choose which prompt to
    process based on the user's input.

2. **Chain prompts:** For complex tasks that involve multiple sequential steps,
   make each step a prompt and chain the prompts together in a sequence. In this
   sequential chain of prompts, the output of one prompt in the sequence becomes
   the input of the next prompt. The output of the last prompt in the sequence
   is the final output.

3. **Aggregate responses:** Aggregation is when you want to perform different
   parallel tasks on different portions of the data and aggregate the results to
   produce the final output. For example, you can tell the model to perform one
   operation on the first part of the data, perform another operation on the
   rest of the data and aggregate the results.

## Experiment with model parameters {% id="model-parameters" %}

Each call that you send to a model includes parameter values that control how
the model generates a response. The model can generate different results for
different parameter values. Experiment with different parameter values to get
the best values for the task. The parameters available for
different models may differ. The most common parameters are the following:

1.  **Max output tokens:** Specifies the maximum number of tokens that can be
    generated in the response. A token is approximately four characters. 100
    tokens correspond to roughly 60-80 words.

2.  **Temperature:** The temperature controls the degree of randomness in token
    selection. The temperature is used for sampling during response generation,
    which occurs when `topP` and `topK` are applied. Lower temperatures are good
    for prompts that require a more deterministic or less open-ended response,
    while higher temperatures can lead to more diverse or creative results. A
    temperature of 0 is deterministic, meaning that the highest probability
    response is always selected.

{% callout type="note" %}
    Note: {% partial file="googledevai/en/gemini-api/docs/_shared/temperature-warning.md" /%}
{% /callout %}

3.  **`topK`:** The `topK` parameter changes how the model selects tokens for
    output. A `topK` of 1 means the selected token is the most probable among
    all the tokens in the model's vocabulary (also called greedy decoding),
    while a `topK` of 3 means that the next token is selected from among the 3
    most probable using the temperature. For each token selection step, the
    `topK` tokens with the highest probabilities are sampled. Tokens are then
    further filtered based on `topP` with the final token selected using
    temperature sampling.

4.  **`topP`:** The `topP` parameter changes how the model selects tokens for
    output. Tokens are selected from the most to least probable until the sum of
    their probabilities equals the `topP` value. For example, if tokens A, B,
    and C have a probability of 0.3, 0.2, and 0.1 and the `topP` value is 0.5,
    then the model will select either A or B as the next token by using the
    temperature and exclude C as a candidate. The default `topP` value is 0.95.

5.  **`stop_sequences`:** Set a stop sequence to
    tell the model to stop generating content. A stop sequence can be any
    sequence of characters. Try to avoid using a sequence of characters that
    may appear in the generated content.

## Prompt iteration strategies {% id="iteration" %}

Prompt design can sometimes require a few iterations before
you consistently get the response you're looking for. This section provides
guidance on some things you can try when iterating on your prompts:

1.  **Use different phrasing:** Using different words or phrasing in your
    prompts often yields different responses from the model even though they
    all mean the same thing. If you're not getting the expected results from
    your prompt, try rephrasing it.

    ```none
Version 1:
    How do I bake a pie?

    Version 2:
    Suggest a recipe for a pie.

    Version 3:
    What's a good pie recipe?
    ```

2.  **Switch to an analogous task:** If you can't get the model to follow your
    instructions for a task, try giving it instructions for an analogous task
    that achieves the same result.

    This prompt tells the model to categorize a book by using predefined
    categories:

    **Prompt:**
```none
Which category does The Odyssey belong to:
    thriller
    sci-fi
    mythology
    biography
```

**Response:**
```none
The Odyssey belongs to the category of **mythology**.

        Here's why:

        * **Mythology:** The Odyssey tells the story of Odysseus, a hero from Greek mythology, and his
        journey home after the Trojan War. It features gods, monsters, and supernatural events common to
        Greek mythology.
    .....
```

_(gemini-2.5-flash)_

    The response is correct, but the model didn't stay within the bounds of the
    options. You also want to model to just respond with one of the options instead
    of in a full sentence. In this case, you can rephrase the instructions as a
    multiple choice question and ask the model to choose an option.

    **Prompt:**
```none
Multiple choice problem: Which of the following options describes the book The Odyssey?
    Options:

    - thriller
    - sci-fi
    - mythology
    - biography
```

**Response:**
```none
The correct answer is **mythology**.
```

_(gemini-2.5-flash)_

3.  **Change the order of prompt content:** The order of the content in the
    prompt can sometimes affect the response. Try changing the content order and
    see how that affects the response.

    ```none
    Version 1:
    [examples]
    [context]
    [input]

    Version 2:
    [input]
    [examples]
    [context]

    Version 3:
    [examples]
    [input]
    [context]
    ```

## Fallback responses {% id="fallback-responses" %}

A fallback response is a response returned by the model when either the prompt
or the response triggers a safety filter. An example of a fallback response is
"I'm not able to help with that, as I'm only a language model."

If the model responds with a fallback response, try increasing the temperature.

## Grounding and code execution {% id="grounding-and-code-execution" %}

Gemini is able to use tools to avoid hallucinations in scenarios where it might
otherwise produce incorrect responses.

[Grounding with Google Search](/docs/google-search) connects the
Gemini model to real-time web content, and should be enabled whenever the model
may need to know obscure or recent facts.

Gemini's [code execution tool](/docs/code-execution) enables the
model to generate and run Python code, and should be enabled whenever the model
needs to perform any kind of arithmetic, counting, or calculation.

## Gemini 3 {% id="gemini-3" %}

[Gemini 3 models](/docs/models#gemini-3) are designed for advanced
reasoning and instruction following.
They respond best to prompts that are direct, well-structured, and clearly
define the task and any constraints. The following practices are recommended for
optimal results with Gemini 3:

### Core prompting principles {% id="core-prompting-principles" %}

*   **Be precise and direct:** State your goal clearly and concisely. Avoid
    unnecessary or overly persuasive language.

*   **Use consistent structure:** Employ clear delimiters to separate different
    parts of your prompt. XML-style tags (e.g., `<context>`, `<task>`) or
    Markdown headings are effective. Choose one format and use it consistently
    within a single prompt.

*   **Define parameters:** Explicitly explain any ambiguous terms or parameters.
*   **Control output verbosity:** By default, Gemini 3 models provide direct and
    efficient answers. If you need a more conversational or detailed response,
    you must explicitly request it in your instructions.

*   **Handle multimodal inputs coherently:** When using text, images, audio, or
    video, treat them as equal-class inputs. Ensure your instructions clearly
    reference each modality as needed.

*   **Prioritize critical instructions:** Place essential behavioral
    constraints, role definitions (persona), and output format requirements in
    the System Instruction or at the very beginning of the user prompt.

*   **Structure for long contexts:** When providing large amounts of context
    (e.g., documents, code), supply all the context first. Place your specific
    instructions or questions at the very *end* of the prompt.

*   **Anchor context:** After a large block of data, use a clear transition
    phrase to bridge the context and your query, such as "Based on the
    information above..."

### Gemini 3 Flash strategies {% id="gemini-3-flash-strategies" %}

*   **Current day accuracy:** Add the following clause to the system
    instructions to help the model pay attention to the current day being in
    2026:

    ```none
    For time-sensitive user queries that require up-to-date information, you
    MUST follow the provided current time (date and year) when formulating
    search queries in tool calls. Remember it is 2026 this year.
    ```

*   **Knowledge cutoff accuracy:** Add the following clause to the system
    instructions to make the model aware of its knowledge cutoff:

    ```none
    Your knowledge cutoff date is January 2025.
    ```

*   **Grounding performance:** Add the following clause to the system
    instructions (with edits where appropriate) to improve the model's ability
    to ground responses in provided context:

    ```none
    You are a strictly grounded assistant limited to the information provided in
    the User Context. In your answers, rely **only** on the facts that are
    directly mentioned in that context. You must **not** access or utilize your
    own knowledge or common sense to answer. Do not assume or infer from the
    provided facts; simply report them exactly as they appear. Your answer must
    be factual and fully truthful to the provided text, leaving absolutely no
    room for speculation or interpretation. Treat the provided context as the
    absolute limit of truth; any facts or details that are not directly
    mentioned in the context must be considered **completely untruthful** and
    **completely unsupported**. If the exact answer is not explicitly written in
    the context, you must state that the information is not available.
    ```

### Enhancing reasoning and planning {% id="enhancing-reasoning-and-planning" %}

Gemini 2.5 and 3 series models automatically generate internal "thinking" text
to improve reasoning performance. As such, it's generally not necessary to have
the model outline, plan, or detail reasoning steps in the returned response
itself. For problems that require heavy reasoning, simple requests like "Think
very hard before answering" can improve performance, though at the cost of
extra thinking tokens.

See the [Gemini thinking](/docs/thinking) documentation for more
detail.

### Structured prompting examples {% id="structured-prompting-examples" %}

Using tags or Markdown helps the model distinguish between instructions,
context, and tasks.

**XML example:**

```xml
<role>
You are a helpful assistant.
</role>

<constraints>
1. Be objective.
2. Cite sources.
</constraints>

<context>
[Insert User Input Here - The model knows this is data, not instructions]
</context>

<task>
[Insert the specific user request here]
</task>
```

**Markdown example:**

```markdown
# Identity
You are a senior solution architect.

# Constraints
- No external libraries allowed.
- Python 3.11+ syntax only.

# Output format
Return a single code block.
```

### Example template combining best practices {% id="example-template-combining-best-practices" %}

This template captures the core principles for prompting with Gemini 3. Always
make sure to iterate and modify for your specific use case.

**System Instruction:**

```xml
<role>
You are Gemini 3, a specialized assistant for [Insert Domain, e.g., Data Science].
You are precise, analytical, and persistent.
</role>

<instructions>
1. **Plan**: Analyze the task and create a step-by-step plan.
2. **Execute**: Carry out the plan.
3. **Validate**: Review your output against the user's task.
4. **Format**: Present the final answer in the requested structure.
</instructions>

<constraints>
- Verbosity: [Specify Low/Medium/High]
- Tone: [Specify Formal/Casual/Technical]
</constraints>

<output_format>
Structure your response as follows:

1. **Executive Summary**: [Short overview]
2. **Detailed Response**: [The main content]
</output_format>
```

**User Prompt:**

```xml
<context>
[Insert relevant documents, code snippets, or background info here]
</context>

<task>
[Insert specific user request here]
</task>

<final_instruction>
Remember to think step-by-step before answering.
</final_instruction>
```

## Agentic workflows {% id="agentic-workflows" %}

For deep agentic workflows, specific instructions are often required to control
how the model reasons, plans, and executes tasks. While Gemini provides strong
general performance, complex agents often require you to configure the trade-off
between computational cost (latency and tokens) and task accuracy.

When designing prompts for agents, consider the following dimensions of behavior
that you can steer in the agent:

### Reasoning and strategy {% id="reasoning-and-strategy" %}

Configuration for how the model thinks and plans before taking action.

* **Logical decomposition:** Defines how thoroughly the model must analyze constraints, prerequisites, and the order of operations.
* **Problem diagnosis**: Controls the depth of analysis when identifying causes and the model’s use of abductive reasoning. Determines if the model should accept the most obvious answer or explore complex, less probable explanations.
* **Information exhaustiveness:** The trade-off between analyzing every available policy and document versus prioritizing efficiency and speed.

### Execution and reliability {% id="execution-and-reliability" %}

Configuration for how the agent operates autonomously and handles roadblocks.

* **Adaptability:** How the model reacts to new data. Determines whether it should strictly adhere to its initial plan or pivot immediately when observations contradict assumptions.
* **Persistence and Recovery:** The degree to which the model attempts to self-correct errors. High persistence increases success rates but risks higher token costs or loops.
* **Risk Assessment:** The logic for evaluating consequences. Explicitly distinguishes between low-risk exploratory actions (reads) and high-risk state changes (writes).

### Interaction and output {% id="interaction-and-output" %}

Configuration for how the agent communicates with the user and formats results.

* **Ambiguity and permission handling:** Defines when the model is permitted to make assumptions versus when it must pause execution to ask the user for clarification or permission.
* **Verbosity:** Controls the volume of text generated alongside tool calls. This determines if the model explains its actions to the user or remains silent during execution.
* **Precision and completeness:** The required fidelity of the output. Specifies whether the model must solve for every edge case and provide exact figures or if ballpark estimates are acceptable.

### System instruction template {% id="agentic-si-template" %}

The following system instruction is an example that has been evaluated by
researchers to improve performance on agentic benchmarks where the model must
adhere to a complex rulebook and interact with a user. It encourages the agent
to act as a strong reasoner and planner, enforces specific behaviors across
dimensions listed above and requires the model to proactively plan before taking
any action.

You can adapt this template to fit your specific use case constraints.

```markdown
You are a very strong reasoner and planner. Use these critical instructions to structure your plans, thoughts, and responses.

Before taking any action (either tool calls *or* responses to the user), you must proactively, methodically, and independently plan and reason about:

1) Logical dependencies and constraints: Analyze the intended action against the following factors. Resolve conflicts in order of importance:
    1.1) Policy-based rules, mandatory prerequisites, and constraints.
    1.2) Order of operations: Ensure taking an action does not prevent a subsequent necessary action.
        1.2.1) The user may request actions in a random order, but you may need to reorder operations to maximize successful completion of the task.
    1.3) Other prerequisites (information and/or actions needed).
    1.4) Explicit user constraints or preferences.

2) Risk assessment: What are the consequences of taking the action? Will the new state cause any future issues?
    2.1) For exploratory tasks (like searches), missing *optional* parameters is a LOW risk. **Prefer calling the tool with the available information over asking the user, unless** your `Rule 1` (Logical Dependencies) reasoning determines that optional information is required for a later step in your plan.

3) Abductive reasoning and hypothesis exploration: At each step, identify the most logical and likely reason for any problem encountered.
    3.1) Look beyond immediate or obvious causes. The most likely reason may not be the simplest and may require deeper inference.
    3.2) Hypotheses may require additional research. Each hypothesis may take multiple steps to test.
    3.3) Prioritize hypotheses based on likelihood, but do not discard less likely ones prematurely. A low-probability event may still be the root cause.

4) Outcome evaluation and adaptability: Does the previous observation require any changes to your plan?
    4.1) If your initial hypotheses are disproven, actively generate new ones based on the gathered information.

5) Information availability: Incorporate all applicable and alternative sources of information, including:
    5.1) Using available tools and their capabilities
    5.2) All policies, rules, checklists, and constraints
    5.3) Previous observations and conversation history
    5.4) Information only available by asking the user

6) Precision and Grounding: Ensure your reasoning is extremely precise and relevant to each exact ongoing situation.
    6.1) Verify your claims by quoting the exact applicable information (including policies) when referring to them.

7) Completeness: Ensure that all requirements, constraints, options, and preferences are exhaustively incorporated into your plan.
    7.1) Resolve conflicts using the order of importance in #1.
    7.2) Avoid premature conclusions: There may be multiple relevant options for a given situation.
        7.2.1) To check for whether an option is relevant, reason about all information sources from #5.
        7.2.2) You may need to consult the user to even know whether something is applicable. Do not assume it is not applicable without checking.
    7.3) Review applicable sources of information from #5 to confirm which are relevant to the current state.

8) Persistence and patience: Do not give up unless all the reasoning above is exhausted.
    8.1) Don't be dissuaded by time taken or user frustration.
    8.2) This persistence must be intelligent: On *transient* errors (e.g. please try again), you *must* retry **unless an explicit retry limit (e.g., max x tries) has been reached**. If such a limit is hit, you *must* stop. On *other* errors, you must change your strategy or arguments, not repeat the same failed call.

9) Inhibit your response: only take an action after all the above reasoning is completed. Once you've taken an action, you cannot take it back.
```

## Next steps {% id="next-steps" %}

-   Now that you have a deeper understanding of prompt design, try writing your
    own prompts using [Google AI Studio](http://aistudio.google.com).

-   To learn about multimodal prompting, see
    [Prompting with media files](/docs/files#prompt-guide).

-   To learn about image prompting, see the [Nano Banana](/docs/image-generation#prompt-guide)
    prompt guide.

-   To learn about video prompting, see the [Veo prompt guide](/docs/veo#prompt-guide).

# Logs and datasets
Source: https://aistudio.google.com/docs/logs-datasets
Description: Learn how to configure project logging, view logs in AI Studio, and create shared datasets.

In this guide you'll learn how to
view logs from Gemini API usage in the Google AI Studio dashboard
to better understand model behavior and how users may be interacting with your
applications. Use logging to observe, debug, and optionally share usage
feedback with Google to help improve Gemini across developer use cases. To learn
how Google uses logging data, see the
[Data Logging and Sharing](/docs/logs-policy) policy doc.

All `GenerateContent`, `BatchGenerateContent`, `StreamGenerateContent` API
calls, and [Interactions](/docs/interactions-overview) API calls excluding
Managed Agents are supported. This includes calls made through
[OpenAI compatibility](/docs/openai) endpoints.

{% callout type="note" %}
Storage for Gemini API logs are only available for projects on the
Gemini API paid tier.
{% /callout %}

## Configure project logging {% id="configure-logging" %}

By default, both the [Interactions](/docs/interactions-overview) API and the
Generate Content API store requests (`store=true`). For the Interactions API,
this also enables server-side state management features.

{% callout type="note" %}
Starting October 26, 2026, the Generate Content API stores requests by
default for *new* projects. Projects created before this date keep their
existing storage setting for the Generate Content API, which is off
(`store=false`) unless previously enabled in AI Studio.
{% /callout %}

In Google [AI Studio](/logs) you can enable or
disable storage for individual projects and change these
preferences at any time through the **Settings** panel in your
[Gemini API Logs Dashboard][logs_and_datasets]. You can toggle logging on or off
independently for the `generateContent` API and the
[Interactions](/docs/interactions-overview) API
to change the default storage behavior for a project.

{% callout type="warning" %}
Toggling Interactions API logging *off* in the AI Studio
**Settings** panel will prevent
the API from automatically storing and retrieving conversation history unless
explicitly overridden per-request.
{% /callout %}

### Request-level logging {% id="request-logging" %}

Both APIs store requests by default (`store=true`):

*   **[Interactions API](/docs/interactions-overview):** Stores requests by default to simplify server-side state management.
*   **Generate Content API (`generateContent`, `streamGenerateContent`, and
    `batchGenerateContent`):** Stores requests by default for projects created
    on or after October 26, 2026. Projects created before that date don't store
    requests by default (`store=false`) unless logging is enabled in AI Studio.

The request-level `store` property takes precedence over the project-level
setting. Setting `store` on Generate Content API requests requires
`google-genai` 2.33.0 or later for Python, `@google/genai` 2.31.0 or later
for JavaScript, `google-genai` 1.79.0 or later for Java, and
`google.golang.org/genai` 1.76.0 or later for Go. Here is how you can set
the `store` property:

**GenerateContent API**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents='Explain quantum entanglement in simple terms.',
    config={'store': True} # Set to False to disable logging of this request
)

print(response.text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const response = await client.models.generateContent({
    model: 'gemini-3.8-flash',
    contents: 'Explain quantum entanglement in simple terms.',
    config: {
        store: true // Set to false to disable logging of this request
    }
});

console.log(response.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        "Explain quantum entanglement in simple terms.",
        GenerateContentConfig.builder()
            .store(true) // Set to false to disable logging of this request
            .build());

System.out.println(response.text());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    response, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.8-flash",
        genai.Text("Explain quantum entanglement in simple terms."),
        &genai.GenerateContentConfig{
            Store: genai.Ptr(true), // Set to false to disable logging of this request
        },
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response.Text())
}
```
{% /tab %}

{% /tabs %}

**Interactions API**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain quantum entanglement in simple terms.",
    store=True # Set to False to disable logging of this request
)

print(interaction.outputs[-1].text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Explain quantum entanglement in simple terms.',
    store: true // Set to false to disable logging of this request
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain quantum entanglement in simple terms."))
        .store(true) // Set to false to disable logging of this request
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Explain quantum entanglement in simple terms."),
            Store: genai.Ptr(true), // Set to false to disable logging of this request
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% /tabs %}

## View project logs in AI Studio {% id="view-logs" %}

1. Go to the Logs page in [AI Studio](/logs).
1. Select a project from the drop-down.
1. Logs will appear in the table in reverse chronological order, if they exist.
1. For projects created before October 26, 2026, first enable Generate Content API logging in the [settings panel](/docs/logs-datasets#configure-logging) to observe project logs for the Generate Content API.

{% callout type="note" %}
A project requires at least one active API key for logs to be displayed. If all API keys in a project are deleted (for example, if a leaked key was deleted), you will lose visibility of the project's logs until an API key is available.
{% /callout %}

Click an entry for a preview of the payload. You can
inspect the full prompt and response from Gemini, and the context from the
previous turns. For **Interactions API** requests, logs also include a direct
link to the `previous_interaction_id`.

## Configure project storage retention {% id="retention" %}

Logs will expire and be marked for deletion after a default retention window of
55 days (unless [saved to a dataset](/docs/logs-datasets#create), which don't expire).
You can configure the retention window of a project's logs to 7, 14, 28, or 55
days max.

## Create and share datasets {% id="create" %}

You can save logs to datasets to organize and export them more effectively.

* From the [Logs page](https://aistudio.google.com/logs), locate the filter bar
  at the top to select a property to filter by.
* From your filtered view, use the checkboxes to select all or individual logs.
* Click the **Create dataset** button that appears at the top of the list.
* Give your new dataset a name and optional description.
* You will see the dataset you just created with the curated set of logs.
* Export your dataset for further analysis as CSV, JSONL files or to Google Sheets.

Datasets can be helpful for a number of different use cases.

* **Curate challenge sets:** Drive future improvements that target areas where you want your AI to improve.
* **Curate sample sets:** For example, a sample from real usage to generate responses from another model, or a collection of edge cases for routine checks before deployment.
* **Evaluation sets:** Sets that are representative of real usage across important capabilities, for comparison across other models or system instruction iterations.

You can contribute to Gemini research and development by choosing to share
your datasets with Google as demonstration examples.

## Limitations {% id="limitations" %}

Logging is not currently supported for the following:

* Imagen and Veo models
* Gemini embedding models
* Gemini Robotics model
* Inputs containing videos, GIFs or PDFs
* Public Preview Agents in the Gemini API

## What's next {% id="next-steps" %}

- **Prototype with session history:** Use [AI Studio Build](https://aistudio.google.com/apps) to vibe code apps and add your API key to enable a history of Gemini API logs for AI features.
- **Re-run logs with the Gemini Batch API:** Use datasets for response sampling
and evaluation of models or application logic by re-running logs with the
[Gemini Batch API][batch_api_cookbook].

[logs_and_datasets]: https://aistudio.google.com/logs
[batch_api_cookbook]: https://github.com/google-gemini/cookbook/blob/main/examples/Datasets.ipynb

# Data logging and sharing
Source: https://aistudio.google.com/docs/logs-policy
Description: The policy for sharing your data logs for Gemini improvements.

This page outlines the storage and management of
[Gemini API logs](/docs/logs-datasets), which are developer-owned
API data from supported Gemini API calls for projects with billing enabled. Logs
encompass the entire process from a user's request to the model's response.
These logs which are private to your Google Cloud project are separate from any
logs held solely for [abuse monitoring](/docs/usage-policies)
purposes.

## Data that can be shared {% id="shared-data" %}

Logging is on by default for Interactions API calls, and for Generate Content
API calls in projects created on or after October 26, 2026. As a project owner,
you can turn logging on or off at any time from the
[Logs and Datasets](/logs) page in AI Studio. Logs are for your own use, and you
can choose to share them with Google as feedback to help us continually improve
our models.

With logging enabled, you can help us build AI systems that continue to be
valuable for developers across various fields and use cases by choosing to
contribute the following data for product improvements and model training:

* **Datasets:** Use the Logs and Datasets interface of Google AI Studio to
choose logs (requests, responses, metadata etc.) of interest from
supported Gemini API calls; contributed through inclusion in datasets, with the
option to opt-out during dataset creation.

* **Feedback:** When reviewing logs, you can provide feedback; including thumbs
up and down ratings and any written comments you provide.

When you share a dataset with Google, your logs in that dataset, including
requests and responses, will be processed in accordance with our
[Terms](https://developers.google.com/terms) for
"[Unpaid Services](/docs/terms#data-use-unpaid)," meaning the dataset may be
used to develop and improve Google products, services, and machine learning
technologies, including improving and training our models.

Do not donate data from API clients available to users in the European Economic
Area, Switzerland, or the United Kingdom, and do not donate data that is
personal, sensitive, or confidential.

{% callout type="note" %}
Options are dependent on your location.
{% /callout %}

## How we use your data {% id="use-data" %}

Logs are retained for a default maximum period of 55 days. After this period,
logs are automatically marked for deletion. The storage retention window for a
project can be updated in AI Studio to automatically mark logs for deletion
after 7, 14, 28, or 55 days.

[Datasets](/docs/logs-datasets) can be created to retain logs of
interest beyond the set retention period for downstream use cases and
optional contribution to model improvements. Logs stored in datasets don't
have set retention periods.

By default, because logging is only available for billing-enabled projects,
prompts and responses within logs are not used for product improvement or
development, in accordance with our [Terms](https://developers.google.com/terms)
on data use.

If you choose to share datasets of your logs with Google, those datasets will be
used as real-world demonstration data to better understand the diversity of
domains and contexts AI systems and applications are used in. This data may be
used to improve model quality, and inform the training and evaluation of future
models and services. This data is processed in accordance with our data use
terms for [Unpaid Services](/docs/terms#data-use-unpaid).

Accordingly, human reviewers may read, annotate, and process the API inputs and
outputs you share. Before data is used for model improvement, Google takes steps
to protect user privacy as part of this process. This includes disconnecting
this data from your Google Account, API key, and Cloud project before reviewers
see or annotate it.

## Data permissions {% id="permissions" %}

By opting-in to contributing API data, you confirm that you have the necessary
permissions for Google to process and use the data as described in this
documentation. **Please do not contribute logs containing sensitive,
confidential, or proprietary information obtained through the paid service**.
The license you grant to Google under the "[Submission of Content](https://developers.google.com/terms#b_submission_of_content)"
section in the API Terms also extends, to the extent required under applicable
law for our use, to any content (e.g., prompts, including associated system
instructions, cached content, and files such as images, videos, or documents)
you submit to the Services and to any generated responses.

## Data sharing and feedback {% id="sharing-feedback" %}

You can help us advance the frontier of AI research, the Gemini API and Google
AI Studio by opting in to share your data as examples, enabling us to
continually improve our models across various contexts and build AI systems that
continue to be valuable to developers across various fields and use cases.

### Gemini API Contributor Tier {% id="contributor-tier" %}

{% callout type="note" %}
**New:** The Gemini API Contributor Tier is available as an invite-only private
preview. Eligible users will be invited by email and see a callout in AI Studio.
{% /callout %}

The Gemini Contributor Tier allows developers to get discounted token costs on
select models in exchange for permission to use data from those models to
provide, improve, and develop Google products and services and machine learning
technologies.

Developers receive up to 50% off token costs for select models, with the same
real-time performance of the [standard API](/docs/optimization). The following
models are supported:

| Model | Contributor Tier |
| ------------------ | :--------------------------: |
| [Gemini 4 Argon](/docs/pricing#gemini-4-argon) | ✔️ |
| [Gemini 3.1 Pro Preview](/docs/pricing#gemini-3.1-pro-preview) | ✔️ |
| [Gemini 3.8 Flash](/docs/pricing#gemini-3.8-flash) | ✔️ |
| [Gemini 3.5 Flash-Lite](/docs/pricing#gemini-3.5-flash-lite) | ✔️ |

**Data Use:**

*   By enabling the Contributor Tier for a project, your data from participating
    model use in your project will be used in accordance with our terms for
    "[Unpaid Services](/docs/terms#unpaid-services)." Because your data will be
    used to improve Google products and machine learning technologies, please
    don't submit sensitive or personal information.

# Safety settings
Source: https://aistudio.google.com/docs/safety-settings
Description: Configure content moderation filters and safety thresholds in the Gemini API.

The Gemini API provides safety settings that you can adjust during the
prototyping stage to determine if your application requires a more or less
restrictive safety configuration. You can adjust these settings across
filter categories to restrict or allow certain types of content.

This guide covers how to set safety settings on an interaction, what happens
when content is blocked, and which categories and thresholds you can use.

{% callout type="note" %}
Applications that use less restrictive safety settings may be subject to
review. See the [Terms of Service] for more information.
{% /callout %}

[Terms of Service]: /docs/terms#use-restrictions

## Set safety settings {% id="set-safety-settings" %}

Pass a list of `safety_settings` when you create an interaction. Each setting
pairs a harm category (`type`) with a block threshold (`threshold`).

The following example sets the hate speech (`hate_speech`) category to
`block_low_and_above`, which blocks any content that has a low or higher
probability of being hate speech:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Some potentially unsafe prompt.",
    safety_settings=[
        {
            "type": "hate_speech",
            "threshold": "block_low_and_above",
        }
    ],
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Some potentially unsafe prompt.",
    safety_settings: [
      {
        type: "hate_speech",
        threshold: "block_low_and_above",
      },
    ],
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.HarmCategory;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.SafetySetting;
import com.google.genai.gaos.models.interactions.Threshold;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

SafetySetting hateSpeechSafety =
    SafetySetting.builder()
        .type(HarmCategory.HATE_SPEECH)
        .threshold(Threshold.BLOCK_LOW_AND_ABOVE)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Some potentially unsafe prompt."))
        .safetySettings(List.of(hateSpeechSafety))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Some potentially unsafe prompt."),
            SafetySettings: []interactions.SafetySetting{
                {
                    Type:      interactions.HarmCategoryHateSpeech,
                    Threshold: interactions.ThresholdBlockLowAndAbove,
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Some potentially unsafe prompt.",
    "safety_settings": [
      {"type": "hate_speech", "threshold": "block_low_and_above"}
    ]
  }'
```
{% /tab %}
{% /tabs %}

You can include one setting per category. Categories you don't set use the
default threshold, which is **Off** for Gemini 2.5 and later models.

## When content is blocked {% id="when-content-is-blocked" %}

If a safety filter blocks the input or the model's response, the interaction
fails with an HTTP `400` error. The blocked content isn't returned.

The error `code` tells you why the request was blocked:

*   `safety`: The input or response was blocked by a safety filter.
*   `jailbreak`, `prohibited_content`, or `blocklist`: The input was blocked
    for that reason. The error `message` starts with `Input blocked:`.

For example:

```json
{
  "error": {
    "code": "safety",
    "message": "Request blocked due to safety violations (harmful content). Please modify your input and retry."
  }
}
```

For background interactions (`background=true`), the interaction's `status` is
set to `failed`, and the same `code` and `message` appear in its `errors` list.
When streaming, the error arrives as an `error` event.

## Safety filters {% id="safety-filters" %}

The Gemini API's adjustable safety filters cover the following categories:

{% table %}
* Category
* Value (API)
* Description
---

* Harassment
* `harassment`
* Abusive, threatening, or content intended to bully, torment, or ridicule.
---

* Hate speech
* `hate_speech`
* Content that promotes violence or incites hatred against individuals or
  groups based on certain attributes.
---

* Sexually explicit
* `sexually_explicit`
* Content that contains sexually explicit material.
---

* Dangerous
* `dangerous_content`
* Content that promotes, facilitates, or enables dangerous activities.
---

* Jailbreak
* `jailbreak`
* Prompts designed to bypass safety filters.
{% /table %}

You can use these filters to adjust what's appropriate for your use case. For
example, if you're building video game dialogue, you may deem it acceptable to
allow more content that's rated as *Dangerous* due to the nature of the game.

In addition to the adjustable safety filters, the Gemini API has built-in
protections against core harms, such as content that endangers child safety.
These types of harm are always blocked and cannot be adjusted.

## Block thresholds {% id="safety-filtering-per-request" %}

Due to the model's inherent safety, additional filters are **Off** by default.
The default model behavior covers most use cases, so you should only adjust
these settings if it's consistently required for your application.

The following table describes the thresholds you can set for each category. For
example, if you set **Hate speech** to **Block few** (`block_only_high`),
content with a high probability of being hate speech is blocked, and anything
with a lower probability is allowed.

{% table %}
* Threshold (Google AI Studio)
* Threshold (API)
* Description
---

* Off
* `off`
* Turn off the safety filter
---

* Block few
* `block_only_high`
* Block when high probability of unsafe content
---

* Block some
* `block_medium_and_above`
* Block when medium or high probability of unsafe content
---

* Block most
* `block_low_and_above`
* Block when low, medium or high probability of unsafe content
{% /table %}

### Probability versus severity {% id="safety-filtering-level" %}

The Gemini API rates the probability of content being unsafe as high, medium,
low, or negligible. It blocks content based on that probability, not on the
severity of the harm. Some content can have a low probability of being unsafe
even though the harm could be severe. For example, compare these sentences:

1. The robot punched me.
2. The robot slashed me up.

The first sentence might have a higher probability of being unsafe, but you
might consider the second more severe. Test carefully to find the level of
blocking that supports your use case while minimizing harm to end users.

## Adjust safety settings in Google AI Studio {% id="safety-settings-ai-studio" %}

Click **Safety settings** under **Advanced settings** in the **Run settings**
panel to open the **Run safety settings** modal. In the modal, you can use the
sliders to adjust the content filtering level per safety category:

{% image
  src="/googledevai/static/gemini-api/docs/images/safety_settings_ui.png"
  alt="A rendering of the safety settings options in AI Studio"
  caption=""
  variant="screenshot"
/%}

{% callout type="note" %}
You are responsible for ensuring that safety settings for your intended
use case comply with the [Terms of Service].
{% /callout %}

When you send a request (for example, by asking the model a question), a
{% icon name="warning" /%} **Content blocked** message appears if the request's
content is blocked. To see more details, hold the pointer over the
**Content blocked** text to see the category and the probability of the harm
classification.

## Next steps {% id="next-steps" %}

* See the [Interactions API reference](https://ai.google.dev/api/interactions-api)
  to learn more about the full API.
* Review the [safety guidance](/docs/safety-guidance) for a general look at safety
  considerations when developing with LLMs.
* Learn more about assessing probability versus severity from the [Jigsaw
  team](https://developers.perspectiveapi.com/s/about-the-api-score).
* Learn more about the products that contribute to safety solutions like the
  [Perspective
  API](https://medium.com/jigsaw/reducing-toxicity-in-large-language-models-with-perspective-api-c31c39b7a4d7).

# Safety and factuality guidance
Source: https://aistudio.google.com/docs/safety-guidance
Description: Apply best practices for safety, fairness, and factuality in Gemini apps.

Generative artificial intelligence models are powerful tools, but they are not
without their limitations. Their versatility and applicability can sometimes
lead to unexpected outputs, such as outputs that are inaccurate, biased, or
offensive. Post-processing, and rigorous manual evaluation are essential to
limit the risk of harm from such outputs.

The models provided by the Gemini API can be used for a wide variety of
generative AI and natural language processing (NLP) applications. Use of these
functions is only available through the Gemini API or the Google AI Studio web
app. Your use of Gemini API is also subject to the [Generative AI Prohibited Use
Policy](https://policies.google.com/terms/generative-ai/use-policy) and the
[Gemini API terms of service](/docs/terms).

Part of what makes large language models (LLMs) so useful is that they're
creative tools that can address many different language tasks. Unfortunately,
this also means that large language models can generate output that you don't
expect, including text that's offensive, insensitive, or factually incorrect.
What's more, the incredible versatility of these models is also what makes it
difficult to predict exactly what kinds of undesirable output they might
produce. While the Gemini API has been designed with
[Google's AI principles](https://ai.google/principles/)
in mind, the onus is on developers to apply these models responsibly. To aid
developers in creating safe, responsible applications, the Gemini API has some
built-in content filtering as well as adjustable safety settings across 4
dimensions of harm. Refer to the [safety settings](/docs/safety-settings) guide to
learn more. It also offers Grounding with Google Search enabled to improve
factuality, though this may be disabled for developers whose use cases are
more creative and not information-seeking.

This document is meant to introduce you to some safety risks that can arise when
using LLMs, and recommend emerging safety design and development
recommendations. (Note that laws and regulations may also impose restrictions,
but such considerations are beyond the scope of this guide.)

The following steps are recommended when building applications with LLMs:

* Understanding the safety risks of your application
* Considering adjustments to mitigate safety risks
* Performing safety testing appropriate to your use case
* Soliciting feedback from users and monitoring usage

The adjustment and testing phases should be iterative until you reach
performance appropriate for your application.

![Model implementation cycle](/googledevai/static/gemini-api/docs/images/safety_diagram.png)

## Understand the safety risks of your application {% id="understand-the-safety-risks-of-your-application" %}

In this context, safety is being defined as the ability of an LLM to avoid
causing harm to its users, for example, by generating toxic language or content
that promotes stereotypes. The models available through the Gemini API have been
designed with [Google’s AI principles](https://ai.google/principles/) in mind
and your use of it is subject to the [Generative AI Prohibited Use
Policy](https://policies.google.com/terms/generative-ai/use-policy). The API
provides built-in safety filters to help address some common language model
problems such as toxic language and hate speech, and striving for inclusiveness
and avoidance of stereotypes. However, each application can pose a different set
of risks to its users. So as the application owner, you are responsible for
knowing your users and the potential harms your application may cause, and
ensuring that your application uses LLMs safely and responsibly.

As part of this assessment, you should consider the likelihood that harm could
occur and determine its seriousness and mitigation steps. For example, an
app that generates essays based on factual events would need to be more careful
about avoiding misinformation, as compared to an app that generates fictional
stories for entertainment. A good way to begin exploring potential safety risks
is to research your end users, and others who might be affected by your
application's results. This can take many forms including researching state of
the art studies in your app domain, observing how people are using similar apps,
or running a user study, survey, or conducting informal interviews with
potential users.

### Advanced tips {% id="advanced-tips" %}

* Speak with a diverse mix of prospective users within your target
    population about your application and its intended purpose so as
    to get a wider perspective on potential risks and to adjust diversity
    criteria as needed.

* The [AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework)
    released by the U.S. government's
    National Institute of Standards and Technology (NIST) provides more
    detailed guidance and additional learning resources for AI risk management.

* DeepMind's publication on the
    [ethical and social risks of harm from language models](https://arxiv.org/abs/2112.04359)
    describes in detail the ways that language model
    applications can cause harm.

## Consider adjustments to mitigate safety and factuality risks {% id="consider-adjustments-to-mitigate-safety-and-factuality-risks" %}

Now that you have an understanding of the risks, you can decide how to mitigate
them. Determining which risks to prioritize and how much you should do to try to
prevent them is a critical decision, similar to triaging bugs in a software
project. Once you've determined priorities, you can start thinking about the
types of mitigations that would be most appropriate. Often simple changes can
make a difference and reduce risks.

For example, when designing an application consider:

* **Tuning the model output** to better reflect what is acceptable in your
    application context. Tuning can make the output of the model more
    predictable and consistent and therefore can help mitigate certain risks.

* **Providing an input method that facilities safer outputs.** The exact input
    you give to an LLM can make a difference in the quality of the output.
    Experimenting with input prompts to find what works most safely in your
    use-case is well worth the effort, as you can then provide a UX that
    facilitates it. For example, you could restrict users to choose only from a
    drop-down list of input prompts, or offer pop-up suggestions with
    descriptive
    phrases which you've found perform safely in your application context.

* **Blocking unsafe inputs and filtering output before it is shown to the
    user.** In simple situations, blocklists can be used to identify and block
    unsafe words or phrases in prompts or responses, or require human reviewers
    to manually alter or block such content.

{% callout type="note" %}
    Note: Automatically blocking based on a static list can have unintended
    results such as targeting a particular group that commonly uses vocabulary
    in the blocklist.
{% /callout %}

* **Using trained classifiers to label each prompt with potential harms or
    adversarial signals.** Different strategies can then be employed on how to
    handle the request based on the type of harm detected. For example, If the
    input is overtly adversarial or abusive in nature, it could be blocked and
    instead output a pre-scripted response.
    **Advanced tip:** If signals determine the output to be harmful, the
    application can employ the following options:

    * Provide an error message or pre-scripted output.
    * Try the prompt again, in case an alternative safe output is
        generated, since sometimes the same prompt will elicit different
        outputs.

* **Putting safeguards in place against deliberate misuse** such as assigning
    each user a unique ID and imposing a limit on the volume of user queries
    that can be submitted in a given period. Another safeguard is to try and
    protect against possible prompt injection. Prompt injection, much like SQL
    injection, is a way for malicious users to design an input prompt that
    manipulates the output of the model, for example, by sending an input prompt
    that instructs the model to ignore any previous examples. See the
    [Generative AI Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy)
    for details about deliberate misuse.

* **Adjusting functionality to something that is inherently lower risk.**
    Tasks that are narrower in scope (e.g., extracting keywords from passages of
    text) or that have greater human oversight (e.g., generating short-form
    content that will be reviewed by a human), often pose a lower risk. So for
    instance, instead of creating an application to write an email reply from
    scratch, you might instead limit it to expanding on an outline or suggesting
    alternative phrasings.

* **Adjusting harmful content safety settings to decrease how likely you are to
    see responses that could be harmful.** The Gemini API provides safety
    settings that you can adjust during the prototyping stage to determine if
    your application requires more or less restrictive safety configuration. You
    can adjust these settings across five filter categories to restrict or allow
    certain types of content. Refer to the
    [safety settings guide](/docs/safety-settings) to learn about
    the adjustable safety settings available through the Gemini API.

* **Decrease potential factual inaccuracies or hallucinations by enabling
    Grounding with Google Search**. Remember, many AI models are experimental
    and may present factually inaccurate information, hallucinate, or otherwise
    produce problematic outputs. The Grounding with Google Search feature
    connects the Gemini model to real-time web content and works with all
    available languages. This allows Gemini to provide more accurate answers and
    cite verifiable sources beyond the models knowledge cutoff.

## Perform safety testing appropriate to your use case {% id="perform-safety-testing-appropriate-to-your-use-case" %}

Testing is a key part of building robust and safe applications, but the extent,
scope and strategies for testing will vary. For example, a just-for-fun haiku
generator is likely to pose less severe risks than, say, an application designed
for use by law firms to summarize legal documents and help draft contracts. But
the haiku generator may be used by a wider variety of users which means the
potential for adversarial attempts or even unintended harmful inputs can be
greater. The implementation context also matters. For instance, an application
with outputs that are reviewed by human experts prior to any action being taken
might be deemed less likely to produce harmful outputs than the identical
application without such oversight.

It's not uncommon to go through several iterations of making changes and testing
before feeling confident that you're ready to launch, even for applications that
are relatively low risk. Two kinds of testing are particularly useful for AI
applications:

* **Safety benchmarking** involves designing safety metrics that reflect the
    ways your application could be unsafe in the context of how it is likely to
    get used, then testing how well your application performs on the metrics
    using evaluation datasets. It's good practice to think about the minimum
    acceptable levels of safety metrics before testing so that 1) you can
    evaluate the test results against those expectations and 2) you can gather
    the evaluation dataset based on the tests that evaluate the metrics you care
    about most.

    **Advanced tips:**

    * Beware of over-relying on “off the shelf” approaches as it's
        likely you'll need to build your own testing datasets using human
        raters to fully suit your application's context.

    * If you have more than one metric you'll need to decide how you'll
        trade off if a change leads to improvements for one metric to the
        detriment of another. Like with other performance engineering,
        you may want to focus on worst-case performance across your
        evaluation set rather than average performance.

* **Adversarial testing** involves proactively trying to break your
    application. The goal is to identify points of weakness so that you can take
    steps to remedy them as appropriate. Adversarial testing can take
    significant time/effort from evaluators with expertise in your application —
    but the more you do, the greater your chance of spotting problems,
    especially those occurring rarely or only after repeated runs of the
    application.

    * Adversarial testing is a method for systematically evaluating an ML
        model with the intent of learning how it behaves when provided with
        malicious or inadvertently harmful input:

        * An input may be malicious when the input is clearly designed to
            produce an unsafe or harmful output-- for example, asking a text
            generation model to generate a hateful rant about a particular
            religion.

        * An input is inadvertently harmful when the input itself may be
            innocuous, but produces harmful output -- for example, asking a text
            generation model to describe a person of a particular ethnicity and
            receiving a racist output.

    * What distinguishes an adversarial test from a standard evaluation is the
        composition of the data used for testing. For adversarial tests, select
        test data that is most likely to elicit problematic output from
        the model. This means probing the model's behavior for all the types of
        harms that are possible, including rare or unusual examples and
        edge-cases that are relevant to safety policies. It should also include
        diversity in the different dimensions of a sentence such as structure,
        meaning and length. You can refer to the [Google's Responsible AI
        practices in
        fairness](https://ai.google/responsibilities/responsible-ai-practices/?category=fairness)
        for more details on what to consider when building a test dataset.
    **Advanced tips:**

    * Use [automated testing](https://www.deepmind.com/blog/red-teaming-language-models-with-language-models)
        instead of the traditional method of enlisting people in 'red
        teams' to try and break your application. In automated testing,
        the 'red team' is another language model that finds input text
        that elicit harmful outputs from the model being tested.

{% callout type="note" %}
 Note: LLMs are known to sometimes produce different outputs for the
       same input prompt. Multiple rounds of testing may be needed to catch more
       of the problematic outputs.
{% /callout %}

## Monitor for problems {% id="monitor-for-problems" %}

No matter how much you test and mitigate, you can never guarantee perfection, so
plan upfront how you'll spot and deal with problems that arise. Common
approaches include setting up a monitored channel for users to share feedback
(e.g., thumbs up/down rating) and running a user study to proactively solicit
feedback from a diverse mix of users — especially valuable if usage patterns are
different to expectations.

### Advanced tips {% id="advanced-tips" %}

* When users give feedback to AI products, it can greatly improve the AI
    performance and the user experience over time by, for example,
    helping you choose better examples for prompt tuning. The
    [Feedback and Control chapter](https://pair.withgoogle.com/chapter/feedback-controls/)
    in [Google's People and AI guidebook](https://pair.withgoogle.com/guidebook/chapters)
    highlights key considerations to take into account when designing
    feedback mechanisms.

## Next steps {% id="next-steps" %}

* Refer to the
    [safety settings](/docs/safety-settings) guide to learn about the adjustable
    safety settings available through the Gemini API.

* See the [intro to prompting](/docs/prompting-strategies) to get
    started writing your first prompts.

# ReAct agent from scratch with Gemini and LangGraph
Source: https://aistudio.google.com/docs/langgraph-example
Description: Building LangGraph Agents with Gemini

LangGraph is a framework for building stateful LLM applications, making it a
good choice for constructing ReAct (Reasoning and Acting) Agents.

ReAct agents combine LLM reasoning with action execution. They iteratively
think, use tools, and act on observations to achieve user goals, dynamically
adapting their approach. Introduced in ["ReAct: Synergizing Reasoning and Acting
in Language Models"](https://arxiv.org/abs/2210.03629) (2023), this pattern
tries to mirror human-like, flexible problem-solving over rigid workflows.

LangGraph offers a prebuilt ReAct agent ([
    `create_react_agent`](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent)),
that shines when you need more control and customization for your ReAct
implementations. This guide will show you a simplified version.

LangGraph models agents as graphs using three key components:

* `State`: Shared data structure (typically `TypedDict` or `Pydantic BaseModel`) representing the application's current snapshot.
* `Nodes`: Encodes logic of your agents. They receive the current State as input, perform some computation or side-effect, and return an updated State, such as LLM calls or tool calls.
* `Edges`: Define the next `Node` to execute based on the current `State`, allowing for conditional logic and fixed transitions.

If you don't have an API Key yet, you can get one from [Google AI
Studio](https://aistudio.google.com/apikey).

```bash
pip install langgraph langchain-google-genai geopy requests
```

Set your API key in the environment variable `GEMINI_API_KEY`.

```python
import os

# Read your API key from the environment variable or set it manually
api_key = os.getenv("GEMINI_API_KEY")
```

To better understand how to implement a ReAct agent using LangGraph, this guide
will walk through a practical example. You will create an agent whose goal is to
use a tool to find the current weather for a specified location.

For this weather agent, the `State` will maintain the ongoing conversation
history (as a list of messages) and a counter (as an integer) for the number of
steps taken, for illustrative purposes.

LangGraph provides a helper function, `add_messages`, for updating state message
lists. It functions as a
[reducer](https://langchain-ai.github.io/langgraph/concepts/low_level/#reducers),
taking the current list, plus the new messages, and returns a combined list. It
handles updates by message ID and defaults to an "append-only" behavior for new,
unseen messages.

{% callout type="note" %}
Note: Since having a list of messages in the state is common, there exists a
prebuilt state called `MessagesState` that you can use as a base class. For this
example the messages will be listed explicitly.
{% /callout %}

```python
from typing import Annotated,Sequence, TypedDict

from langchain_core.messages import BaseMessage
from langgraph.graph.message import add_messages # helper function to add messages to the state

class AgentState(TypedDict):
    """The state of the agent."""
    messages: Annotated[Sequence[BaseMessage], add_messages]
    number_of_steps: int
```

Next, define your weather tool.

```python
from langchain_core.tools import tool
from geopy.geocoders import Nominatim
from pydantic import BaseModel, Field
import requests

geolocator = Nominatim(user_agent="weather-app")

class SearchInput(BaseModel):
    location:str = Field(description="The city and state, e.g., San Francisco")
    date:str = Field(description="the forecasting date for when to get the weather format (yyyy-mm-dd)")

@tool("get_weather_forecast", args_schema=SearchInput, return_direct=True)
def get_weather_forecast(location: str, date: str):
    """Retrieves the weather using Open-Meteo API.

    Takes a given location (city) and a date (yyyy-mm-dd).

    Returns:
        A dict with the time and temperature for each hour.
    """
    # Note that Colab may experience rate limiting on this service. If this
    # happens, use a machine to which you have exclusive access.
    location = geolocator.geocode(location)
    if location:
        try:
            response = requests.get(f"https://api.open-meteo.com/v1/forecast?latitude={location.latitude}&longitude={location.longitude}&hourly=temperature_2m&start_date={date}&end_date={date}")
            data = response.json()
            return dict(zip(data["hourly"]["time"], data["hourly"]["temperature_2m"]))
        except Exception as e:
            return {"error": str(e)}
    else:
        return {"error": "Location not found"}

tools = [get_weather_forecast]
```

Now initialize the model and bind the tools to the model.

```python
from datetime import datetime
from langchain_google_genai import ChatGoogleGenerativeAI

# Create LLM class
llm = ChatGoogleGenerativeAI(
    model= "gemini-3.8-flash",
    temperature=1.0,
    max_retries=2,
    google_api_key=api_key,
)

# Bind tools to the model
model = llm.bind_tools([get_weather_forecast])

# Test the model with tools
res=model.invoke(f"What is the weather in Berlin on {datetime.today()}?")

print(res)
```

The last step before you can run your agent is to define your nodes and edges.
In this example, you have two nodes and one edge.

- `call_tool` node that executes your tool method. LangGraph has a prebuilt node
  for this called
  [ToolNode](https://langchain-ai.github.io/langgraph/how-tos/tool-calling/).

- `call_model` node that uses the `model_with_tools` to call the model.
- `should_continue` edge that decides whether to call the tool or the model.

The number of nodes and edges is not fixed. You can add as many nodes and edges
as you want to your graph. For example, you could add a node for adding
structured output or a self-verification/reflection node to check the model
output before calling the tool or the model.

```python
from langchain_core.messages import ToolMessage
from langchain_core.runnables import RunnableConfig

tools_by_name = {tool.name: tool for tool in tools}

# Define our tool node
def call_tool(state: AgentState):
    outputs = []
    # Iterate over the tool calls in the last message
    for tool_call in state["messages"][-1].tool_calls:
        # Get the tool by name
        tool_result = tools_by_name[tool_call["name"]].invoke(tool_call["args"])
        outputs.append(
            ToolMessage(
                content=tool_result,
                name=tool_call["name"],
                tool_call_id=tool_call["id"],
            )
        )
    return {"messages": outputs}

def call_model(
    state: AgentState,
    config: RunnableConfig,
):
    # Invoke the model with the system prompt and the messages
    response = model.invoke(state["messages"], config)
    # This returns a list, which combines with the existing messages state
    # using the add_messages reducer.
    return {"messages": [response]}

# Define the conditional edge that determines whether to continue or not
def should_continue(state: AgentState):
    messages = state["messages"]
    # If the last message is not a tool call, then finish
    if not messages[-1].tool_calls:
        return "end"
    # default to continue
    return "continue"
```

With all of the agent components ready, you can now assemble them.

```python
from langgraph.graph import StateGraph, END

# Define a new graph with our state
workflow = StateGraph(AgentState)

# 1. Add the nodes
workflow.add_node("llm", call_model)
workflow.add_node("tools", call_tool)
# 2. Set the entrypoint as `agent`, this is the first node called
workflow.set_entry_point("llm")
# 3. Add a conditional edge after the `llm` node is called.
workflow.add_conditional_edges(
    # Edge is used after the `llm` node is called.
    "llm",
    # The function that will determine which node is called next.
    should_continue,
    # Mapping for where to go next, keys are strings from the function return,
    # and the values are other nodes.
    # END is a special node marking that the graph is finish.
    {
        # If `tools`, then we call the tool node.
        "continue": "tools",
        # Otherwise we finish.
        "end": END,
    },
)
# 4. Add a normal edge after `tools` is called, `llm` node is called next.
workflow.add_edge("tools", "llm")

# Now we can compile and visualize our graph
graph = workflow.compile()
```

You can visualize your graph using the `draw_mermaid_png` method.

```python
from IPython.display import Image, display

display(Image(graph.get_graph().draw_mermaid_png()))
```

![png](/googledevai/static/gemini-api/docs/images/langgraph-react-agent_16_0.png)

Now run the agent.

```python
from datetime import datetime
# Create our initial message dictionary
inputs = {"messages": [("user", f"What is the weather in Berlin on {datetime.today()}?")]}

# call our graph with streaming to see the steps
for state in graph.stream(inputs, stream_mode="values"):
    last_message = state["messages"][-1]
    last_message.pretty_print()
```

You can now continue with your conversation, ask for the weather in another
city, or request a comparison.

```python
state["messages"].append(("user", "Would it be warmer in Munich?"))

for state in graph.stream(state, stream_mode="values"):
    last_message = state["messages"][-1]
    last_message.pretty_print()
```

# Customer support analysis with Gemini and CrewAI
Source: https://aistudio.google.com/docs/crewai-example
Description: Building CrewAI Agents with Gemini

[CrewAI](https://docs.crewai.com/introduction) is a framework for orchestrating
autonomous AI agents that collaborate to achieve complex goals. It lets you
define agents by specifying roles, goals, and backstories, and then define tasks
for them.

This example demonstrates how to build a multi-agent system for analyzing
customer support data to identify issues and propose process improvements using
Gemini 3 Flash, generating a report intended to be read by a Chief Operating
Officer (COO).

The guide will show you how to create a "crew" of AI agents that can do the
following tasks:

1. Fetch and analyze customer support data (simulated in this example).
2. Identify recurring problems and process bottlenecks.
3. Suggest actionable improvements.
4. Compile the findings into a concise report suitable for a COO.

You need a Gemini API key. If you don't already have one, you can [get one in
Google AI Studio](https://aistudio.google.com/apikey).

```posix-terminal
pip install "crewai[tools]"
```

Set your Gemini API key as an environment variable named `GEMINI_API_KEY`, then
configure CrewAI to use the Gemini model.

```python
import os
from crewai import LLM

gemini_api_key = os.getenv("GEMINI_API_KEY")

gemini_llm = LLM(
    model='gemini/gemini-3.8-flash',
    api_key=gemini_api_key,
    temperature=1.0 # Use the Gemini 3 recommended temperature
)
```

## Define components {% id="components" %}

Build CrewAI applications using **Tools**, **Agents**, **Tasks**, and the
**Crew** itself. The following sections explain each of these components.

### Tools {% id="tools" %}

Tools are capabilities that agents can use to interact with the outside world or
perform specific actions. Here, you define a placeholder tool to simulate
fetching customer support data. In a real application, you would connect to a
database, API or file system. For more information on tools, see the [CrewAI
tools guide](https://docs.crewai.com/concepts/tools).

```python
from crewai.tools import BaseTool

# Placeholder tool for fetching customer support data
class CustomerSupportDataTool(BaseTool):
    name: str = "Customer Support Data Fetcher"
    description: str = (
      "Fetches recent customer support interactions, tickets, and feedback. "
      "Returns a summary string.")

    def _run(self, argument: str) -> str:
        # In a real scenario, this would query a database or API.
        # For this example, return simulated data.
        print(f"--- Fetching data for query: {argument} ---")
        return (
            """Recent Support Data Summary:

- 50 tickets related to 'login issues'. High resolution time (avg 48h).
- 30 tickets about 'billing discrepancies'. Mostly resolved within 12h.
- 20 tickets on 'feature requests'. Often closed without resolution.
- Frequent feedback mentions 'confusing user interface' for password reset.
- High volume of calls related to 'account verification process'.
- Sentiment analysis shows growing frustration with 'login issues' resolution time.
- Support agent notes indicate difficulty reproducing 'login issues'."""
        )

support_data_tool = CustomerSupportDataTool()
```

### Agents {% id="agents" %}

Agents are the individual AI workers in your crew. Each agent has a specific
`role`, `goal`, `backstory`, assigned `llm`, and optional `tools`. For more
information on agents, see the [CrewAI agents
guide](https://docs.crewai.com/concepts/agents).

```python
from crewai import Agent

# Agent 1: Data analyst
data_analyst = Agent(
    role='Customer Support Data Analyst',
    goal='Analyze customer support data to identify trends, recurring issues, and key pain points.',
    backstory=(
        """You are an expert data analyst specializing in customer support operations.
        Your strength lies in identifying patterns and quantifying problems from raw support data."""
    ),
    verbose=True,
    allow_delegation=False, # This agent focuses on its specific task
    tools=[support_data_tool], # Assign the data fetching tool
    llm=gemini_llm # Use the configured Gemini LLM
)

# Agent 2: Process optimizer
process_optimizer = Agent(
    role='Process Optimization Specialist',
    goal='Identify bottlenecks and inefficiencies in current support processes based on the data analysis. Propose actionable improvements.',
    backstory=(
        """You are a specialist in optimizing business processes, particularly in customer support.
        You excel at pinpointing root causes of delays and inefficiencies and suggesting concrete solutions."""
    ),
    verbose=True,
    allow_delegation=False,
    # No tools needed, this agent relies on the context provided by data_analyst.
    llm=gemini_llm
)

# Agent 3: Report writer
report_writer = Agent(
    role='Executive Report Writer',
    goal='Compile the analysis and improvement suggestions into a concise, clear, and actionable report for the COO.',
    backstory=(
        """You are a skilled writer adept at creating executive summaries and reports.
        You focus on clarity, conciseness, and highlighting the most critical information and recommendations for senior leadership."""
    ),
    verbose=True,
    allow_delegation=False,
    llm=gemini_llm
)
```

### Tasks {% id="tasks" %}

Tasks define the specific assignments for the agents. Each task has a
`description`, `expected_output`, and is assigned to an `agent`. Tasks are run
sequentially by default and include the context of the previous task. For more
information on tasks, see the [CrewAI tasks
guide](https://docs.crewai.com/concepts/tasks).

```python
from crewai import Task

# Task 1: Analyze data
analysis_task = Task(
    description=(
        """Fetch and analyze the latest customer support interaction data (tickets, feedback, call logs)
        focusing on the last quarter. Identify the top 3-5 recurring issues, quantify their frequency
        and impact (e.g., resolution time, customer sentiment). Use the Customer Support Data Fetcher tool."""
    ),
    expected_output=(
        """A summary report detailing the key findings from the customer support data analysis, including:

- Top 3-5 recurring issues with frequency.
- Average resolution times for these issues.
- Key customer pain points mentioned in feedback.
- Any notable trends in sentiment or support agent observations."""
    ),
    agent=data_analyst # Assign task to the data_analyst agent
)

# Task 2: Identify bottlenecks and suggest improvements
optimization_task = Task(
    description=(
        """Based on the data analysis report provided by the Data Analyst, identify the primary bottlenecks
        in the support processes contributing to the identified issues (especially the top recurring ones).
        Propose 2-3 concrete, actionable process improvements to address these bottlenecks.
        Consider potential impact and ease of implementation."""
    ),
    expected_output=(
        """A concise list identifying the main process bottlenecks (e.g., lack of documentation for agents,
        complex escalation path, UI issues) linked to the key problems.
A list of 2-3 specific, actionable recommendations for process improvement
(e.g., update agent knowledge base, simplify password reset UI, implement proactive monitoring)."""
    ),
    agent=process_optimizer # Assign task to the process_optimizer agent
    # This task implicitly uses the output of analysis_task as context
)

# Task 3: Compile COO report
report_task = Task(
    description=(
        """Compile the findings from the Data Analyst and the recommendations from the Process Optimization Specialist
        into a single, concise executive report for the COO. The report should clearly state:

1. The most critical customer support issues identified (with brief data points).
2. The key process bottlenecks causing these issues.
3. The recommended process improvements.
Ensure the report is easy to understand, focuses on actionable insights, and is formatted professionally."""
    ),
    expected_output=(
        """A well-structured executive report (max 1 page) summarizing the critical support issues,
        underlying process bottlenecks, and clear, actionable recommendations for the COO.
        Use clear headings and bullet points."""
    ),
    agent=report_writer # Assign task to the report_writer agent
)
```

### Crew {% id="crew" %}

The `Crew` brings the agents and tasks together, defining the workflow process
(such as "sequential").

```python
from crewai import Crew, Process

support_analysis_crew = Crew(
    agents=[data_analyst, process_optimizer, report_writer],
    tasks=[analysis_task, optimization_task, report_task],
    process=Process.sequential, # Tasks will run sequentially in the order defined
    verbose=True
)
```

## Run the crew {% id="run-crew" %}

Finally, kick off the crew execution with any necessary inputs.

```python
# Start the crew's work
print("--- Starting Customer Support Analysis Crew ---")
# The 'inputs' dictionary provides initial context if needed by the first task.
# In this case, the tool simulates data fetching regardless of the input.
result = support_analysis_crew.kickoff(inputs={'data_query': 'last quarter support data'})

print("--- Crew Execution Finished ---")
print("--- Final Report for COO ---")
print(result)
```

The script will now execute. The `Data Analyst` will use the tool, the `Process
Optimizer` will analyze the findings, and the `Report Writer` will compile the
final report, which is then printed to the console. The `verbose=True` setting
will show the detailed thought process and actions of each agent.

To learn more about CrewAI, check out the [CrewAI
introduction](https://docs.crewai.com/introduction).

# Research agent with Gemini and LlamaIndex
Source: https://aistudio.google.com/docs/llama-index
Description: Building Research Agents with Gemini

LlamaIndex is a framework for building knowledge agents using LLMs connected to
your data. This example shows you how to build a multi-agent workflow for a
Research Agent. In LlamaIndex, [
    `Workflows`](https://docs.llamaindex.ai/en/stable/module_guides/workflow/)
are the building blocks of agent and multi-agent systems.

You need a Gemini API key. If you don't already have one, you can
[get one in Google AI Studio](https://aistudio.google.com/apikey).
First, install all required LlamaIndex libraries. LlamaIndex uses
the `google-genai` package under the hood.

```posix-terminal
pip install llama-index llama-index-utils-workflow llama-index-llms-google-genai llama-index-tools-google
```

## Set up Gemini in LlamaIndex {% id="setup" %}

The engine of any LlamaIndex agent is an LLM that handles reasoning and text
processing. This example uses Gemini 3 Flash. Make sure you [set your API key as
an environment variable](https://ai.google.dev/docs/api-key).

```python
import os
from llama_index.llms.google_genai import GoogleGenAI

# Set your API key in the environment elsewhere, or with os.environ['GEMINI_API_KEY'] = '...'
assert 'GEMINI_API_KEY' in os.environ

llm = GoogleGenAI(model="gemini-3.8-flash")
```

## Build tools {% id="tools" %}

Agents use tools to interact with the outside world, like searching the web or
storing information. [Tools in LlamaIndex
](https://docs.llamaindex.ai/en/stable/module_guides/deploying/agents/tools/)
can be regular Python functions, or imported from pre-existing `ToolSpecs`.
Gemini comes with a built-in tool for using Google Search, which is used here.

```python
from google.genai import types

google_search_tool = types.Tool(
    google_search=types.GoogleSearch()
)

llm_with_search = GoogleGenAI(
    model="gemini-3.8-flash",
    generation_config=types.GenerateContentConfig(tools=[google_search_tool])
)
```

Now test the LLM instance with a query that requires search. This guide assumes
a running event loop (such as `python -m asyncio` or Google Colab).

```python
response = await llm_with_search.acomplete("What's the weather like today in Biarritz?")
print(response)
```

The Research Agent will use Python functions as tools. There are a lot of ways
you could go about building a system to perform this task. In this example, you
will use the following:

1. `search_web` uses Gemini with Google Search to search the web for information on the given topic.
2. `record_notes` saves research found on the web to the state so that the other tools can use it.
3. `write_report` writes the report using the information found by the `ResearchAgent`
4. `review_report` reviews the report and provides feedback.

The `Context` class passes the state between agents/tools, and each agent will
have access to the current state of the system.

```python
from llama_index.core.workflow import Context

async def search_web(ctx: Context, query: str) -> str:
    """Useful for searching the web about a specific query or topic"""
    response = await llm_with_search.acomplete(f"""Please research given this query or topic,
    and return the result\n<query_or_topic>{query}</query_or_topic>""")
    return response

async def record_notes(ctx: Context, notes: str, notes_title: str) -> str:
    """Useful for recording notes on a given topic."""
    current_state = await ctx.store.get("state")
    if "research_notes" not in current_state:
        current_state["research_notes"] = {}
    current_state["research_notes"][notes_title] = notes
    await ctx.store.set("state", current_state)
    return "Notes recorded."

async def write_report(ctx: Context, report_content: str) -> str:
    """Useful for writing a report on a given topic."""
    current_state = await ctx.store.get("state")
    current_state["report_content"] = report_content
    await ctx.store.set("state", current_state)
    return "Report written."

async def review_report(ctx: Context, review: str) -> str:
    """Useful for reviewing a report and providing feedback."""
    current_state = await ctx.store.get("state")
    current_state["review"] = review
    await ctx.store.set("state", current_state)
    return "Report reviewed."
```

## Build a multi-agent assistant {% id="multiagent" %}

To build a multi-agent system, you define the agents and their interactions.
Your system will have three agents:

1. A `ResearchAgent` searches the web for information on the given topic.
2. A `WriteAgent` writes the report using the information found by the `ResearchAgent`.
3. A `ReviewAgent` reviews the report and provides feedback.

This example uses the `AgentWorkflow` class to create a multi-agent system that
will execute these agents in order. Each agent takes a `system_prompt` that
tells it what it should do, and suggests how to work with the other agents.

Optionally, you can help your multi-agent system by specifying which other
agents it can talk to using `can_handoff_to` (if not, it will try to figure this
out on its own).

```python
from llama_index.core.agent.workflow import (
    AgentInput,
    AgentOutput,
    ToolCall,
    ToolCallResult,
    AgentStream,
)
from llama_index.core.agent.workflow import FunctionAgent, ReActAgent

research_agent = FunctionAgent(
    name="ResearchAgent",
    description="Useful for searching the web for information on a given topic and recording notes on the topic.",
    system_prompt=(
        "You are the ResearchAgent that can search the web for information on a given topic and record notes on the topic. "
        "Once notes are recorded and you are satisfied, you should hand off control to the WriteAgent to write a report on the topic."
    ),
    llm=llm,
    tools=[search_web, record_notes],
    can_handoff_to=["WriteAgent"],
)

write_agent = FunctionAgent(
    name="WriteAgent",
    description="Useful for writing a report on a given topic.",
    system_prompt=(
        "You are the WriteAgent that can write a report on a given topic. "
        "Your report should be in a markdown format. The content should be grounded in the research notes. "
        "Once the report is written, you should get feedback at least once from the ReviewAgent."
    ),
    llm=llm,
    tools=[write_report],
    can_handoff_to=["ReviewAgent", "ResearchAgent"],
)

review_agent = FunctionAgent(
    name="ReviewAgent",
    description="Useful for reviewing a report and providing feedback.",
    system_prompt=(
        "You are the ReviewAgent that can review a report and provide feedback. "
        "Your feedback should either approve the current report or request changes for the WriteAgent to implement."
    ),
    llm=llm,
    tools=[review_report],
    can_handoff_to=["ResearchAgent","WriteAgent"],
)
```

The Agents are defined, now you can create the `AgentWorkflow` and run it.

```python
from llama_index.core.agent.workflow import AgentWorkflow

agent_workflow = AgentWorkflow(
    agents=[research_agent, write_agent, review_agent],
    root_agent=research_agent.name,
    initial_state={
        "research_notes": {},
        "report_content": "Not written yet.",
        "review": "Review required.",
    },
)
```

During execution of the workflow, you can stream events, tool calls and updates
to the console.

```python
from llama_index.core.agent.workflow import (
    AgentInput,
    AgentOutput,
    ToolCall,
    ToolCallResult,
    AgentStream,
)

research_topic = """Write me a report on the history of the web.
Briefly describe the history of the world wide web, including
the development of the internet and the development of the web,
including 21st century developments"""

handler = agent_workflow.run(
    user_msg=research_topic
)

current_agent = None
current_tool_calls = ""
async for event in handler.stream_events():
    if (
        hasattr(event, "current_agent_name")
        and event.current_agent_name != current_agent
    ):
        current_agent = event.current_agent_name
        print(f"\n{'='*50}")
        print(f"🤖 Agent: {current_agent}")
        print(f"{'='*50}\n")
    elif isinstance(event, AgentOutput):
        if event.response.content:
            print("📤 Output:", event.response.content)
        if event.tool_calls:
            print(
                "🛠️ Planning to use tools:",
                [call.tool_name for call in event.tool_calls],
            )
    elif isinstance(event, ToolCallResult):
        print(f"🔧 Tool Result ({event.tool_name}):")
        print(f" Arguments: {event.tool_kwargs}")
        print(f" Output: {event.tool_output}")
    elif isinstance(event, ToolCall):
        print(f"🔨 Calling Tool: {event.tool_name}")
        print(f" With arguments: {event.tool_kwargs}")
```

After the workflow is complete, you can print the final output of the report, as
well as the final review state from then review agent.

```python
state = await handler.ctx.store.get("state")
print("Report Content:\n", state["report_content"])
print("\n------------\nFinal Review:\n", state["review"])
```

## Go further with custom workflows {% id="go-further-with-custom-workflows" %}

The `AgentWorkflow` is a great way to get started with multi-agent systems. But
what if you need more control? You can build a workflow from scratch. Here are
some reasons why you might want to build your own workflow:

* **More control over the process**: You can decide the exact path your agents
    take. This includes creating loops, making decisions at certain points, or
    having agents work in parallel on different tasks.

* **Use complex data**: Go beyond plain text. Custom workflows let you use
    more structured data, like JSON objects or custom classes, for your inputs
    and outputs.

* **Work with different media**: Build agents that can understand and process
    not just text, but also images, audio, and video.

* **Smarter planning**: You can design a workflow that first creates a
    detailed plan before the agents start working. This is useful for complex
    tasks that require multiple steps.

* **Enable self-correction**: Create agents that can review their own work. If
    the output isn't good enough, the agent can try again, creating a loop of
    improvement until the result is perfect.

To learn more about LlamaIndex Workflows, see the [LlamaIndex Workflows
Documentation](https://docs.llamaindex.ai/en/stable/module_guides/workflow/).

# Market research agent with Gemini and the AI SDK by Vercel
Source: https://aistudio.google.com/docs/vercel-ai-sdk-example
Description: Building apps with Gemini and the AI SDK by Vercel

The [AI SDK by Vercel](https://ai-sdk.dev) is a powerful open-source library for
building AI-powered applications, user interfaces, and agents in TypeScript.

This guide will walk you through building a Node.js application with TypeScript
that uses the AI SDK to connect with the Gemini API via the [Google Generative AI Provider](https://ai-sdk.dev/providers/ai-sdk-providers/google) and perform automated market trend analysis. The final
application will:

1. Use Gemini with Google Search to research current market trends.
2. Extract structured data from the research to generate charts.
3. Combine the research and charts into a professional HTML report and save it as a PDF.

## Prerequisites {% id="prerequisites" %}

To complete this guide, you'll need:

- A Gemini API key. You can create one for free in [Google AI Studio](https://aistudio.google.com/apikey).
- [Node.js](https://nodejs.org/en/download) version 18 or later.
- A package manager, such as `npm`, `pnpm`, or `yarn`.

{% callout type="note" %}
While this guide focuses on a Node.js environment, the AI SDK is
also fully compatible with browser-based frameworks like [Next.js](https://nextjs.org/).
{% /callout %}

## Set up your application {% id="setup" %}

First, create a new directory for your project and initialize it.

{% tabs %}
{% tab label="npm" %}
```posix-terminal
mkdir market-trend-app

cd market-trend-app

npm init -y
```
{% /tab %}
{% tab label="pnpm" %}
```posix-terminal
mkdir market-trend-app

cd market-trend-app

pnpm init
```
{% /tab %}
{% tab label="yarn" %}
```posix-terminal
mkdir market-trend-app

cd market-trend-app

yarn init -y
```
{% /tab %}
{% /tabs %}

### Install dependencies {% id="install-dependencies" %}

Next, install the AI SDK, the Google Generative AI provider, and other
necessary dependencies.

{% tabs %}
{% tab label="npm" %}
```posix-terminal
npm install ai @ai-sdk/google zod

npm install -D @types/node tsx typescript && npx tsc --init
```

To prevent a TypeScript compiler error, comment out the following line in
the generated `tsconfig.json`:

```json
//"verbatimModuleSyntax": true,
```
{% /tab %}
{% tab label="pnpm" %}
```posix-terminal
pnpm add ai @ai-sdk/google zod

pnpm add -D @types/node tsx typescript
```
{% /tab %}
{% tab label="yarn" %}
```posix-terminal
yarn add ai @ai-sdk/google zod

yarn add -D @types/node tsx typescript && yarn tsc --init
```

To prevent a TypeScript compiler error, comment out the following line in
the generated `tsconfig.json`:

```json
//"verbatimModuleSyntax": true,
```
{% /tab %}
{% /tabs %}

This application will also use the third-party packages [Puppeteer](https://pptr.dev/)
and [Chart.js](https://www.chartjs.org) for rendering charts and
creating a PDF:

{% tabs %}
{% tab label="npm" %}
```posix-terminal
npm install puppeteer chart.js

npm install -D @types/chart.js
```
{% /tab %}
{% tab label="pnpm" %}
```posix-terminal
pnpm add puppeteer chart.js

pnpm add -D @types/chart.js
```
{% /tab %}
{% tab label="yarn" %}
```posix-terminal
yarn add puppeteer chart.js

yarn add -D @types/chart.js
```
{% /tab %}
{% /tabs %}

The `puppeteer` package requires running a script to download the Chromium
browser. Your package manager may ask for approval, so ensure you approve the
script when prompted.

### Configure your API key {% id="set-up-api-key" %}

Set the `GOOGLE_GENERATIVE_AI_API_KEY` environment variable with your Gemini API
key. The Google Generative AI Provider automatically looks for your API key in
this environment variable.

{% tabs %}
{% tab label="MacOS/Linux" %}
```posix-terminal
export GOOGLE_GENERATIVE_AI_API_KEY="YOUR_API_KEY_HERE"
```
{% /tab %}
{% tab label="Powershell" %}
```posix-terminal
setx GOOGLE_GENERATIVE_AI_API_KEY "YOUR_API_KEY_HERE"
```
{% /tab %}
{% /tabs %}

## Create your application {% id="create-application" %}

Now, let's create the main file for our application. Create a new file named
`main.ts` in your project directory. You'll build up the logic in this file
step-by-step.

For a quick test to ensure everything is set up correctly, add the following
code to `main.ts`. This basic example uses `generateText` to get a simple
response from Gemini.

```ts
import { google } from "@ai-sdk/google";
import { generateText } from "ai";

async function main() {
  const { text } = await generateText({
    model: google("gemini-3.8-flash"),
    prompt: 'What is plant-based milk?',
  });

  console.log(text);
}

main().catch(console.error);
```

Before adding more complexity, run this script to verify that your environment
is configured correctly. Run the following command in your terminal:

{% tabs %}
{% tab label="npm" %}
```posix-terminal
npx tsc && node main.js
```
{% /tab %}
{% tab label="pnpm" %}
```posix-terminal
pnpm tsx main.ts
```
{% /tab %}
{% tab label="yarn" %}
```posix-terminal
yarn tsc && node main.js
```
{% /tab %}
{% /tabs %}

If everything is set up correctly, you'll see Gemini's response printed to the
console.

## Perform market research with Google Search {% id="market-research" %}

To get up-to-date information, you can enable the
[Google Search](/docs/google-search) tool for Gemini. When this tool
is active, the model can search the web to answer the prompt and will return
the sources it used.

Replace the content of `main.ts` with the following code to perform the first
step of our analysis.

```ts
import { google } from "@ai-sdk/google";
import { generateText } from "ai";

async function main() {
  // Step 1: Search market trends
  const { text: marketTrends, sources } = await generateText({
    model: google("gemini-3.8-flash"),
    tools: {
      google_search: google.tools.googleSearch({}),
    },
    prompt: `Search the web for market trends for plant-based milk in North America for 2024-2025.
          I need to know the market size, key players and their market share, and primary consumer drivers.
          `,
  });

  console.log("Market trends found:\n", marketTrends);
  // To see the sources, uncomment the following line:
  // console.log("Sources:\n", sources);
}

main().catch(console.error);
```

## Extract chart data {% id="extract-chart-data" %}

Next, let's process the research text to extract structured data suitable for
charts. Use the AI SDK's `generateObject` function along with a `zod`
schema to define the exact data structure.

Also create a helper function to convert this structured data into a
configuration that `Chart.js` can understand.

Add the following code to `main.ts`. Note the new imports and the added
"Step 2".

```ts
import { google } from "@ai-sdk/google";
import { generateText, generateObject } from "ai";
import { z } from "zod/v4";
import { ChartConfiguration } from "chart.js";

// Helper function to create Chart.js configurations
function createChartConfig({labels, data, label, type, colors,}: {
  labels: string[];
  data: number[];
  label: string;
  type: "bar" | "line";
  colors: string[];
}): ChartConfiguration {
  return {
    type: type,
    data: {
      labels: labels,
      datasets: [
        {
          label: label,
          data: data,
          borderWidth: 1,
          ...(type === "bar" && { backgroundColor: colors }),
          ...(type === "line" && colors.length > 0 && { borderColor: colors[0] }),
        },
      ],
    },
    options: {
      animation: { duration: 0 }, // Disable animations for static PDF rendering
    },
  };
}

async function main() {
  // Step 1: Search market trends
  const { text: marketTrends, sources } = await generateText({
    model: google("gemini-3.8-flash"),
    tools: {
      google_search: google.tools.googleSearch({}),
    },
    prompt: `Search the web for market trends for plant-based milk in North America for 2024-2025.
          I need to know the market size, key players and their market share, and primary consumer drivers.
          `,
  });

  console.log("Market trends found.");

  // Step 2: Extract chart data
  const { object: chartData } = await generateObject({
    model: google("gemini-3.8-flash"),
    schema: z.object({
      chartConfigurations: z
        .array(
          z.object({
            type: z.enum(["bar", "line"]).describe('The type of chart to generate. Either "bar" or "line"',),
            labels: z.array(z.string()).describe("A list of chart labels"),
            data: z.array(z.number()).describe("A list of the chart data"),
            label: z.string().describe("A label for the chart"),
            colors: z.array(z.string()).describe('A list of colors to use for the chart, e.g. "rgba(255, 99, 132, 0.8)"',),
          }),
        )
        .describe("A list of chart configurations"),
    }),
    prompt: `Given the following market trends text, come up with a list of 1-3 meaningful bar or line charts
    and generate chart data.

Market Trends:
${marketTrends}
`,
  });

  const chartConfigs = chartData.chartConfigurations.map(createChartConfig);

  console.log("Chart configurations generated.");
}

main().catch(console.error);
```

## Generate the final report {% id="generate-report" %}

In the final step, instruct Gemini to act as an expert report writer.
Provide it with the market research, the chart configurations, and a clear
set of instructions for building an HTML report. Then, use
[Puppeteer](https://pptr.dev/) to render this HTML and save it as a PDF.

Add the final `puppeteer` import and "Step 3" to your `main.ts` file.

~~~ts
// ... (imports from previous step)
import puppeteer from "puppeteer";

// ... (createChartConfig helper function from previous step)

async function main() {
  // ... (Step 1 and 2 from previous step)

  // Step 3: Generate the final HTML report and save it as a PDF
  const { text: htmlReport } = await generateText({
    model: google("gemini-3.8-flash"),
    prompt: `You are an expert financial analyst and report writer.
    Your task is to generate a comprehensive market analysis report in HTML format.

    **Instructions:**

    1. Write a full HTML document.
    2. Use the provided "Market Trends" text to write the main body of the report. Structure it with clear headings and paragraphs.
    3. Incorporate the provided "Chart Configurations" to visualize the data. For each chart, you MUST create a unique <canvas> element and a corresponding <script> block to render it using Chart.js.
    4. Reference the "Sources" at the end of the report.
    5. Do not include any placeholder data; use only the information provided.
    6. Return only the raw HTML code.

    **Chart Rendering Snippet:**
    Include this script in the head of the HTML: <script src="path/to/chart.js"></script>
    For each chart, use a structure like below, ensuring the canvas 'id' is unique for each chart, and apply the correspinding config:

    ---

      <canvas id="chart1"></canvas>

    <script>
      new Chart(document.getElementById('chart1'), config);
    </script>
    ---
    (For the second chart, use 'chart2' and the corresponding config, and so on.)

    **Data:**

    - Market Trends: ${marketTrends}
    - Chart Configurations: ${JSON.stringify(chartConfigs)}
    - Sources: ${JSON.stringify(sources)}
    `,
  });

  // LLMs may wrap the HTML in a markdown code block, so strip it.
  const finalHtml = htmlReport.replace(/^```html\n/, "").replace(/\n```$/, "");

  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.setContent(finalHtml);
  await page.pdf({ path: "report.pdf", format: "A4" });
  await browser.close();

  console.log("\nReport generated successfully: report.pdf");
}

main().catch(console.error);
~~~

## Run your application {% id="run-application" %}

You are now ready to run the application. Execute the following command in
your terminal:

{% tabs %}
{% tab label="npm" %}
```posix-terminal
  npx tsc && node main.js
```
{% /tab %}
{% tab label="pnpm" %}
```posix-terminal
  pnpm tsx main.ts
```
{% /tab %}
{% tab label="yarn" %}
```posix-terminal
  yarn tsc && node main.js
```
{% /tab %}
{% /tabs %}

You will see logging in your terminal as the script executes each step.
Once complete, a `report.pdf` file containing your market analysis will be
created in your project directory.

Below, you'll see the first two pages of an example PDF report:

![Market analysis report](/googledevai/static/gemini-api/docs/images/market-research-pdf.jpg)

## Further resources {% id="further-resources" %}

For more information about building with Gemini and the AI SDK,
explore these resources:

- [AI SDK docs](https://ai-sdk.dev/docs)
- [AI SDK Google Generative AI docs](https://ai-sdk.dev/providers/ai-sdk-providers/google)
- [AI SDK cookbook: Get Started with Gemini](https://ai-sdk.dev/cookbook/guides/gemini)

# Durable AI agent with Gemini and Temporal
Source: https://aistudio.google.com/docs/temporal-example
Description: Building durable AI agents with Gemini and Temporal

This tutorial walks you through building a durable AI agent that uses the Gemini
API for reasoning and [Temporal](https://temporal.io/) for durability. It uses
Temporal's built-in [Gemini SDK integration](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/google_genai).

The agent can call tools, like looking up weather alerts or geolocating an IP
address, and will loop until it has enough information to respond.

What makes this different from a typical agent demo is **durability**. Every LLM
call and every tool invocation is persisted by Temporal. If the process crashes,
the network drops, or an API times out, Temporal automatically retries and
resumes from the last completed step. No conversation history is lost, and no
tool calls are incorrectly repeated.

## Architecture {% id="architecture" %}

The architecture consists of three parts:

*   **Workflow:** A single `generate_content` call. The Gemini SDK's automatic
    function calling (AFC) loop runs *inside* the Workflow, and Temporal makes
    every step of it durable.
*   **Activities:** Individual units of work that Temporal makes durable. The
    Gemini API calls become Activities automatically.
*   **Worker:** The process that executes the Workflows and Activities, and the
    only place your API key lives.

In this example, you will place all three of these pieces in a single file
(`durable_agent_worker.py`). In a real-world implementation, you would separate
them to allow for various deployment and scalability advantages. You will supply
prompts to the agent with the Temporal CLI, so there is no client code to write.

## Prerequisites {% id="prerequisites" %}

To complete this guide, you'll need:

*   A Gemini API key. You can create one for free in
    [Google AI Studio](https://aistudio.google.com/apikey).
*   [Python](https://www.python.org/downloads/) version 3.10 or later.
*   [uv](https://docs.astral.sh/uv/getting-started/installation/) for dependency
    management.
*   The [Temporal CLI](https://docs.temporal.io/cli) for running a local
    development server and starting Workflows.

## Setup {% id="setup" %}

Before you begin, ensure you have a
[Temporal development server](https://docs.temporal.io/cli#start-dev-server)
running locally:

```posix-terminal
temporal server start-dev
```

Next, create a project and install the required dependencies:

```posix-terminal
uv init durable-gemini-agent

cd durable-gemini-agent

uv add "temporalio[google-genai]" httpx python-dotenv
```

uv creates and manages the virtual environment for you, so every Python command
later in this tutorial runs through `uv run`.

Create a `.env` file in your project directory with your Gemini API key. You
can get an API key from
[Google AI Studio](https://aistudio.google.com/apikey).

```posix-terminal
echo "GOOGLE_API_KEY=your-api-key-here" > .env
```

{% callout type="note" %}
Note: Only the worker process needs the API key. Whatever starts the
Workflow does not require it, and neither does the Workflow itself—the real
`genai.Client` is constructed on the worker and never crosses into Workflow
code, so no auth material can appear in Temporal's event history.
{% /callout %}

## Implementation {% id="implementation" %}

The rest of this tutorial walks through `durable_agent_worker.py` from top to
bottom, building up the agent piece by piece. Create the file and follow along.

{% callout type="note" %}
Note: The `temporalio.contrib.google_genai` integration is experimental. Its API
may change in future versions of the Temporal Python SDK.
{% /callout %}

### Imports and sandbox setup {% id="imports" %}

Start with the imports that must be defined up-front. The
`workflow.unsafe.imports_passed_through()` block tells Temporal's Workflow
sandbox to let `httpx` pass through without restriction. Importing `httpx`
executes `class _CookieCompatRequest(urllib.request.Request)`, and the sandbox
blocks subclassing that stdlib class.

Your tools use `httpx`, and `activity_as_tool()` needs the Workflow to import
those tool functions so Gemini can derive their schemas from the signatures. So
`httpx` reaches the sandbox no matter how you split the files—moving the tools
into their own module doesn't avoid it.

```python
from temporalio import workflow

with workflow.unsafe.imports_passed_through():
    import httpx
```

You don't need to list `google.genai` here. The Temporal plugin you configure
later adds it—along with `pydantic_core` and `annotated_types`—to the sandbox
passthrough set for you.

### System instructions {% id="system-instructions" %}

Next, define the agent's personality. The system instructions tell the model how
to behave. This agent is instructed to respond in haikus when no tools are
needed.

```python
SYSTEM_INSTRUCTIONS = """
You are a helpful agent that can use tools to help the user.
You will be given an input from the user and a list of tools to use.
You may or may not need to use the tools to satisfy the user ask.
If no tools are needed, respond in haikus.
"""
```

### Tool definitions {% id="tool-definitions" %}

Now define the tools the agent can use. Each tool is an ordinary Temporal
Activity: an async function decorated with `@activity.defn`, with type-annotated
parameters and a descriptive docstring. Gemini builds the function declaration
from that signature and docstring, so document each parameter in the `Args`
section.

```python
import json

from temporalio import activity

NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

@activity.defn
async def get_weather_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"

    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers, timeout=5.0)
        response.raise_for_status()
        return json.dumps(response.json())
```

Next, define tools for IP address geolocation:

```python
@activity.defn
async def get_ip_address() -> str:
    """Get the public IP address of the current machine."""
    async with httpx.AsyncClient() as client:
        response = await client.get("https://icanhazip.com")
        response.raise_for_status()
        return response.text.strip()

@activity.defn
async def get_location_info(ipaddress: str) -> str:
    """Get the location information for an IP address including city, state, and country.

    Args:
        ipaddress: An IP address to look up
    """
    async with httpx.AsyncClient() as client:
        response = await client.get(f"http://ip-api.com/json/{ipaddress}")
        response.raise_for_status()
        result = response.json()
        return f"{result['city']}, {result['regionName']}, {result['country']}"
```

That's the whole tool layer. There is no tool registry, no `FunctionDeclaration`
construction, and no dispatch table—the next section wraps these Activities with
`activity_as_tool()`, which passes each parameter through to the Activity
positionally. Tools with zero, one, or several parameters all work.

### The agent Workflow {% id="agent-workflow" %}

Now you have all the pieces to finish building the agent. The `AgentWorkflow`
class makes one `generate_content` call. `TemporalAsyncClient` is a drop-in
`AsyncClient` whose every API call runs as a Temporal Activity, and
`activity_as_tool()` turns each of your Activities into a Gemini tool.

When the model asks for a tool, the SDK's AFC loop—running inside the
Workflow—dispatches it through `workflow.execute_activity`, appends the result
to the conversation, and calls the model again. That loop is the agent, and it
is durable because each step is an Activity recorded in Temporal's event
history.

```python
from datetime import timedelta

from google.genai import types
from temporalio.contrib.google_genai import TemporalAsyncClient, activity_as_tool
from temporalio.workflow import ActivityConfig

TOOL_CONFIG = ActivityConfig(start_to_close_timeout=timedelta(seconds=30))

@workflow.defn
class AgentWorkflow:
    """Agent workflow that uses Gemini for LLM calls and executes tools."""

    @workflow.run
    async def run(self, prompt: str) -> str:
        client = TemporalAsyncClient()

        response = await client.models.generate_content(
            model="gemini-3.8-flash",
            contents=prompt,
            config=types.GenerateContentConfig(
                system_instruction=SYSTEM_INSTRUCTIONS,
                tools=[
                    activity_as_tool(get_weather_alerts, activity_config=TOOL_CONFIG),
                    activity_as_tool(get_ip_address, activity_config=TOOL_CONFIG),
                    activity_as_tool(get_location_info, activity_config=TOOL_CONFIG),
                ],
            ),
        )

        # Leave this in place. You will un-comment it during a durability
        # test later on.
        # await workflow.sleep(timedelta(seconds=10))

        return response.text or ""
```

A few things to note:

*   Construct `TemporalAsyncClient` **inside** the Workflow. It carries no
    credentials; it only knows how to turn API calls into Activity invocations.
*   `activity_config` must set `start_to_close_timeout` or
    `schedule_to_close_timeout`. Temporal requires a timeout and there is no
    default for tool Activities.
*   The Gemini API Activities default to a 60-second `start_to_close_timeout`.
    Override it with `TemporalAsyncClient(activity_config=...)` if your model
    calls need longer.

The agent is fully durable. If the worker crashes after several turns, Temporal
picks up exactly where it left off without re-invoking already executed LLM
calls or tool calls.

### Retries {% id="retries" %}

Temporal owns retries, so don't enable the Gemini SDK's own retry loop. Set
retry behavior with a `retry_policy` on the Activity config instead:

```python
from temporalio.common import RetryPolicy

TOOL_CONFIG = ActivityConfig(
    start_to_close_timeout=timedelta(seconds=30),
    retry_policy=RetryPolicy(maximum_attempts=3),
)
```

API failures are also classified for you. Transient statuses (408, 429, 5xx)
stay retryable so the Activity's retry policy applies; other statuses (such as a
400 for a malformed request) are non-retryable, so the Workflow fails fast
instead of burning attempts on an error that won't resolve.

You can extend that classification. The integration surfaces each API failure as
an `ApplicationError` whose type is the Gemini exception class name—`ClientError`
for 4xx, `ServerError` for 5xx—so listing a name in
`non_retryable_error_types` moves it out of the transient set. For example, to
stop retrying Gemini-side outages and fail the Workflow on the first 5xx, apply
the policy to the Gemini API Activities through `TemporalAsyncClient`:

```python
from temporalio.common import RetryPolicy

client = TemporalAsyncClient(
    activity_config=ActivityConfig(
        start_to_close_timeout=timedelta(seconds=60),
        retry_policy=RetryPolicy(
            maximum_attempts=5,
            non_retryable_error_types=["ServerError"],
        ),
    ),
)
```

### Worker startup {% id="worker-startup" %}

Finally, wire everything together. The Temporal worker connects to the Temporal
service and acts as a scheduler for the Workflow and Activity tasks.

This is where the real `genai.Client` is created, with your API key.
`GoogleGenAIPlugin` takes that client and registers the Gemini API Activities,
installs the Pydantic data converter, and configures the Workflow sandbox.

```python
import asyncio
import os

from dotenv import load_dotenv
from google import genai
from temporalio.client import Client
from temporalio.contrib.google_genai import GoogleGenAIPlugin
from temporalio.envconfig import ClientConfig
from temporalio.worker import Worker

async def main():
    gemini = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])
    plugin = GoogleGenAIPlugin(gemini)

    config = ClientConfig.load_client_connect_config()
    config.setdefault("target_host", "localhost:7233")
    client = await Client.connect(**config, plugins=[plugin])

    worker = Worker(
        client,
        task_queue="gemini-agent",
        workflows=[
            AgentWorkflow,
        ],
        activities=[
            get_weather_alerts,
            get_ip_address,
            get_location_info,
        ],
    )
    await worker.run()

if __name__ == "__main__":
    load_dotenv()
    asyncio.run(main())
```

The plugin removes three pieces of boilerplate you would otherwise need here:

*   No `data_converter=pydantic_data_converter`—the plugin installs the Pydantic
    payload converter itself.
*   No `activity_executor=ThreadPoolExecutor`—every Activity is async.
*   No Gemini Activities in the `activities` list—the plugin registers them.
    You only register your own tools.

## Run the agent {% id="run-agent" %}

That's the entire agent. You don't need to write a client—the Temporal CLI can
start the Workflow for you.

If you haven't already, start the Temporal development server:

```posix-terminal
temporal server start-dev
```

In a new terminal window, start the agent worker:

```posix-terminal
uv run durable_agent_worker.py
```

In a third terminal window, submit a query to your agent:

```posix-terminal
temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
    --input '"are there any weather alerts for where I am?"'
```

Note the task queue: it's the same one the worker polls. Starting the Workflow
dispatches a Workflow task carrying the user prompt to that queue, which is what
initiates the agent. `execute` blocks until the Workflow completes and prints the
result. If you'd rather not wait, use `temporal workflow start` with an explicit
`--workflow-id`, then collect the result later with
`temporal workflow result -w your-workflow-id`. Temporal generates the Workflow
ID for you when you omit `--workflow-id`.

`--input` takes JSON, so a bare string prompt needs its own quotes inside the
shell quotes. The CLI needs no Gemini API key, and no data converter
configuration either: the Workflow's argument and return value are both plain
strings, which the default JSON payload converter handles.

Open the Temporal UI at
`http://localhost:8233/namespaces/default/workflows` to watch the agentic loop
unfold. You'll see `gemini_api_client_async_request` Activities—one per model
turn—interleaved with one Activity per tool call, each labeled with a
`tool_call` summary. That interleaving *is* the AFC loop, made durable and
observable.

Try a few different prompts to see the agent reason and call tools. Each command
is the same as the one above with a new `--input`:

```posix-terminal
temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
    --input '"are there any weather alerts for New York?"'

temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
    --input '"where am I?"'

temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
    --input '"what is my ip address?"'

temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
    --input '"tell me a joke"'
```

The last prompt doesn't require any tools, so the agent responds in a haiku
based on the `SYSTEM_INSTRUCTIONS`.

## Test durability {% id="test-durability" %}

Building on Temporal ensures your agent survives failures seamlessly. You can
test this using two distinct experiments.

### Simulating a network outage {% id="network-outage" %}

In this test, you'll temporarily disable your computer's internet connection,
submit a Workflow, watch Temporal automatically retry, and then restore the
network to see it recover.

1.  Disconnect your machine from the internet (for example, turn off your
    Wi-Fi).
2.  Submit a Workflow:

    ```posix-terminal
    temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
        --input '"tell me a joke"'
    ```

3.  Check the Temporal UI (`http://localhost:8233`). You will see the Gemini API
    Activity failing and Temporal automatically managing the retries in the
    background.
4.  Reconnect to the internet.
5.  The next automated retry will successfully reach the Gemini API, and your
    terminal will print the final result.

### Surviving a worker crash {% id="worker-crash" %}

In this test, you kill the worker mid-execution and restart it. Temporal replays
the Workflow history (event sourcing) and resumes from the last completed
Activity—already-completed LLM invocations and tool calls are not repeated.

1.  To give yourself time to kill the worker, open `durable_agent_worker.py` and
    uncomment the durable timer in `AgentWorkflow.run`:

    ```python
    await workflow.sleep(timedelta(seconds=10))
    ```

    `workflow.sleep` is a Temporal timer, not a local one. It is recorded in
    history and survives the restart, which is what makes this test reliable.

2.  Restart the worker:

    ```posix-terminal
    uv run durable_agent_worker.py
    ```

3.  Submit a query that triggers several tools:

    ```posix-terminal
    temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
        --input '"are there any weather alerts where I am?"'
    ```

4.  Once the tool calls have completed and the timer is running, kill the worker
    process (`Ctrl-C` in the worker terminal, or `kill %1` if running in the
    background).
5.  Restart the worker:

    ```posix-terminal
    uv run durable_agent_worker.py
    ```

Temporal replays the Workflow history. The LLM calls and tool invocations that
already completed are **not** re-executed—their results are instantly replayed
from history (the event log), the timer resumes, and the Workflow finishes
successfully.

## Going further {% id="going-further" %}

The integration supports more than this tutorial covers. See the
[plugin documentation](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/google_genai)
for details:

*   **Streaming.** Use `generate_content_stream` as usual. To let an external
    consumer (a chat UI) observe chunks in real time while the Workflow runs
    durably, set `TemporalAsyncClient(streaming_topic=...)` and host a
    `WorkflowStream` in the Workflow.
*   **MCP.** Register a client-side MCP server on the worker with
    `GoogleGenAIPlugin(mcp_servers={...})` and reference it by name in the
    Workflow with `TemporalMcpClientSession`. Tool discovery and calls run as
    Activities against a pooled worker-side connection.
*   **Vertex AI.** Pass `vertexai=True` to both the worker-side `genai.Client`
    and the Workflow-side `TemporalAsyncClient`, setting `project` and
    `location` explicitly on the Workflow side so replay stays deterministic.

## Further resources {% id="further-resources" %}

*   [Temporal documentation](https://docs.temporal.io/)
*   [Temporal Python SDK](https://docs.temporal.io/develop/python)
*   [Temporal Gemini SDK integration](https://docs.temporal.io/develop/python/integrations/google-genai)
*   [Google GenAI SDK](https://googleapis.github.io/python-genai/)

# Release notes
Source: https://aistudio.google.com/docs/changelog
Description: Keep track of updates to the Gemini API

This page documents updates to the Gemini API.

## November 2, 2026 {% id="11-02-2026" %}

*   **Gemini 2.5 Pro deprecation**:
    [`gemini-2.5-pro`](/docs/models/gemini-2.5-pro) is
    [deprecated](/docs/deprecations#gemini-2.5-pro-models) and is no longer
    available to select in Google AI Studio. Effective December 1, 2026, all API
    requests to `gemini-2.5-pro` will automatically route to
    [`gemini-3.8-flash`](/docs/models/gemini-3.8-flash) and be billed at
    [Gemini 3.8 Flash rates](/docs/pricing#gemini-3.8-flash). Before December 1,
    2026, update your model string to `gemini-3.8-flash` and review the
    [Gemini 3.8 Flash migration guide](/docs/whats-new-gemini-3.8#migrate-to-gemini-3-8-flash).
    Breaking API changes include function calling and `thought_signature`
    validation, `thinking_level` replacing `thinking_budget`, and removed
    sampling parameters and prefilled model turns.
*   **Gemini 2.5 Flash deprecation**:
    [`gemini-2.5-flash`](/docs/models/gemini-2.5-flash) is
    [deprecated](/docs/deprecations#gemini-2.5-flash-models) and is no longer
    available to select in Google AI Studio. Effective December 1, 2026, all API
    requests to `gemini-2.5-flash` will automatically route to
    [`gemini-3.5-flash-lite`](/docs/models/gemini-3.5-flash-lite) and be billed
    at [Gemini 3.5 Flash-Lite rates](/docs/pricing#gemini-3.5-flash-lite).
    Before December 1, 2026, update your model string to `gemini-3.5-flash-lite`
    and review the
    [Gemini 3.5 Flash-Lite migration guide](/docs/whats-new-gemini-3.6#migrate-to-gemini-3-5-flash-lite).
    Breaking API changes include function calling and `thought_signature`
    validation, `thinking_level` replacing `thinking_budget`, and removed
    sampling parameters and prefilled model turns.

## October 30, 2026 {% id="10-30-2026" %}

*   **Computer Use generally available (GA)**: Released the
    [Computer Use](/docs/computer-use) tool to general availability (GA) across
    the Interactions and GenerateContent APIs.

## October 27, 2026 {% id="10-27-2026" %}

*   **Gemini API CLI (`gemini-api`) beta**: Released the [Gemini API
    CLI](/docs/cli) (`gemini-api`), a stateless, zero-dependency command-line
    client for AI coding agents, scripts, and CI pipelines. Use `gemini-api` on
    the [Interactions API](/docs/interactions-overview) to generate text and
    media, analyze files, and run [Gemini managed agents](/docs/agents). See the
    [Gemini API CLI guide](/docs/cli) to get started.

## October 26, 2026 {% id="10-26-2026" %}

*   **Generate Content API storage on by default**: New projects using the
    Generate Content API (`generateContent`, `streamGenerateContent`, and
    `batchGenerateContent`) on the paid tier now store requests by default
    (`store=true`), matching the Interactions API. Existing projects
    keep their current setting. To opt out, set `store=false` on individual
    requests or turn off Generate Content API logging in the **Settings** panel
    of the [Logs and Datasets](/logs) dashboard. See
    [Logs and datasets](/docs/logs-datasets#configure-logging) for details.

## October 13, 2026 {% id="10-13-2026" %}

*   **Gemini 4 Argon (`gemini-4-argon`) generally available (GA)**: Released
    [Gemini 4 Argon](/docs/models/gemini-4-argon) (`gemini-4-argon`), our most
    capable model built for complex coding, agentic, math, and science tasks.

    For API changes, pricing, and migration guidance, see
    [What's new in Gemini 4 Argon](/docs/latest-model).

## October 8, 2026 {% id="10-08-2026" %}

*   **Gemini 3.7 Flash deprecation**:
    [`gemini-3.7-flash`](/docs/whats-new-gemini-3.7) is deprecated and has been
    replaced by [`gemini-3.8-flash`](/docs/whats-new-gemini-3.8). It is no longer
    available to select in Google AI Studio, and API requests to
    `gemini-3.7-flash` are automatically routed to `gemini-3.8-flash`. Update
    your model string to `gemini-3.8-flash` and review the
    [Gemini 3.8 Flash guide](/docs/whats-new-gemini-3.8).
*   **Gemini 3.5 Flash deprecation**:
    [`gemini-3.5-flash`](/docs/whats-new-gemini-3.5) is deprecated and has been
    replaced by [`gemini-3.6-flash`](/docs/whats-new-gemini-3.6). It is no
    longer available to select in Google AI Studio, and API requests to
    `gemini-3.5-flash` are automatically routed to `gemini-3.6-flash`. Update
    your model string to `gemini-3.6-flash` (or
    [`gemini-3.8-flash`](/docs/whats-new-gemini-3.8)) and review the
    [Gemini 3.6 Flash guide](/docs/whats-new-gemini-3.6).
*   **Deep Research Agent `deep-research-pro-preview-12-2025` deprecation**:
    The `deep-research-pro-preview-12-2025` agent is deprecated and will be
    [shut down](/docs/deprecations#managed-agents) on **October 23, 2026**.

    Migrate your requests to one of the newer [Deep
    Research](/docs/deep-research) agent versions:

    *   [`deep-research-preview-04-2026`](/docs/models/deep-research-preview-04-2026):
        Designed for speed and efficiency, ideal to be streamed back to a client
        UI.
    *   [`deep-research-max-preview-04-2026`](/docs/models/deep-research-max-preview-04-2026):
        Maximum comprehensiveness for automated context gathering and synthesis.

    To migrate, update the `agent` parameter in your `interactions.create`
    requests from `deep-research-pro-preview-12-2025` to
    `deep-research-preview-04-2026` (or `deep-research-max-preview-04-2026`).

## October 6, 2026 {% id="10-06-2026" %}

*   **Gemini Nano Banana 2.1 generally available (GA)**: Released
    [Gemini Nano Banana 2.1](/docs/models/gemini-nano-banana-2.1)
    (`gemini-nano-banana-2.1`), the latest high-efficiency image generation and
    conversational editing model. An update to Nano Banana 2
    ([`gemini-3.1-flash-image`](/docs/models/gemini-3.1-flash-image)), it
    maintains Flash-level speed and cost efficiency while delivering significant
    improvements in visual quality, prompt adherence, multi-turn character
    consistency, text rendering, and wide and panoramic aspect ratio generation
    (`1:4`, `4:1`, `1:8`, `8:1`) across `1K`, `2K`, and `4K` resolutions.

    See the [Image generation guide](/docs/image-generation) to get started.

*   **Deprecation announcement**: The `gemini-3.1-flash-image` model is
    deprecated (no shutdown date announced). Migrate to
    [`gemini-nano-banana-2.1`](/docs/models/gemini-nano-banana-2.1).

## September 22, 2026 {% id="09-22-2026" %}

*   **Gemini 3.8 Flash TTS and Gemini 3.8 Flash-Lite TTS generally available
    (GA)**: Released our next-generation text-to-speech (TTS) audio models and
    the Gemini API Voices endpoint (`/v1beta/voices`):

    *   **[Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts)
        (`gemini-3.8-flash-tts`)**: Flagship creative TTS model engineered for
        studio-grade voice fidelity, nuanced acting, regional dialects, and
        long-form multi-turn stability.
    *   **[Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts)
        (`gemini-3.8-flash-lite-tts`)**: Fast, cost-efficient TTS model built to
        replace `gemini-3.1-flash-tts-preview` for high-throughput production
        and real-time voice agent cascades.
    *   **[Voice design](/docs/voice-design),
        [Voice replication](/docs/voice-replication), and the
        [Extended Voice Library](/docs/speech-generation#voice-library)**:
        Create persistent custom vocal personas from text prompts, replicate
        voices with consent verification, and query 150+ prebuilt and custom
        voices.

    See the [Text-to-speech guide](/docs/speech-generation) to get started.

## September 18, 2026 {% id="09-18-2026" %}

*   **Gemini 2.5 models access update**: To ensure reliable performance for
    everyone, we are limiting access to the 2.5 models to users who have
    actively used them in the past. These models are not deprecated and will
    continue to be served until further notice through the API. For any new
    projects, use our latest models: 3.5 Flash-Lite or 3.8 Flash. This
    helps us maintain sufficient capacity for both ongoing legacy workflows and
    new applications.

## September 17, 2026 {% id="09-17-2026" %}

*   **Antigravity Agent 09-2026**: Released `antigravity-preview-09-2026`,
    which replaces and deprecates `antigravity-preview-05-2026`.

    If you run on a remote sandbox (`environment: "remote"`) and read only
    `output_text` or `model_output` steps, update the agent string and nothing
    else changes.

    If you run tools locally (`local_environment`) or parse `function_call`
    steps, the built-in tools changed. Parameters use PascalCase instead of
    snake_case, and file edits use line-range replacements instead of full
    rewrites.

    | Capability | 05-2026 | 09-2026 |
    | :---- | :---- | :---- |
    | File creation | `write_file(path, content)` | `write_to_file(TargetFile, CodeContent, Overwrite, Description)` |
    | File editing | `write_file(path, content)`, full rewrite | `replace_file_content(TargetFile, StartLine, EndLine, TargetContent, ReplacementContent)` |
    | File reading | `read_file(path, offset, limit)`, byte offsets | `view_file(AbsolutePath, StartLine, EndLine, ContentOffset)` |
    | Directory listing | `list_files(path)` | `list_dir(DirectoryPath)` |
    | File and code search | None, agents used shell commands | `find_by_name(SearchDirectory, Pattern, MaxDepth)` and `grep_search(SearchPath, Query, IsRegex)` |
    | Shell execution | `code_execution(command, timeout_seconds)` | Unchanged |
    | Web search | `google_search(queries)` | Unchanged |

    See the [Antigravity Agent](/docs/antigravity-agent) guide.
    `antigravity-preview-05-2026` shuts down on October 5, 2026, tracked on the
    [deprecations](/docs/deprecations#managed-agents) page.

## September 15, 2026 {% id="09-15-2026" %}

*   **Gemini 3.8 Live and Gemini 3.8 Live Extended Thinking generally available
    (GA)**: Released our next-generation Live API models for real-time
    multimodal dialogue and agentic tool use:

    *   **[Gemini 3.8 Live](/docs/models/gemini-3.8-live) (`gemini-3.8-live`)**:
        Engineered for sub-second conversational latency with native audio
        understanding, affective dialogue, proactive audio, and
        synchronous/asynchronous function calling.
    *   **[Gemini 3.8 Live Extended Thinking](/docs/models/gemini-3.8-live-extended-thinking)
        (`gemini-3.8-live-extended-thinking`)**: Specialized for complex
        reasoning, multi-step planning, and long-horizon state tracking with
        configurable thinking levels (`MINIMAL`, `LOW`, `MEDIUM`, `HIGH`) and
        asynchronous function calling.

    To get started, see the
    [Thinking in the Live API guide](/docs/live-api/thinking) and the
    [Live API overview](/docs/live-api).

## September 3, 2026 {% id="09-03-2026" %}

*   **Lyria 3.5 generally available (GA)**: Released the next generation of
    Google's music generation model:
    *   [`lyria-3.5`](/docs/models/lyria-3.5):
        Full-length song generation with improved musical coherence, natural
        vocals, and fine-grained duration and structural control.

    The model supports text and image inputs and generates high-fidelity 44.1
        kHz stereo audio. See the [Music generation](/docs/music-generation)
        guide for details and code samples.

## September 2, 2026 {% id="09-02-2026" %}

*   **Gemini 3.8 Flash generally available (GA)**: Released `gemini-3.8-flash`,
    our most intelligent Flash model, engineered for long-horizon software
    engineering, autonomous agents, and complex enterprise workflows.

    To get started, see the [Gemini 3.8 Flash](/docs/models/gemini-3.8-flash)
    model page and the [Gemini 3.8 Flash guide](/docs/whats-new-gemini-3.8).

## September 1, 2026 {% id="09-01-2026" %}

*   **Agentic video understanding**: Released agentic video understanding for
    Gemini 3.7 Flash, 3.6 Flash, and 3.5 Flash-Lite across the Interactions and
    GenerateContent APIs. The model dynamically navigates video timelines,
    requesting transcripts, frames, or audio tracks on demand. This approach
    uses up to 88% fewer tokens for long-form content compared to static
    processing.

    To get started, see the [Agentic video
    understanding](/docs/video-understanding#agentic-video-understanding) guide.

## August 27, 2026 {% id="08-27-2026" %}

*   **Gemini Omni Flash generally available (GA)**: Released
    `gemini-omni-1.1-flash`, the GA version of our fast, conversational video
    generation and editing model. This release includes significant new
    capabilities:
    *   **Video extension**: Seamlessly extend existing videos by generating
        continuations at the end of a clip using the `extend` task or directly
        with a prompt.
    *   **Interpolation (first + last frame)**: Generate a video transitioning
        between two images using the `image_to_video` task with up to 2 images.
    *   **Resolution control**: New `resolution` parameter in `video_config`
        supports `360p`, `720p` (default), `1080p`, and `4k` outputs.
        1080p and 4K outputs are generated using upscaling.

    The existing `gemini-omni-flash-preview` endpoint will be deprecated on
        September 30, 2026.

    To get started, see the [Gemini Omni Flash](/docs/models/gemini-omni-flash)
    model page and the [omni guide](/docs/omni).

## August 26, 2026 {% id="08-26-2026" %}

*   **Gemini 3.5 Transcribe generally available (GA)**: Released two dedicated
    speech-to-text models based on Gemini's audio understanding:
    *   **Gemini 3.5 Transcribe** (`gemini-3.5-transcribe`): High-accuracy,
        low-latency non-streaming speech-to-text with utterance-based language
        detection across 80+ languages, speaker diarization, word-level
        timestamps, and custom vocabulary biasing (up to 1,000 terms).
    *   **Gemini 3.5 Transcribe Live** (`gemini-3.5-transcribe-live`):
        Low-latency, bidirectional streaming speech-to-text over WebSockets
        using the Live API, supporting interim and finalized transcription
        events, Smart transcription mode, and multiple Voice Activity Detection
        (VAD) strategies.

    To get started, see the [Audio transcription guide](/docs/transcribe), the
        [Live transcription guide](/docs/live-api/live-transcribe), and the
        [Gemini 3.5 Transcribe model page](/docs/models/gemini-3.5-transcribe).

## August 13, 2026 {% id="08-13-2026" %}

*   **Gemini 3.7 Flash generally available (GA)**: Released our most intelligent
    workhorse model yet for coding and agents:
    *   **Gemini 3.7 Flash** (`gemini-3.7-flash`): Substantial improvements
        across software engineering, web development, and agentic workflows,
        available at an introductory price through December 31, 2026.

    To get started, see the [Gemini 3.7 Flash](/docs/models/gemini-3.7-flash)
        model page and the [Latest model guide](/docs/latest-model).

## July 30, 2026 {% id="07-30-2026" %}

*   **Gemini Robotics ER 2 in public preview**: Released two new embodied
    reasoning model endpoints for robotics:
    *   `gemini-robotics-er-2-preview`: Advanced spatial reasoning, agentic code
        execution, multi-step tool orchestration, video moment finding, progress
        classification, and multi-robot coordination.
    *   `gemini-robotics-er-2-streaming-preview`: Optimized for real-time text
        streaming using the Live API, enabling low-latency robot agents with
        bidirectional audio and video input.

    Both model endpoints accept text, image, video, and audio inputs and support
    function calling with blocking behavior for physical robot actions. To get
        started, see the [Gemini Robotics ER overview](/docs/robotics-overview).
    For real-time streaming use cases, see [Robotics with
        streaming](/docs/robotics-streaming).

*   **Deprecation announcement**: The `gemini-robotics-er-1.6-preview` model
    will be [shut down](/docs/deprecations) on August 31, 2026.

## July 21, 2026 {% id="07-21-2026" %}

*   **Gemini 3.6 Flash and Gemini 3.5 Flash-Lite generally available (GA)**:
    Released stable, production-ready versions of our latest 3.x Flash models:
    *   **Gemini 3.6 Flash** (`gemini-3.6-flash`): Features improved token
        efficiency and code/agentic planning capabilities at a lower price point
        than 3.5 Flash, resolving developer feedback around output verbosity.
    *   **Gemini 3.5 Flash-Lite** (`gemini-3.5-flash-lite`): Offers a
        low-latency, highly cost-effective subagent option designed for
        high-volume automation.

    To learn more, see the [Gemini 3.6 Flash guide](/docs/whats-new-gemini-3.6).

*   **Deprecated parameters**: The sampling parameters `temperature`, `top_p`
    and `top_k` are now deprecated. See the [Gemini 3.6 Flash
    guide](/docs/whats-new-gemini-3.6#sampling-parameter-deprecation) for
    details.

## July 6, 2026 {% id="07-06-2026" %}

*   [Developer logs](/docs/logs-datasets) support for the Interactions API: logs
    for supported Interactions API calls are now viewable in the [AI Studio
    dashboard](https://aistudio.google.com/logs).

## June 30, 2026 {% id="06-30-2026" %}

*   **Gemini Omni Flash in public preview**: Released
    `gemini-omni-flash-preview`, a high-performance multimodal model designed
    for high-speed video generation and conversational video editing. Using the
    [Interactions API](/docs/interactions-overview), you can generate 3–10
    second videos at 720p from text descriptions or animate still images, and
    then conversationally edit and refine the outputs. To get started, see the
    [Gemini Omni Flash](/docs/omni) guide and the [Gemini Omni
    Flash](/docs/models/gemini-omni-flash) model card.

*   Released `gemini-3.1-flash-lite-image` (Nano Banana 2 Lite) to general
    availability (GA), our built-in multimodal model optimized for ultra-low
    latency and cost-effective image generation and editing. See the [Gemini 3.1
    Flash Lite Image](/docs/models/gemini-3.1-flash-lite-image) model card and
    the [Image generation](/docs/image-generation) guide.

## June 24, 2026 {% id="06-24-2026" %}

*   **Computer Use**: Launched public preview support for the [Computer
    Use](/docs/computer-use) tool in Gemini 3.5 Flash. This release includes
    simplified actions with intents, built-in support for browser, mobile, and
    desktop environments, configurable safety policies, and advanced prompt
    injection detection.

## June 17, 2026 {% id="06-17-2026" %}

*   **Streaming support for speech generation**: Streaming via
    `streamGenerateContent` (and `stream: true` in the Interactions API) is now
    supported for the `gemini-3.1-flash-tts-preview` model. To learn more, see
    the [Text-to-Speech](/docs/speech-generation#streaming) guide.

## June 15, 2026 {% id="06-15-2026" %}

*   **Deprecation announcement**: The following image generation models are
    being deprecated and will be [shut down](/docs/deprecations) on
    **August 17, 2026**:

    *   **Imagen 4 and Gemini 3 Image models**:
        *   `imagen-4.0-generate-001`
        *   `imagen-4.0-ultra-generate-001`
        *   `imagen-4.0-fast-generate-001`

    To migrate your code to newer stable or preview endpoints, refer to the
            [Gemini deprecations](/docs/deprecations#imagen-models) page.

*   **Deprecation announcement**: The following video generation models are
    being deprecated and will be [shut down](/docs/deprecations) on
    **June 30, 2026**:

    *   **Veo models**:
        *   `veo-2.0-generate-001`
        *   `veo-3.0-generate-001`
        *   `veo-3.0-fast-generate-001`

    Update your integration to either use the Veo 3.1 preview model IDs
            (`veo-3.1-generate-preview`, `veo-3.1-fast-generate-preview`) or the
    3.1 GA models available through the [Gemini Enterprise Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate)
    to avoid service interruptions.

*   **Deprecation announcement**: The experimental GMP Contextual View tool (a
    fixed interface for Grounding with Google Maps outputs) will [shut
    down](/docs/deprecations) on **June 15, 2026**:

## June 1, 2026 {% id="06-01-2026" %}

*   The following Gemini 2.0 models are now [shut down](/docs/deprecations):

    *   `gemini-2.0-flash`
    *   `gemini-2.0-flash-001`
    *   `gemini-2.0-flash-lite`
    *   `gemini-2.0-flash-lite-001`

    Use [`gemini-3.5-flash`](/docs/models/gemini-3.5-flash) or
        [`gemini-3.1-flash-lite`](/docs/models/gemini-3.1-flash-lite) instead.

## May 28, 2026 {% id="05-28-2026" %}

*   Released `gemini-3.1-flash-image` (Nano Banana 2) and `gemini-3-pro-image`
    (Nano Banana Pro), the generally available (GA) versions of our native
    visual models, [Gemini 3.1 Flash Image](/docs/models/gemini-3.1-flash-image)
    and [Gemini 3 Pro Image](/docs/models/gemini-3-pro-image).

*   **Video-to-image generation support**: You can now pass a video file (via
    direct upload or as a public YouTube URL) as multimodal context alongside a
    text prompt to generate high-quality thumbnails, cinematic movie posters, or
    summary infographics. This feature is supported exclusively on the
    `gemini-3.1-flash-image` model. To learn more, see the [Video-to-image
    generation](/docs/image-generation#video-to-image) guide.

*   Deprecation announcement: The `gemini-3.1-flash-image-preview` and
    `gemini-3-pro-image-preview` models are deprecated and will be [shut
    down](/docs/deprecations) on June 25, 2026.

## May 25, 2026 {% id="05-25-2026" %}

*   The `gemini-3.1-flash-lite-preview` model has been [shut
    down](/docs/deprecations). Use
    [`gemini-3.1-flash-lite`](/docs/models/gemini-3.1-flash-lite) instead.

## May 19, 2026 {% id="05-19-2026" %}

*   Released `gemini-3.5-flash`, the generally available (GA) version of [Gemini
    3.5 Flash](/docs/models/gemini-3.5-flash), our most intelligent model for
    sustained frontier performance on agentic and coding tasks.

*   Launched the **Managed Agents in the Gemini API** in public preview. This
    enables developers to build and deploy autonomous, stateful agents that run
    in secure, isolated Google-hosted Linux sandbox environments. To learn more,
    see the [Agents overview](/docs/agents) page and the
    [Quickstart](/docs/managed-agents-quickstart).

*   Released the general-purpose **Antigravity Agent** managed agent,
    [`antigravity-preview-05-2026`](/docs/models/antigravity-preview-05-2026),
    in public preview. The Antigravity agent can autonomously plan, reason,
    write and execute code, manage files, and browse the web inside its sandbox
    container. See the [Antigravity Agent](/docs/antigravity-agent) guide for
    code samples and specifications.

## May 7, 2026 {% id="05-07-2026" %}

*   Released `gemini-3.1-flash-lite`, the generally available (GA) version of
    [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite), optimized for
    speed, scale, and cost efficiency.

*   Deprecation announcement: The `gemini-3.1-flash-lite-preview` model is
    deprecating on 5/11/26 and will be [shut down](/docs/deprecations) on May
    25, 2026.

## May 6, 2026 {% id="05-06-2026" %}

*   **Upcoming breaking change**: The [Interactions API](/docs/interactions-overview)
    request and response schema (`outputs` → `steps`) and output format
    configuration (`response_format`) are changing. The new schema becomes the
    default on **May 26** and the legacy schema will be removed on **June 8**.
    See the [migration guide](/docs/interactions-breaking-changes-may-2026) for
    details.

## May 5, 2026 {% id="05-05-2026" %}

*   Updated **File Search** to support multimodal search. You can now natively
    embed and search through images using the `gemini-embedding-2` model.
    Grounding metadata now includes `media_id` for visual citations and
    `page_numbers` that indicate where information is found. To learn more, see
    the [File Search](/docs/file-search) guide.

## May 4, 2026 {% id="05-04-2026" %}

*   Launched event-driven [Webhooks](/docs/webhooks) support in the Gemini API
    to replace polling workflows for the Batch API and long-running operations.

## April 30, 2026 {% id="04-30-2026" %}

*   The `gemini-robotics-er-1.5-preview` model has been [shut
    down](/docs/deprecations). Use
    [`gemini-robotics-er-1.6-preview`](/docs/models/gemini-robotics-er-1.6-preview)
    instead.

## April 22, 2026 {% id="04-22-2026" %}

*   Released `gemini-embedding-2` as generally available (GA). To learn more,
    see the [Embeddings](/docs/embeddings) page.

## April 21, 2026 {% id="04-21-2026" %}

*   Released new versions of the [Deep Research](/docs/deep-research) agent with
    collaborative planning, visualization support, MCP server integration, and
    File Search:

    *   [`deep-research-preview-04-2026`](/docs/models/deep-research-preview-04-2026):
        Designed for speed and efficiency, ideal to be streamed back to a client
        UI.

    *   [`deep-research-max-preview-04-2026`](/docs/models/deep-research-max-preview-04-2026):
        Maximum comprehensiveness for automated context gathering and synthesis.

## April 15, 2026 {% id="04-15-2026" %}

*   Launched [Gemini 3.1 Flash TTS
    Preview](/docs/models/gemini-3.1-flash-tts-preview), our cost-efficient,
    expressive, and steerable text to speech model. Read the
    [Text-to-Speech](/docs/speech-generation) docs to learn more.

## April 14, 2026 {% id="04-14-2026" %}

*   Released `gemini-robotics-er-1.6-preview`, our updated robotics model. It
    now has new capabilities like instrument reading, improved spatial and
    physical reasoning capabilities. To learn more, see [Gemini
    Robotics-ER](/docs/robotics-overview) page and the
    [blog](https://deepmind.google/blog/gemini-robotics-er-1-6).

*   Deprecation announcement: The `gemini-robotics-er-1.5-preview` model will be
    [shut down](/docs/deprecations) on April 30, 2026 at 9AM PST.

## April 2, 2026 {% id="04-02-2026" %}

*   Released `gemma-4-26b-a4b-it` and `gemma-4-31b-it`, available on [AI
    Studio](https://aistudio.google.com) and through the Gemini API, as part of
    the [Gemma 4](https://ai.google.dev/gemma/docs/core) launch.

## April 1, 2026 {% id="04-01-2026" %}

*   Introduced the new [Flex](/docs/flex-inference) and
    [Priority](/docs/priority-inference) inference tiers, offering more options
    for optimizing cost or latency.

## March 31, 2026 {% id="03-31-2026" %}

*   Launched Veo 3.1 Lite Preview,
    [`veo-3.1-lite-generate-preview`](/docs/models/veo-3.1-lite-generate-preview),
    our most cost-efficient [video generation](/docs/video) model, designed for
    rapid iteration and building high-volume applications.

*   The `gemini-2.5-flash-lite-preview-09-2025` model has been shut down. Use
    [`gemini-3.1-flash-lite-preview`](/docs/models/gemini-3.1-flash-lite-preview)
    instead.

## March 26, 2026 {% id="03-26-2026" %}

*   Released
    [`gemini-3.1-flash-live-preview`](/docs/models/gemini-3.1-flash-live-preview),
    the latest audio-to-audio (A2A) model designed for real-time dialogue and
    voice-first AI applications. Read the [Live API](/docs/live-api) docs to get
    started.

## March 25, 2026 {% id="03-25-2026" %}

*   Launched [Lyria 3](/docs/music-generation) music generation models:
    [`lyria-3-clip-preview`](/docs/models/lyria-3-clip-preview) (30-second
    clips) and [`lyria-3-pro-preview`](/docs/models/lyria-3-pro-preview)
    (full-length songs). Both models accept text and image inputs and generate
    high-quality, 48kHz stereo audio. See the [Music
    generation](/docs/music-generation) guide for details and code samples.

## March 23, 2026 {% id="03-23-2026" %}

*   Rolled out [Prepay and Postpay billing plans](/docs/billing) in AI Studio.
    Existing accounts may be affected; read the [Billing](/docs/billing)
    documentation for more information.

## March 18, 2026 {% id="03-18-2026" %}

*   Released the new [Built-in Tools and Function Calling
    Combination](/docs/tool-combination) feature, making it possible to use
    Gemini's built-in tools alongside custom function calling tools in a single
    API call.

*   [Grounding with Google Maps](/docs/maps-grounding#supported-models) is now
    supported for Gemini 3 models going forward.

## March 16, 2026 {% id="03-16-2026" %}

*   Introduced revamped [Usage Tiers](/docs/billing#about-billing) and [Billing
    Account spend caps](/docs/billing#tier-spend-caps) for a better user billing
    experience.

## March 12, 2026 {% id="03-12-2026" %}

*   Introduced [project-level spend caps](/docs/billing#project-spend-caps) to
    billing in AI Studio.

## March 10, 2026 {% id="03-10-2026" %}

*   Released `gemini-embedding-2-preview`, our first multimodal embedding model.
    It supports text, image, video, audio, and PDF inputs, mapping all
    modalities into a unified embedding space. To learn more, see
    [Embeddings](/docs/embeddings).

*   Deprecation announcement: The `gemini-2.5-flash-lite-preview-09-2025` model
    will be [shut down](/docs/deprecations) on March 31, 2026.

## March 9, 2026 {% id="03-09-2026" %}

*   The Gemini 3 Pro Preview model has been [shut down](/docs/deprecations). The
    `gemini-3-pro-preview` now points to
    [`gemini-3.1-pro-preview`](/docs/models/gemini-3.1-pro-preview).

## March 3, 2026 {% id="03-03-2026" %}

*   Launched Gemini 3.1 Flash-Lite Preview, the first Flash-Lite model in the
    Gemini 3 series. Read the [model
    page](/docs/models/gemini-3.1-flash-lite-preview) for specs, specific
    updates, and developer guidance.

## February 26, 2026 {% id="02-26-2026" %}

*   Launched Nano Banana 2, [Gemini 3.1 Flash Image
    Preview](/docs/models/gemini-3.1-flash-image), a high-efficiency
    model optimized for speed and high-volume use cases.

*   Deprecation announcement: Gemini 3 Pro Preview (`gemini-3-pro-preview`) will
    be [shut down](/docs/deprecations) March 9, 2026.

## February 19, 2026 {% id="02-19-2026" %}

*   Released [Gemini 3.1 Pro Preview](/docs/models/gemini-3.1-pro-preview), our
    latest iteration in the new Gemini 3 series family.

*   Launched a separate endpoint `gemini-3.1-pro-preview-customtools`, which is
    better at prioritizing custom tools, for users building with a mix of bash
    and tools.

## February 18, 2026 {% id="02-18-2026" %}

*   Deprecation announcement: The following models will be [shut
    down](/docs/deprecations) June 1, 2026:

    *   `gemini-2.0-flash`
    *   `gemini-2.0-flash-001`
    *   `gemini-2.0-flash-lite`
    *   `gemini-2.0-flash-lite-001`

## February 17, 2026 {% id="02-17-2026" %}

*   The following models are [shut down](/docs/deprecations):

    *   `gemini-2.5-flash-preview-09-25`
    *   `imagen-4.0-generate-preview-06-06`
    *   `imagen-4.0-ultra-generate-preview-06-06`

## January 29, 2026 {% id="01-29-2026" %}

*   Launched support for the Computer Use tool in `gemini-3-pro-preview` and
    `gemini-3-flash-preview`.

## January 21, 2026 {% id="01-21-2026" %}

*   Changed the `latest` aliases:

    *   `gemini-pro-latest` switched to `gemini-3-pro-preview`
    *   `gemini-flash-latest` switched to `gemini-3-flash-preview`

## January 15, 2026 {% id="01-15-2026" %}

*   Deprecation announcement: The following models will be [shut
    down](/docs/deprecations) February 17, 2026:

    *   `gemini-2.5-flash-preview-09-25`
    *   `imagen-4.0-generate-preview-06-06`
    *   `imagen-4.0-ultra-generate-preview-06-06`

*   The `gemini-2.5-flash-image-preview` model has been shut down.

## January 14, 2026 {% id="01-14-2026" %}

*   The `text-embedding-004` model has been [shut down](/docs/deprecations).

## January 13, 2026 {% id="01-13-2026" %}

*   Added 4k output resolutions for [Veo](/docs/video) and more support for
    portrait videos in all resolutions.

## January 12, 2026 {% id="01-12-2026" %}

*   Launched model lifecycle feature. Some models will now specify the lifecycle
    stage and deprecation timeline. See the following documentation for more
    information:

    *   [Model stages](https://ai.google.dev/api/generate-content#ModelStatus)

## January 8, 2026 {% id="01-08-2026" %}

*   Launched support for Cloud Storage buckets and any public and private DB
    pre-signed URL as data input source for the Gemini API. The file size limit
    has also increased from 20MB to 100MB. For details, see [File input methods
    guide](/docs/file-input-methods).

## December 19, 2025 {% id="12-19-2025" %}

*   Introduced a breaking change to the Interactions API in v1beta. The
    `total_reasoning_tokens` field has been renamed to `total_thought_tokens` to
    better align with the concept of "thoughts" in thinking models.

## December 17, 2025 {% id="12-17-2025" %}

*   Launched Gemini 3 Flash Preview, `gemini-3-flash-preview`, delivering fast
    frontier-class performance that rivals larger models at a fraction of the
    cost. With upgraded visual and spatial reasoning, and agentic coding
    capabilities. Read the documentation on some new features, including:

    *   [Multimodal function responses](/docs/function-calling#multimodal)
    *   [Code execution with images](/docs/code-execution#images)

## December 12, 2025 {% id="12-12-2025" %}

*   Released `gemini-2.5-flash-native-audio-preview-12-2025`, a new native audio
    model for the Live API. This update improves the model's ability to handle
    complex workflows. To learn more, see the [Live API
    guide](/docs/live-api/capabilities) and [Gemini 2.5 Flash Native
    Audio](/docs/models/gemini-2.5-flash-native-audio-preview-12-2025).

## December 11, 2025 {% id="12-11-2025" %}

*   Launched the Interactions API. This API provides a unified interface for
    interacting with Gemini models and agents. To learn more, see the
    [Interactions API](/docs/interactions-overview) guide.

*   Launched the Gemini Deep Research agent in preview. It can autonomously
    plan, execute, and synthesize results for multi-step research tasks. See the
    [Deep Research](/docs/deep-research) guide for details.

## December 10, 2025 {% id="12-10-2025" %}

*   Launched enhancements to our [text-to-speech
    models](/docs/speech-generation), Gemini 2.5 Flash TTS preview (optimized
    for low latency) and Gemini 2.5 Pro TTS preview (optimized for quality),
    including enhanced expressivity, precision pacing, and seamless dialogue.

## December 9, 2025 {% id="12-09-2025" %}

*   The following Gemini Live API models are now shut down:
    -   `gemini-2.0-flash-live-001`
    -   `gemini-live-2.5-flash-preview`

## December 5, 2025 {% id="12-05-2025" %}

*   Gemini 3 billing for [Grounding with Google Search](/docs/google-search)
    will begin on January 5, 2026.

## December 4, 2025 {% id="12-04-2025" %}

*   Deprecation announcement: The `gemini-2.5-flash-image-preview` model will be
    shut down January 15, 2026.

## December 3, 2025 {% id="12-03-2025" %}

*   Deprecation announcement: The `text-embedding-004` model will be shut down
    January 14, 2026.

## November 20, 2025 {% id="11-20-2025" %}

*   Released Gemini 3 Pro Image Preview, `gemini-3-pro-image-preview`, the next
    iteration to the Nano Banana model. Read the [Image
    generation](/docs/image-generation) page for more details.

## November 18, 2025 {% id="11-18-2025" %}

*   Launched the first Gemini 3 series model, `gemini-3-pro-preview`, our
    state-of-the-art reasoning and multimodal understanding model with powerful
    agentic and coding capabilities.

    In addition to improvements in intelligence and performance, Gemini 3 Pro
    Preview introduces new behavior around:

    *   [Media resolution](/docs/media-resolution)
    *   [Thought signatures](/docs/thinking#signatures)
    *   [Thinking levels](/docs/thinking#thinking-levels)

    Read the Gemini 3 Developer Guide for migration, new features, and specs.

## November 11, 2025 {% id="11-11-2025" %}

*   Deprecation announcement: The following models will be shut down:

    *   November 12:
        -   `veo-3.0-fast-generate-preview`
        -   `veo-3.0-generate-preview`

    *   November 14:
        -   `gemini-2.0-flash-exp-image-generation`
        -   `gemini-2.0-flash-preview-image-generation`

## November 10, 2025 {% id="11-10-2025" %}

*   The following model is shut down:

    -   `imagen-3.0-generate-002`

    Use [Imagen 4](/docs/image-generation) instead. Refer to the
        [Gemini deprecations table](/docs/deprecations) for more details.

## November 6, 2025 {% id="11-06-2025" %}

*   Launched the File Search API to public preview, enabling developers to
    ground responses in their own data. Read the new [File
    Search](/docs/file-search) page for more info.

## November 4, 2025 {% id="11-04-2025" %}

*   For [Gemini 2.5 Flash Image](/docs/image-generation), the input token count
    for images has been reduced from 1290 to 258, lowering the cost of image
    editing.

*   Deprecation announcement: The following models will be shut down:

    *   November 18th:

        -   `gemini-2.5-flash-lite-preview-06-17`
        -   `gemini-2.5-flash-preview-05-20`

    *   December 2nd:

        -   `gemini-2.0-flash-thinking-exp`
        -   `gemini-2.0-flash-thinking-exp-01-21`
        -   `gemini-2.0-flash-thinking-exp-1219`
        -   `gemini-2.5-pro-preview-03-25`
        -   `gemini-2.5-pro-preview-05-06`
        -   `gemini-2.5-pro-preview-06-05`

    *   December 9th:

        -   `gemini-2.0-flash-lite-preview`
        -   `gemini-2.0-flash-lite-preview-02-05`
        -   `gemini-2.0-flash-exp`
        -   `gemini-2.0-pro-exp`
        -   `gemini-2.0-pro-exp-02-05`

## October 29, 2025 {% id="10-29-2025" %}

*   Launched the new [logging and datasets](/docs/logs-datasets) tool for the
    Gemini API.

## October 20, 2025 {% id="10-20-2025" %}

*   The following Gemini Live API models are now shut down:
    -   `gemini-2.5-flash-preview-native-audio-dialog`
    -   `gemini-2.5-flash-exp-native-audio-thinking-dialog`

    You can use `gemini-2.5-flash-native-audio-preview-09-2025` instead.

*   Deprecation announcement: Shut down for `gemini-2.0-flash-live-001` and
    `gemini-live-2.5-flash-preview` coming December 09, 2025.

## October 17, 2025 {% id="10-17-2025" %}

*   **Grounding with Google Maps** is now generally available. For more
    information, see [Grounding with Google Maps](/docs/maps-grounding)
    documentation.

## October 15, 2025 {% id="10-15-2025" %}

*   Released [Veo 3.1 and 3.1 Fast](/docs/video) models in public
    preview, with new features including:

    -   Extending Veo-created videos.
    -   Referencing up to three images to generate a video.
    -   Providing first and last frame images to generate videos from.

    This launch also added more options for Veo 3 output video durations: 4, 6,
    and 8 seconds.

*   Deprecation announcement: Shut down for `veo-3.0-generate-preview` and
    `veo-3.0-fast-generate-preview` coming November 12, 2025.

## October 7, 2025 {% id="10-07-2025" %}

*   Launched [Gemini 2.5 Computer Use Preview](/docs/computer-use)

## October 2, 2025 {% id="10-02-2025" %}

*   Launched Gemini 2.5 Flash Image GA: [Image Generation with Gemini](/docs/image-generation)

## September 29, 2025 {% id="09-29-2025" %}

*   The following Gemini 1.5 models are now shut down:
    -   `gemini-1.5-pro`
    -   `gemini-1.5-flash-8b`
    -   `gemini-1.5-flash`

## September 25, 2025 {% id="09-25-2025" %}

*   Released Gemini Robotics-ER 1.5 model in preview. See the [Robotics
    overview](/docs/robotics-overview) to learn about how to use the model for
    your robotics application.

*   Launched following preview models:
    -   `gemini-2.5-flash-preview-09-2025`
    -   `gemini-2.5-flash-lite-preview-09-2025`

    See the [Models](/docs/models) page for details.

## September 23, 2025 {% id="09-23-2025" %}

*   Released `gemini-2.5-flash-native-audio-preview-09-2025`, a new native audio
    model for the Live API with improved function calling and speech cut off
    handling. To learn more, see the [Live API
    guide](/docs/live-api/capabilities) and [Gemini 2.5 Flash Native
    Audio](/docs/models).

## September 16, 2025 {% id="09-16-2025" %}

*   Deprecation announcement: The following models will be shut down in October
    2025:
    -   `embedding-001`
    -   `embedding-gecko-001`
    -   `gemini-embedding-exp-03-07` (`gemini-embedding-exp`)

    See the [Embeddings](/docs/embeddings) page for details on the latest embeddings
        model.

## September 10, 2025 {% id="09-10-2025" %}

*   Released support for the [Embeddings model in Batch
    API](/docs/batch-api#batch-embedding), and added Batch API to the [OpenAI
    compatibility library](/docs/openai#batch) for even easier ways to get
    started with batch queries.

## September 9, 2025 {% id="09-09-2025" %}

*   Launched Veo 3 and Veo 3 Fast GA, with lower pricing and new options for
    aspect ratios, resolution, and seeding. Read the [Veo
    documentation](/docs/video) for more information.

## August 26, 2025 {% id="08-26-2025" %}

*   Launched [Gemini 2.5 Image
    Preview](/docs/models), our latest native
    image generation model.

## August 18, 2025 {% id="08-18-2025" %}

*   Released [URL context tool](/docs/url-context) to general availability (GA),
    a tool for providing URLs as additional context to prompts. Support for
    using URL context with the `gemini-2.0-flash` model (available during
    experimental release) will be discontinued in one week.

## August 14, 2025 {% id="08-14-2025" %}

*   Released Imagen 4 Ultra, Standard and Fast models as generally available
    (GA). To learn more, see the [Imagen](/docs/image-generation) page.

## August 7, 2025 {% id="08-07-2025" %}

*   `allow_adult` setting in Image to Video generation are now available in
    restricted regions. See the
    [Veo](/docs/video?example=dialogue) page for details.

## July 31, 2025 {% id="07-31-2025" %}

*   Launched image-to-video generation for the Veo 3 Preview model.
*   Released Veo 3 Fast Preview model.
*   To learn more about Veo 3, visit the [Veo](/docs/video) page.

## July 22, 2025 {% id="07-22-2025" %}

*   Released `gemini-2.5-flash-lite`, our fast, low-cost, high-performance
    Gemini
    2.5 model. To learn more, see [Gemini 2.5
    Flash-Lite](/docs/models#gemini-25-flash-lite).

## July 17, 2025 {% id="07-17-2025" %}

*   Launched `veo-3.0-generate-preview`, the latest update to Veo introducing
    video with audio generation. To learn more about Veo 3, visit the
    [Veo](/docs/video) page.

*   Increased rate limits for Imagen 4 Standard and Ultra. Visit the [Rate
    limits](/docs/rate-limits) page for more details.

## July 14, 2025 {% id="07-14-2025" %}

*   Released `gemini-embedding-001`, the stable version of our text embedding
    model. To learn more, see [embeddings](/docs/embeddings). The
    `gemini-embedding-exp-03-07` model will be deprecated on August 14, 2025.

## July 7, 2025 {% id="07-07-2025" %}

*   Launched Gemini API Batch Mode. Batch up requests and send them to process
    asynchronously. To learn more, see [Batch Mode](/docs/batch-api).

## June 26, 2025 {% id="06-26-2025" %}

*   The preview models `gemini-2.5-pro-preview-05-06` and
    `gemini-2.5-pro-preview-03-25` are now redirecting to the latest stable
    version `gemini-2.5-pro`.

*   `gemini-2.5-pro-exp-03-25` is shut down.

## June 24, 2025 {% id="06-24-2025" %}

*   Released Imagen 4 Ultra and Standard Preview models. To learn more, see the
    [Image generation](/docs/image-generation) page.

## June 17, 2025 {% id="06-17-2025" %}

*   Released `gemini-2.5-pro`, the stable version of our most powerful model,
    now with adaptive thinking. To learn more, see [Gemini 2.5
    Pro](/docs/models#gemini-25-pro) and [Thinking](/docs/thinking).
    `gemini-2.5-pro-preview-05-06` will be redirected to `gemini-2.5-pro` on
    June 26, 2025.

*   Released `gemini-2.5-flash`, our first stable 2.5 Flash model. To learn
    more, see [Gemini 2.5 Flash](/docs/models#gemini-25-flash).
    `gemini-2.5-flash-preview-04-17` will be deprecated on July 15, 2025.

*   Released `gemini-2.5-flash-lite-preview-06-17`, a low-cost, high-performance
    Gemini 2.5 model. To learn more, see [Gemini 2.5 Flash-Lite
    Preview](/docs/models#gemini-25-flash-lite).

## June 05, 2025 {% id="06-05-2025" %}

*   Released `gemini-2.5-pro-preview-06-05`, a new version of our most powerful
    model, now with adaptive thinking. To learn more, see [Gemini 2.5 Pro
    Preview](/docs/models) and
    [Thinking](/docs/thinking). `gemini-2.5-pro-preview-05-06` will be
    redirected to `gemini-2.5-pro` on June 26, 2025.

## May 27, 2025 {% id="05-27-2025" %}

*   The last available tuning model, Gemini 1.5 Flash 001, has been shut down.
    Tuning is no longer supported on any models. See [Fine tuning with the
    Gemini API](/docs/model-tuning).

## May 20, 2025 {% id="05-20-2025" %}

**API updates:**

*   Launched support for [custom video preprocessing](/docs/video-understanding#customize-video-processing)
    using clipping intervals and configurable frame rate sampling.

*   Launched multi-tool use, which supports configuring [code
    execution](/docs/code-execution) and [Grounding with Google
    Search](/docs/google-search) on the same `generateContent` request.

*   Launched support for [asynchronous function calls](/docs/live-api/tools#async-function-calling)
    in the Live API.

*   Launched an experimental [URL context tool](/docs/url-context) for providing
    URLs as additional context to prompts.

**Model updates:**

*   Released `gemini-2.5-flash-preview-05-20`, a Gemini
    [preview](/docs/models#model-versions) model optimized for price-performance
    and adaptive thinking. To learn more, see [Gemini 2.5 Flash
    Preview](/docs/models) and
    [Thinking](/docs/thinking).

*   Released the [`gemini-2.5-pro-preview-tts`](/docs/models)
    and
    [`gemini-2.5-flash-preview-tts`](/docs/models)
    models, which are capable of [generating speech](/docs/speech-generation)
    with one or two speakers.

*   Released the `lyria-realtime-exp` model, which [generates
    music](/docs/music-generation) in real time.

*   Released `gemini-2.5-flash-preview-native-audio-dialog` and
    `gemini-2.5-flash-exp-native-audio-thinking-dialog`, new Gemini models for
    the Live API with native audio output capabilities. To learn more, see the
    [Live API guide](/docs/live-api/capabilities#native-audio-output) and
    [Gemini 2.5 Flash Native Audio](/docs/models).

*   Released `gemma-3n-e4b-it` preview, available on [AI
    Studio](https://aistudio.google.com) and through the Gemini API, as part of
    the [Gemma 3n](https://ai.google.dev/gemma/docs/3n) launch.

## May 7, 2025 {% id="05-07-2025" %}

*   Released `gemini-2.0-flash-preview-image-generation`, a preview model for
    generating and editing images. To learn more, see [Image
    generation](https://ai.google.dev/docs/image-generation) and [Gemini 2.0
    Flash Preview Image
    Generation](https://ai.google.dev/docs/models#gemini-2.0-flash-preview-image-generation).

## May 6, 2025 {% id="05-06-2025" %}

*   Released `gemini-2.5-pro-preview-05-06`, a new version of our most powerful
    model, with improvements on code and function calling.
    `gemini-2.5-pro-preview-03-25` will automatically point to the new version
    of the model.

## April 17, 2025 {% id="04-17-2025" %}

*   Released `gemini-2.5-flash-preview-04-17`, a Gemini
    [preview](/docs/models#model-versions) model optimized for price-performance
    and adaptive thinking. To learn more, see [Gemini 2.5 Flash
    Preview](/docs/models) and
    [Thinking](/docs/thinking).

## April 16, 2025 {% id="04-16-2025" %}

*   Launched context caching for [Gemini 2.0
    Flash](/docs/models).

## April 9, 2025 {% id="04-09-2025" %}

**Model updates:**

*   Released `veo-2.0-generate-001`, a generally available (GA) text- and
    image-to-video model, capable of generating detailed and artistically
    nuanced videos. To learn more, see the [Veo docs](/docs/video).

*   Released `gemini-2.0-flash-live-001`, a public preview version of the [Live
    API](/docs/live-api) model with billing enabled.

    *   **Enhanced Session Management and Reliability**
        *   **Session Resumption:** Keep sessions alive across temporary network
            disruptions. The API now supports server-side session state storage
            (for up to 24 hours) and provides handles (session_resumption) to
            reconnect and resume where you left off.

        *   **Longer Sessions via Context Compression:** Enable extended
            interactions beyond previous time limits. Configure context window
            compression with a sliding window mechanism to automatically manage
        context length, preventing abrupt terminations due to context limits.

        *   **Graceful Disconnect Notification:** Receive a `GoAway` server
            message indicating when a connection is about to close, allowing for
            graceful handling before termination.

    *   **More Control over Interaction Dynamics**
    *   **Configurable Voice Activity Detection (VAD):** Choose sensitivity
        levels or disable automatic VAD entirely and use new client events
        (`activityStart`, `activityEnd`) for manual turn control.

    *   **Configurable Interruption Handling:** Decide whether user input should
        interrupt the model's response.

    *   **Configurable Turn Coverage:** Choose whether the API processes all
        audio and video input continuously or only captures it when the end-user
        is detected speaking.

    *   **Configurable Media Resolution:** Optimize for quality or token usage
        by selecting the resolution for input media.

    *   **Richer Output and Features**
    *   **Expanded Voice & Language Options:** Choose from two new voices and
    30 new languages for audio output. The output language is now configurable
        within `speechConfig`.

    *   **Text Streaming:** Receive text responses incrementally as they are
        generated, enabling faster display to the user.

    *   **Token Usage Reporting:** Gain insights into usage with detailed token
        counts provided in the `usageMetadata` field of server messages, broken
        down by modality and prompt or response phases.

## April 4, 2025 {% id="04-04-2025" %}

*   Released `gemini-2.5-pro-preview-03-25`, a public preview Gemini 2.5 Pro
    version with billing enabled. You can continue to use
    `gemini-2.5-pro-exp-03-25` on sthe free tier.

## March 25, 2025 {% id="03-25-2025" %}

*   Released `gemini-2.5-pro-exp-03-25`, a public experimental Gemini model with
    thinking mode always on by default. To learn more, see [Gemini 2.5 Pro
    Experimental](/docs/models).

## March 12, 2025 {% id="03-12-2025" %}

**Model updates:**

*   Launched an experimental [Gemini 2.0 Flash](/docs/image-generation)
    model capable of image generation and editing.

*   Released `gemma-3-27b-it`, available on [AI
    Studio](https://aistudio.google.com) and through the Gemini API, as part of
    the [Gemma 3](https://ai.google.dev/gemma/docs/core) launch.

**API updates:**

*   Added support for [YouTube URLs](/docs/image-understanding) as a
    media source.

*   Added support for including an [inline
    video](/docs/image-understanding) of less than 20MB.

## March 11, 2025 {% id="03-11-2025" %}

**SDK updates:**

*   Released the [Google Gen AI SDK for TypeScript and JavaScript](https://googleapis.github.io/js-genai)
    to public preview.

## March 7, 2025 {% id="03-07-2025" %}

**Model updates:**

*   Released `gemini-embedding-exp-03-07`, an [experimental](/docs/models)
    Gemini-based embeddings model in public preview.

## February 28, 2025 {% id="02-28-2025" %}

**API updates:**

*   Support for [Search as a tool](/docs/google-search) added to
    `gemini-2.0-pro-exp-02-05`, an experimental model based on Gemini 2.0 Pro.

## February 25, 2025 {% id="02-25-2025" %}

**Model updates:**

*   Released `gemini-2.0-flash-lite`, a generally available (GA) version of
    [Gemini 2.0 Flash-Lite](/docs/models), which is
    optimized for speed, scale, and cost efficiency.

## February 19, 2025 {% id="02-19-2025" %}

**AI Studio updates:**

*   Support for [additional regions](https://ai.google.dev/docs/available-regions)
    (Kosovo, Greenland and Faroe Islands).

**API updates:**

*   Support for [additional regions](https://ai.google.dev/docs/available-regions)
    (Kosovo, Greenland and Faroe Islands).

## February 18, 2025 {% id="02-18-2025" %}

**Model updates:**

*   Gemini 1.0 Pro is no longer supported. For the list of supported models, see
    [Gemini models](/docs/models).

## February 11, 2025 {% id="02-11-2025" %}

**API updates:**

*   Updates on the [OpenAI libraries
    compatibility](https://ai.google.dev/docs/openai).

## February 6, 2025 {% id="02-06-2025" %}

**Model updates:**

*   Released `imagen-3.0-generate-002`, a generally available (GA) version of
    [Imagen 3 in the Gemini API](/docs/image-generation).

**SDK updates:**

*   Released the [Google Gen AI SDK for Java](https://github.com/googleapis/java-genai)
for public preview.

## February 5, 2025 {% id="02-05-2025" %}

**Model updates:**

*   Released `gemini-2.0-flash-001`, a generally available (GA) version of
    [Gemini 2.0 Flash](/docs/models) that supports text-only
    output.

*   Released `gemini-2.0-pro-exp-02-05`, an [experimental](/docs/models) public
    preview version of Gemini 2.0 Pro.

*   Released `gemini-2.0-flash-lite-preview-02-05`, an experimental public
    preview [model](/docs/models) optimized for cost
    efficiency.

**API updates:**

*   Added [file input and graph output](/docs/code-execution#input-output)
    support to code execution.

**SDK updates:**

*   Released the [Google Gen AI SDK for Python](https://googleapis.github.io/python-genai/)
    to general availability (GA).

## January 21, 2025 {% id="01-21-2025" %}

**Model updates:**

*   Released `gemini-2.0-flash-thinking-exp-01-21`, the latest preview version
    of the model behind the [Gemini 2.0 Flash Thinking Model](/docs/thinking).

## December 19, 2024 {% id="12-19-2024" %}

**Model updates:**

*   Released Gemini 2.0 Flash Thinking Mode for public preview. Thinking Mode is
    a test-time compute model that lets you see the model's thought process
    while it generates a response, and produces responses with stronger
    reasoning capabilities.

    Read more about Gemini 2.0 Flash Thinking Mode in our [overview
    page](/docs/thinking).

## December 11, 2024 {% id="12-11-2024" %}

**Model updates:**

*   Released [Gemini 2.0 Flash Experimental](/docs/models) for
    public preview. Gemini 2.0 Flash Experimental's partial list of features
    includes:

    *   Twice as fast as Gemini 1.5 Pro
    *   Bidirectional streaming with our Live API
    *   Multimodal response generation in the form of text, images, and speech
    *   Built-in tool use with multi-turn reasoning to use features like code
        execution, Search, function calling, and more

Read more about Gemini 2.0 Flash in our [overview page](/docs/models).

## November 21, 2024 {% id="11-21-24" %}

**Model updates:**

*   Released `gemini-exp-1121`, an even more powerful experimental Gemini API
    model.

**Model updates:**

*   Updated the `gemini-1.5-flash-latest` and `gemini-1.5-flash` model aliases
    to use `gemini-1.5-flash-002`.

    *   Change to `top_k` parameter: The `gemini-1.5-flash-002` model supports
        `top_k` values between 1 and 41 (exclusive). Values greater than 40 will
        be changed to 40.

## November 14, 2024 {% id="11-14-24" %}

**Model updates:**

*   Released `gemini-exp-1114`, a powerful experimental Gemini API model.

## November 8, 2024 {% id="11-08-24" %}

**API updates:**

*   Added [support for Gemini](/docs/openai) in the OpenAI libraries / REST API.

## October 31, 2024 {% id="10-31-24" %}

**API updates:**

*   Added [support for Grounding with Google Search](/docs/google-search).

## October 3, 2024 {% id="10-03-24" %}

**Model updates:**

*   Released `gemini-1.5-flash-8b-001`, a stable version of our smallest Gemini
   API model.

## September 24, 2024 {% id="09-24-24" %}

**Model updates:**

*   Released `gemini-1.5-pro-002` and `gemini-1.5-flash-002`, two new stable
    versions of Gemini 1.5 Pro and 1.5 Flash, for general availability.

*   Updated the `gemini-1.5-pro-latest` model code to use `gemini-1.5-pro-002`
    and the `gemini-1.5-flash-latest` model code to use `gemini-1.5-flash-002`.

*   Released `gemini-1.5-flash-8b-exp-0924` to replace
    `gemini-1.5-flash-8b-exp-0827`.
*   Released the [civic integrity safety filter](/docs/safety-settings#safety-filters)
    for the Gemini API and AI Studio.

*   Released support for two new parameters for Gemini 1.5 Pro and 1.5 Flash in
    Python and NodeJS:
    [`frequencyPenalty`](https://ai.google.dev/api/generate-content#FIELDS.frequency_penalty)
    and
    [`presencePenalty`](https://ai.google.dev/api/generate-content#FIELDS.presence_penalty).

## September 19, 2024 {% id="09-19-24" %}

**AI Studio updates:**

*   Added thumb-up and thumb-down buttons to model responses, to enable users to
    provide feedback on the quality of a response.

**API updates:**

*   Added support for Google Cloud credits, which can now be used towards Gemini
    API usage.

## September 17, 2024 {% id="09-17-24" %}

**AI Studio updates:**

*   Added an **Open in Colab** button that exports a prompt &ndash; and the code
    to run it &ndash; to a Colab notebook. The feature doesn't yet support
    prompting with tools (JSON mode, function calling, or code execution).

## September 13, 2024 {% id="09-13-24" %}

**AI Studio updates:**

*   Added support for compare mode, which lets you compare responses across
    models and prompts to find the best fit for your use case.

## August 30, 2024 {% id="08-30-24" %}

**Model updates:**

*   Gemini 1.5 Flash supports [supplying JSON schema through model
    configuration](/docs/structured-output).

## August 27, 2024 {% id="08-27-24" %}

**Model updates:**

*   Released the following [experimental models](/docs/models):

    *   `gemini-1.5-pro-exp-0827`
    *   `gemini-1.5-flash-exp-0827`
    *   `gemini-1.5-flash-8b-exp-0827`

## August 9, 2024 {% id="08-09-24" %}

**API updates:**

*   Added support for [PDF processing](/docs/document-processing).

## August 5, 2024 {% id="08-05-24" %}

**Model updates:**

*   Fine-tuning support released for Gemini 1.5 Flash.

## August 1, 2024 {% id="08-01-24" %}

**Model updates:**

*   Released `gemini-1.5-pro-exp-0801`, a new experimental version of [Gemini
    1.5 Pro](/docs/models).

## July 12, 2024 {% id="07-12-24" %}

**Model updates:**

*   Support for Gemini 1.0 Pro Vision removed from Google AI services and tools.

## June 27, 2024 {% id="06-27-24" %}

**Model updates:**

*   General availability release for Gemini 1.5 Pro's 2M context window.

**API updates:**

*   Added support for [code execution](/docs/code-execution).

## June 18, 2024 {% id="06-18-24" %}

**API updates:**

*   Added support for [context caching](/docs/caching).

## June 12, 2024 {% id="06-12-204" %}

**Model updates:**

*   Gemini 1.0 Pro Vision deprecated.

## May 23, 2024 {% id="05-23-24" %}

**Model updates:**

*   [Gemini 1.5 Pro](/docs/models) (`gemini-1.5-pro-001`) is
    generally available (GA).

*   [Gemini 1.5 Flash](/docs/models) (`gemini-1.5-flash-001`)
    is generally available (GA).

## May 14, 2024 {% id="05-14-24" %}

**API updates:**

*   Introduced a 2M context window for Gemini 1.5 Pro (waitlist).
*   Introduced pay-as-you-go [billing](/docs/billing) for Gemini 1.0 Pro, with
    Gemini 1.5 Pro and Gemini 1.5 Flash billing coming soon.

*   Introduced increased rate limits for the upcoming paid tier of Gemini 1.5
    Pro.

*   Added built-in video support to the [File
    API](https://ai.google.dev/api/rest/v1beta/files).
*   Added plain text support to the [File
    API](https://ai.google.dev/api/rest/v1beta/files).
*   Added support for parallel function calling, which returns more than one
    call at a time.

## May 10, 2024 {% id="05-10-24" %}

**Model updates:**

*   Released [Gemini 1.5 Flash](/docs/models)
    (`gemini-1.5-flash-latest`) in preview.

## April 9, 2024 {% id="04-09-24" %}

**Model updates:**

*   Released [Gemini 1.5 Pro](/docs/models)
    (`gemini-1.5-pro-latest`) in preview.

*   Released a new text embedding model, `text-embeddings-004`, which supports
    [elastic embedding](/docs/embeddings) sizes under 768.

**API updates:**

*   Released the [File API](https://ai.google.dev/api/rest/v1beta/files) for
    temporarily storing media files for use in prompting.

*   Added support for prompting with text, image, and audio data, also known as
    *multimodal* prompting. To learn more, see [Prompting with
    media](/docs/files#prompt-guide).

*   Released [System instructions](/docs/text-generation) in beta.

*   Added [Function calling mode](/docs/function-calling#function_calling_modes),
    which defines the execution behavior for function calling.

*   Added support for the `response_mime_type` configuration option, which lets
    you request responses in [JSON format](https://ai.google.dev/api#json).

## March 19, 2024 {% id="03-09-24" %}

**Model updates:**

*   Added support for [tuning Gemini 1.0 Pro](https://developers.googleblog.com/en/tune-gemini-pro-in-google-ai-studio-or-with-the-gemini-api/)
   in Google AI Studio or with the Gemini API.

## December 13 2023 {% id="12-13-23" %}

**Model updates:**

*   gemini-pro: New text model for a wide variety of tasks. Balances capability
    and efficiency.

*   gemini-pro-vision: New multimodal model for a wide variety of tasks.
    Balances capability and efficiency.

*   embedding-001: New embeddings model.
*   aqa: A new specially tuned model that is trained to answer questions using
    text passages for grounding generated answers.

See [Gemini models](/docs/models) for more details.

**API version updates:**

*   v1: The stable API channel.
*   v1beta: Beta channel. This channel has features that may be under
    development.

See [the API versions topic](https://ai.google.dev/gemini-api/docs/api-versions) for more details.

**API updates:**

*   `GenerateContent` is a single unified endpoint for chat and text.
*   Streaming available through the `StreamGenerateContent` method.
*   Multimodal capability: Image is a new supported modality
*   New beta features:
    *   [Function Calling](/docs/function-calling)
    *   Semantic Retriever
    *   Attributed Question Answering (AQA)
*   Updated candidate count: Gemini models only return 1 candidate.
*   Different Safety Settings and SafetyRating categories. See [safety
    settings](/docs/safety-settings) for more details.

*   Tuning models is not yet supported for Gemini models (Work in progress).

# Gemini deprecations
Source: https://aistudio.google.com/docs/deprecations
Description: Keep track of deprecation schedules for Gemini models and features

This page lists the known deprecation schedules for [stable
(GA)](/docs/models#stable) and [preview](/docs/models#preview) models and for
managed agents in the Gemini API. A "**deprecation**" is the announcement that
we no longer provide support for a model, and that it will be "**shut down**" in
the near future. Once a model is "**shutdown**", it is completely turned off, and
the endpoint is no longer available.

Deprecation announcements are made on the [Release notes](/docs/changelog) page,
and the announced earliest shutdown dates are tracked on this page.
Already-shutdown models and agents are listed under the **Deprecated models**
and **Deprecated agents** sections.

{% callout type="note" %}
Note: The **shutdown dates listed in the table indicate the *earliest possible
dates* on which a model might be retired**. We will communicate the exact
shutdown date to users with advance notice to ensure a smooth transition to a
replacement model.
{% /callout %}

## Gemini 3 models {% id="gemini-3-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-3.8-flash-tts`
*   September 22, 2026
*   No shutdown date announced
*
---

*   `gemini-3.8-flash-lite-tts`
*   September 22, 2026
*   No shutdown date announced
*
---

*   `gemini-3.8-live`
*   September 15, 2026
*   No shutdown date announced
*
---

*   `gemini-3.8-live-extended-thinking`
*   September 15, 2026
*   No shutdown date announced
*
---

*   `gemini-3.8-flash`
*   September 2, 2026
*   No shutdown date announced
*
---

*   `gemini-3.7-flash`
*   August 13, 2026
*   N/A
*   `gemini-3.8-flash` (`gemini-3.7-flash` is no longer available in Google AI Studio; the endpoint is not shutting down and automatically routes API requests to `gemini-3.8-flash`)
---

*   `gemini-3.6-flash`
*   July 21, 2026
*   No shutdown date announced
*
---

*   `gemini-3.5-flash-lite`
*   July 21, 2026
*   No shutdown date announced
*
---

*   `gemini-3.5-flash`
*   May 19, 2026
*   N/A
*   `gemini-3.6-flash` (`gemini-3.5-flash` is no longer available in Google AI Studio; the endpoint is not shutting down and automatically routes API requests to `gemini-3.6-flash`)
---

*   `gemini-3.1-flash-lite`
*   May 7, 2026
*   May 7, 2027
*   `gemini-3.5-flash-lite`
{% /table %}

### Preview models {% id="gemini-3-preview-models" %}

{% table %}
* Model
* Release date
* Shutdown date
* Recommended replacement
---
* `gemini-3.1-flash-tts-preview`
* February 26, 2026
* November 17, 2026
* `gemini-3.8-flash-tts` or `gemini-3.8-flash-lite-tts`
---
* `gemini-3.1-pro-preview`
* February 19, 2026
* No shutdown date announced
*
---
* `gemini-3-flash-preview`
* December 17, 2025
* No shutdown date announced
* `gemini-3.6-flash`
{% /table %}

### Deprecated models {% id="gemini-3-deprecated-models" %}

{% table %}
* Model
* Release date
* Shutdown date
* Recommended replacement
---
* `gemini-3-pro-preview`
* November 18, 2025
* March 9, 2026
* `gemini-3.1-pro-preview`
---
* `gemini-3.1-flash-lite-preview`
* March 3, 2026
* May 25, 2026
* `gemini-3.1-flash-lite`
{% /table %}

## Gemini 2.5 Pro models {% id="gemini-2.5-pro-models" %}

{% callout type="caution" %}
`gemini-2.5-pro` is deprecated and is no longer available to select in Google AI
Studio. Access through the API is limited to existing users who have actively
used it in the past. Effective December 1, 2026, all API requests to
`gemini-2.5-pro` will automatically route to
[`gemini-3.8-flash`](/docs/models/gemini-3.8-flash) and be billed at
[Gemini 3.8 Flash rates](/docs/pricing#gemini-3.8-flash). Review the breaking
API changes in the
[Gemini 3.8 Flash migration guide](/docs/whats-new-gemini-3.8#migrate-to-gemini-3-8-flash)
before December 1, 2026.
{% /callout %}

{% table %}
* Model
* Release date
* Shutdown date
* Recommended replacement
---
* `gemini-2.5-pro`
* June 17, 2025
* December 1, 2026
* `gemini-3.8-flash` (`gemini-2.5-pro` is no longer available in Google AI Studio; effective December 1, 2026, API requests to `gemini-2.5-pro` will automatically route to `gemini-3.8-flash`)
{% /table %}

### Deprecated models {% id="gemini-2.5-pro-deprecated-models" %}

{% table %}
* Model
* Release date
* Shutdown date
* Recommended replacement
---
* `gemini-2.5-computer-use-preview-10-2025`
* October 7, 2025
* July 28, 2026
* `gemini-3.8-flash`
---
* `gemini-2.5-pro-preview-03-25`
* March 3, 2025
* December 2, 2025
* `gemini-3.8-flash`
---
* `gemini-2.5-pro-preview-05-06`
* May 6, 2025
* December 2, 2025
* `gemini-3.8-flash`
---
* `gemini-2.5-pro-preview-06-05`
* June 5, 2025
* December 2, 2025
* `gemini-3.8-flash`
{% /table %}

## Gemini 2.5 Flash models {% id="gemini-2.5-flash-models" %}

{% callout type="caution" %}
`gemini-2.5-flash` is deprecated and is no longer available to select in Google
AI Studio. Effective December 1, 2026, all API requests to `gemini-2.5-flash`
will automatically route to
[`gemini-3.5-flash-lite`](/docs/models/gemini-3.5-flash-lite) and be billed at
[Gemini 3.5 Flash-Lite rates](/docs/pricing#gemini-3.5-flash-lite). Review the
breaking API changes in the
[Gemini 3.5 Flash-Lite migration guide](/docs/whats-new-gemini-3.6#migrate-to-gemini-3-5-flash-lite)
before December 1, 2026. Access to the 2.5 models is limited to users who have
actively used them in the past. `gemini-2.5-flash-lite` is not deprecated and
remains available through the API until further notice.
{% /callout %}

{% table %}
* Model
* Release date
* Shutdown date
* Recommended replacement
---
* `gemini-2.5-flash`
* June 17, 2025
* December 1, 2026
* `gemini-3.5-flash-lite` (`gemini-2.5-flash` is no longer available in Google AI Studio; effective December 1, 2026, API requests to `gemini-2.5-flash` will automatically route to `gemini-3.5-flash-lite`)
---
* `gemini-2.5-flash-lite`
* July 22, 2025
* No shutdown date announced
*
{% /table %}

### Deprecated models {% id="gemini-2.5-flash-deprecated-models" %}

{% table %}
* Model
* Release date
* Shutdown date
* Recommended replacement
---
* `gemini-2.5-flash-lite-preview-09-2025`
* September 25, 2025
* March 31, 2026
* `gemini-3.1-flash-lite`
---
* `gemini-2.5-flash-preview-05-20`
* May 20, 2025
* November 18, 2025
* `gemini-3.6-flash`
---
* `gemini-2.5-flash-preview-09-2025`
* September 25, 2025
* February 17, 2026
* `gemini-3.6-flash`
{% /table %}

## Gemini 2.0 models {% id="gemini-2.0-models" %}

### Deprecated models {% id="gemini-2.0-deprecated-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-2.0-flash`
*   February 5, 2025
*   June 1, 2026
*   `gemini-3.6-flash`
---

*   `gemini-2.0-flash-001`
*   February 5, 2025
*   June 1, 2026
*   `gemini-3.6-flash`
---

*   `gemini-2.0-flash-lite`
*   February 25, 2025
*   June 1, 2026
*   `gemini-3.1-flash-lite`
---

*   `gemini-2.0-flash-lite-001`
*   February 25, 2025
*   June 1, 2026
*   `gemini-3.1-flash-lite`
---

*   `gemini-2.0-flash-lite-preview`
*   February 5, 2025
*   December 9, 2025
*   `gemini-3.1-flash-lite`
---

*   `gemini-2.0-flash-lite-preview-02-05`
*   February 5, 2025
*   December 9, 2025
*   `gemini-3.1-flash-lite`
{% /table %}

## Live API models {% id="live-api-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-3.8-live`
*   September 15, 2026
*   No shutdown date announced
*
---

*   `gemini-3.8-live-extended-thinking`
*   September 15, 2026
*   No shutdown date announced
*
---

*   `gemini-3.5-transcribe-live`
*   August 2026
*   No shutdown date announced
*
{% /table %}

### Preview models {% id="live-api-preview-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-3.5-live-translate-preview`
*   June 2026
*   No shutdown date announced
*
---

*   `gemini-3.1-flash-live-preview`
*   March 11, 2026
*   November 17, 2026
*   `gemini-3.8-live`
---

*   `gemini-2.5-flash-native-audio-preview-12-2025`
*   December 12, 2025
*   November 17, 2026
*   `gemini-3.8-live`
{% /table %}

### Deprecated models {% id="live-api-deprecated-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-live-2.5-flash-preview`
*   June 17, 2025
*   December 9, 2025
*   `gemini-3.8-live`
---

*   `gemini-2.0-flash-live-001`
*   April 9, 2025
*   December 9, 2025
*   `gemini-3.8-live`
{% /table %}

## Audio models {% id="audio-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-3.5-transcribe`
*   August 2026
*   No shutdown date announced
*
{% /table %}

### Preview models {% id="audio-preview-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-2.5-flash-preview-tts`
*   May 20, 2025
*   November 17, 2026
*   `gemini-3.8-flash-tts` or `gemini-3.8-flash-lite-tts`
---

*   `gemini-2.5-pro-preview-tts`
*   May 20, 2025
*   November 17, 2026
*   `gemini-3.8-flash-tts` or `gemini-3.8-flash-lite-tts`
{% /table %}

## Embedding models {% id="embedding-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-embedding-2`
*   April 22, 2026
*   No shutdown date announced
*
---

*   `gemini-embedding-001`
*   July 14, 2025
*   May 14, 2028
*   `gemini-embedding-2`
{% /table %}

### Deprecated models {% id="embedding-deprecated-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-embedding-2-preview`
*   March 10, 2026
*   August 10, 2026
*   `gemini-embedding-2`
---

*   `text-embedding-004`
*   April 9, 2024
*   January 14, 2026
*   `gemini-embedding-2`
---

*   `embedding-001`
*   April 9, 2024
*   October 30, 2025
*   `gemini-embedding-2`
---

*   `embedding-gecko-001`
*
*   October 30, 2025
*   `gemini-embedding-2`
---

*   `gemini-embedding-exp`
*
*   October 30, 2025
*   `gemini-embedding-2`
---

*   `gemini-embedding-exp-03-07`
*
*   October 30, 2025
*   `gemini-embedding-2`
{% /table %}

## Nano Banana models {% id="nano-banana-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-nano-banana-2.1`
*   October 6, 2026
*   No shutdown date announced
*
---

*   `gemini-3.1-flash-lite-image`
*   June 30, 2026
*   No shutdown date announced
*
---

*   `gemini-3.1-flash-image`
*   May 28, 2026
*   No shutdown date announced
*   `gemini-nano-banana-2.1`
---

*   `gemini-3-pro-image`
*   May 28, 2026
*   No shutdown date announced
*
---

*   `gemini-2.5-flash-image`
*   October 2, 2025
*   March 15, 2027
*   `gemini-3.1-flash-lite-image`
{% /table %}

### Deprecated models {% id="nano-banana-deprecated-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-3.1-flash-image-preview`
*   February 26, 2026
*   June 25, 2026
*   `gemini-nano-banana-2.1`
---

*   `gemini-3-pro-image-preview`
*   November 20, 2025
*   June 25, 2026
*   `gemini-3-pro-image`
---

*   `gemini-2.5-flash-image-preview`
*   May 7, 2025
*   January 15, 2026
*   `gemini-nano-banana-2.1`
---

*   `gemini-2.0-flash-preview-image-generation`
*   May 7, 2025
*   November 14, 2025
*   `gemini-nano-banana-2.1`
{% /table %}

## Imagen models {% id="imagen-models" %}

### Deprecated models {% id="imagen-deprecated-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `imagen-4.0-generate-001`
*   June 24, 2025
*   August 17, 2026
*   `gemini-nano-banana-2.1`
---

*   `imagen-4.0-ultra-generate-001`
*   June 24, 2025
*   August 17, 2026
*   `gemini-nano-banana-2.1`
---

*   `imagen-4.0-fast-generate-001`
*   June 24, 2025
*   August 17, 2026
*   `gemini-nano-banana-2.1`
---

*   `imagen-4.0-generate-preview-06-06`
*   June 24, 2025
*   February 17, 2026
*   `gemini-nano-banana-2.1`
---

*   `imagen-4.0-ultra-generate-preview-06-06`
*   June 24, 2025
*   February 17, 2026
*   `gemini-nano-banana-2.1`
---

*   `imagen-3.0-generate-002`
*   February 6, 2025
*   November 10, 2025
*   `gemini-nano-banana-2.1`
{% /table %}

## Veo models {% id="veo-models" %}

### Deprecated models {% id="veo-deprecated-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `veo-3.1-lite-generate-preview`
*   March 31, 2026
*   October 22, 2026
*   `gemini-omni-1.1-flash`
---

*   `veo-3.1-generate-preview`
*   October 15, 2025
*   October 22, 2026
*   `gemini-omni-1.1-flash`
---

*   `veo-3.1-fast-generate-preview`
*   October 15, 2025
*   October 22, 2026
*   `gemini-omni-1.1-flash`
---

*   `veo-3.0-generate-001`
*   September 9, 2025
*   June 30, 2026
*   `gemini-omni-1.1-flash` or the GA models on the [Gemini Enterprise Agent
    Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate)
---

*   `veo-3.0-fast-generate-001`
*   September 9, 2025
*   June 30, 2026
*   `gemini-omni-1.1-flash` or the GA models on the [Gemini Enterprise
    Agent
    Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate)
---

*   `veo-2.0-generate-001`
*   April 9, 2025
*   June 30, 2026
*   `gemini-omni-1.1-flash` or the GA models on the [Gemini Enterprise Agent
    Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate)
---

*   `veo-3.0-generate-preview`
*   July 31, 2025
*   November 12, 2025
*   `gemini-omni-1.1-flash`
---

*   `veo-3.0-fast-generate-preview`
*   July 31, 2025
*   November 12, 2025
*   `gemini-omni-1.1-flash`
{% /table %}

## Gemini Omni Flash models {% id="gemini-omni-flash-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-omni-1.1-flash`
*   August 27, 2026
*   No shutdown date announced
*
{% /table %}

### Deprecated models {% id="gemini-omni-flash-deprecated-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-omni-flash-preview`
*   June 30, 2026
*   October 22, 2026
*   `gemini-omni-1.1-flash`
{% /table %}

## Lyria models {% id="lyria-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `lyria-3.5`
*   September 3, 2026
*   No shutdown date announced
*
{% /table %}

### Preview models {% id="lyria-preview-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `lyria-3-clip-preview`
*   March 25, 2026
*   No shutdown date announced
*
---

*   `lyria-3-pro-preview`
*   March 25, 2026
*   No shutdown date announced
*   `lyria-3.5`
---

*   `lyria-realtime-exp`
*   May 20, 2025
*   No shutdown date announced
*
{% /table %}

## Robotics models {% id="robotics-models" %}

### Preview models {% id="robotics-preview-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-robotics-er-2-preview`
*   July 30, 2026
*   No shutdown date announced
*
---

*   `gemini-robotics-er-2-streaming-preview`
*   July 30, 2026
*   No shutdown date announced
*
{% /table %}

### Deprecated models {% id="robotics-deprecated-models" %}

{% table %}

*   Model
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `gemini-robotics-er-1.6-preview`
*   April 14, 2026
*   August 31, 2026
*   `gemini-robotics-er-2-preview`
---

*   `gemini-robotics-er-1.5-preview`
*   September 25, 2025
*   April 30, 2026
*   `gemini-robotics-er-2-preview`
{% /table %}

## Managed agents {% id="managed-agents" %}

### Preview agents {% id="managed-agents-preview-agents" %}

{% table %}

*   Agent
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `antigravity-preview-09-2026`
*   September 17, 2026
*   No shutdown date announced
*
---

*   `deep-research-preview-04-2026`
*   April 21, 2026
*   No shutdown date announced
*
---

*   `deep-research-max-preview-04-2026`
*   April 21, 2026
*   No shutdown date announced
*
---

*   `deep-research-pro-preview-12-2025`
*   December 11, 2025
*   October 23, 2026
*   `deep-research-preview-04-2026`
{% /table %}

### Deprecated agents {% id="managed-agents-deprecated-agents" %}

{% table %}

*   Agent
*   Release date
*   Shutdown date
*   Recommended replacement
---

*   `antigravity-preview-05-2026`
*   May 19, 2026
*   October 5, 2026
*   `antigravity-preview-09-2026`
{% /table %}

# Gemini API libraries
Source: https://aistudio.google.com/docs/libraries
Description: Download and get started with the Gemini API Libraries + SDKs

When building with the Gemini API, we recommend using the **Google GenAI SDK**.
These are the official, production-ready libraries that we develop and maintain
for the most popular languages. They are in [General Availability](/docs/libraries#new-libraries) and used in all our official
documentation and examples.

{% callout type="note" %}
Note: If you're using one of our legacy libraries, we strongly recommend you
[migrate](/docs/migrate) to the Google GenAI SDK. Review the
[legacy libraries](/docs/libraries#previous-sdks) section for more
information. If you're using an AI coding assistant, install the
[Gemini API development skill](/docs/coding-agents) to give your
agent access to the latest documentation and best practices.
{% /callout %}

If you're new to the Gemini API, follow our [Get started guide](/docs/get-started) to get started.

## Language support and installation {% id="install" %}

The Google GenAI SDK is available for the Python, JavaScript/TypeScript, Go and
Java languages. You can install each language's library using package managers,
or visit their GitHub repos for further engagement:
{% tabs %}
{% tab label="Python" %}
* Library: [`google-genai`](https://pypi.org/project/google-genai)

* GitHub Repository: [googleapis/python-genai](https://github.com/googleapis/python-genai)

* Installation: `pip install google-genai`
{% /tab %}
{% tab label="JavaScript" %}
* Library: [`@google/genai`](https://www.npmjs.com/package/@google/genai)

* GitHub Repository: [googleapis/js-genai](https://github.com/googleapis/js-genai)

* Installation: `npm install @google/genai`
{% /tab %}
{% tab label="Go" %}
* Library: [`google.golang.org/genai`](https://pkg.go.dev/google.golang.org/genai)

* GitHub Repository: [googleapis/go-genai](https://github.com/googleapis/go-genai)

* Installation: `go get google.golang.org/genai`
{% /tab %}
{% tab label="Java" %}
* Library: `google-genai`

* GitHub Repository: [googleapis/java-genai](https://github.com/googleapis/java-genai)

* Installation: If you're using Maven, add the following to your dependencies:

  ```xml
  <dependencies>
    <dependency>
      <groupId>com.google.genai</groupId>
      <artifactId>google-genai</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>
  ```
{% /tab %}
{% tab label="C# (.NET)" %}
* Library: `Google.GenAI`

* GitHub Repository: [googleapis/dotnet-genai](https://googleapis.github.io/dotnet-genai/)

* Installation: `dotnet add package Google.GenAI`
{% /tab %}
{% /tabs %}

## General availability {% id="new-libraries" %}

As of May 2025, the Google GenAI SDK has reached General Availability (GA)
across all supported platforms and are the recommended libraries to access the
Gemini API. They are stable, fully supported for production use, and are
actively maintained. They provide access to the latest features, and offer the
best performance working with Gemini.

If you're using one of our legacy libraries,
we strongly recommend you migrate so that you can access the latest features and
get the best performance working with Gemini. Review the [legacy libraries](/docs/libraries#previous-sdks) section for more information.

## Legacy libraries and migration {% id="previous-sdks" %}

If you are using one of our legacy libraries, we recommend that you
[migrate to the new libraries](/docs/migrate).

The legacy libraries don't provide access to recent features (such as
[Live API](/docs/live-api) and [Veo](/docs/video)) and are
deprecated as of November 30th, 2025.

Each legacy library's support status varies, detailed in the following table:

| Language | Legacy library | Support status | Recommended library |
| :--- | :--- | :--- | :--- |
| **Python** | [`google-generativeai`](https://github.com/google-gemini/deprecated-generative-ai-python) | Not actively maintained | [`google-genai`](https://github.com/googleapis/python-genai) |
| **JavaScript/TypeScript** | [`@google/generativeai`](https://github.com/google-gemini/generative-ai-js) | Not actively maintained | [`@google/genai`](https://github.com/googleapis/js-genai) |
| **Go** | [`google.golang.org/generative-ai`](https://github.com/google/generative-ai-go) | Not actively maintained | [`google.golang.org/genai`](https://github.com/googleapis/go-genai) |
| **Dart and Flutter** | [`google_generative_ai`](https://pub.dev/packages/google_generative_ai/install) | Not actively maintained | Use [Genkit Dart](https://genkit.dev/docs/dart/get-started/) or [Firebase AI Logic](https://pub.dev/packages/firebase_ai) |
| **Swift** | [`generative-ai-swift`](https://github.com/google/generative-ai-swift) | Not actively maintained | Use [Firebase AI Logic](https://firebase.google.com/products/firebase-ai-logic) |
| **Android** | [`generative-ai-android`](https://github.com/google-gemini/generative-ai-android) | Not actively maintained | Use [Firebase AI Logic](https://firebase.google.com/products/firebase-ai-logic) |

**Note for Java developers:** There was no legacy Google-provided Java SDK for
the Gemini API, so no migration from a previous Google library is required. You
can start directly with the new library in the
[Language support and installation](/docs/libraries#install) section.

# Migrate to the Google GenAI SDK
Source: https://aistudio.google.com/docs/migrate
Description: Migrate existing applications to the unified Google Gen AI SDK.

Starting with the Gemini 2.0 release in late 2024, we introduced a new set of
libraries called the [Google GenAI SDK](/docs/libraries). It offers
an improved developer experience through
an [updated client architecture](/docs/migrate#client), and
[simplifies the transition](/docs/migrate-to-cloud) between developer
and enterprise workflows.

The Google GenAI SDK is now in [General Availability (GA)](/docs/libraries#new-libraries) across all supported
platforms. If you're using one of our [legacy libraries](/docs/libraries#previous-sdks), we strongly recommend you to
migrate.

This guide provides before-and-after examples of migrated code to help you get
started.

{% callout type="note" %}
The Go examples omit imports and other boilerplate code to improve
readability.
{% /callout %}

## Installation {% id="install-sdk" %}

**Before**

{% tabs %}
{% tab label="Python" %}
```shell
pip install -U -q "google-generativeai"
```
{% /tab %}
{% tab label="JavaScript" %}
```shell
npm install @google/generative-ai
```
{% /tab %}
{% tab label="Java" %}
```xml
<dependency>
    <groupId>com.google.ai.client.generativeai</groupId>
    <artifactId>generativeai</artifactId>
    <version>0.9.0</version>
</dependency>
```
{% /tab %}

{% tab label="Go" %}
```shell
go get github.com/google/generative-ai-go
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```shell
pip install -U -q "google-genai"
```
{% /tab %}
{% tab label="JavaScript" %}
```shell
npm install @google/genai
```
{% /tab %}
{% tab label="Java" %}
```xml
<dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>1.67.0</version>
</dependency>
```
{% /tab %}

{% tab label="Go" %}
```shell
go get google.golang.org/genai
```
{% /tab %}
{% /tabs %}

## API access {% id="client" %}

The old SDK implicitly handled the API client behind the scenes using a variety
of ad hoc methods. This made it hard to manage the client and credentials.
Now, you interact through a central `Client` object. This `Client` object acts
as a single entry point for various API services (e.g., `models`, `chats`,
`files`, `tunings`), promoting consistency and simplifying credential and
configuration management across different API calls.

**Before (Less Centralized API Access)**

{% tabs %}
{% tab label="Python" %}
The old SDK didn't explicitly use a top-level client object for most API
  calls. You would directly instantiate and interact with `GenerativeModel`
  objects.

  ```python
import google.generativeai as genai

# Directly create and use model objects
model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content(...)
chat = model.start_chat(...)
  ```
{% /tab %}
{% tab label="JavaScript" %}
While `GoogleGenerativeAI` was a central point for models and chat, other
  functionalities like file and cache management often required importing and
  instantiating entirely separate client classes.

  ```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";
import { GoogleAIFileManager, GoogleAICacheManager } from "@google/generative-ai/server"; // For files/caching

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const fileManager = new GoogleAIFileManager("GEMINI_API_KEY");
const cacheManager = new GoogleAICacheManager("GEMINI_API_KEY");

// Get a model instance, then call methods on it
const model = genAI.getGenerativeModel({ model: "gemini-3.8-flash" });
const result = await model.generateContent(...);
const chat = model.startChat(...);

// Call methods on separate client objects for other services
const uploadedFile = await fileManager.uploadFile(...);
const cache = await cacheManager.create(...);
  ```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

// Previously, model operations were called on separate model instances
Client client = new Client();
GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "Tell me a story.", null);
Chat chat = client.chats.create("gemini-3.8-flash");
```
{% /tab %}

{% tab label="Go" %}
The `genai.NewClient` function created a client, but generative model
  operations were typically called on a separate `GenerativeModel` instance
  obtained from this client. Other services might have been accessed via
  distinct packages or patterns.

  ```go
import (
    "github.com/google/generative-ai-go/genai"
    "github.com/google/generative-ai-go/genai/fileman" // For files
    "google.golang.org/api/option"
)

client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
fileClient, err := fileman.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))

// Get a model instance, then call methods on it
model := client.GenerativeModel("gemini-3.8-flash")
resp, err := model.GenerateContent(...)
cs := model.StartChat()

// Call methods on separate client objects for other services
uploadedFile, err := fileClient.UploadFile(...)
  ```
{% /tab %}
{% /tabs %}

**After (Centralized Client Object)**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

# Create a single client object
client = genai.Client()

# Access API methods through services on the client object
response = client.models.generate_content(...)
chat = client.chats.create(...)
my_file = client.files.upload(...)
tuning_job = client.tunings.tune(...)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

// Create a single client object
const ai = new GoogleGenAI({apiKey: "GEMINI_API_KEY"});

// Access API methods through services on the client object
const response = await ai.models.generateContent(...);
const chat = ai.chats.create(...);
const uploadedFile = await ai.files.upload(...);
const cache = await ai.caches.create(...);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.CachedContent;
import com.google.genai.types.CreateCachedContentConfig;
import com.google.genai.types.File;
import com.google.genai.types.GenerateContentResponse;

// Create a single client object
Client client = new Client();

// Access API methods through services on the client object
GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "Tell me a story.", null);
Chat chat = client.chats.create("gemini-3.8-flash");
File uploadedFile = client.files.upload("sample.txt", null);
CachedContent cache =
    client.caches.create("gemini-3.8-flash", CreateCachedContentConfig.builder().build());
```
{% /tab %}

{% tab label="Go" %}
```go
import "google.golang.org/genai"

// Create a single client object
client, err := genai.NewClient(ctx, nil)

// Access API methods through services on the client object
result, err := client.Models.GenerateContent(...)
chat, err := client.Chats.Create(...)
uploadedFile, err := client.Files.Upload(...)
tuningJob, err := client.Tunings.Tune(...)
```
{% /tab %}
{% /tabs %}

## Authentication {% id="authenticate" %}

Both legacy and new libraries authenticate using API keys. You can
[create](https://aistudio.google.com/apikey) your API key in Google AI
Studio.

**Before**

{% tabs %}
{% tab label="Python" %}
The old SDK handled the API client object implicitly.

  ```python
import google.generativeai as genai

genai.configure(api_key=...)
  ```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;

// Passing the API key explicitly to the client builder
Client client = Client.builder().apiKey("GEMINI_API_KEY").build();
```
{% /tab %}

{% tab label="Go" %}
Import the Google libraries:

  ```go
import (
    "github.com/google/generative-ai-go/genai"
    "google.golang.org/api/option"
)
  ```
  Create the client:

  ```go
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
  ```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
With Google GenAI SDK, you create an API client first, which is used to call
  the API.
  The new SDK will pick up your API key from the `GEMINI_API_KEY` environment
  variables, if you don't pass one to the client.

  ```shell
export GEMINI_API_KEY="YOUR_API_KEY"
  ```

  ```python
from google import genai

client = genai.Client() # Set the API key using the GEMINI_API_KEY env var.
                        # Alternatively, you could set the API key explicitly:
                        # client = genai.Client(api_key="YOUR_API_KEY")
  ```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({apiKey: "GEMINI_API_KEY"});
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;

// The client automatically picks up the GEMINI_API_KEY environment variable,
// or you can pass it explicitly via Client.builder().apiKey("GEMINI_API_KEY").build()
Client client = new Client();
```
{% /tab %}

{% tab label="Go" %}
Import the GenAI library:

  ```go
import "google.golang.org/genai"
  ```

  Create the client:

  ```go
client, err := genai.NewClient(ctx, &genai.ClientConfig{
      Backend: genai.BackendGeminiAPI,
})
  ```
{% /tab %}
{% /tabs %}

## Generate content {% id="generate-content" %}

### Text {% id="text" %}

**Before**

{% tabs %}
{% tab label="Python" %}
Previously, there were no client objects, you accessed APIs directly through
  `GenerativeModel` objects.

  ```python
import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content(
    'Tell me a story in 300 words'
)
print(response.text)
  ```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-3.8-flash" });
const prompt = "Tell me a story in 300 words";

const result = await model.generateContent(prompt);
console.log(result.response.text());
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
String prompt = "Tell me a story in 300 words";

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", prompt, null);
System.out.println(response.text());
```
{% /tab %}

{% tab label="Go" %}
```go
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-3.8-flash")
resp, err := model.GenerateContent(ctx, genai.Text("Tell me a story in 300 words."))
if err != nil {
    log.Fatal(err)
}

printResponse(resp) // utility for printing response parts
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
The new Google GenAI SDK provides access to all the API methods through the
  `Client` object. Except for a few stateful special cases (`chat` and
  live-api `session`s), these are all stateless functions. For utility and
  uniformity, objects returned are `pydantic` classes.

  ```python
from google import genai
client = genai.Client()

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents='Tell me a story in 300 words.'
)
print(response.text)

print(response.model_dump_json(
    exclude_none=True, indent=4))
  ```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Tell me a story in 300 words.",
});
console.log(response.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "Tell me a story in 300 words.", null);
System.out.println(response.text());
```
{% /tab %}

{% tab label="Go" %}
```go
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
    log.Fatal(err)
}

result, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", genai.Text("Tell me a story in 300 words."), nil)
if err != nil {
    log.Fatal(err)
}
debugPrint(result) // utility for printing result
```
{% /tab %}
{% /tabs %}

### Image {% id="image" %}

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content([
    'Tell me a story based on this image',
    Image.open(image_path)
])
print(response.text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({ model: "gemini-3.8-flash" });

function fileToGenerativePart(path = '', mimeType = '') {
  return {
    inlineData: {
      data: Buffer.from(fs.readFileSync(path)).toString("base64"),
      mimeType,
    },
  };
}

const prompt = "Tell me a story based on this image";

const imagePart = fileToGenerativePart(
  `path/to/organ.jpg`,
  "image/jpeg",
);

const result = await model.generateContent([prompt, imagePart]);
console.log(result.response.text());
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("path/to/organ.jpg"));
Part imagePart = Part.fromBytes(imageBytes, "image/jpeg");

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        Content.fromParts(Part.fromText("Tell me a story based on this image"), imagePart),
        null);
System.out.println(response.text());
```
{% /tab %}

{% tab label="Go" %}
```go
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-3.8-flash")

imgData, err := os.ReadFile("path/to/organ.jpg")
if err != nil {
    log.Fatal(err)
}

resp, err := model.GenerateContent(ctx,
    genai.Text("Tell me about this instrument"),
    genai.ImageData("jpeg", imgData))
if err != nil {
    log.Fatal(err)
}

printResponse(resp) // utility for printing response
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
Many of the same convenience features exist in the new SDK. For
  example, `PIL.Image` objects are automatically converted.

  ```python
from google import genai
from PIL import Image

client = genai.Client()

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=[
        'Tell me a story based on this image',
        Image.open(image_path)
    ]
)
print(response.text)
  ```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

const organ = await ai.files.upload({
  file: "path/to/organ.jpg",
});

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    createUserContent([
      "Tell me a story based on this image",
      createPartFromUri(organ.uri, organ.mimeType)
    ]),
  ],
});
console.log(response.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.File;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;

Client client = new Client();

File organ = client.files.upload("path/to/organ.jpg", null);

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        Content.fromParts(
            Part.fromText("Tell me a story based on this image"),
            Part.fromUri(organ.uri().orElse(""), organ.mimeType().orElse("image/jpeg"))),
        null);
System.out.println(response.text());
```
{% /tab %}

{% tab label="Go" %}
```go
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
    log.Fatal(err)
}

imgData, err := os.ReadFile("path/to/organ.jpg")
if err != nil {
    log.Fatal(err)
}

parts := []*genai.Part{
    {Text: "Tell me a story based on this image"},
    {InlineData: &genai.Blob{Data: imgData, MIMEType: "image/jpeg"}},
}
contents := []*genai.Content{
    {Parts: parts},
}

result, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
debugPrint(result) // utility for printing result
```
{% /tab %}
{% /tabs %}

### Streaming {% id="streaming" %}

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

response = model.generate_content(
    "Write a cute story about cats.",
    stream=True)
for chunk in response:
    print(chunk.text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({ model: "gemini-3.8-flash" });

const prompt = "Write a story about a magic backpack.";

const result = await model.generateContentStream(prompt);

// Print text as it comes in.
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  process.stdout.write(chunkText);
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.ResponseStream;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
String prompt = "Write a story about a magic backpack.";

try (ResponseStream<GenerateContentResponse> stream =
    client.models.generateContentStream("gemini-3.8-flash", prompt, null)) {
  for (GenerateContentResponse chunk : stream) {
    System.out.print(chunk.text());
  }
}
```
{% /tab %}

{% tab label="Go" %}
```go
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-3.8-flash")
iter := model.GenerateContentStream(ctx, genai.Text("Write a story about a magic backpack."))
for {
    resp, err := iter.Next()
    if err == iterator.Done {
        break
    }
    if err != nil {
        log.Fatal(err)
    }
    printResponse(resp) // utility for printing the response
}
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

for chunk in client.models.generate_content_stream(
  model='gemini-3.8-flash',
  contents='Tell me a story in 300 words.'
):
    print(chunk.text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

const response = await ai.models.generateContentStream({
  model: "gemini-3.8-flash",
  contents: "Write a story about a magic backpack.",
});
let text = "";
for await (const chunk of response) {
  console.log(chunk.text);
  text += chunk.text;
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.ResponseStream;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();

try (ResponseStream<GenerateContentResponse> response =
    client.models.generateContentStream(
        "gemini-3.8-flash", "Tell me a story in 300 words.", null)) {
  for (GenerateContentResponse chunk : response) {
    System.out.println(chunk.text());
  }
}
```
{% /tab %}

{% tab label="Go" %}
```go
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
    log.Fatal(err)
}

for result, err := range client.Models.GenerateContentStream(
    ctx,
    "gemini-3.8-flash",
    genai.Text("Write a story about a magic backpack."),
    nil,
) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}
```
{% /tab %}
{% /tabs %}

## Configuration {% id="configuration" %}

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

model = genai.GenerativeModel(
  'gemini-3.8-flash',
    system_instruction='you are a story teller for kids under 5 years old',
    generation_config=genai.GenerationConfig(
      max_output_tokens=400,
      top_k=2,
      top_p=0.5,
      temperature=0.5,
      response_mime_type='application/json',
      stop_sequences=['\n'],
    )
)
response = model.generate_content('tell me a story in 100 words')
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({
  model: "gemini-3.8-flash",
  generationConfig: {
    candidateCount: 1,
    stopSequences: ["x"],
    maxOutputTokens: 20,
    temperature: 1.0,
  },
});

const result = await model.generateContent(
  "Tell me a story about a magic backpack.",
);
console.log(result.response.text())
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .systemInstruction(
            Content.fromParts(Part.fromText("you are a story teller for kids under 5 years old")))
        .maxOutputTokens(400)
        .topK(2.0f)
        .topP(0.5f)
        .temperature(0.5f)
        .responseMimeType("application/json")
        .stopSequences(Arrays.asList("\n"))
        .build();

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "tell me a story in 100 words", config);
System.out.println(response.text());
```
{% /tab %}

{% tab label="Go" %}
```go
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-3.8-flash")
model.SetTemperature(0.5)
model.SetTopP(0.5)
model.SetTopK(2.0)
model.SetMaxOutputTokens(100)
model.ResponseMIMEType = "application/json"
resp, err := model.GenerateContent(ctx, genai.Text("Tell me about New York"))
if err != nil {
    log.Fatal(err)
}
printResponse(resp) // utility for printing response
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
For all methods in the new SDK, the required arguments are provided as
  keyword arguments. All optional inputs are provided in the `config`
  argument. Config arguments can be specified as either Python dictionaries or
  `Config` classes in the `google.genai.types` namespace. For utility and
  uniformity, all definitions within the `types` module are `pydantic`
  classes.

  ```python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model='gemini-3.8-flash',
  contents='Tell me a story in 100 words.',
  config=types.GenerateContentConfig(
      system_instruction='you are a story teller for kids under 5 years old',
      max_output_tokens= 400,
      top_k= 2,
      top_p= 0.5,
      temperature= 0.5,
      response_mime_type= 'application/json',
      stop_sequences= ['\n'],
      seed=42,
  ),
)
  ```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Tell me a story about a magic backpack.",
  config: {
    candidateCount: 1,
    stopSequences: ["x"],
    maxOutputTokens: 20,
    temperature: 1.0,
  },
});

console.log(response.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .candidateCount(1)
        .stopSequences(Arrays.asList("x"))
        .maxOutputTokens(20)
        .temperature(1.0f)
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "Tell me a story about a magic backpack.", config);
System.out.println(response.text());
```
{% /tab %}

{% tab label="Go" %}
```go
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
    log.Fatal(err)
}

result, err := client.Models.GenerateContent(ctx,
    "gemini-3.8-flash",
    genai.Text("Tell me about New York"),
    &genai.GenerateContentConfig{
        Temperature: genai.Ptr[float32](0.5),
        TopP: genai.Ptr[float32](0.5),
        TopK: genai.Ptr[float32](2.0),
        ResponseMIMEType: "application/json",
        StopSequences: []string{"Yankees"},
        CandidateCount: 2,
        Seed: genai.Ptr[int32](42),
        MaxOutputTokens: 128,
        PresencePenalty: genai.Ptr[float32](0.5),
        FrequencyPenalty: genai.Ptr[float32](0.5),
    },
)
if err != nil {
    log.Fatal(err)
}
debugPrint(result) // utility for printing response
```
{% /tab %}
{% /tabs %}

## Safety settings {% id="safety-settings" %}

Generate a response with safety settings:

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content(
    'say something bad',
    safety_settings={
        'HATE': 'BLOCK_ONLY_HIGH',
        'HARASSMENT': 'BLOCK_ONLY_HIGH',
  }
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI, HarmCategory, HarmBlockThreshold } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({
  model: "gemini-3.8-flash",
  safetySettings: [
    {
      category: HarmCategory.HARM_CATEGORY_HARASSMENT,
      threshold: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
    },
  ],
});

const unsafePrompt =
  "I support Martians Soccer Club and I think " +
  "Jupiterians Football Club sucks! Write an ironic phrase telling " +
  "them how I feel about them.";

const result = await model.generateContent(unsafePrompt);

try {
  result.response.text();
} catch (e) {
  console.error(e);
  console.log(result.response.candidates[0].safetyRatings);
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HarmBlockThreshold;
import com.google.genai.types.HarmCategory;
import com.google.genai.types.SafetySetting;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .safetySettings(
            Arrays.asList(
                SafetySetting.builder()
                    .category(HarmCategory.Known.HARM_CATEGORY_HARASSMENT)
                    .threshold(HarmBlockThreshold.Known.BLOCK_LOW_AND_ABOVE)
                    .build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "say something bad", config);
System.out.println(response.text());
```
{% /tab %}

{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model='gemini-3.8-flash',
  contents='say something bad',
  config=types.GenerateContentConfig(
      safety_settings= [
          types.SafetySetting(
              category='HARM_CATEGORY_HATE_SPEECH',
              threshold='BLOCK_ONLY_HIGH'
          ),
      ]
  ),
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI, HarmCategory, HarmBlockThreshold} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const unsafePrompt =
  "I support Martians Soccer Club and I think " +
  "Jupiterians Football Club sucks! Write an ironic phrase telling " +
  "them how I feel about them.";

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: unsafePrompt,
  config: {
    safetySettings: [
      {
        category: HarmCategory.HARM_CATEGORY_HARASSMENT,
        threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
      },
    ],
  },
});

console.log("Finish reason:", response.candidates?.[0]?.finishReason);
console.log("Safety ratings:", response.candidates?.[0]?.safetyRatings);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HarmBlockThreshold;
import com.google.genai.types.HarmCategory;
import com.google.genai.types.SafetySetting;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .safetySettings(
            Arrays.asList(
                SafetySetting.builder()
                    .category(HarmCategory.Known.HARM_CATEGORY_HATE_SPEECH)
                    .threshold(HarmBlockThreshold.Known.BLOCK_ONLY_HIGH)
                    .build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "say something bad", config);
System.out.println("Finish reason: " + response.finishReason());
```
{% /tab %}

{% /tabs %}

## Async {% id="async" %}

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content_async(
    'tell me a story in 100 words'
)
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
To use the new SDK with `asyncio`, there is a separate `async`
  implementation of every method under `client.aio`.

  ```python
from google import genai

client = genai.Client()

response = await client.aio.models.generate_content(
    model='gemini-3.8-flash',
    contents='Tell me a story in 300 words.'
)
  ```
{% /tab %}
{% /tabs %}

## Chat {% id="chat" %}

Start a chat and send a message to the model:

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
chat = model.start_chat()

response = chat.send_message(
    "Tell me a story in 100 words")
response = chat.send_message(
    "What happened after that?")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({ model: "gemini-3.8-flash" });
const chat = model.startChat({
  history: [
    {
      role: "user",
      parts: [{ text: "Hello" }],
    },
    {
      role: "model",
      parts: [{ text: "Great to meet you. What would you like to know?" }],
    },
  ],
});
let result = await chat.sendMessage("I have 2 dogs in my house.");
console.log(result.response.text());
result = await chat.sendMessage("How many paws are in my house?");
console.log(result.response.text());
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
Chat chat = client.chats.create("gemini-3.8-flash");

GenerateContentResponse response1 = chat.sendMessage("Tell me a story in 100 words");
System.out.println(response1.text());

GenerateContentResponse response2 = chat.sendMessage("What happened after that?");
System.out.println(response2.text());
```
{% /tab %}

{% tab label="Go" %}
```go
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey("GEMINI_API_KEY"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-3.8-flash")
cs := model.StartChat()

cs.History = []*genai.Content{
    {
        Parts: []genai.Part{
            genai.Text("Hello, I have 2 dogs in my house."),
        },
        Role: "user",
    },
    {
        Parts: []genai.Part{
            genai.Text("Great to meet you. What would you like to know?"),
        },
        Role: "model",
    },
}

res, err := cs.SendMessage(ctx, genai.Text("How many paws are in my house?"))
if err != nil {
    log.Fatal(err)
}
printResponse(res) // utility for printing the response
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

chat = client.chats.create(model='gemini-3.8-flash')

response = chat.send_message(
    message='Tell me a story in 100 words')
response = chat.send_message(
    message='What happened after that?')
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const chat = ai.chats.create({
  model: "gemini-3.8-flash",
  history: [
    {
      role: "user",
      parts: [{ text: "Hello" }],
    },
    {
      role: "model",
      parts: [{ text: "Great to meet you. What would you like to know?" }],
    },
  ],
});

const response1 = await chat.sendMessage({
  message: "I have 2 dogs in my house.",
});
console.log("Chat response 1:", response1.text);

const response2 = await chat.sendMessage({
  message: "How many paws are in my house?",
});
console.log("Chat response 2:", response2.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
Chat chat = client.chats.create("gemini-3.8-flash");

GenerateContentResponse response1 = chat.sendMessage("I have 2 dogs in my house.");
System.out.println("Chat response 1: " + response1.text());

GenerateContentResponse response2 = chat.sendMessage("How many paws are in my house?");
System.out.println("Chat response 2: " + response2.text());
```
{% /tab %}

{% tab label="Go" %}
```go
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
    log.Fatal(err)
}

chat, err := client.Chats.Create(ctx, "gemini-3.8-flash", nil, nil)
if err != nil {
    log.Fatal(err)
}

result, err := chat.SendMessage(ctx, genai.Part{Text: "Hello, I have 2 dogs in my house."})
if err != nil {
    log.Fatal(err)
}
debugPrint(result) // utility for printing result

result, err = chat.SendMessage(ctx, genai.Part{Text: "How many paws are in my house?"})
if err != nil {
    log.Fatal(err)
}
debugPrint(result) // utility for printing result
```
{% /tab %}
{% /tabs %}

## Function calling {% id="function-calling" %}

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai
from enum import Enum

def get_current_weather(location: str) -> str:
    """Get the current whether in a given location.

    Args:
        location: required, The city and state, e.g. San Franciso, CA
        unit: celsius or fahrenheit
    """
    print(f'Called with: {location=}')
    return "23C"

model = genai.GenerativeModel(
    model_name="gemini-3.8-flash",
    tools=[get_current_weather]
)

response = model.generate_content("What is the weather in San Francisco?")
function_call = response.candidates[0].parts[0].function_call
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
In the new SDK, automatic function calling is the default. Here, you disable
 it.

  ```python
from google import genai
from google.genai import types

client = genai.Client()

def get_current_weather(location: str) -> str:
    """Get the current whether in a given location.

    Args:
        location: required, The city and state, e.g. San Franciso, CA
        unit: celsius or fahrenheit
    """
    print(f'Called with: {location=}')
    return "23C"

response = client.models.generate_content(
  model='gemini-3.8-flash',
  contents="What is the weather like in Boston?",
  config=types.GenerateContentConfig(
      tools=[get_current_weather],
      automatic_function_calling={'disable': True},
  ),
)

function_call = response.candidates[0].content.parts[0].function_call
  ```
{% /tab %}
{% /tabs %}

### Automatic function calling {% id="automatic-function" %}

**Before**

{% tabs %}
{% tab label="Python" %}
The old SDK only supports automatic function calling in chat. In the new SDK
  this is the default behavior in `generate_content`.

  ```python
import google.generativeai as genai

def get_current_weather(city: str) -> str:
    return "23C"

model = genai.GenerativeModel(
    model_name="gemini-3.8-flash",
    tools=[get_current_weather]
)

chat = model.start_chat(
    enable_automatic_function_calling=True)
result = chat.send_message("What is the weather in San Francisco?")
  ```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
client = genai.Client()

def get_current_weather(city: str) -> str:
    return "23C"

response = client.models.generate_content(
  model='gemini-3.8-flash',
  contents="What is the weather like in Boston?",
  config=types.GenerateContentConfig(
      tools=[get_current_weather]
  ),
)
```
{% /tab %}
{% /tabs %}

## Code execution {% id="code-execution" %}

Code execution is a tool that allows the model to generate Python code, run it,
and return the result.

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

model = genai.GenerativeModel(
    model_name="gemini-3.8-flash",
    tools="code_execution"
)

result = model.generate_content(
  "What is the sum of the first 50 prime numbers? Generate and run code for "
  "the calculation, and make sure you get all 50.")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({
  model: "gemini-3.8-flash",
  tools: [{ codeExecution: {} }],
});

const result = await model.generateContent(
  "What is the sum of the first 50 prime numbers? " +
    "Generate and run code for the calculation, and make sure you get " +
    "all 50.",
);

console.log(result.response.text());
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Tool;
import com.google.genai.types.ToolCodeExecution;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .tools(
            Arrays.asList(
                Tool.builder().codeExecution(ToolCodeExecution.builder().build()).build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        "What is the sum of the first 50 prime numbers? Generate and run code for "
            + "the calculation, and make sure you get all 50.",
        config);
System.out.println(response.text());
```
{% /tab %}

{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents='What is the sum of the first 50 prime numbers? Generate and run '
            'code for the calculation, and make sure you get all 50.',
    config=types.GenerateContentConfig(
        tools=[types.Tool(code_execution=types.ToolCodeExecution)],
    ),
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: `Write and execute code that calculates the sum of the first 50 prime numbers.
            Ensure that only the executable code and its resulting output are generated.`,
});

// Each part may contain text, executable code, or an execution result.
for (const part of response.candidates?.[0]?.content?.parts || []) {
  console.log(part);
  console.log("\n");
}

console.log("-".repeat(80));
// The `.text` accessor concatenates the parts into a markdown-formatted text.
console.log("\n", response.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import com.google.genai.types.Tool;
import com.google.genai.types.ToolCodeExecution;
import java.util.Arrays;

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .tools(
            Arrays.asList(
                Tool.builder().codeExecution(ToolCodeExecution.builder().build()).build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        "Write and execute code that calculates the sum of the first 50 prime numbers. "
            + "Ensure that only the executable code and its resulting output are generated.",
        config);

if (response.parts() != null) {
  for (Part part : response.parts()) {
    System.out.println(part);
  }
}
System.out.println(response.text());
```
{% /tab %}

{% /tabs %}

## Search grounding {% id="search-grounding" %}

`GoogleSearch` (Gemini>=2.0) and `GoogleSearchRetrieval` (Gemini < 2.0) are
tools that allow the model to retrieve public web data for grounding, powered by
Google.

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content(
    contents="what is the Google stock price?",
    tools='google_search_retrieval'
)
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents='What is the Google stock price?',
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                google_search=types.GoogleSearch()
            )
        ]
    )
)
```
{% /tab %}
{% /tabs %}

## JSON response {% id="json-response" %}

Generate answers in JSON format.

**Before**

{% tabs %}
{% tab label="Python" %}
By specifying a `response_schema` and setting
  `response_mime_type="application/json"` users can constrain the model to
  produce a `JSON` response following a given structure.

  ```python
import google.generativeai as genai
import typing_extensions as typing

class CountryInfo(typing.TypedDict):
    name: str
    population: int
    capital: str
    continent: str
    major_cities: list[str]
    gdp: int
    official_language: str
    total_area_sq_mi: int

model = genai.GenerativeModel(model_name="gemini-3.8-flash")
result = model.generate_content(
    "Give me information of the United States",
    generation_config=genai.GenerationConfig(
        response_mime_type="application/json",
        response_schema = CountryInfo
    ),
)
  ```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");

const schema = {
  description: "List of recipes",
  type: SchemaType.ARRAY,
  items: {
    type: SchemaType.OBJECT,
    properties: {
      recipeName: {
        type: SchemaType.STRING,
        description: "Name of the recipe",
        nullable: false,
      },
    },
    required: ["recipeName"],
  },
};

const model = genAI.getGenerativeModel({
  model: "gemini-3.8-flash",
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: schema,
  },
});

const result = await model.generateContent(
  "List a few popular cookie recipes.",
);
console.log(result.response.text());
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;
import java.util.Arrays;
import java.util.Map;

Client client = new Client();

Schema schema =
    Schema.builder()
        .description("List of recipes")
        .type(Type.Known.ARRAY)
        .items(
            Schema.builder()
                .type(Type.Known.OBJECT)
                .properties(
                    Map.of(
                        "recipeName",
                        Schema.builder()
                            .type(Type.Known.STRING)
                            .description("Name of the recipe")
                            .build()))
                .required(Arrays.asList("recipeName"))
                .build())
        .build();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .responseMimeType("application/json")
        .responseSchema(schema)
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "List a few popular cookie recipes.", config);
System.out.println(response.text());
```
{% /tab %}

{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
The new SDK uses
  `pydantic` classes to provide the schema (although you can pass a
  `genai.types.Schema`, or equivalent `dict`). When possible, the SDK will
  parse the returned JSON, and return the result in `response.parsed`. If you
  provided a `pydantic` class as the schema the SDK will convert that `JSON`
  to an instance of the class.

  ```python
from google import genai
from pydantic import BaseModel

client = genai.Client()

class CountryInfo(BaseModel):
    name: str
    population: int
    capital: str
    continent: str
    major_cities: list[str]
    gdp: int
    official_language: str
    total_area_sq_mi: int

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents='Give me information of the United States.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': CountryInfo,
    },
)

response.parsed
  ```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "List a few popular cookie recipes.",
  config: {
    responseMimeType: "application/json",
    responseSchema: {
      type: "array",
      items: {
        type: "object",
        properties: {
          recipeName: { type: "string" },
          ingredients: { type: "array", items: { type: "string" } },
        },
        required: ["recipeName", "ingredients"],
      },
    },
  },
});
console.log(response.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;
import java.util.Arrays;
import java.util.Map;

Client client = new Client();

Schema schema =
    Schema.builder()
        .type(Type.Known.ARRAY)
        .items(
            Schema.builder()
                .type(Type.Known.OBJECT)
                .properties(
                    Map.of(
                        "recipeName", Schema.builder().type(Type.Known.STRING).build(),
                        "ingredients",
                            Schema.builder()
                                .type(Type.Known.ARRAY)
                                .items(Schema.builder().type(Type.Known.STRING).build())
                                .build()))
                .required(Arrays.asList("recipeName", "ingredients"))
                .build())
        .build();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .responseMimeType("application/json")
        .responseSchema(schema)
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "List a few popular cookie recipes.", config);
System.out.println(response.text());
```
{% /tab %}

{% /tabs %}

## Files {% id="files" %}

### Upload {% id="upload" %}

Upload a file:

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import requests
import pathlib
import google.generativeai as genai

# Download file
response = requests.get(
    'https://storage.googleapis.com/generativeai-downloads/data/a11.txt')
pathlib.Path('a11.txt').write_text(response.text)

file = genai.upload_file(path='a11.txt')

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.generate_content([
    'Can you summarize this file:',
    my_file
])
print(response.text)
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
import requests
import pathlib
from google import genai

client = genai.Client()

# Download file
response = requests.get(
    'https://storage.googleapis.com/generativeai-downloads/data/a11.txt')
pathlib.Path('a11.txt').write_text(response.text)

my_file = client.files.upload(file='a11.txt')

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=[
        'Can you summarize this file:',
        my_file
    ]
)
print(response.text)
```
{% /tab %}
{% /tabs %}

### List and get {% id="list-and-get" %}

List uploaded files and get an uploaded file with a filename:

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

for file in genai.list_files():
  print(file.name)

file = genai.get_file(name=file.name)
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
client = genai.Client()

for file in client.files.list():
    print(file.name)

file = client.files.get(name=file.name)
```
{% /tab %}
{% /tabs %}

### Delete {% id="delete" %}

Delete a file:

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import pathlib
import google.generativeai as genai

pathlib.Path('dummy.txt').write_text(dummy)
dummy_file = genai.upload_file(path='dummy.txt')

file = genai.delete_file(name=dummy_file.name)
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
import pathlib
from google import genai

client = genai.Client()

pathlib.Path('dummy.txt').write_text(dummy)
dummy_file = client.files.upload(file='dummy.txt')

response = client.files.delete(name=dummy_file.name)
```
{% /tab %}
{% /tabs %}

## Context caching {% id="context-caching" %}

Context caching allows the user to pass the content to the model once, cache the
input tokens, and then refer to the cached tokens in subsequent calls to lower
the cost.

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import requests
import pathlib
import google.generativeai as genai
from google.generativeai import caching

# Download file
response = requests.get(
    'https://storage.googleapis.com/generativeai-downloads/data/a11.txt')
pathlib.Path('a11.txt').write_text(response.text)

# Upload file
document = genai.upload_file(path="a11.txt")

# Create cache
apollo_cache = caching.CachedContent.create(
    model="gemini-3.8-flash",
    system_instruction="You are an expert at analyzing transcripts.",
    contents=[document],
)

# Generate response
apollo_model = genai.GenerativeModel.from_cached_content(
    cached_content=apollo_cache
)
response = apollo_model.generate_content("Find a lighthearted moment from this transcript")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
import { GoogleGenerativeAI } from "@google/generative-ai";

const cacheManager = new GoogleAICacheManager("GEMINI_API_KEY");
const fileManager = new GoogleAIFileManager("GEMINI_API_KEY");

const uploadResult = await fileManager.uploadFile("path/to/a11.txt", {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});

console.log(cacheResult);

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModelFromCachedContent(cacheResult);
const result = await model.generateContent(
  "Please summarize this transcript.",
);
console.log(result.response.text());
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.CachedContent;
import com.google.genai.types.Content;
import com.google.genai.types.CreateCachedContentConfig;
import com.google.genai.types.File;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import java.util.Arrays;

Client client = new Client();

File uploadResult = client.files.upload("path/to/a11.txt", null);

CachedContent cacheResult =
    client.caches.create(
        "gemini-3.8-flash",
        CreateCachedContentConfig.builder()
            .contents(
                Arrays.asList(
                    Content.fromParts(
                        Part.fromUri(
                            uploadResult.uri().orElse(""),
                            uploadResult.mimeType().orElse("text/plain")))))
            .systemInstruction(
                Content.fromParts(Part.fromText("You are an expert at analyzing transcripts.")))
            .build());

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        "Please summarize this transcript.",
        GenerateContentConfig.builder().cachedContent(cacheResult.name().orElse("")).build());
System.out.println(response.text());
```
{% /tab %}

{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
import requests
import pathlib
from google import genai
from google.genai import types

client = genai.Client()

# Check which models support caching.
for m in client.models.list():
  for action in m.supported_actions:
    if action == "createCachedContent":
      print(m.name)
      break

# Download file
response = requests.get(
    'https://storage.googleapis.com/generativeai-downloads/data/a11.txt')
pathlib.Path('a11.txt').write_text(response.text)

# Upload file
document = client.files.upload(file='a11.txt')

# Create cache
model='gemini-3.8-flash'
apollo_cache = client.caches.create(
      model=model,
      config={
          'contents': [document],
          'system_instruction': 'You are an expert at analyzing transcripts.',
      },
  )

# Generate response
response = client.models.generate_content(
    model=model,
    contents='Find a lighthearted moment from this transcript',
    config=types.GenerateContentConfig(
        cached_content=apollo_cache.name,
    )
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-3.8-flash";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});
console.log("Cache created:", cache);

const response = await ai.models.generateContent({
  model: modelName,
  contents: "Please summarize this transcript",
  config: { cachedContent: cache.name },
});
console.log("Response text:", response.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.CachedContent;
import com.google.genai.types.Content;
import com.google.genai.types.CreateCachedContentConfig;
import com.google.genai.types.File;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import java.util.Arrays;

Client client = new Client();

File document = client.files.upload("a11.txt", null);
String modelName = "gemini-3.8-flash";

CachedContent cache =
    client.caches.create(
        modelName,
        CreateCachedContentConfig.builder()
            .contents(
                Arrays.asList(
                    Content.fromParts(
                        Part.fromUri(
                            document.uri().orElse(""), document.mimeType().orElse("text/plain")))))
            .systemInstruction(
                Content.fromParts(Part.fromText("You are an expert analyzing transcripts.")))
            .build());

GenerateContentResponse response =
    client.models.generateContent(
        modelName,
        "Find a lighthearted moment from this transcript",
        GenerateContentConfig.builder().cachedContent(cache.name().orElse("")).build());
System.out.println(response.text());
```
{% /tab %}

{% /tabs %}

## Count tokens {% id="count-tokens" %}

Count the number of tokens in a request.

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

model = genai.GenerativeModel('gemini-3.8-flash')
response = model.count_tokens(
    'The quick brown fox jumps over the lazy dog.')
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
const model = genAI.getGenerativeModel({
  model: "gemini-3.8-flash",
});

// Count tokens in a prompt without calling text generation.
const countResult = await model.countTokens(
  "The quick brown fox jumps over the lazy dog.",
);

console.log(countResult.totalTokens); // 11

const generateResult = await model.generateContent(
  "The quick brown fox jumps over the lazy dog.",
);

// On the response for `generateContent`, use `usageMetadata`
// to get separate input and output token counts
// (`promptTokenCount` and `candidatesTokenCount`, respectively),
// as well as the combined token count (`totalTokenCount`).
console.log(generateResult.response.usageMetadata);
// candidatesTokenCount and totalTokenCount depend on response, may vary
// { promptTokenCount: 11, candidatesTokenCount: 124, totalTokenCount: 135 }
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.CountTokensResponse;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
String prompt = "The quick brown fox jumps over the lazy dog.";

CountTokensResponse countResult = client.models.countTokens("gemini-3.8-flash", prompt, null);
System.out.println(countResult.totalTokens().orElse(0));

GenerateContentResponse generateResult =
    client.models.generateContent("gemini-3.8-flash", prompt, null);
System.out.println(generateResult.usageMetadata());
```
{% /tab %}

{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

response = client.models.count_tokens(
    model='gemini-3.8-flash',
    contents='The quick brown fox jumps over the lazy dog.',
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const prompt = "The quick brown fox jumps over the lazy dog.";
const countTokensResponse = await ai.models.countTokens({
  model: "gemini-3.8-flash",
  contents: prompt,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: prompt,
});
console.log(generateResponse.usageMetadata);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.CountTokensResponse;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();
String prompt = "The quick brown fox jumps over the lazy dog.";

CountTokensResponse countTokensResponse =
    client.models.countTokens("gemini-3.8-flash", prompt, null);
System.out.println(countTokensResponse.totalTokens().orElse(0));

GenerateContentResponse generateResponse =
    client.models.generateContent("gemini-3.8-flash", prompt, null);
System.out.println(generateResponse.usageMetadata());
```
{% /tab %}

{% /tabs %}

## Generate images {% id="generate-images" %}

Generate images:

**Before**

{% tabs %}
{% tab label="Python" %}
```python
#pip install https://github.com/google-gemini/generative-ai-python@imagen
import google.generativeai as genai

imagen = genai.ImageGenerationModel(
    "imagen-3.0-generate-001")
gen_images = imagen.generate_images(
    prompt="Robot holding a red skateboard",
    number_of_images=1,
    safety_filter_level="block_low_and_above",
    person_generation="allow_adult",
    aspect_ratio="3:4",
)
```
{% /tab %}
{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

gen_images = client.models.generate_images(
    model='gemini-2.5-flash-image',
    prompt='Robot holding a red skateboard',
    config=types.GenerateImagesConfig(
        number_of_images= 1,
        safety_filter_level= "BLOCK_LOW_AND_ABOVE",
        person_generation= "ALLOW_ADULT",
        aspect_ratio= "3:4",
    )
)

for n, image in enumerate(gen_images.generated_images):
    pathlib.Path(f'{n}.png').write_bytes(
        image.image.image_bytes)
```
{% /tab %}
{% /tabs %}

## Embed content {% id="embed-content" %}

Generate content embeddings.

**Before**

{% tabs %}
{% tab label="Python" %}
```python
import google.generativeai as genai

response = genai.embed_content(
  model='models/gemini-embedding-001',
  content='Hello world'
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
  import { GoogleGenerativeAI } from "@google/generative-ai";

  const genAI = new GoogleGenerativeAI("GEMINI_API_KEY");
  const model = genAI.getGenerativeModel({
    model: "gemini-embedding-001",
});

  const result = await model.embedContent("Hello world!");

  console.log(result.embedding);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-001", "Hello world!", null);
System.out.println(response.embeddings());
```
{% /tab %}

{% /tabs %}

**After**

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

response = client.models.embed_content(
  model='gemini-embedding-001',
  contents='Hello world',
)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
const text = "Hello World!";
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: text,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();
String text = "Hello World!";

EmbedContentResponse result =
    client.models.embedContent(
        "gemini-embedding-001",
        text,
        EmbedContentConfig.builder().outputDimensionality(10).build());
System.out.println(result.embeddings());
```
{% /tab %}

{% /tabs %}

# Migrating to the Interactions API
Source: https://aistudio.google.com/docs/migrate-to-interactions
Description: Guide for migrating from generateContent to the Interactions API.

This guide helps you migrate from the `generateContent` API to the Interactions
API.

The Interactions API is the standard interface for building with Gemini. It is
optimized for agentic workflows, server-side state management, and complex
multi-modal, multi-turn conversations, while still fully supporting simple
stateless single-turn requests. While `generateContent` remains fully supported,
we recommend the Interactions API for all new development.

{% callout type="note" %}
  **Automate this migration with a coding agent.** If you use
  a coding agent that supports skills (like Gemini CLI or Jules), install the
  [Gemini API skill](/docs/coding-agents#gemini-api-dev) and run:

  `/gemini-api-dev migrate my app to the interactions api`

  The skill applies the API changes described in this guide.
{% /callout %}

### Why migrate? {% id="why-migrate" %}

The Interactions API provides a more structured and powerful way to build with
Gemini:

* **Server-side history management**: Simplified multi-turn flows via
  `previous_interaction_id`. The server enables state by default (`store=true`),
  but you can opt into stateless behavior by setting `store=false`.
* **Observable execution steps**: Typed steps make it easy to debug complex
  flows and render UI for intermediate events (like thoughts or search widgets).
* **Built for agentic workflows**: Native support for multi-step tool use,
  orchestration, and complex reasoning flows through typed execution steps.
* **Long-running and background tasks**: Supports offloading time-intensive
  operations like Deep Think and Deep Research to background processes using
  `background=true`.

## Basic input/output {% id="basic-input-output" %}

This section shows how to migrate a simple text generation request.

### Before (generateContent) {% id="before-generatecontent" %}

The `generateContent` API is stateless and returns the response directly. The
response structure wraps the output in a list of `candidates`, each containing
`content` with a list of `parts` to parse.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash", contents="Tell me a joke."
)
print(response.text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Tell me a joke.",
});
console.log(response.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();

GenerateContentResponse response =
    client.models.generateContent("gemini-2.5-flash-lite", "Tell me a joke.", null);
System.out.println(response.text());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    response, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash-lite",
        genai.Text("Tell me a joke."),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response.Text())
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    {{ '**' }}"contents": [{
        "parts": [{
            "text": "Tell me a joke."
        }]
    }]{{ '**' }}
}'

# Response
{
  {{ '**' }}"candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Why did the chicken cross the road? To get to the other side!"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ]{{ '**' }},
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 12,
    "totalTokenCount": 16
  }
}
```
{% /tab %}
{% /tabs %}

The Interactions API returns a stored interaction resource with a `steps`
timeline. While you can inspect the `steps` array manually to find intermediate
events, the Google GenAI SDKs provide convenience properties
directly on the returned `Interaction` object to access the final output.

The most common convenience property is **`.output_text`** (String), which
automatically extracts and joins consecutive `TextContent` blocks at the
end of the model's response. While this works perfectly for simple responses,
it does not include earlier text blocks separated by non-text content (such
as thoughts, images, audio, or tool calls). For complex or interleaved
multimodal responses, you must manually iterate over `steps` instead.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash", input="Tell me a joke."
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Tell me a joke.'
});

console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a joke."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a joke."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    {{ '**' }}"input": "Tell me a joke."{{ '**' }}
}'

# Response
{
  "id": "int_123",
  "status": "completed",
  {{ '**' }}"steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Tell me a joke."
        }
      ]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

## Multi-turn conversations {% id="multi-turn-conversations" %}

The Interactions API stores interactions by default, enabling server-side state
management for multi-turn conversations.

### Before (generateContent) {% id="before-generatecontent" %}

In `generateContent`, you must manually manage conversation history using the
`contents` array or a client-side chat helper.

{% tabs %}
{% tab label="Python" %}
**Using the chat helper (recommended)**

```python
from google import genai

client = genai.Client()

chat = client.chats.create(model="gemini-3.8-flash")
response1 = chat.send_message("Hi, my name is Phil.")
print(response1.text)

response2 = chat.send_message("What is my name?")
print(response2.text)
```

**Manually managing history**

```python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Content(
            role="user", parts=[types.Part.from_text("Hi, my name is Phil.")]
        ),
        types.Content(
            role="model",
            parts=[types.Part.from_text("Hi Phil, how can I help you?")],
        ),
        types.Content(
            role="user", parts=[types.Part.from_text("What is my name?")]
        ),
    ],
)
print(response.text)
```
{% /tab %}
{% tab label="JavaScript" %}
**Using the chat helper (recommended)**

```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const chat = client.chats.create({ model: 'gemini-3.8-flash' });
let response = await chat.sendMessage({ message: 'Hi, my name is Phil.' });
console.log(response.text);

response = await chat.sendMessage({ message: 'What is my name?' });
console.log(response.text);
```

**Manually managing history**

```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const response = await client.models.generateContent({
    model: 'gemini-3.8-flash',
    contents: [
        { role: 'user', parts: [{ text: 'Hi, my name is Phil.' }] },
        { role: 'model', parts: [{ text: 'Hi Phil, how can I help you?' }] },
        { role: 'user', parts: [{ text: 'What is my name?' }] }
    ]
});
console.log(response.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import java.util.Arrays;

Client client = new Client();

// Using the chat helper (recommended)
Chat chat = client.chats.create("gemini-2.5-flash-lite");
GenerateContentResponse response1 = chat.sendMessage("Hi, my name is Phil.");
System.out.println(response1.text());

GenerateContentResponse response2 = chat.sendMessage("What is my name?");
System.out.println(response2.text());

// Manually managing history
GenerateContentResponse manualResponse =
    client.models.generateContent(
        "gemini-2.5-flash-lite",
        Arrays.asList(
            Content.builder()
                .role("user")
                .parts(Arrays.asList(Part.fromText("Hi, my name is Phil.")))
                .build(),
            Content.builder()
                .role("model")
                .parts(Arrays.asList(Part.fromText("Hi Phil, how can I help you?")))
                .build(),
            Content.builder()
                .role("user")
                .parts(Arrays.asList(Part.fromText("What is my name?")))
                .build()),
        null);
System.out.println(manualResponse.text());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Using the chat helper (recommended)
    chat, err := client.Chats.Create(ctx, "gemini-2.5-flash-lite", nil, nil)
    if err != nil {
        log.Fatal(err)
    }
    response1, err := chat.SendMessage(ctx, genai.Part{Text: "Hi, my name is Phil."})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response1.Text())

    response2, err := chat.SendMessage(ctx, genai.Part{Text: "What is my name?"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response2.Text())

    // Manually managing history
    history := []*genai.Content{
        genai.NewContentFromText("Hi, my name is Phil.", genai.RoleUser),
        genai.NewContentFromText("Hi Phil, how can I help you?", genai.RoleModel),
        genai.NewContentFromText("What is my name?", genai.RoleUser),
    }
    manualResponse, err := client.Models.GenerateContent(ctx, "gemini-2.5-flash-lite", history, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(manualResponse.Text())
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request (the second turn requires sending the entire history)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    {{ '**' }}"contents": [
        {"role": "user", "parts": [{"text": "Hi, my name is Phil."}]},
        {"role": "model", "parts": [{"text": "Hi Phil, how can I help you?"}]},
        {"role": "user", "parts": [{"text": "What is my name?"}]}
    ]{{ '**' }}
}'

# Response
{
  {{ '**' }}"candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Your name is Phil."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

### After (Interactions API) {% id="after-interactions-api" %}

The Interactions API manages state on the server. You continue a conversation by
referencing the `previous_interaction_id`.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction1 = client.interactions.create(
    model="gemini-3.8-flash", input="Hi, my name is Phil."
)
print("Response 1:", interaction1.output_text)

interaction2 = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction1.id,
    input="What is my name?",
)
print("Response 2:", interaction2.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Hi, my name is Phil.'
});
console.log("Response 1:", interaction.output_text);

interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    previous_interaction_id: interaction.id,
    input: 'What is my name?'
});
console.log("Response 2:", interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction req1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Hi, my name is Phil."))
        .build();

Interaction interaction1 =
    client.interactions.create(CreateInteractionRequestBody.of(req1)).interaction().get();
System.out.println("Response 1: " + interaction1.outputText().orElse(""));

CreateModelInteraction req2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .previousInteractionId(interaction1.id().orElse(""))
        .input(InteractionsInput.of("What is my name?"))
        .build();

Interaction interaction2 =
    client.interactions.create(CreateInteractionRequestBody.of(req2)).interaction().get();
System.out.println("Response 2: " + interaction2.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res1.Interaction.OutputText != nil {
        fmt.Println("Response 1:", *res1.Interaction.OutputText)
    }

    res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            PreviousInteractionID: res1.Interaction.ID,
            Input:                 interactions.NewInteractionsInput("What is my name?"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res2.Interaction.OutputText != nil {
        fmt.Println("Response 2:", *res2.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
# First Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    {{ '**' }}"input": "Hi, my name is Phil."{{ '**' }}
}'

# Second Request (using ID from first response)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    {{ '**' }}"previous_interaction_id": "int_123",
    "input": "What is my name?"{{ '**' }}
}'

# Response to Second Request
{
  "id": "int_123",
  {{ '**' }}"steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [{ "type": "text", "text": "Hi, my name is Phil." }]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [{ "type": "text", "text": "Hello Phil! How can I help you today?" }]
    },
    {
      "type": "user_input",
      "status": "done",
      "content": [{ "type": "text", "text": "What is my name?" }]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [{ "type": "text", "text": "Your name is Phil." }]
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

## Multimodal inputs {% id="multimodal-inputs" %}

Both APIs support multimodal inputs (text, images, video, etc.).

### Before (generateContent) {% id="before-generatecontent" %}

In `generateContent`, you pass a list of `parts` within the `contents` array.
The response returns output in the `parts` of the first candidate.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

with open("sample.jpg", "rb") as f:
    image_bytes = f.read()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
        "Describe this image.",
    ],
)
print(response.text)
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("sample.jpg"));

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-2.5-flash-lite",
        Content.fromParts(
            Part.fromBytes(imageBytes, "image/jpeg"), Part.fromText("Describe this image.")),
        null);
System.out.println(response.text());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("sample.jpg")
    if err != nil {
        log.Fatal(err)
    }

    contents := []*genai.Content{
        genai.NewContentFromParts([]*genai.Part{
            genai.NewPartFromBytes(imageBytes, "image/jpeg"),
            genai.NewPartFromText("Describe this image."),
        }, genai.RoleUser),
    }

    response, err := client.Models.GenerateContent(ctx, "gemini-2.5-flash-lite", contents, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response.Text())
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    {{ '**' }}"contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/jpeg",
                    "data": "..."
                }
            },
            {
                "text": "Describe this image."
            }
        ]
    }]{{ '**' }}
}'

# Response
{
  {{ '**' }}"candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "This is a picture of a beautiful sunset."
          }
        ],
        "role": "model"
      }
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

### After (Interactions API) {% id="after-interactions-api" %}

In the Interactions API, you pass an array to the `input` field. You retrieve
output content by finding the `model_output` step in the timeline.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

with open("sample.jpg", "rb") as f:
    image_bytes = f.read()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "image",
            "mime_type": "image/jpeg",
            "data": image_bytes,
        },
        {"type": "text", "text": "Describe this image."},
    ],
)
print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';

const client = new GoogleGenAI({});

const imageBytes = fs.readFileSync('sample.jpg').toString('base64');

const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: [
        {
            type: 'image',
            mime_type: 'image/jpeg',
            data: imageBytes
        },
        {
            type: 'text',
            text: 'Describe this image.'
        }
    ]
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("sample.jpg"));
String base64ImageData = Base64.getEncoder().encodeToString(imageBytes);

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.ofContent(
                Arrays.asList(
                    ImageContent.builder()
                        .mimeType(ImageContentMimeType.IMAGE_JPEG)
                        .data(base64ImageData)
                        .build(),
                    TextContent.builder().text("Describe this image.").build())))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    imageBytes, err := os.ReadFile("sample.jpg")
    if err != nil {
        log.Fatal(err)
    }
    base64ImageData := base64.StdEncoding.EncodeToString(imageBytes)

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.ImageContent{
                    MimeType: interactions.ImageContentMimeType("image/jpeg").ToPointer(),
                    Data:     genai.Ptr(base64ImageData),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: "Describe this image.",
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    {{ '**' }}"input": [
        {
            "type": "image",
            "mime_type": "image/jpeg",
            "data": "..."
        },
        {
            "type": "text",
            "text": "Describe this image."
        }
    ]{{ '**' }}
}'

# Response
{
  "id": "int_multimodal",
  {{ '**' }}"steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        {
          "type": "image",
          "mime_type": "image/jpeg",
          "data": "..."
        },
        {
          "type": "text",
          "text": "Describe this image."
        }
      ]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "This is a picture of a beautiful sunset over the mountains."
        }
      ]
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

## Structured output {% id="structured-output" %}

To make the model return JSON matching a specific schema, configure the response
format.

### Before (generateContent) {% id="before-generatecontent" %}

In `generateContent`, you configure output format using the `response_mime_type`
and `response_schema` fields nested inside the `config` (or `generationConfig`)
object.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types
from pydantic import BaseModel

client = genai.Client()

class Recipe(BaseModel):
    recipe_name: str
    ingredients: list[str]

response = client.models.generate_content(
    model="gemini-2.5-flash-lite",
    contents="Give me a recipe for chocolate chip cookies.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=Recipe,
    ),
)
print(response.text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI, Type } from '@google/genai';

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash-lite',
    contents: 'Give me a recipe for chocolate chip cookies.',
    config: {
        responseMimeType: 'application/json',
        responseSchema: {
            type: Type.OBJECT,
            properties: {
                recipe_name: { type: Type.STRING },
                ingredients: {
                    type: Type.ARRAY,
                    items: { type: Type.STRING },
                },
            },
            required: ['recipe_name', 'ingredients'],
        },
    },
});
console.log(response.text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;
import java.util.Arrays;
import java.util.Map;

Client client = new Client();

Schema recipeSchema =
    Schema.builder()
        .type(Type.Known.OBJECT)
        .properties(
            Map.of(
                "recipe_name", Schema.builder().type(Type.Known.STRING).build(),
                "ingredients",
                    Schema.builder()
                        .type(Type.Known.ARRAY)
                        .items(Schema.builder().type(Type.Known.STRING).build())
                        .build()))
        .required(Arrays.asList("recipe_name", "ingredients"))
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-2.5-flash-lite",
        "Give me a recipe for chocolate chip cookies.",
        GenerateContentConfig.builder()
            .responseMimeType("application/json")
            .responseSchema(recipeSchema)
            .build());
System.out.println(response.text());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    recipeSchema := &genai.Schema{
        Type: genai.TypeObject,
        Properties: map[string]*genai.Schema{
            "recipe_name": {Type: genai.TypeString},
            "ingredients": {
                Type:  genai.TypeArray,
                Items: &genai.Schema{Type: genai.TypeString},
            },
        },
        Required: []string{"recipe_name", "ingredients"},
    }

    response, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash-lite",
        genai.Text("Give me a recipe for chocolate chip cookies."),
        &genai.GenerateContentConfig{
            ResponseMIMEType: "application/json",
            ResponseSchema:   recipeSchema,
        },
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response.Text())
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    {{ '**' }}"contents": [{
        "parts": [{
            "text": "Give me a recipe for chocolate chip cookies."
        }]
    }],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseSchema": {
            "type": "OBJECT",
            "properties": {
                "recipe_name": { "type": "STRING" },
                "ingredients": {
                    "type": "ARRAY",
                    "items": { "type": "STRING" }
                }
            },
            "required": ["recipe_name", "ingredients"]
        }
    }{{ '**' }}
}'

# Response
{
  {{ '**' }}"candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "{\n \"recipe_name\": \"Chocolate Chip Cookies\",\n \"ingredients\": [\n \"1 cup butter\",\n \"1 cup sugar\",\n \"2 cups flour\",\n \"1 cup chocolate chips\"\n ]\n}"
          }
        ],
        "role": "model"
      }
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

### After (Interactions API) {% id="after-interactions-api" %}

In the Interactions API, output format controls move to a
top-level `response_format` field. Pass a single format object, or an array of
format objects when you request more than one output type.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from pydantic import BaseModel

client = genai.Client()

class Recipe(BaseModel):
    recipe_name: str
    ingredients: list[str]

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Give me a recipe for chocolate chip cookies.",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Recipe.model_json_schema(),
    },
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Give me a recipe for chocolate chip cookies.',
    response_format: {
        type: 'text',
        mime_type: 'application/json',
        schema: {
            type: 'object',
            properties: {
                recipe_name: { type: 'string' },
                ingredients: {
                    type: 'array',
                    items: { type: 'string' }
                }
            },
            required: ['recipe_name', 'ingredients']
        }
    }
});
console.log(interaction.output_text);
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> properties = new HashMap<>();
properties.put("recipe_name", Map.of("type", "string"));
properties.put("ingredients", Map.of("type", "array", "items", Map.of("type", "string")));

Map<String, Object> schema = new HashMap<>();
schema.put("type", "object");
schema.put("properties", properties);
schema.put("required", Arrays.asList("recipe_name", "ingredients"));

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Give me a recipe for chocolate chip cookies."))
        .responseFormat(
            CreateModelInteractionResponseFormat.of(
                ResponseFormat.of(
                    TextResponseFormat.builder()
                        .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
                        .schema(schema)
                        .build())))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    schema := map[string]any{
        "type": "object",
        "properties": map[string]any{
            "recipe_name": map[string]any{"type": "string"},
            "ingredients": map[string]any{
                "type":  "array",
                "items": map[string]any{"type": "string"},
            },
        },
        "required": []string{"recipe_name", "ingredients"},
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Give me a recipe for chocolate chip cookies."),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(interactions.TextResponseFormat{
                    MimeType: interactions.TextResponseFormatMimeType("application/json").ToPointer(),
                    Schema:   schema,
                }),
            )),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    {{ '**' }}"input": "Give me a recipe for chocolate chip cookies.",
    "response_format": {
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "type": "object",
            "properties": {
                "recipe_name": { "type": "string" },
                "ingredients": {
                    "type": "array",
                    "items": { "type": "string" }
                }
            },
            "required": ["recipe_name", "ingredients"]
        }
    }{{ '**' }}
}'

# Response
{
  "id": "int_structured",
  {{ '**' }}"steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [{ "type": "text", "text": "Give me a recipe for chocolate chip cookies." }]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "{\n \"recipe_name\": \"Chocolate Chip Cookies\",\n \"ingredients\": [\n \"1 cup butter\",\n \"1 cup sugar\",\n \"2 cups flour\",\n \"1 cup chocolate chips\"\n ]\n}"
        }
      ]
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

## Multimodal generation {% id="multimodal-generation" %}

When generating content in modalities beyond text (such as images or audio), the
primary difference is how the response structures the generated media.

### Before (generateContent) {% id="before-generatecontent" %}

In `generateContent`, the response returns generated media directly in the
`parts` of the candidate, typically as base64 data in `inlineData`.

```json
# Response structure concept
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here is your generated image:"
          },
          {
            "inlineData": {
              "mimeType": "image/jpeg",
              "data": "...base64..."
            }
          }
        ]
      }
    }
  ]
}
```

### After (Interactions API) {% id="after-interactions-api" %}

In the Interactions API, generated media appears as distinct items within the
`content` array of a `model_output` step in the timeline, maintaining the
chronological flow of the interaction.

```json
# Response structure concept
{
  "id": "int_123",
  "steps": [
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Here is your generated image:"
        },
        {
          "type": "image",
          "mime_type": "image/jpeg",
          "data": "...base64..." // Or a reference URL in future
        }
      ]
    }
  ]
}
```

This keeps the response parsing consistent with how inputs and text outputs are
handled-everything is a step in the timeline.

## Server-side tools {% id="server-side-tools" %}

Gemini supports built-in server-side tools like Google Search grounding. The
primary difference is how the response represents tool execution.

### Before (generateContent) {% id="before-generatecontent" %}

In `generateContent`, server-side tools are largely opaque. You enable the tool
and get a final answer with a separate `groundingMetadata` object. Crucially,
citations are not inline; `groundingSupports` use character indices to map text
segments back to web sources in `groundingChunks`.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Who won Euro 2024?",
    config=types.GenerateContentConfig(
        tools=[{"google_search": {}}]
    ),
)

metadata = response.candidates[0].grounding_metadata
if metadata.search_entry_point:
    print(f"Search Entry Point: {metadata.search_entry_point.rendered_content}")

for support in metadata.grounding_supports:
    print(f"Citation: {support.segment.text}")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const response = await client.models.generateContent({
    model: 'gemini-3.8-flash',
    contents: 'Who won Euro 2024?',
    config: {
        tools: [{ googleSearch: {} }]
    }
});

const metadata = response.candidates?.[0]?.groundingMetadata;
if (metadata?.searchEntryPoint) {
    console.log(`Search Entry Point: ${metadata.searchEntryPoint.renderedContent}`);
}
if (metadata?.groundingSupports) {
    for (const support of metadata.groundingSupports) {
        if (support?.segment?.text) {
            console.log(`Citation: ${support.segment.text}`);
        }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Candidate;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.GoogleSearch;
import com.google.genai.types.GroundingMetadata;
import com.google.genai.types.GroundingSupport;
import com.google.genai.types.Tool;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.Optional;

Client client = new Client();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-2.5-flash-lite",
        "Who won Euro 2024?",
        GenerateContentConfig.builder()
            .tools(
                Arrays.asList(
                    Tool.builder().googleSearch(GoogleSearch.builder().build()).build()))
            .build());

List<Candidate> candidates = response.candidates().orElse(Collections.emptyList());
if (!candidates.isEmpty() && candidates.get(0).groundingMetadata().isPresent()) {
  GroundingMetadata metadata = candidates.get(0).groundingMetadata().get();
  if (metadata.searchEntryPoint().isPresent()) {
    System.out.println(
        "Search Entry Point: " + metadata.searchEntryPoint().get().renderedContent().orElse(""));
  }
  for (GroundingSupport support : metadata.groundingSupports().orElse(Collections.emptyList())) {
    Optional<String> segmentText = support.segment().flatMap(s -> s.text());
    segmentText.ifPresent(text -> System.out.println("Citation: " + text));
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    response, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash-lite",
        genai.Text("Who won Euro 2024?"),
        &genai.GenerateContentConfig{
            Tools: []*genai.Tool{
                {GoogleSearch: &genai.GoogleSearch{}},
            },
        },
    )
    if err != nil {
        log.Fatal(err)
    }

    if len(response.Candidates) > 0 && response.Candidates[0].GroundingMetadata != nil {
        metadata := response.Candidates[0].GroundingMetadata
        if metadata.SearchEntryPoint != nil {
            fmt.Println("Search Entry Point:", metadata.SearchEntryPoint.RenderedContent)
        }
        for _, support := range metadata.GroundingSupports {
            if support.Segment != nil {
                fmt.Println("Citation:", support.Segment.Text)
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    {{ '**' }}"contents": [{
        "parts": [{
            "text": "Who won Euro 2024?"
        }]
    }],
    "tools": [{
        "googleSearchRetrieval": {}
    }]{{ '**' }}
}'

# Response
{
  {{ '**' }}"candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "UEFA Euro 2024 winner",
          "who won euro 2024"
        ],
        "searchEntryPoint": {
          "renderedContent": " HTML and CSS for the search widget "
        },
        "groundingChunks": [
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "aljazeera.com"}},
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "uefa.com"}}
        ],
        "groundingSupports": [
          {
            "segment": {"startIndex": 0, "endIndex": 85, "text": "Spain won Euro 2024, defeatin..."},
            "groundingChunkIndices": [0]
          },
          {
            "segment": {"startIndex": 86, "endIndex": 210, "text": "This victory marks Spain's..."},
            "groundingChunkIndices": [0, 1]
          }
        ]
      }
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

### After (Interactions API) {% id="after-interactions-api" %}

In the Interactions API, server-side tools provide full timeline transparency.
The API records the call and result as distinct execution `steps`
(`google_search_call` and `google_search_result`), exposing exactly what data
the model retrieved.

Furthermore, the API returns citations **inline**. Instead of mapping indices
from a separate metadata object, the text item within the `model_output` step
contains its own `annotations` array linking directly to the source.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Who won Euro 2024?",
    tools=[{"type": "google_search"}],
)

for step in interaction.steps:
    if step.type == "google_search_result":
        print(f"Search Suggestions: {step.search_suggestions}")
    elif step.type == "model_output":
        print(f"Answer: {step.content[0].text}")
        if step.content[0].annotations:
            for anno in step.content[0].annotations:
                print(f"Citation: {anno.title} ({anno.uri})")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Who won Euro 2024?',
    tools: [{ type: 'google_search' }]
});

for (const step of interaction.steps || []) {
    if (step.type === 'google_search_result') {
        if (step.result?.[0]?.search_suggestions) {
            console.log(`Search Suggestions: ${step.result[0].search_suggestions}`);
        }
    } else if (step.type === 'model_output') {
        for (const part of step.content || []) {
            if (part.type === 'text') {
                console.log(`Answer: ${part.text}`);
                if (part.annotations) {
                    for (const anno of part.annotations) {
                        if (anno.type === 'url_citation') {
                            console.log(`Citation: ${anno.title} (${anno.url})`);
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.GoogleSearchResult;
import com.google.genai.gaos.models.interactions.GoogleSearchResultStep;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.URLCitation;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;

Client client = new Client();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Who won Euro 2024?"))
        .tools(Arrays.asList(GoogleSearch.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();

for (Step step : interaction.steps().orElse(Collections.emptyList())) {
  if (step instanceof GoogleSearchResultStep) {
    GoogleSearchResultStep searchStep = (GoogleSearchResultStep) step;
    for (GoogleSearchResult res : searchStep.result().orElse(Collections.emptyList())) {
      System.out.println("Search Suggestions: " + res.searchSuggestions().orElse(""));
    }
  } else if (step instanceof ModelOutputStep) {
    ModelOutputStep modelOutput = (ModelOutputStep) step;
    for (Content contentBlock : modelOutput.content().orElse(Collections.emptyList())) {
      if (contentBlock instanceof TextContent) {
        TextContent textContent = (TextContent) contentBlock;
        System.out.println("Answer: " + textContent.text().orElse(""));
        for (Annotation anno : textContent.annotations().orElse(Collections.emptyList())) {
          if (anno instanceof URLCitation) {
            URLCitation cit = (URLCitation) anno;
            System.out.println(
                "Citation: " + cit.title().orElse("") + " (" + cit.url().orElse("") + ")");
          }
        }
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Who won Euro 2024?"),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.GoogleSearch{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if searchStep := step.GoogleSearchResultStep; searchStep != nil {
            for _, r := range searchStep.Result {
                if r.SearchSuggestions != nil {
                    fmt.Println("Search Suggestions:", *r.SearchSuggestions)
                }
            }
        } else if modelOutput := step.ModelOutputStep; modelOutput != nil {
            for _, contentBlock := range modelOutput.Content {
                if textContent := contentBlock.TextContent; textContent != nil {
                    fmt.Println("Answer:", textContent.Text)
                    for _, anno := range textContent.Annotations {
                        if cit := anno.URLCitation; cit != nil {
                            fmt.Printf("Citation: %s (%s)\n", cit.GetTitle(), cit.GetURL())
                        }
                    }
                }
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    {{ '**' }}"input": "Who won Euro 2024?",
    "tools": [{{ '{' }}"type": "google_search"{{ '}' }}]{{ '**' }}
}'

# Response (showing grounding)
{
  "id": "int_grounded",
  {{ '**' }}"steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [{ "type": "text", "text": "Who won Euro 2024?" }]
    },
    {
      "type": "google_search_call",
      "status": "done",
      "content": [{ "type": "text", "text": "UEFA Euro 2024 winner" }]
    },
    {
      "type": "google_search_result",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Spain won Euro 2024..."
        }
      ]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Spain won Euro 2024, defeating England 2-1.",
          "annotations": [
            {
              "start_index": 0,
              "end_index": 42,
              "uri": "https://vertexaisearch...",
              "title": "aljazeera.com"
            }
          ]
        }
      ]
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

## Function calling {% id="function-calling" %}

The structure of function calls and results has also changed to fit the Steps
schema.

### Before (generateContent) {% id="before-generatecontent" %}

In `generateContent`, the response returns function calls within the candidates.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="What's the weather in Boston?",
    config=types.GenerateContentConfig(tools=[weather_tool]),
)

function_call = response.candidates[0].content.parts[0].function_call
print(f"Requested tool: {function_call.name}")

result = "52°F and rain"

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Content(
            role="user",
            parts=[
                types.Part.from_text(text="What's the weather in Boston?")
            ],
        ),
        response.candidates[0].content,
        types.Content(
            role="user",
            parts=[
                types.Part.from_function_response(
                    name=function_call.name,
                    response={"result": result},
                )
            ],
        ),
    ],
    config=types.GenerateContentConfig(tools=[weather_tool]),
)
print(response.text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

let response = await client.models.generateContent({
    model: 'gemini-3.8-flash',
    contents: "What's the weather in Boston?",
    config: { tools: [weatherTool] }
});

const candidateContent = response.candidates?.[0]?.content;
const functionCall = candidateContent?.parts?.[0]?.functionCall;
if (functionCall) {
    console.log(`Requested tool: ${functionCall.name}`);
}

const result = "52°F and rain";

if (candidateContent && functionCall) {
    response = await client.models.generateContent({
        model: 'gemini-3.8-flash',
        contents: [
            { role: 'user', parts: [{ text: "What's the weather in Boston?" }] },
            candidateContent,
            {
                role: 'user',
                parts: [{
                    functionResponse: {
                        name: functionCall.name,
                        response: { result: result }
                    }
                }]
            }
        ],
        config: { tools: [weatherTool] }
    });
    console.log(response.text);
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.FunctionCall;
import com.google.genai.types.FunctionDeclaration;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;
import com.google.genai.types.Schema;
import com.google.genai.types.Tool;
import com.google.genai.types.Type;
import java.util.Arrays;
import java.util.Map;

Client client = new Client();

FunctionDeclaration weatherFunc =
    FunctionDeclaration.builder()
        .name("get_weather")
        .description("Gets weather")
        .parameters(
            Schema.builder()
                .type(Type.Known.OBJECT)
                .properties(Map.of("location", Schema.builder().type(Type.Known.STRING).build()))
                .build())
        .build();

Tool weatherTool = Tool.builder().functionDeclarations(Arrays.asList(weatherFunc)).build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-2.5-flash-lite",
        "What's the weather in Boston?",
        GenerateContentConfig.builder().tools(Arrays.asList(weatherTool)).build());

FunctionCall functionCall = response.functionCalls().get(0);
System.out.println("Requested tool: " + functionCall.name().orElse(""));

String result = "52°F and rain";

GenerateContentResponse finalResponse =
    client.models.generateContent(
        "gemini-2.5-flash-lite",
        Arrays.asList(
            Content.builder()
                .role("user")
                .parts(Arrays.asList(Part.fromText("What's the weather in Boston?")))
                .build(),
            response.candidates().get().get(0).content().get(),
            Content.builder()
                .role("user")
                .parts(
                    Arrays.asList(
                        Part.fromFunctionResponse(
                            functionCall.name().orElse(""), Map.of("result", result))))
                .build()),
        GenerateContentConfig.builder().tools(Arrays.asList(weatherTool)).build());
System.out.println(finalResponse.text());
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    weatherTool := &genai.Tool{
        FunctionDeclarations: []*genai.FunctionDeclaration{
            {
                Name:        "get_weather",
                Description: "Gets weather",
                Parameters: &genai.Schema{
                    Type: genai.TypeObject,
                    Properties: map[string]*genai.Schema{
                        "location": {Type: genai.TypeString},
                    },
                },
            },
        },
    }

    config := &genai.GenerateContentConfig{
        Tools: []*genai.Tool{weatherTool},
    }

    response, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash-lite",
        genai.Text("What's the weather in Boston?"),
        config,
    )
    if err != nil {
        log.Fatal(err)
    }

    calls := response.FunctionCalls()
    if len(calls) > 0 {
        functionCall := calls[0]
        fmt.Println("Requested tool:", functionCall.Name)

        result := "52°F and rain"
        history := []*genai.Content{
            genai.NewContentFromText("What's the weather in Boston?", genai.RoleUser),
            response.Candidates[0].Content,
            genai.NewContentFromParts([]*genai.Part{
                genai.NewPartFromFunctionResponse(functionCall.Name, map[string]any{"result": result}),
            }, genai.RoleUser),
        }

        finalResponse, err := client.Models.GenerateContent(ctx, "gemini-2.5-flash-lite", history, config)
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println(finalResponse.Text())
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    {{ '**' }}"contents": [{
        "parts": [{
            "text": "What is the weather like in Boston, MA?"
        }]
    }],
    "tools": [{
        "functionDeclarations": [{
            "name": "get_weather",
            "description": "Get the current weather",
            "parameters": {
                "type": "OBJECT",
                "properties": {
                    "location": {"type": "STRING"}
                },
                "required": ["location"]
            }
        }]
    }]{{ '**' }}
}'

# Response
{
  {{ '**' }}"candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "get_weather",
              "args": { "location": "Boston, MA" }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

### After (Interactions API) {% id="after-interactions-api" %}

Tool calls and results are now distinct steps in the timeline.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Gets weather",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {"type": "string"}
        },
    },
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What's the weather in Boston?",
    tools=[weather_tool],
)

for step in interaction.steps:
    if step.type == "function_call":
        print(f"Executing {step.name} for {step.arguments}")

        result = "52°F and rain"

        interaction = client.interactions.create(
            model="gemini-3.8-flash",
            previous_interaction_id=interaction.id,
            input=[
                {
                    "type": "function_result",
                    "call_id": step.id,
                    "name": step.name,
                    "result": [{"type": "text", "text": result}],
                }
            ],
        )
        print(next_interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: "What's the weather in Boston?",
    tools: [
        {
            type: "function",
            name: "get_weather",
            description: "Get weather for a location",
            parameters: {
                type: "object",
                properties: {
                    location: { type: "string" }
                },
                required: ["location"]
            }
        }
    ]
});

for (const step of interaction.steps || []) {
    if (step.type === 'function_call') {
        console.log(`Executing ${step.name} for ${JSON.stringify(step.arguments)}`);

        const result = "52°F and rain";

        const nextInteraction = await client.interactions.create({
            model: 'gemini-3.8-flash',
            previous_interaction_id: interaction.id,
            input: [
                {
                    type: 'function_result',
                    call_id: step.id,
                    name: step.name,
                    result: [{ type: 'text', text: result }]
                }
            ]
        });

        console.log(nextInteraction.output_text);
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.FunctionResultStep;
import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> properties = new HashMap<>();
properties.put("location", Map.of("type", "string"));

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");
parameters.put("properties", properties);
parameters.put("required", Arrays.asList("location"));

Function weatherTool =
    Function.builder()
        .name("get_weather")
        .description("Gets weather")
        .parameters(parameters)
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("What's the weather in Boston?"))
        .tools(Arrays.asList(weatherTool))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();

for (Step step : interaction.steps().orElse(Collections.emptyList())) {
  if (step instanceof FunctionCallStep) {
    FunctionCallStep fcStep = (FunctionCallStep) step;
    System.out.println(
        "Executing "
            + fcStep.name().orElse("")
            + " for "
            + fcStep.arguments().orElse(Collections.emptyMap()));

    String result = "52°F and rain";

    FunctionResultStep funcResult =
        FunctionResultStep.builder()
            .callId(fcStep.id().orElse(""))
            .name(fcStep.name().orElse(""))
            .result(
                FunctionResultStepResultUnion.of(
                    Arrays.asList(TextContent.builder().text(result).build())))
            .build();

    CreateModelInteraction nextRequest =
        CreateModelInteraction.builder()
            .model(Model.of("gemini-3.8-flash"))
            .previousInteractionId(interaction.id().orElse(""))
            .input(InteractionsInput.ofStep(Arrays.asList(funcResult)))
            .build();

    Interaction nextInteraction =
        client.interactions.create(CreateInteractionRequestBody.of(nextRequest)).interaction().get();
    System.out.println(nextInteraction.outputText().orElse(""));
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    weatherTool := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Gets weather"),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{"type": "string"},
            },
            "required": []string{"location"},
        },
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("What's the weather in Boston?"),
            Tools: []interactions.Tool{weatherTool},
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if fcStep := step.FunctionCallStep; fcStep != nil {
            fmt.Printf("Executing %s for %v\n", fcStep.Name, fcStep.Arguments)

            result := "52°F and rain"
            funcResult := interactions.NewStep(interactions.FunctionResultStep{
                CallID: fcStep.ID,
                Name:   genai.Ptr(fcStep.Name),
                Result: interactions.NewFunctionResultStepResultUnion([]interactions.FunctionResultSubcontent{
                    interactions.NewFunctionResultSubcontent(interactions.TextContent{Text: result}),
                }),
            })

            nextRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
                Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
                    Model:                 interactions.Model("gemini-3.8-flash"),
                    PreviousInteractionID: res.Interaction.ID,
                    Input:                 interactions.NewInteractionsInput([]interactions.Step{funcResult}),
                }),
            })
            if err != nil {
                log.Fatal(err)
            }
            if nextRes.Interaction.OutputText != nil {
                fmt.Println(*nextRes.Interaction.OutputText)
            }
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Initial Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    {{ '**' }}"input": "What's the weather in Boston?",
    "tools": [{
        "type": "function",
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": { "type": "string" }
            },
            "required": ["location"]
        }
    }]{{ '**' }}
}'

# Response (requires action)
{
  "id": "int_001",
  "status": "requires_action",
  {{ '**' }}"steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        { "type": "text", "text": "What's the weather in Boston?" }
      ]
    },
    {
      "type": "function_call",
      "status": "waiting",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]{{ '**' }}
}

# Submit Tool Result Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    {{ '**' }}"previous_interaction_id": "int_001",
    "input": {
        "type": "function_result",
        "call_id": "fc_1",
        "name": "get_weather",
        "result": [
            { "type": "text", "text": "52°F with rain" }
        ]
    }{{ '**' }}
}'

# Final Response
{
  "id": "int_002",
  "status": "completed",
  {{ '**' }}"steps": [
    {
      "type": "function_result",
      "call_id": "fc_1",
      "name": "get_weather",
      "result": [
        { "type": "text", "text": "52°F with rain" }
      ]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        { "type": "text", "text": "It's 52°F with rain in Boston." }
      ]
    }
  ]{{ '**' }}
}
```
{% /tab %}
{% /tabs %}

## Streaming {% id="streaming" %}

A key difference in streaming is that the Interactions API uses the same
endpoint with `"stream": true` in the request body, whereas the
`generateContent` API required calling a dedicated endpoint
(`:streamGenerateContent`).

Additionally, streaming events now use specialized types to monitor the
interaction lifecycle and track execution steps along the timeline.

### Before (generateContentStream) {% id="before-generatecontentstream" %}

With `generateContent`, you consume a stream of response chunks.

{% tabs %}
{% tab label="Python" %}
```python
response = client.models.generate_content_stream(
    model="gemini-3.8-flash", contents="Tell me a story"
)
for chunk in response:
    print(chunk.text, end="")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
const responseStream = await client.models.generateContentStream({
    model: 'gemini-3.8-flash',
    contents: 'Tell me a story',
});
for await (const chunk of responseStream) {
    process.stdout.write(chunk.text);
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.ResponseStream;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();

try (ResponseStream<GenerateContentResponse> responseStream =
    client.models.generateContentStream("gemini-2.5-flash-lite", "Tell me a story", null)) {
  for (GenerateContentResponse chunk : responseStream) {
    System.out.print(chunk.text());
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    for chunk, err := range client.Models.GenerateContentStream(
        ctx,
        "gemini-2.5-flash-lite",
        genai.Text("Tell me a story"),
        nil,
    ) {
        if err != nil {
            log.Fatal(err)
        }
        fmt.Print(chunk.Text())
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    {{ '**' }}"contents": [{
        "parts": [{
            "text": "Tell me a story"
        }]
    }]{{ '**' }}
}'

# Response stream
{{ '**' }}event: content.start
data: {"event_type": "content.start", "index": 0, "content": {"type": "thought"}}
event: content.delta
data: {"event_type": "content.delta", "index": 0, "delta": {"type": "thought_summary", "text": "User wants an explanation."}}
event: content.stop
data: {"event_type": "content.stop", "index": 0}
event: content.start
data: {"event_type": "content.start", "index": 1, "content": {"type": "text"}}
event: content.delta
data: {"event_type": "content.delta", "index": 1, "delta": {"type": "text", "text": "Hello"}}
event: content.stop
data: {"event_type": "content.stop", "index": 1}{{ '**' }}
```
{% /tab %}
{% /tabs %}

### After (Interactions API) {% id="after-interactions-api" %}

In the Interactions API, streaming uses Server-Sent Events (SSE) and specialized
delta types to represent execution steps as they happen.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a story",
    stream=True,
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)
    elif event.event_type == "interaction.completed":
        print(f"\n\n--- Stream Finished ---")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Tell me a story',
    stream: true,
});

for await (const event of stream) {
    if (event.event_type === 'step.delta') {
        if (event.delta.type === 'text' && 'text' in event.delta) {
            process.stdout.write(event.delta.text);
        }
    } else if (event.event_type === 'interaction.completed') {
        console.log('\n\n--- Stream Finished ---');
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.InteractionCompletedEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.utils.EventStream;

Client client = new Client();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a story"))
        .stream(true)
        .build();

try (EventStream<InteractionSSEStreamEvent> stream =
    client.interactions.create(CreateInteractionRequestBody.of(request)).events()) {
  for (InteractionSSEStreamEvent streamEvent : stream) {
    if (streamEvent.data().isPresent()) {
      InteractionSSEEvent event = streamEvent.data().get();
      if (event instanceof StepDelta) {
        StepDelta stepDelta = (StepDelta) event;
        if (stepDelta.delta().isPresent() && stepDelta.delta().get() instanceof TextDelta) {
          TextDelta textDelta = (TextDelta) stepDelta.delta().get();
          System.out.print(textDelta.text().orElse(""));
        }
      } else if (event instanceof InteractionCompletedEvent) {
        System.out.println("\n\n--- Stream Finished ---");
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:  interactions.Model("gemini-3.8-flash"),
            Input:  interactions.NewInteractionsInput("Tell me a story"),
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        } else if event.GetDataInteractionCompleted() != nil {
            fmt.Println("\n\n--- Stream Finished ---")
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
  {{ '**' }}event: interaction.created
  data: {"interaction": {"id": "int_xyz", "status": "in_progress"}, "event_type": "interaction.created"}
  event: interaction.status_update
  data: {"interaction_id": "int_xyz", "status": "in_progress", "event_type": "interaction.status_update"}
  event: step.start
  data: {"index": 0, "step": {"type": "thought"}, "event_type": "step.start"}
  event: step.delta
  data: {"index": 0, "delta": {"type": "thought_summary", "content": {"type": "text", "text": "User wants an explanation."}}, "event_type": "step.delta"}
  event: step.stop
  data: {"index": 0, "event_type": "step.stop"}
  event: step.start
  data: {"index": 1, "step": {"type": "model_output"}, "event_type": "step.start"}
  event: step.delta
  data: {"index": 1, "delta": {"type": "text", "text": "Hello"}, "event_type": "step.delta"}
  event: step.stop
  data: {"index": 1, "event_type": "step.stop"}
  event: interaction.completed
  data: {"interaction": {"id": "int_xyz", "status": "completed", "usage": {"total_input_tokens": 10, "total_output_tokens": 5, "total_tokens": 15}}, "event_type": "interaction.completed"}{{ '**' }}
```
{% /tab %}
{% /tabs %}

### Streaming tools and function calls {% id="streaming-tools-and-function-calls" %}

The way tools behave in the stream has shifted significantly from
`generateContent` to provide more granular control and visibility.

#### Before (generateContent) {% id="before-generatecontent" %}

With `generateContent`, streaming function calls arrived complete in a single
chunk. You could not see the arguments being generated in real-time, so the
handler simply checked for a complete `functionCall` object.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
from google.genai import types

client = genai.Client()

stream = client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents="What's the weather in Boston?",
    config=types.GenerateContentConfig(tools=[weather_tool]),
)

for chunk in stream:
    if chunk.candidates[0].content.parts[0].function_call:
        fc = chunk.candidates[0].content.parts[0].function_call
        print(f"Call: {fc.name}({fc.args})")
    elif chunk.text:
        print(chunk.text, end="")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const stream = await client.models.generateContentStream({
    model: 'gemini-3.8-flash',
    contents: "What's the weather in Boston?",
    config: { tools: [weatherTool] }
});

for await (const chunk of stream) {
    const part = chunk.candidates?.[0]?.content?.parts?.[0];
    if (part?.functionCall) {
        console.log(`Call: ${part.functionCall.name}(${JSON.stringify(part.functionCall.args)})`);
    } else if (part?.text) {
        process.stdout.write(part.text);
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.ResponseStream;
import com.google.genai.types.FunctionCall;
import com.google.genai.types.FunctionDeclaration;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Schema;
import com.google.genai.types.Tool;
import com.google.genai.types.Type;
import java.util.Arrays;
import java.util.Map;

Client client = new Client();

FunctionDeclaration weatherFunc =
    FunctionDeclaration.builder()
        .name("get_weather")
        .description("Gets weather")
        .parameters(
            Schema.builder()
                .type(Type.Known.OBJECT)
                .properties(Map.of("location", Schema.builder().type(Type.Known.STRING).build()))
                .build())
        .build();

Tool weatherTool = Tool.builder().functionDeclarations(Arrays.asList(weatherFunc)).build();

try (ResponseStream<GenerateContentResponse> stream =
    client.models.generateContentStream(
        "gemini-2.5-flash-lite",
        "What's the weather in Boston?",
        GenerateContentConfig.builder().tools(Arrays.asList(weatherTool)).build())) {
  for (GenerateContentResponse chunk : stream) {
    if (chunk.functionCalls() != null && !chunk.functionCalls().isEmpty()) {
      FunctionCall fc = chunk.functionCalls().get(0);
      System.out.println("Call: " + fc.name().orElse("") + "(" + fc.args().orElse(Map.of()) + ")");
    } else if (chunk.text() != null) {
      System.out.print(chunk.text());
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    weatherTool := &genai.Tool{
        FunctionDeclarations: []*genai.FunctionDeclaration{
            {
                Name:        "get_weather",
                Description: "Gets weather",
                Parameters: &genai.Schema{
                    Type: genai.TypeObject,
                    Properties: map[string]*genai.Schema{
                        "location": {Type: genai.TypeString},
                    },
                },
            },
        },
    }

    for chunk, err := range client.Models.GenerateContentStream(
        ctx,
        "gemini-2.5-flash-lite",
        genai.Text("What's the weather in Boston?"),
        &genai.GenerateContentConfig{
            Tools: []*genai.Tool{weatherTool},
        },
    ) {
        if err != nil {
            log.Fatal(err)
        }
        if calls := chunk.FunctionCalls(); len(calls) > 0 {
            fc := calls[0]
            fmt.Printf("Call: %s(%v)\n", fc.Name, fc.Args)
        } else if text := chunk.Text(); text != "" {
            fmt.Print(text)
        }
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    {{ '**' }}"contents": [{"parts": [{"text": "What'\''s the weather in Boston?"}]}],
    "tools": [{"functionDeclarations": [{"name": "get_weather", "parameters": {"type": "OBJECT", "properties": {"location": {"type": "STRING"}}}}]}]{{ '**' }}
}'

{{ '**' }}{"candidates": [{"content": {"parts": [{"functionCall": {"name": "get_weather", "args": {"location": "Boston, MA"}}}]}}]}{{ '**' }}
```
{% /tab %}
{% /tabs %}

#### After (Interactions API) {% id="after-interactions-api" %}

The Interactions API streams function call arguments character-by-character as
`arguments_delta` events. The entire tool lifecycle - thought, call, result, and
output - plays out as a series of distinct steps.

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="What's the weather in Boston?",
    tools=[get_weather_tool],
    stream=True,
)

for event in stream:
    if event.event_type == "step.start":
        if event.step.type == "function_call":
            print(f"Calling: {event.step.name}")
    elif event.event_type == "step.delta":
        if event.delta.type == "arguments_delta":
            print(f" args: {event.delta.arguments}")
        elif event.delta.type == "text":
            print(event.delta.text, end="")
    elif event.event_type == "interaction.completed":
        print("\n--- Done ---")
```
{% /tab %}
{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: "What's the weather in Boston?",
    tools: [getWeatherTool],
    stream: true,
});

for await (const event of stream) {
    if (event.event_type === 'step.start') {
        if (event.step.type === 'function_call') {
            console.log(`Calling: ${event.step.name}`);
        }
    } else if (event.event_type === 'step.delta') {
        if (event.delta.type === 'arguments_delta') {
            console.log(` args: ${event.delta.arguments}`);
        } else if (event.delta.type === 'text') {
            process.stdout.write(event.delta.text);
        }
    } else if (event.event_type === 'interaction.completed') {
        console.log('\n--- Done ---');
    }
}
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ArgumentsDelta;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.FunctionCallStep;
import com.google.genai.gaos.models.interactions.InteractionCompletedEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEEvent;
import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.StepDelta;
import com.google.genai.gaos.models.interactions.StepDeltaData;
import com.google.genai.gaos.models.interactions.StepStart;
import com.google.genai.gaos.models.interactions.TextDelta;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.utils.EventStream;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

Client client = new Client();

Map<String, Object> properties = new HashMap<>();
properties.put("location", Map.of("type", "string"));

Map<String, Object> parameters = new HashMap<>();
parameters.put("type", "object");
parameters.put("properties", properties);
parameters.put("required", Arrays.asList("location"));

Function getWeatherTool =
    Function.builder()
        .name("get_weather")
        .description("Gets weather")
        .parameters(parameters)
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("What's the weather in Boston?"))
        .tools(Arrays.asList(getWeatherTool))
        .stream(true)
        .build();

try (EventStream<InteractionSSEStreamEvent> stream =
    client.interactions.create(CreateInteractionRequestBody.of(request)).events()) {
  for (InteractionSSEStreamEvent streamEvent : stream) {
    if (streamEvent.data().isPresent()) {
      InteractionSSEEvent event = streamEvent.data().get();
      if (event instanceof StepStart) {
        StepStart stepStart = (StepStart) event;
        if (stepStart.step().isPresent() && stepStart.step().get() instanceof FunctionCallStep) {
          FunctionCallStep fcStep = (FunctionCallStep) stepStart.step().get();
          System.out.println("Calling: " + fcStep.name().orElse(""));
        }
      } else if (event instanceof StepDelta) {
        StepDelta stepDelta = (StepDelta) event;
        if (stepDelta.delta().isPresent()) {
          StepDeltaData delta = stepDelta.delta().get();
          if (delta instanceof ArgumentsDelta) {
            System.out.println("  args: " + ((ArgumentsDelta) delta).arguments().orElse(""));
          } else if (delta instanceof TextDelta) {
            System.out.print(((TextDelta) delta).text().orElse(""));
          }
        }
      } else if (event instanceof InteractionCompletedEvent) {
        System.out.println("\n--- Done ---");
      }
    }
  }
}
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    getWeatherTool := interactions.NewTool(interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Gets weather"),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{"type": "string"},
            },
            "required": []string{"location"},
        },
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:  interactions.Model("gemini-3.8-flash"),
            Input:  interactions.NewInteractionsInput("What's the weather in Boston?"),
            Tools:  []interactions.Tool{getWeatherTool},
            Stream: genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepStart := event.GetDataStepStart(); stepStart != nil {
            if fcStep := stepStart.GetStepFunctionCall(); fcStep != nil {
                fmt.Println("Calling:", fcStep.Name)
            }
        } else if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if argsDelta := stepDelta.GetDeltaArgumentsDelta(); argsDelta != nil {
                fmt.Println("  args:", argsDelta.GetArguments())
            } else if textDelta := stepDelta.GetDeltaText(); textDelta != nil {
                fmt.Print(textDelta.GetText())
            }
        } else if event.GetDataInteractionCompleted() != nil {
            fmt.Println("\n--- Done ---")
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```json
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.8-flash",
    {{ '**' }}"input": "What'\''s the weather in Boston?",
    "tools": [{"type": "function", "name": "get_weather", "parameters": {"type": "object", "properties": {"location": {"type": "string"}}}}],
    "stream": true{{ '**' }}
}'

// Stream 1: the model calls the function
event: interaction.created
data: {"interaction": {"id": "int_1", "status": "in_progress"}, "event_type": "interaction.created"}

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

// ── Step 0: Thought ──────────────────────────────────
event: step.start
data: {"index": 0, "step": {"type": "thought"}, "event_type": "step.start"}

event: step.delta
data: {"index": 0, "delta": {"type": "thought_summary", "content": {"type": "text", "text": "The user wants weather data for Boston. I'll call the get_weather tool."}}, "event_type": "step.delta"}

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

// ── Step 1: Function Call (arguments streamed) ───────
event: step.start
data: {"index": 1, "step": {"type": "function_call", "id": "fc_1", "name": "get_weather", "arguments": {}}, "event_type": "step.start"}

event: step.delta
data: {"index": 1, "delta": {"type": "arguments_delta", "arguments": "{\"location\": \"Boston, MA\"}"}, "event_type": "step.delta"}

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

// The stream ends with status requires_action: the model needs the tool result.
event: interaction.completed
data: {"interaction": {"id": "int_1", "status": "requires_action", "usage": {"total_input_tokens": 34, "total_output_tokens": 15, "total_tokens": 49}}, "event_type": "interaction.completed"}

event: done
data: [DONE]

// ── (Client submits the tool result) ──────────────────
// The client calls interactions.create with the function_result as input
// and previous_interaction_id set to "int_1". This opens a new stream.

// Stream 2: the model uses the result
event: interaction.created
data: {"interaction": {"id": "int_2", "status": "in_progress"}, "event_type": "interaction.created"}

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

// ── Step 0: Thought ──────────────────────────────────
event: step.start
data: {"index": 0, "step": {"type": "thought"}, "event_type": "step.start"}

event: step.delta
data: {"index": 0, "delta": {"type": "thought_summary", "content": {"type": "text", "text": "Got weather data. Composing the final response."}}, "event_type": "step.delta"}

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

// ── Step 1: Model Output (text streamed) ─────────────
event: step.start
data: {"index": 1, "step": {"type": "model_output"}, "event_type": "step.start"}

event: step.delta
data: {"index": 1, "delta": {"type": "text", "text": "It's currently 52°F and rainy in Boston."}, "event_type": "step.delta"}

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

// ── Interaction complete ─────────────────────────────
event: interaction.completed
data: {"interaction": {"id": "int_2", "status": "completed", "usage": {"total_input_tokens": 256, "total_output_tokens": 128, "total_tokens": 384}}, "event_type": "interaction.completed"}

event: done
data: [DONE]
```
{% /tab %}
{% /tabs %}

# Interactions API: Breaking changes migration guide (May 2026)
Source: https://aistudio.google.com/docs/interactions-breaking-changes-may-2026
Description: Guide for migrating to upcoming breaking changes in the Interactions API, including the steps schema and response format changes.

{% callout type="warning" %}
**Breaking changes**: The changes described in this guide are
  breaking changes to the Interactions API. The legacy schema will be
  removed on **June 8, 2026**. Use the
  `Api-Revision` request header to
  [manage your migration](/docs/interactions-breaking-changes-may-2026#how-to-migrate).
{% /callout %}

The `v1beta` Interactions API is introducing breaking changes that restructure the
API shape to support future capabilities like mid-flight steering and
asynchronous tool calls. This page explains what's changing and provides
before-and-after code examples to help you migrate. There are two categories
of changes:

1. [**Steps schema**](/docs/interactions-breaking-changes-may-2026#steps-schema): A new `steps` array replaces the
    `outputs` array, providing a structured timeline of each interaction turn.
2. [**Output format configuration**](/docs/interactions-breaking-changes-may-2026#output-format-config): A new polymorphic
    `response_format` consolidates all output format controls and removes
    `response_mime_type`.

Follow the steps in [How to migrate to the new schema](/docs/interactions-breaking-changes-may-2026#how-to-migrate) to
update your integration.

## Core change: `outputs` to `steps` {% id="steps-schema" %}

The new schema replaces the `outputs` array with a `steps` array.

- **Legacy**: Responses returned a flat `outputs` array containing only the model's generated content.
- **New schema**: Responses return a `steps` array containing structured steps with type discriminators.

`POST /interactions` returns only output steps. `GET /interactions/{id}`
returns the full step timeline, including the initial `user_input` step.

### Basic input/output (unary) {% id="basic-unary" %}

#### Before (legacy)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Request
interaction = client.interactions.create(
    model="gemini-3.8-flash", input="Tell me a joke."
)

# Response access
print(interaction.outputs[-1].text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
// Request
const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Tell me a joke.'
});

// Response access
console.log(interaction.outputs[-1].text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a joke."
  }'
```

```none
// Response
{
  "id": "int_123",
  "role": "model",
  {{ '<strong>' }}"outputs": [
    {
      "type": "text",
      "text": "Why did the chicken cross the road?"
    }
  ]{{ '</strong>' }}
}
```

{% /tab %}
{% /tabs %}
#### After (new schema)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Request
interaction = client.interactions.create(
    model="gemini-3.8-flash", input="Tell me a joke."
)

# Response access (Recommended sugar)
print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
// Request
const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Tell me a joke.'
});

// Response access (Recommended sugar)
console.log(interaction.output_text);
```

Note: For details on SDK convenience properties (including `.output_text`,
`.output_image`, and `.output_audio`), see
[Access outputs with SDK convenience properties][sdk-convenience]
in the overview.

[sdk-convenience]: /docs/interactions-overview#sdk-sugar

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  {{ '**' }}-H "Api-Revision: 2026-05-20" \{{ '**' }}
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a joke."
  }'
```

```html
// POST Response
{
  "id": "int_123",
  {{ '<strong>' }}"steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]{{ '</strong>' }}
}

// GET /v1beta/interactions/int_123 (returns full timeline including input)
{
  "id": "int_123",
  "steps": [
    {
      "type": "user_input",
      "content": [
        { "type": "text", "text": "Tell me a joke." }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}
```

{% /tab %}
{% /tabs %}
### Function calling {% id="function-calling" %}

The request structure remains unchanged, but the response replaces the flat
`outputs` content with structured steps.
#### Before (legacy)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Accessing function call in legacy schema
for output in interaction.outputs:
    if output.type == "function_call":
        print(f"Calling {output.name} with {output.arguments}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
// Accessing function call in legacy schema
for (const output of interaction.outputs) {
    if (output.type === 'function_call') {
        console.log(`Calling ${output.name} with ${JSON.stringify(output.arguments)}`);
    }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```json
// Response
{
  "id": "int_001",
  "role": "model",
  "status": "requires_action",
  {{ '<strong>' }}"outputs": [
    {
      "type": "thought",
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]{{ '</strong>' }}
}
```

{% /tab %}
{% /tabs %}
#### After (new schema)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Accessing function call in new steps schema
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Calling {step.name} with {step.arguments}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
// Accessing function call in new steps schema
for (const step of interaction.steps) {
    if (step.type === 'function_call') {
        console.log(`Calling ${step.name} with ${JSON.stringify(step.arguments)}`);
    }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```json
// POST Response
{
  "id": "int_001",
  "status": "requires_action",
  {{ '<strong>' }}"steps": [
    {
      "type": "thought",
      "summary": [{
        "type": "text",
        "text": "I need to check the weather in Boston..."
      }],
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]{{ '</strong>' }}
}
```

{% /tab %}
{% /tabs %}
### Server-side tools {% id="server-side-tools" %}

Server-side tools (like Google Search or Code Execution) now yield specific
step types in the `steps` array. While the legacy schema returned these
operations as specific content types within the `outputs` array, the new schema
moves them into the `steps` array. The following examples use Google Search.

#### Before (legacy)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Accessing search results in legacy schema
for output in interaction.outputs:
    if output.type == "google_search_call":
        print(f"Searched for: {output.arguments.queries}")
    elif output.type == "google_search_result":
        print(f"Found results: {output.result.rendered_content}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
// Accessing search results in legacy schema
for (const output of interaction.outputs) {
    if (output.type === 'google_search_call') {
        console.log(`Searched for: ${output.arguments.queries}`);
    } else if (output.type === 'google_search_result') {
        console.log(`Found results: ${output.result.renderedContent}`);
    }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Who won the last Super Bowl?",
    "tools": [
      { "type": "google_search" }
    ]
  }'
```

```html
// Response
{
  "id": "int_456",
  {{ '<strong>' }}"outputs": [
    {
      "type": "google_search_call",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] }
    },
    {
      "type": "google_search_result",
      "call_id": "gs_1",
      "result": {
        "rendered_content": "...",
        "url": "https://www.nfl.com/super-bowl"
      }
    },
    {
      "type": "text",
      "text": "The Kansas City Chiefs won the last Super Bowl.",
      "annotations": [
        {
          "start_index": 4,
          "end_index": 22,
          "source": "https://www.nfl.com/super-bowl"
        }
      ]
    }
  ]{{ '</strong>' }},
  "status": "completed"
}
```

{% /tab %}
{% /tabs %}
#### After (new schema)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Accessing search results in new steps schema
for step in interaction.steps:
    if step.type == "google_search_call":
        print(f"Searched for: {step.arguments.queries}")
    elif step.type == "google_search_result":
        print(f"Found results: {step.result[0].search_suggestions}")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
// Accessing search results in new steps schema
for (const step of interaction.steps) {
    if (step.type === 'google_search_call') {
        console.log(`Searched for: ${step.arguments.queries}`);
    } else if (step.type === 'google_search_result') {
        console.log(`Found results: ${step.result[0].search_suggestions}`);
    }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  {{ '**' }}-H "Api-Revision: 2026-05-20" \{{ '**' }}
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Who won the last Super Bowl?",
    "tools": [
      { "type": "google_search" }
    ]
  }'
```

```html
// POST Response
{
  "id": "int_456",
  {{ '<strong>' }}"steps": [
    {
      "type": "google_search_call",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] },
      "signature": "abc123..."
    },
    {
      "type": "google_search_result",
      "call_id": "gs_1",
      "result": {
        "search_suggestions": "..."
      },
      "signature": "abc123..."
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The Kansas City Chiefs won the last Super Bowl.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.nfl.com/super-bowl",
              "title": "NFL.com",
              "start_index": 4,
              "end_index": 22
            }
          ]
        }
      ]
    }
  ]{{ '</strong>' }},
  "status": "completed"
}
```

{% /tab %}
{% /tabs %}
### Streaming {% id="streaming" %}

Streaming exposes new event types:

#### New event types {% id="event-types" %}
 - `interaction.created`
 - `interaction.completed`
 - `step.start`
 - `step.delta`
 - `step.stop`

`interaction.status_update` is unchanged. It carries the new `status` (for
example `in_progress` or `requires_action`). Every event names its type in
the `event_type` field of the JSON payload, matching the SSE `event:` line.

#### Deprecated event types {% id="deprecated-event-types" %}

The following legacy event types are replaced by the new events listed above:

 - `interaction.start` → `interaction.created`
 - `content.start` → `step.start`
 - `content.delta` → `step.delta`
 - `content.stop` → `step.stop`
 - `interaction.complete` → `interaction.completed`

**Streaming function calls**: When you use streaming with function calling,
the `step.start` event delivers the function name, and `step.delta` events
stream the arguments as partial JSON strings (using `arguments_delta`). You
must accumulate these deltas to get the full arguments. This differs from
unary calls where you receive the complete function call object at once.

#### Examples {% id="streaming-examples" %}

##### Before (Legacy)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Legacy streaming used content.delta
stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain quantum entanglement in simple terms.",
    stream=True,
)

for chunk in stream:
    if chunk.event_type == "content.delta":
        if chunk.delta.type == "text":
            print(chunk.delta.text, end="", flush=True)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
// Legacy streaming used content.delta
const stream = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Explain quantum entanglement in simple terms.',
    stream: true,
});

for await (const chunk of stream) {
    if (chunk.event_type === 'content.delta') {
        if (chunk.delta.type === 'text') {
            process.stdout.write(chunk.delta.text);
        }
    }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain quantum entanglement in simple terms.",
    "stream": true
  }'
```

```none
// Response (SSE Lines)
// event: interaction.start
// data: {"id": "int_123", "status": "in_progress"}
//
// event: content.start
// data: {"index": 0, "type": "text"}
//
// event: content.delta
// data: {"delta": {"type": "text", "text": "Quantum entanglement is..."}}
//
// event: content.stop
// data: {"index": 0}
//
// event: interaction.complete
// data: {"id": "int_123", "status": "done", "usage": {"total_tokens": 42}}
```

{% /tab %}
{% /tabs %}
##### After (New Schema)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
# Consuming stream and handling new event types
for event in client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a story.",
    stream=True,
):
    if event.event_type == "step.delta":  # CHANGED: step.delta instead of content.delta
        if event.delta.type == "text":
            print(event.delta.text, end="")
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
// Consuming stream and handling new event types
const stream = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Tell me a story.',
    stream: true,
});

for await (const event of stream) {
    if (event.event_type === 'step.delta') {  // CHANGED: step.delta instead of content.delta
        if (event.delta.type === 'text') {
            process.stdout.write(event.delta.text);
        }
    }
}
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

 ```bash
 {{ '**' }}# Opt-in needed before May 26th{{ '**' }}
 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
   -H "Content-Type: application/json" \
   -H "Accept: text/event-stream" \
   {{ '**' }}-H "Api-Revision: 2026-05-20" \{{ '**' }}
   -d '{
     "model": "gemini-3.8-flash",
     "input": "Tell me a story.",
     "stream": true
   }'
 ```

 ```none
 // Response (SSE Lines)
 // event: interaction.created
 // data: {"interaction": {"id": "int_xyz", "status": "in_progress", "object": "interaction", "model": "gemini-3.8-flash"}, "event_type": "interaction.created"}
 //
 // event: interaction.status_update
 // data: {"interaction_id": "int_xyz", "status": "in_progress", "event_type": "interaction.status_update"}
 //
 // event: step.start
 // data: {"index": 0, "step": {"type": "thought", "signature": "abc123..."}, "event_type": "step.start"}
 //
 // event: step.stop
 // data: {"index": 0, "event_type": "step.stop"}
 //
 // event: step.start
 // data: {"index": 1, "step": {"content": [{"text": "Once upon", "type": "text"}], "type": "model_output"}, "event_type": "step.start"}
 //
 // event: step.delta
 // data: {"index": 1, "delta": {"text": " a time...", "type": "text"}, "event_type": "step.delta"}
 //
 // event: step.stop
 // data: {"index": 1, "event_type": "step.stop"}
 //
 // event: interaction.completed
 // data: {"interaction": {"id": "int_xyz", "status": "completed", "usage": {"total_input_tokens": 10, "total_output_tokens": 5, "total_tokens": 15}}, "event_type": "interaction.completed"} // NEW: Dedicated completion event
 ```

{% /tab %}
{% /tabs %}
### Stateless Conversation History {% id="stateless-history" %}

If you manage conversation history manually on the client side (stateless use
case), you must update how you string along previous turns.

- **Legacy**: Developers often collected the `outputs` array from responses and sent them back in the `input` field on the next turn.
- **New schema**: You should now collect the `steps` array from the response and pass it in the `input` field of the next request, appending your new user turn as a `user_input` step.

## Output format configuration: `response_format` changes {% id="output-format-config" %}

The updated API consolidates all output format controls into a unified,
polymorphic `response_format` field. This centralizes output configuration at
the top level and keeps `generation_config` focused on model behavior (like
temperature, top_p, and thinking).

### Key changes {% id="response-format-changes" %}

- **The API removes `response_mime_type`.** You now specify the MIME type
    per format entry inside `response_format`.
- **`response_format` is now a polymorphic object (or array).** Each
    entry has a `type` discriminator (`text`, `audio`, `image`) and
    type-specific fields. To request multiple output modalities, pass an
    array of format entries.
- **`image_config` moves from `generation_config` to `response_format`.**
    You now specify image output settings like `aspect_ratio` and `image_size`
    in a `response_format` entry with `"type": "image"`.

### Structured output (JSON) {% id="structured-output" %}

The new schema removes the `response_mime_type` field. Instead, specify the
MIME type and JSON schema inside a `response_format` object with
`"type": "text"`.

#### Before (legacy)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Summarize this article.",
    response_mime_type="application/json",
    response_format={
        "type": "object",
        "properties": {
            "summary": {"type": "string"}
        }
    },
)

print(interaction.outputs[-1].text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Summarize this article.',
    response_mime_type: 'application/json',
    response_format: {
        type: 'object',
        properties: {
            summary: { type: 'string' }
        }
    },
});

console.log(interaction.outputs[-1].text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Summarize this article.",
    "response_mime_type": "application/json",
    "response_format": {
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      }
    }
  }'
```

{% /tab %}
{% /tabs %}
#### After (new schema)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Summarize this article.",
    # response_mime_type is removed -- specify mime_type inside response_format
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "type": "object",
            "properties": {
                "summary": {"type": "string"}
            }
        }
    },
)

# Print response
print(interaction.output_text)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Summarize this article.',
    // response_mime_type is removed -- specify mime_type inside response_format
    response_format: {
        type: 'text',
        mime_type: 'application/json',
        schema: {
            type: 'object',
            properties: {
                summary: { type: 'string' }
            }
        }
    },
});

// Print response
console.log(interaction.output_text);
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  {{ '**' }}-H "Api-Revision: 2026-05-20" \{{ '**' }}
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Summarize this article.",
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" }
        }
      }
    }
  }'
```

{% /tab %}
{% /tabs %}
### Image configuration {% id="image-config" %}

The new schema removes `image_config` from `generation_config`. You now specify
image output settings in a `response_format` entry with `"type": "image"`.

#### Before (legacy)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Generate an image of a sunset over the ocean.",
    generation_config={
        "image_config": {
            "aspect_ratio": "1:1",
            "image_size": "1K"
        }
    },
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Generate an image of a sunset over the ocean.',
    generation_config: {
        image_config: {
            aspect_ratio: '1:1',
            image_size: '1K'
        }
    },
});
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Generate an image of a sunset over the ocean.",
    "generation_config": {
      "image_config": {
        "aspect_ratio": "1:1",
        "image_size": "1K"
      }
    }
  }'
```

{% /tab %}
{% /tabs %}
#### After (new schema)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Generate an image of a sunset over the ocean.",
    # image_config is removed from generation_config -- use response_format
    response_format={
        "type": "image",
        "mime_type": "image/jpeg",
        "aspect_ratio": "1:1",
        "image_size": "1K"
    },
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Generate an image of a sunset over the ocean.',
    // image_config is removed from generation_config -- use response_format
    response_format: {
        type: 'image',
        mime_type: 'image/jpeg',
        aspect_ratio: '1:1',
        image_size: '1K'
    },
});
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  {{ '**' }}-H "Api-Revision: 2026-05-20" \{{ '**' }}
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Generate an image of a sunset over the ocean.",
    "response_format": {
      "type": "image",
      "mime_type": "image/jpeg",
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }'
```

{% /tab %}
{% /tabs %}
### Audio configuration {% id="audio-config" %}

The new schema replaces `response_modalities: ["audio"]` with a `response_format` entry of `"type": "audio"`.

#### Before (legacy)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
interaction = client.interactions.create(
    model="gemini-3.1-flash-tts-preview",
    input="Say cheerfully: Have a wonderful day!",
    response_modalities=["audio"],
    generation_config={
        "speech_config": [
            {"voice": "Kore"}
        ]
    }
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const interaction = await client.interactions.create({
    model: 'gemini-3.1-flash-tts-preview',
    input: 'Say cheerfully: Have a wonderful day!',
    response_modalities: ['audio'],
    generation_config: {
        speech_config: [
            { voice: 'Kore' }
        ]
    },
});
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-tts-preview",
    "input": "Say cheerfully: Have a wonderful day!",
    "response_modalities": ["audio"],
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'
```

{% /tab %}
{% /tabs %}
#### After (new schema)

{% tabs %}
{% tab label="Python" filename="sample.py" %}

```python
interaction = client.interactions.create(
    model="gemini-3.1-flash-tts-preview",
    input="Say cheerfully: Have a wonderful day!",
    # response_modalities is removed -- use response_format
    response_format={
        "type": "audio"
    },
    generation_config={
        "speech_config": [
            {"voice": "Kore"}
        ]
    }
)
```

{% /tab %}
{% tab label="JavaScript" filename="sample.js" %}

```javascript
const interaction = await client.interactions.create({
    model: 'gemini-3.1-flash-tts-preview',
    input: 'Say cheerfully: Have a wonderful day!',
    // response_modalities is removed -- use response_format
    response_format: {
        type: 'audio'
    },
    generation_config: {
        speech_config: [
            { voice: 'Kore' }
        ]
    },
});
```

{% /tab %}
{% tab label="REST" filename="sample.sh" %}

```bash
# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.1-flash-tts-preview",
    "input": "Say cheerfully: Have a wonderful day!",
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'
```

To request multiple output modalities (for example, text and audio together),
pass an array of format entries to `response_format` instead of a single
object.

{% /tab %}
{% /tabs %}
## How to migrate to the new schema {% id="how-to-migrate" %}

### SDK users {% id="sdk-users" %}

Upgrade to the latest SDK version (Python ≥2.0.0, JavaScript ≥2.0.0). The
SDK automatically opts you into the new schema — no code changes needed beyond
updating how you read responses (see examples above). Note that only the new
schema is supported in these SDK versions. Older SDK versions
(Python 1.x.x, JavaScript 1.x.x) will continue to work until the legacy
schema is removed on **June 8, 2026**.

### REST API users {% id="raw-api-users" %}

Add the `Api-Revision: 2026-05-20` header to your requests to opt in to
the new schema now. After **May 26**, the new schema becomes the default for all
requests. You can temporarily opt out with `Api-Revision: 2026-05-07`
until **June 8**, when the API permanently removes the legacy schema.

### Timeline {% id="timeline" %}

| Date | Phase | SDK users | REST API users |
|---|---|---|---|
| **May 7** | Opt-in | New SDK version available (Python ≥2.0.0, JS ≥2.0.0). Upgrade to get the new schema automatically. | Add `Api-Revision: 2026-05-20` header to opt in. Default remains legacy. |
| **May 26** | Default flip | No action needed if already upgraded. Older SDKs (Python 1.x.x, JS 1.x.x) still work but return legacy responses. | New schema is now the default. Send `Api-Revision: 2026-05-07` header to opt out. |
| **June 8** | Sunset | Python 1.x.x and JS 1.x.x SDK versions will break for Interactions API calls. | Legacy schema removed for Interactions API. `Api-Revision` header ignored. |

{% callout type="note" %}
**Note**: New features shipped after May 7 will only
  appear in `steps` responses. Users on the legacy `outputs`
  schema will not receive new capabilities until they migrate.
{% /callout %}

## Migration Checklist {% id="migration-checklist" %}

### Steps schema (`steps`)

- Update code to read response content from the `steps` array instead of `outputs`. [See examples](/docs/interactions-breaking-changes-may-2026#basic-unary).
- Verify that your code handles both `user_input` and `model_output` step types. [See examples](/docs/interactions-breaking-changes-may-2026#basic-unary).
- (Function Calling) Update code to find `function_call` steps in the `steps` array. [See examples](/docs/interactions-breaking-changes-may-2026#function-calling).
- (Server-Side Tools) Update code to handle tool-specific steps (e.g., `google_search_call`, `google_search_result`). [See examples](/docs/interactions-breaking-changes-may-2026#server-side-tools).
- (Stateless History) Update history management to pass the `steps` array in the `input` field of the next request. [See details](/docs/interactions-breaking-changes-may-2026#stateless-history).
- (Streaming only) Update client to listen for new SSE event types (`interaction.created`, `step.delta`, etc.). [See examples](/docs/interactions-breaking-changes-may-2026#streaming).

### Output format configuration (`response_format`)

- Replace `response_mime_type` with a `mime_type` field inside `response_format`. [See examples](/docs/interactions-breaking-changes-may-2026#structured-output).
- Wrap your existing `response_format` JSON schema inside a `{"type": "text", "schema": ...}` object. [See examples](/docs/interactions-breaking-changes-may-2026#structured-output).
- (Image Generation) Move `image_config` from `generation_config` to a `{"type": "image", ...}` entry in `response_format`. [See examples](/docs/interactions-breaking-changes-may-2026#image-config).
- (Speech Generation) Replace `response_modalities=["audio"]` with a `{"type": "audio"}` entry in `response_format`. [See examples](/docs/interactions-breaking-changes-may-2026#audio-config).
- (Multimodal) Convert `response_format` from a single object to an array when requesting multiple output modalities.

# Rate limits
Source: https://aistudio.google.com/docs/rate-limits
Description: Understand request quotas, token limits, and rate limits for the Gemini API.

Rate limits regulate the number of requests you can make to the Gemini API
within a given timeframe. These limits help maintain fair usage, protect against
abuse, and help maintain system performance for all users.

{% button href="https://aistudio.google.com/rate-limit?timeRange=last-28-days" variant="primary" %}View your active rate limits in AI Studio{% /button %}

## How rate limits work {% id="how-rate-limits-work" %}

Rate limits are usually measured across three dimensions:

* Requests per minute (**RPM**)
* Tokens per minute (input) (**TPM**)
* Requests per day (**RPD**)

Your usage is evaluated against each limit, and exceeding any of them will
trigger a rate limit error. For example, if your RPM limit is 20, making 21
requests within a minute will result in an error, even if you haven't exceeded
your TPM or other limits.

Rate limits are applied per project, not per API key. Requests per day (**RPD**)
quotas reset at midnight Pacific time.

Limits vary depending on the specific model being used, and some limits only
apply to specific models. For example, Images per minute, or IPM, is only
calculated for models capable of generating images (Nano Banana), but is
conceptually similar to TPM. Other models might have a token per day limit
(TPD). Built-in tools also have specific rate limits. For example, Grounding
with Google Search on Gemini 3 and newer models is subject to a default limit of
1,500 requests per day (RPD) per project on the Gemini Developer API (see
[Grounding with Google Search](/docs/google-search#pricing)).

Rate limits are more restricted for experimental and preview models.

### Spend-based rate limits {% id="spend-rate-limits" %}

In addition to requests per minute (RPM) and tokens per minute (TPM) limits, the
Gemini API enforces spend-based rate limits to protect against unexpected
charges. Whether these limits apply to your account depends on your billing
history and [usage tier](/docs/rate-limits#usage-tiers).

The following table shows the spend-based rate limits for each
[usage tier](/docs/rate-limits#usage-tiers). These limits are evaluated on a rolling 10-minute
window. Whether these limits apply to your account depends on your billing
history and account standing.

| Usage tier | Spend rate limit (per 10 minutes) |
| :--- | :--- |
| **Free** | N/A |
| **Tier 1** | $10 |
| **Tier 2** | $200 |
| **Tier 3** | $200 |

If you hit a spend-based rate limit, the API returns a `429 RESOURCE_EXHAUSTED`
error. To resolve this:

* Wait and retry after a short period.
* Reduce the rate of expensive requests, for example by using smaller context
  windows or shorter outputs.
* If you consistently hit this limit during normal usage,
  [request a rate limit increase](/docs/rate-limits#request-rate-limit-increase).

## Usage tiers {% id="usage-tiers" %}

Rate limits are tied to the project's usage tier. As your API usage and spending
increase, you'll be automatically upgraded to a higher tier with increased rate
limits.

The qualifications for Tiers 2 and 3 are based on the total cumulative spending
on Google Cloud services (including, but not limited to, the Gemini API) for the
billing account linked to your project.

| Usage tier | Qualification | [Billing tier cap](/docs/billing#tier-spend-caps) |
| :--- | :--- | :--- |
| **Free** | [Active project](/docs/api-key#google-cloud-projects) or free trial | N/A |
| **Tier 1** | [Set up and link an active billing account](/docs/billing#setup-billing) | $250 |
| **Tier 2** | Paid $100 + 3 days from first successful payment | $2,000 |
| **Tier 3** | Paid $1,000 + 30 days from first successful payment | $20,000 - $100,000+ |

While meeting the stated qualification criteria is generally
sufficient for approval, in rare cases an upgrade request may be denied based on
other factors identified during the review process.

This system helps maintain the security and integrity of the Gemini API platform
for all users.

## Gemini API rate limits {% id="current-rate-limits" %}

Rate limits depend on a variety of factors (such as your usage tier) and can be
viewed in Google AI Studio. As your tier and account status change over time,
your rate limits will automatically update.

{% button href="https://aistudio.google.com/rate-limit?timeRange=last-28-days" variant="primary" %}View your active rate limits in AI Studio{% /button %}

Specified rate limits are not guaranteed and actual capacity may vary.

## Priority inference rate limits {% id="priority" %}

[Priority](/docs/priority-inference) consumption holds its own rate
limits even though consumption is counted towards overall interactive traffic
rate limits. **Default rate limits are: 0.3x the [standard rate limit](https://aistudio.google.com/rate-limit) for each model and tier**

## Batch API rate limits {% id="batch-api" %}

[Batch API](/docs/batch-api) requests are subject to their own rate
limits, separate from the non-batch API calls.

* **Concurrent batch requests:** 100
* **Input file size limit:** 2GB
* **File storage limit:** 20GB
* **Enqueued tokens per model:** The **Batch enqueued tokens** table lists the
    maximum number of tokens that can be enqueued for batch processing across
    all your active batch jobs for a given model.

{% tabs %}
{% tab title="Tier 1" %}
{% table %}
* Model
* Batch enqueued tokens
---
---

* Gemini 4 Argon
* 5,000,000
---

* Gemini 3.1 Pro Preview
* 5,000,000
---

* Gemini 3.8 Flash
* 3,000,000
---

* Gemini 3.6 Flash
* 3,000,000
---

* Gemini 3.5 Flash-Lite
* 10,000,000
---

* Gemini 3.1 Flash Lite
* 10,000,000
---

* Gemini 3.1 Flash Lite Preview
* 10,000,000
---

* Gemini 2.5 Pro
* 5,000,000
---

* Gemini 2.5 Pro TTS
* 25,000
---

* Gemini 2.5 Flash
* 3,000,000
---

* Gemini 2.5 Flash Preview
* 3,000,000
---

* Gemini 2.5 Flash Image Preview
* 3,000,000
---

* Gemini 2.5 Flash TTS
* 100,000
---

* Gemini 2.5 Flash Lite
* 10,000,000
---

* Gemini 2.5 Flash Lite Preview
* 10,000,000
---

* Gemini 2.0 Flash
* 10,000,000
---

* Gemini 2.0 Flash Image
* 3,000,000
---

* Gemini 2.0 Flash Lite
* 10,000,000
---
---

* Gemini 3.1 Flash Image Preview 🍌
* 1,000,000
---

* Gemini 3.1 Flash Lite Image 🍌
* 2,000,000
---

* Gemini 3 Pro Image Preview 🍌
* 2,000,000
---
---

* Gemini Embedding
* 500,000
{% /table %}
{% /tab %}
{% tab title="Tier 2" %}
{% table %}
* Model
* Batch enqueued tokens
---
---

* Gemini 4 Argon
* 500,000,000
---

* Gemini 3.1 Pro Preview
* 500,000,000
---

* Gemini 3.5 Flash-Lite
* 500,000,000
---

* Gemini 3.1 Flash Lite
* 500,000,000
---

* Gemini 3.1 Flash Lite Preview
* 500,000,000
---

* Gemini 3.8 Flash
* 400,000,000
---

* Gemini 3.6 Flash
* 400,000,000
---

* Gemini 2.5 Pro
* 500,000,000
---

* Gemini 2.5 Pro TTS
* 100,000
---

* Gemini 2.5 Flash
* 400,000,000
---

* Gemini 2.5 Flash Preview
* 400,000,000
---

* Gemini 2.5 Flash Image Preview
* 400,000,000
---

* Gemini 2.5 Flash TTS
* 100,000
---

* Gemini 2.5 Flash Lite
* 500,000,000
---

* Gemini 2.5 Flash Lite Preview
* 500,000,000
---

* Gemini 2.0 Flash
* 1,000,000,000
---

* Gemini 2.0 Flash Image
* 400,000,000
---

* Gemini 2.0 Flash Lite
* 1,000,000,000
---
---

* Gemini 3.1 Flash Image Preview 🍌
* 250,000,000
---

* Gemini 3.1 Flash Lite Image 🍌
* 270,000,000
---

* Gemini 3 Pro Image Preview 🍌
* 270,000,000
---
---

* Gemini Embedding
* 5,000,000
{% /table %}
{% /tab %}
{% tab title="Tier 3" %}
{% table %}
* Model
* Batch enqueued tokens
---
---

* Gemini 4 Argon
* 1,000,000,000
---

* Gemini 3.1 Pro Preview
* 1,000,000,000
---

* Gemini 3.5 Flash-Lite
* 1,000,000,000
---

* Gemini 3.1 Flash Lite
* 1,000,000,000
---

* Gemini 3.1 Flash Lite Preview
* 1,000,000,000
---

* Gemini 3.8 Flash
* 1,000,000,000
---

* Gemini 3.6 Flash
* 1,000,000,000
---

* Gemini 2.5 Pro
* 1,000,000,000
---

* Gemini 2.5 Pro TTS
* 1,000,000
---

* Gemini 2.5 Flash
* 1,000,000,000
---

* Gemini 2.5 Flash Preview
* 1,000,000,000
---

* Gemini 2.5 Flash Image Preview
* 1,000,000,000
---

* Gemini 2.5 Flash TTS
* 4,000,000
---

* Gemini 2.5 Flash Lite
* 1,000,000,000
---

* Gemini 2.5 Flash Lite Preview
* 1,000,000,000
---

* Gemini 2.0 Flash
* 5,000,000,000
---

* Gemini 2.0 Flash Image
* 1,000,000,000
---

* Gemini 2.0 Flash Lite
* 5,000,000,000
---
---

* Gemini 3.1 Flash Image Preview 🍌
* 750,000,000
---

* Gemini 3.1 Flash Lite Image 🍌
* 1,000,000,000
---

* Gemini 3 Pro Image Preview 🍌
* 1,000,000,000
---
---

* Gemini Embedding
* 10,000,000
{% /table %}
{% /tab %}
{% /tabs %}

## How to upgrade to the next tier {% id="how-to-upgrade-to-the-next-tier" %}

To transition from the Free tier to a paid tier, you must first
[set up billing in AI Studio](/docs/billing).

Once your project meets the [specified criteria](/docs/rate-limits#usage-tiers), it will be
automatically upgraded to the next tier. Tier upgrades from the Free to Tier 1
will typically take effect instantly, and subsequent tier upgrades will take
effect within 10 minutes. Navigate to the [Projects page](https://aistudio.google.com/projects) in AI Studio to check your tiers.

## Request a rate limit increase {% id="request-rate-limit-increase" %}

Each model variation has an associated rate limit (requests per minute, RPM).
For details on those rate limits, see the
[AI Studio Rate Limit](https://aistudio.google.com/rate-limit) page.

{% button href="https://forms.gle/ETzX94k8jf7iSotH9" variant="primary" %}Request paid tier rate limit increase{% /button %}

We offer no guarantees about increasing your rate limit, but we'll do our best
to review your request.

# Billing
Source: https://aistudio.google.com/docs/billing
Description: Understand Gemini API billing tiers, pricing structures, and usage charges.

This guide provides an overview of different Gemini API billing options,
explains how to enable billing and monitor usage, and provides answers to
frequently asked questions (FAQs) about billing.

## About billing and tiers {% id="about-billing" %}

Billing for the Gemini API is based on your payment history.

| Usage tier | Qualification | [Billing tier cap](/docs/billing#spend-caps) |
| :--- | :--- | :--- |
| **Free** | [Active project](/docs/api-key#google-cloud-projects) or free trial | N/A |
| **Tier 1** | [Set up and link an active billing account](/docs/billing#setup-billing) | $250 |
| **Tier 2** | Paid $100 + 3 days from first successful payment | $2,000 |
| **Tier 3** | Paid $1,000 + 30 days from first successful payment | $20,000 - $100,000+ |

New accounts begin on the Free Tier, which allows access to
[certain models](/docs/pricing) in the Gemini API and AI Studio,
up to the models' free tier [rate limits](https://aistudio.google.com/rate-limit).

To deploy your applications directly from Build mode, eligible accounts can use
the **Google Cloud Starter Tier**. This tier lets you publish up to 2 full-stack
applications without setting up a Google Cloud project or billing account.
See [Deploying from Google AI Studio](/docs/aistudio-deploying#starter-tier-eligibility) for
eligibility details and refer to the [Google Cloud Starter Tier documentation](https://docs.cloud.google.com/docs/starter-tier) for more information.

To access higher rate limits, use advanced models, and ensure your prompts and
responses are **not** used to improve Google products{% sup %}*{% /sup %},
you can
[link a billing account](/docs/billing#setup-billing) and [Prepay](/docs/billing#prepay) to move to the
Paid Tiers.
Then, you'll move through higher tiers based on cumulative spend and account
age.

Tiers, rate limits, and billing account caps are all determined at the [billing
account](/docs/billing#cloud-billing) level.

{% sup %}*{% /sup %} *Enterprise-grade data privacy: For more information on
data use
for paid services, see the [Terms of Service](/docs/terms#data-use-paid).*

## Set up billing to access the Paid Tier {% id="setup-billing" %}

You can create a project and set up billing, or import an existing project, to
upgrade to the Paid Tier in [Google AI Studio](https://aistudio.google.com/projects).
Upgrading from the Free Tier to the Paid Tier means linking a billing account
and [prepaying](/docs/billing#prepay) to add a minimum of $5 (or equivalent in other
currencies) of credits to your account.

1. Go to the AI Studio [API keys](https://aistudio.google.com/api-keys) page,
   [Projects](https://aistudio.google.com/projects) page, or anywhere you see
   **Set up billing** button in AI Studio.

   * New users will have a [project and API key](/docs/api-key#google-cloud-projects) created for them by default.

   * If you need a new key, click [**Create API key**](https://aistudio.google.com/api-keys)
     and follow the dialog to add a key-project pair to the table.

1. Find the Free Tier project you want to upgrade to the Paid Tier, and click
   **Set up billing** under the *Billing Tier* column.

1. If you've never set up a Google billing account before:
   * You'll be asked to select your country to agree to the Terms of Service.
   * Then, fill in or confirm your contact information and payment method to continue.
1. If you have set up Google billing accounts in the past:
   * You'll be asked to choose from your existing billing accounts.
   * If you don't want to use any of your existing accounts, click **Add new
     billing account** and fill in or confirm your contact information and
     payment method to continue.

1. Next, you will either be:
   * Asked to prepay a minimum of $5 to complete billing
     setup (meaning your account is auto-assigned to the [Prepay](/docs/billing#prepay)
     billing plan),

   * Given the choice between [Prepay](/docs/billing#prepay) and [Postpay](/docs/billing#postpay)
     billing plans for your account.

   * Assigned to a [Postpay](/docs/billing#postpay) billing plan for an intermediary period
     until the new Prepay system propagates to all users (starting March 23,
     2026).

1. After prepaying or selecting Postpay, your account setup is complete.

### Upgrade to the next paid tier {% id="request-an-upgrade" %}

If you're already on a paid tier and meet the [criteria](/docs/billing#about-billing)
for a plan change, you will be automatically upgraded to the next tier
(subject to [processing times](/docs/billing#processing-times)).

## Verify billing status {% id="verify-billing" %}

After you have [linked a billing account](/docs/billing#setup-billing) to your project, you
can monitor its status on the
[AI Studio Billing page](https://aistudio.google.com/billing). Unlike the free
tier, paid tier status is dynamic; while your usage tier is determined by your
account history, the Gemini API will only serve requests if you have a
positive [Prepay](/docs/billing#prepay) credit balance.

On the [Projects](https://aistudio.google.com/projects) page, you'll be able to
see your project's tier and billing plan under the *Billing Tier* column. Any
billing status actions you may need to take for a project display in the
*Billing Tier* or *Status* columns:

* "***Set up billing***" if the project doesn't have a billing account attached.
* "***Set up Prepay***" if the project does have a billing account attached, but
  is required to use a [Prepay](/docs/billing#prepay) billing plan that needs to be set up.

* "***No credits***" if the billing account is required to purchase
  credits but the Prepay payments account isn't set up or the available credit
  balance is depleted.

Click any of the messages to proceed with the necessary actions.

## Monitor usage {% id="monitor-usage" %}

You can monitor your usage of the Gemini API in
[Google AI Studio](https://aistudio.google.com/usage) in **Dashboard** >
**Usage**.

## Billing plans {% id="billing-plans" %}

Billing plans for the Gemini API and AI Studio fall into two categories that
determine when you pay for usage: Prepay and Postpay. You can check your
assigned billing plan and manage payment methods on the
[AI Studio Billing](https://aistudio.google.com/billing) page.

Important: Prepay and Postpay billing plans start taking effect
**March 23, 2026**.

*  Accounts that predate the introduction of Prepay and Postpay billing plans
   will be evaluated and assigned a plan or offered the choice between plans.

*  Accounts created after the effective date might not be immediately affected;
   you may be assigned a Postpay account initially, and be switched to Prepay
   once the new billing plan system is fully released. See
   [Migrate to prepay](/docs/billing#migrate-to-prepay) for details.

*  If you have a prepay billing account, you must add funds to your account
   before you can use promotional Cloud Credits. After adding funds, your
   promotional credits will be consumed first before your prepaid funds.

### Prepay {% id="prepay" %}

In the Prepay billing plan, you purchase credits towards your prepay balance in
advance of your Gemini API usage, and your API usage costs are deducted from
your Prepay credit balance in [near real-time](/docs/billing#processing-times).
You can prepay by [adding credits](/docs/billing#buy-credits) into your account, or setting
up [auto-reload](/docs/billing#auto-reload). After credits are purchased, unused credits
expire after 12 months and are [non-refundable](/docs/billing#refunds), except after
[switching to a Postpay account](/docs/billing#postpay).

When your Prepay credit balance on the billing account hits $0, all API keys in
all projects linked to that billing account will stop working simultaneously.
Requests then fail with an [HTTP 402 Payment
Required](/docs/api-errors) error until you add credits.
Prepay credits apply only to Gemini API usage costs; you can't use
them to pay for other Google Cloud services.

{% callout type="note" %}
Note: Prepay billing is subject to overages during the approximately 10 minute
billing pipeline latency. Long-running tasks like
[batch mode](/docs/batch-api) and agents may continue to consume
credits beyond your balance before the system can process and halt usage.
{% /callout %}

New users default to the Prepay billing plan. Projects that pre-date the
introduction of Prepay and Postpay billing plans may need to [update their
project's billing details](/docs/billing#verify-billing) before continuing to use the Gemini
API.

*Note that Prepay is not available for [Invoiced (or Offline)](https://docs.cloud.google.com/billing/docs/concepts#billing_account_types)
accounts.*

#### Add Prepay to an existing Postpay account {% id="adding-prepay-to-postpay" %}

If your existing Cloud Billing account uses a **Postpay** plan, you can add **Prepay**
capabilities to purchase credits in advance. These prepay credits let you use
the Gemini API without creating a new Cloud Billing account.

During the setup to add **Prepay** to an existing account, you are
presented with a mandatory confirmation screen explaining that your selected
Cloud Billing account will be modified.

The system must modify your account state *before* you submit your prepayment.
Therefore, canceling the process after confirming the modification but before
completing the prepayment setup might result in temporary service disruptions
for projects already linked to that Cloud Billing account. Ensure you are ready
to complete the prepayment process before confirming the transition. If you
encounter issues, see [Services disrupted after canceling a **Prepay**
setup](https://docs.cloud.google.com/billing/docs/in-product-billing-setup#prepay-issue).

If you are eligible and manually switch from a **Prepay** cycle to a **Postpay**
cycle, any remaining prepay credit balance is automatically refunded to the
original payment method used for the prepayment. However, if you close your
Cloud Billing account for any other reason, any remaining prepay
credits are forfeited and aren't refunded.

#### Buy credits {% id="buy-credits" %}

You can manually purchase credits in advance of your Gemini API usage to load
them into your Prepay account credit balance.

To purchase credits, go to the [AI Studio Billing](https://aistudio.google.com/billing) page and select **Buy credits**.
The minimum purchase is $5. The maximum amount of credits you can prepay for is
$5,000.

{% callout type="note" %}
Note: Prepay users must [purchase Prepaid credits](/docs/billing#buy-credits) before they can
use any Google Cloud credits that are eligible for the Gemini API. Once you have
an active Prepay credit balance, eligible Google Cloud credits are consumed
before your Prepay credit balance. When your Prepay credit balance on the
billing account hits $0, Google Cloud credits will no longer be consumed.
{% /callout %}

#### Auto reload {% id="auto-reload" %}

Auto-reload is an optional feature that automatically tops up your Prepay credit
balance when it's running low. This is useful to prevent service interruptions.

You can set up auto reload and see your auto-reload status in the *Available
credits* card on the [AI Studio Billing](https://aistudio.google.com/billing)
page. Click **Setup auto-reload** or
**Manage auto-reload** to set your payment method, reload amount, and the
minimum balance that triggers a reload payment.

#### Monthly auto-charge limit {% id="monthly-auto-charge-limit" %}

The monthly auto-charge limit is available to Prepay users
and helps prevent unexpected costs from frequent automatic credit reloads.
Use this feature to set a maximum limit for automatic credit reloads within
a single billing cycle. Once the total amount of automatic reloads in a billing
cycle reaches this limit, the system disables auto-reload until the start of the
next month. One-time payments you initiate manually don't count against this
limit.

To set the monthly auto-charge limit when auto-reload is enabled:

1. Go to the [AI Studio Billing](https://aistudio.google.com/billing) page.
1. Click **Manage auto-reload**.
1. Expand the **Monthly Limit** section and enter the maximum monthly limit for auto-reloads.
1. Click **Save**.

### Postpay {% id="postpay" %}

In the Postpay billing plan, your Cloud Billing account accrues costs and you
are automatically charged at the end of the month, or when your costs reach an
[automatically assigned spend cap](/docs/billing#tier-spend-caps) based on your account tier.
The payment is charged to the payment method attached to your Postpay payments
account, which you can manage on the [AI Studio Billing](https://aistudio.google.com/billing) page.
On the **Billing** page you'll be able to view your balance, due dates,
and past payments, as well as make payments and manage payment methods.

When [setting up billing](/docs/billing#setup-billing) for a new project, if you are eligible
for Postpay, you will have the option to choose between Prepay and Postpay in
the [billing setup](/docs/billing#setup-billing) dialogue.

After you switch a Cloud Billing account to use the Postpay billing plan, all
projects linked to that billing account are switched to the Postpay plan. You
can move an eligible account to Prepay by following the steps in [Migrate to prepay](/docs/billing#migrate-to-prepay). You can also
move a project to a billing account with a different billing plan to change
the charging cycle for that project; visit the Cloud documentation on [managing
billing for projects](https://docs.cloud.google.com/billing/docs/how-to/modify-project).

You can learn more about the Postpay charging cycle in the [Cloud Billing guide](https://docs.cloud.google.com/billing/docs/how-to/billing-cycle).

### Migrate to prepay {% id="migrate-to-prepay" %}

Google AI Studio is transitioning developer accounts from Postpay to Prepay billing for Gemini API usage. This change applies only to the Gemini API; other Google Cloud services linked to your billing account remain on Postpay.

Switch to Prepay and add credits before the cutover date in your account notice to avoid service interruptions. Accounts that use only Free Tier features do not need to take action.

To switch an existing Postpay account to Prepay:

1. Go to the [AI Studio Billing](https://aistudio.google.com/billing) page.

1. Select **Switch to Prepay** for your billing account.

1. [Purchase credits](/docs/billing#buy-credits) (minimum $5) to load your starting balance.

To prevent service interruptions after switching, configure [auto-reload](/docs/billing#auto-reload) to top up your credit balance when it runs low.

## Spend caps {% id="spend-caps" %}

The Gemini API supports monthly spend caps at both the billing account tier and
project levels. These controls are designed to protect your account from
unexpected overages, and the ecosystem to ensure service availability.

*Note that spend caps are not available for [Invoiced (or Offline)](https://docs.cloud.google.com/billing/docs/concepts#billing_account_types)
accounts.*

### Project spend caps {% id="project-spend-caps" %}

Experimental: The feature is experimental and limited in scope. You are subject
to overages for around a 10 minute latency period.

You can set your own [project-level](/docs/api-key#google-cloud-projects) spend caps in AI Studio.
This is useful if you have multiple projects under the same billing
account and want to ensure each has access to enough of the cumulative spending
limit.

Accounts with the project editor, owner, or admin [roles](https://docs.cloud.google.com/iam/docs/roles-overview) can set spend caps per
project in AI Studio on the [Spend](https://aistudio.google.com/spend) page
under **Monthly spend cap** > **Edit spend cap**.

For details on the specific Google Cloud IAM permissions required to view or edit spend caps and billing information in AI Studio, see the [AI Studio troubleshooting guide](/docs/troubleshoot-ai-studio#iam-permissions).

If you [move a project to a different billing account](https://docs.cloud.google.com/billing/docs/how-to/modify-project#change_the_billing_account_for_a_project),
any spend cap you already set for that project will persist, but any accumulated
spend will reset to $0 for the new billing cycle.

Long-running tasks like [batch mode](/docs/batch-api) completions and
agent sessions may incur overages beyond your project spend cap.

Billing data processing times can be delayed in AI Studio, up to around 10
minutes. You may experience overages beyond your project cap if billing data
hasn't processed before more charges are accrued.

### Billing account tier spend caps {% id="tier-spend-caps" %}

Each [tier](/docs/billing#about-billing) has a maximum monthly spend limit:

| Usage tier | Spend cap |
| :--- | :--- |
| **Free** | N/A |
| **Tier 1** | $250 |
| **Tier 2** | $2,000 |
| **Tier 3** | $20,000 - $100,000 |

Monthly usage caps are enforced for the Gemini API at the [billing account](/docs/billing#cloud-billing) level. While default limits are preset, you can [request an
increase](https://docs.google.com/forms/d/e/1FAIpQLSdiP6BWJyNNN65lnwnlOr-5Kv0MOFp0jLQyqi_ixVCfddqWBw/viewform)
to accommodate higher usage. Total spend is aggregated across all linked
projects that have the Gemini API service enabled. After the cumulative account
total reaches the tier limit, service is paused for all projects linked to that
billing account until the start of the next billing cycle (the 1st of each
month).

#### Evaluate your billing account spend {% id="evaluate-spend" %}

To evaluate your historical monthly spending to determine if the new [Billing
Account tier spend caps](/docs/billing#tier-spend-caps) will impact your ongoing projects,
follow these steps:

1. In the Google Cloud console, view your [Cloud Billing account Reports](https://console.cloud.google.com/billing/reports) page.

   * If you have more than one billing account, at the prompt, choose the Cloud
     Billing account for which you'd like to view cost reports.

1. The report defaults to "Group by Service" in the "Current month". You will
   see **Gemini API** in the **Service** column and total spend in the **Usage
   cost** column of the table.

1. To see granular costs limited to Gemini API usage, set the **Group by**
   filter to group by **SKU**, and the **Services** filter to **Gemini API**.

1. Adjust the **Time range by usage date** filter to your desired range to
   evaluate your historical spend in a period.

## Processing times {% id="processing-times" %}

Billing signals and updates don't always happen in real time.

* **Credit usage**: Usage costs are typically drawn down from your balance
    within minutes.

* **Payment confirmation**: While most card payments are instant, some forms
    of payment (like bank transfers) may take several days to clear. Services
    only resume or upgrade after the purchase of credits is officially
    confirmed.

* **Tier upgrades**: After a successful payment, or when you meet the
    [upgrade criteria](/docs/billing#about-billing), tier upgrades usually reflect within 10
    minutes.

* **Total Cost breakdown graphs**: The graphs showing your total cost
    breakdown on both the [Billing](https://aistudio.google.com/billing) page
    and the [Spend](https://aistudio.google.com/spend) page can take up to 24
    hours to update.

Read the Cloud Billing guides on [charging cycle](https://docs.cloud.google.com/billing/docs/how-to/billing-cycle#delayed-billing)
and [transaction](https://docs.cloud.google.com/billing/docs/how-to/view-history#missing-transactions)
latencies to learn more about potential billing delays.

## Refunds {% id="refunds" %}

Refunds aren't allowed for **Prepay** billing accounts, except when switching
account types.

**When a Prepay account switches to the Postpay account type** (after you
meet the [criteria](/docs/billing#about-billing) and [manually upgrade](/docs/billing#postpay)
your account), the Prepay account is closed and any remaining prepaid credits
are automatically refunded to the payment method on file.

If you [close](https://docs.cloud.google.com/billing/docs/how-to/close-or-reopen-billing-account#close-a-billing-account)
your Prepay account for any reason other than upgrading to Postpay, any
remaining prepaid credits are forfeited.

Purchased credits expire after 1 year. After expiration, credits are forfeited
and can't be retrieved.

**Postpay** accounts follow the [Google Cloud refund policy](https://docs.cloud.google.com/billing/docs/how-to/resolve-issues#request_a_refund).

## Cloud Billing accounts {% id="cloud-billing" %}

The Gemini API uses [Cloud Billing accounts](https://cloud.google.com/billing/docs/concepts) for billing services, which you
can [set up directly in AI Studio](/docs/billing#setup-billing).
You can use AI Studio to track spending, understand costs, and make payments.

{% callout type="note" %}
Note: New users might be granted a [$300 Welcome credit](https://docs.cloud.google.com/billing/docs/in-product-billing-setup#welcome-credits)
in their new Google Cloud Billing accounts. If you opened your account
**after March 2, 2026**, you can't use these credits to pay for Gemini API and
AI Studio usage, but you can use them on [other Google Cloud products](https://docs.cloud.google.com/free/docs/free-cloud-features) in the
[Google Cloud console](https://console.cloud.google.com/).
{% /callout %}

Tiers, rate limits, and billing account caps are all determined at the billing
account level.

### Projects and API keys {% id="projects-api-keys" %}

All [projects](/docs/api-key#google-cloud-projects) linked to a Cloud
Billing account inherit the billing account's usage tier and associated rate
limits and account caps. If you [change a project](https://docs.cloud.google.com/billing/docs/how-to/modify-project#change_the_billing_account_for_a_project)
from one billing account to another, its tier, and subsequently rate limits and
account caps, will switch to the tier of the new billing account.

Cumulative spend (towards all Google Cloud products) and account age across all
projects tied to a billing account counts towards that billing account's
[tier qualifications](/docs/billing#about-billing).

You can [unlink a project](https://docs.cloud.google.com/billing/docs/how-to/modify-project#disable_billing_for_a_project)
from its billing account to return to the free tier.

[API keys](/docs/api-key) are credentials generated inside a project.
They have no independent billing settings; they inherit the tier limits and
billing status of the project. The cumulative usage from all keys within a
project counts toward that project's spend cap and the billing account's total
spend.

## Frequently asked questions {% id="faq" %}

The following sections provide answers to frequently asked questions.

### What am I billed for? {% class="hide-from-toc" id="what-am-i-billed-for" %}

Gemini API pricing is based on the following:

- Input token count
- Output token count
- Cached token count
- Cached token storage duration

For pricing information, see the [Pricing page](https://ai.google.dev/pricing).

### Where can I view my quota? {% class="hide-from-toc" id="where-can-i-view-my-quota" %}

You can view your quota and system limits in
[AI Studio](https://aistudio.google.com/usage).

### How do I move to a higher rate limit tier, or request more quota? {% class="hide-from-toc" id="how-do-i-request-more-quota" %}

You will automatically be granted more quota when your account reaches the next
[tier requirements](/docs/rate-limits#usage-tiers).

### Can I use the Gemini API for free in EEA (including EU), the UK, and CH? {% class="hide-from-toc" id="is-Gemini-free-in-EEA-UK-CH" %}

Yes, we make the free tier and paid tier available in [many regions](/docs/available-regions).

### If I set up billing with the Gemini API, will I be charged for my Google AI Studio usage? {% class="hide-from-toc" id="is-AI-Studio-free" %}

AI Studio usage remains free of charge unless users link a paid API key for
access to paid features.
Once you link a paid API key as part of a paid project in AI Studio, you will be
charged for AI Studio usage for that key. You can switch between Paid Tier
projects and Free Tier projects as needed by using the respective API keys
linked to each type.

### If I'm on the Free Tier, how do I upgrade to higher tiers? {% class="hide-from-toc" id="how-do-i-upgrade" %}

To access higher tiers, you must set up billing on your project. Click [**Set up
billing**](/docs/billing#setup-billing) in Google AI Studio. This will walk you through
selecting or creating a Cloud Billing account. If you are required to be on the
prepaid billing model, the **Set up billing** process will guide you through the
process to create your Prepay account that is linked to your Cloud Billing
account.

### Can I use 1M tokens in the free tier? {% class="hide-from-toc" id="can-i-use-1m-tokens-for-free" %}

The free tier for Gemini API differs based on the model selected. For now, you
can try the 1M token context window in the following ways:

- In Google AI Studio
- With free-of-charge plans for select models
- With postpaid plans

### Can I revert back to Free Tier after I've upgraded to higher (paid) tiers? {% class="hide-from-toc" id="revert-to-free" %}

To downgrade to the Free Tier, you can [disable billing](https://docs.cloud.google.com/billing/docs/how-to/modify-project#disable_billing_for_a_project)
on each of your projects that you want to downgrade.

### How can I calculate the number of tokens I'm using? {% class="hide-from-toc" id="count-tokens" %}

Use the [`GenerativeModel.count_tokens`](https://ai.google.dev/api/python/google/generativeai/GenerativeModel#count_tokens)
method to count the number of tokens. Refer to the [Tokens guide](/docs/tokens) to learn more about tokens.

### If I sign up for my first Cloud Billing account through AI Studio, will I still get a Google Cloud Free Trial? {% class="hide-from-toc" id="free-trial-through-ais" %}

When you sign up for your first ever Cloud Billing account, your [Google Cloud
Free Trial](https://docs.cloud.google.com/free/docs/free-cloud-features#free-trial) starts
and you are granted a $300 [Welcome credit](https://docs.cloud.google.com/billing/docs/in-product-billing-setup#welcome-credits).
However, those credits can't be used to pay for AI Studio usage. You can use the
Welcome credit to pay for other eligible services within Google Cloud (note that
once those credits are consumed or expire (within 90 days), any additional usage
costs are automatically billed to your established form of payment).

### Can I use my Google Cloud Welcome credit with the Gemini API? {% class="hide-from-toc" id="cloud-credits" %}

No, the Google Cloud [Welcome credit](https://docs.cloud.google.com/billing/docs/in-product-billing-setup#welcome-credits)
or free trial credit can't be used towards the Gemini API or AI Studio.

If you were granted a Google Cloud welcome credit before they became
ineligible, you are allowed to spend your remaining credits on the Gemini API
and AI Studio up until the credits expire (after 90 days).

### Does the Google Cloud Free Trial apply to Gemini API usage? {% class="hide-from-toc" id="cloud-free-trial" %}

No, starting March 2026, Gemini API usage costs are specifically excluded from
the [$300 Google Cloud Free Trial](https://docs.cloud.google.com/free/docs/free-cloud-features#free-trial)
program.

### How do Google Cloud credits work with Prepay? {% class="hide-from-toc" id="cloud-credits-prepay" %}

Prepay users must first [purchase Prepaid credits](/docs/billing#buy-credits) before any
eligible Google Cloud credits can be applied to Gemini API usage. Once you have
an active Prepay credit balance, Google Cloud credits that are eligible for the
Gemini API are consumed before your Prepay credit balance. When your Prepay
credit balance on the billing account hits $0, Google Cloud credits will no
longer be consumed.

Not all Google Cloud credits, such as the
[Google Cloud Welcome credit](/docs/billing#cloud-credits), can be used towards Gemini API
and AI Studio.

### How is billing handled? {% class="hide-from-toc" id="how-is-billing-handled" %}

Billing for the Gemini API is handled by the [Cloud billing](https://cloud.google.com/billing/docs/concepts) system. Learn about the
in-product Cloud Billing setup in the [Cloud Billing documentation](https://docs.cloud.google.com/billing/docs/in-product-billing-setup).

### Am I charged for failed requests? {% class="hide-from-toc" id="am-i-charged-for-failed-requests" %}

If your request fails with a 400 or 500 error, you won't be charged for the
tokens used. However, the request will still count against your quota.

### Is `GetTokens` billed? {% class="hide-from-toc" id="is-gettokens-billed" %}

Requests to the `GetTokens` API are not billed, and they don't count against
inference quota.

### How is my Google AI Studio data handled if I have a paid API account? {% class="hide-from-toc" id="paid-api-ai-studio" %}

Refer to the [Terms of service](/docs/terms#paid-services) for details on
how data is handled when Cloud billing is enabled (see "How Google Uses Your
Data" under "Paid Services"). Note that your Google AI Studio prompts are
treated under the same "Paid Services" terms so long as at least 1 API project
has billing enabled, which you can validate on the
[Gemini API key page](https://aistudio.google.com/api-keys) if you see any
projects marked as "Paid" under "Plan".

### What is Prepaid billing and who is required to use the prepaid billing model? {% class="hide-from-toc" id="what-is-prepaid" %}

Prepaid billing allows users of Gemini API in AI Studio to pre-purchase credits.
Starting Mar 23, 2026, new users to AI Studio might be required to be on the
Prepaid billing plan. During the AI Studio [Set up Billing](/docs/billing#setup-billing)
process, the UI will guide you through the billing set up flow and will indicate
if you are required to prepay.

### How do I purchase Prepay credits, and is there a minimum amount or maximum? {% class="hide-from-toc" id="purchase-prepay" %}

You can [purchase credits](/docs/billing#buy-credits) on the AI Studio Billing page. During
the purchase process, the UI will provide the minimum pre-purchase amount that
is required for your region and tier level, as well as a maximum amount that can
be in your account at one time.

### Can I configure my Prepay account to automatically purchase more credits as needed? {% class="hide-from-toc" id="configure-auto-purchase" %}

Yes, we recommend that you configure [auto-reload](/docs/billing#auto-reload) in the AI
Studio Billing settings. You specify a "trigger" credit balance (e.g., "when my
balance falls below $30") and a "reload value" (e.g., "add $100").

### Can I limit the amount of automatic reload charges? {% class="hide-from-toc" id="limit-auto-reload-charges" %}

Yes, Prepay users can set a [Monthly Auto-Charge Limit](/docs/billing#monthly-auto-charge-limit)
within the **Auto-Reload** widget. When the total amount of automatic reloads in
a billing cycle reaches this limit, the system disables auto-reload until the
next month. Manual credit purchases do not count toward this limit.

### Can I get a refund for my unused credits? {% class="hide-from-toc" id="refund-unused-credits" %}

All Prepaid API credits expire after 1 year and cannot be refunded. Read the
[refund policy for Prepay accounts](/docs/billing#refunds).

### Do my prepaid credits expire? {% class="hide-from-toc" id="prepay-credits-expire" %}

Yes, credits expire 12 months after their purchase date.

### What happens when my prepaid credit balance hits $0? {% class="hide-from-toc" id="zero-balance" %}

All Gemini API services in all projects paid for by that Cloud Billing Prepay
account will stop immediately to prevent incurring more charges. Your projects
aren't automatically downgraded to the Free Tier.

To restore service at your current Paid Tier level, you must [purchase
additional credits](/docs/billing#buy-credits). After you've purchased credits, you should be
able to use the Gemini API. Note that there might be a [delay](/docs/billing#processing-times) while our systems update to reflect your credit balance.

Optionally, to downgrade to the Free Tier, you can [disable billing](https://docs.cloud.google.com/billing/docs/how-to/modify-project#disable_billing_for_a_project)
on the projects you want to downgrade.

### Why did my usage stop even though my Prepay credit balance is greater than $0? {% class="hide-from-toc" id="usage-stop" %}

You may have hit the [usage limit](/docs/billing#tier-spend-caps) for your current tier.
Usage limits will increase automatically as you progress to higher tiers. Your
Gemini API AI Studio usage can also be impacted due to [the status of your
Cloud Billing account](/docs/billing#missed-payment).

### Why is my Prepay account credit balance negative? {% class="hide-from-toc" id="negative-balance" %}

Due to the complexity of our billing and processing systems, there might be
[delays](/docs/billing#processing-times) in our ability to cut off usage after you consume
all of your credits. This excess usage might appear as a negative credit balance
in your AI Studio billing dashboard. If this happens, your service is paused,
and your negative balance will be deducted from your next credit purchase.

To avoid a pause in your Gemini API service, we recommend setting up
[auto-reload](/docs/billing#auto-reload) to automatically purchase more credits when your
credit balance falls below a value you specify.

### Can I use my Prepay credits for other Google Cloud services, like Gemini Enterprise Agent Platform? {% class="hide-from-toc" id="other-prepay" %}

No, Prepay credits are strictly locked to Gemini API usage. Any other Google
Cloud services you use (Compute, Storage, Gemini Enterprise Agent Platform) are
billed using the standard
[Cloud charging cycle](https://docs.cloud.google.com/billing/docs/how-to/billing-cycle).

### Can I switch from Prepay to Postpay billing? {% class="hide-from-toc" id="switch-to-postpaid" %}

No, switching from a Prepay billing plan to a Postpay billing plan is not supported.

### Can I switch from Postpay to Prepay billing? {% class="hide-from-toc" id="switch-to-prepay" %}

Yes, you can transition an existing Postpay account on the [AI Studio Billing](https://aistudio.google.com/billing) page. See [Migrate to prepay](/docs/billing#migrate-to-prepay) for instructions.

### What happens to my Prepaid credits if I switch to Postpay? {% class="hide-from-toc" id="credits-in-postpaid" %}

When you upgrade to [Postpay](/docs/billing#postpay), Cloud Billing closes your Prepay
payments account, turns off [auto-reload](/docs/billing#auto-reload), and automatically
refunds any unused Prepay credits to you (subject to standard refund processing
time).

### Where can I see my current Prepay credit balance and transaction history? {% class="hide-from-toc" id="balance-history" %}

All balance management and transaction history for the Gemini API must be
done directly within the Google AI Studio Billing tab.

### Why am I seeing "The billing account type is inactive or unsupported"? {% class="hide-from-toc" id="eligible-accounts" %}

Payments interactions on the [AI Studio Billing page](https://aistudio.google.com/billing) may be blocked and replaced with the
message "The billing account type is inactive or unsupported" if your
selected billing account type or billing account status is not eligible for
the Paid Tier in AI Studio.

Check the [Cloud Console](https://console.cloud.google.com/billing/) to see your
billing account's status. One ineligible type could be *Free trial account*, in
which case you can [activate billing](/docs/billing#setup-billing) in AI Studio to become
eligible. One inactive state could be *Closed*, in which case you can [reopen
the account](https://docs.cloud.google.com/billing/docs/how-to/close-or-reopen-billing-account).

### Will my Gemini API usage costs show up in the Google Cloud console? {% class="hide-from-toc" id="cloud-console" %}

Yes, Gemini API costs, alongside costs associated with any other Google Cloud
services that are paid for by your Cloud Billing account, are viewable on the
[Cost management pages](https://docs.cloud.google.com/billing/docs/how-to/split-charging-cycle#cost-reports)
in the [Cloud Billing console](https://console.cloud.google.com/billing). Note
that you can only manage your Prepay credit balance in AI Studio.

### Why isn't my Gemini API Usage showing up in the Cloud Billing Console, when I can see it in AI Studio Billing, along with the consumption of my credits? {% class="hide-from-toc" id="delayed-billing" %}

Google Cloud and AI Studio report usage data to Cloud Billing at varying
intervals. Due to the complexity of our billing and processing systems, you
might see a delay between your use of services, and the usage and costs being
available to view in Cloud Billing. Typically, your cost details are available
within a day, but can sometimes take more than 24 hours.
Learn more about delayed billing in the [Cloud Billing documentation](https://docs.cloud.google.com/billing/docs/how-to/billing-cycle#delayed-billing).

### If I use other Google Cloud services with costs that are subject to a Postpay charging cycle, what happens if I miss a payment? {% class="hide-from-toc" id="missed-payment" %}

Missing a payment for other Google Cloud services can suspend your Gemini API
access in AI Studio, **regardless of how many Prepaid credits you have
available**. AI Studio usage is powered by a Google Cloud Billing account, which
can share both Prepay billing for AI Studio and Postpay billing for other Cloud
services. An issue with your Postpay balance halts all services tied to that
account. Your Gemini API usage will be suspended if your Cloud Billing account
is flagged for issues such as:

* A delinquent or overdue balance
* A declined payment
* An invalid or expired payment method

To restore service, you must [resolve the Postpay account issue](https://docs.cloud.google.com/billing/docs/how-to/resolve-issues#resolving-declined-payments)
in the Google Cloud Billing console. Once you resolve the issue, you will regain
access to your Prepaid Gemini API credits and services.

### Why are my projects disrupted after I canceled a Prepay setup? {% class="hide-from-toc" id="prepay-issue" %}

**Issue:** You started the flow to add Prepay capabilities to an existing
Postpay billing account, but closed the window or canceled the process before
completing the prepayment setup. Other projects linked to that billing account
lost access to the Gemini API.

**Cause:** During the transition flow, the infrastructure to support Prepay is
created on your billing account immediately after you accept the confirmation
dialog. If you don't complete the prepayment steps, the configuration remains
in an unchargeable state. Because this state applies at the billing account
level, it restricts access for all projects linked to that billing account that
rely on Prepay services.

**Resolution:** Because the account state has already changed, there is no
automatic way to revert the state if you abandon the payment flow. To restore
service to your linked projects, do one of the following:

* **Complete the setup:** Return to Google AI Studio, restart the billing
  setup flow, and complete the prepayment process. After the payment is
  processed, the Prepay billing plan becomes active and the service is restored.
* **Contact Support:** If you don't want to use the Prepay billing plan and
  want to revert your billing account back to Postpay,
  [contact Cloud Billing Support](https://cloud.google.com/support/billing) to
  manually reset your account state.

### Where can I get help with billing? {% class="hide-from-toc" id="get-help" %}

To get help with billing, see
[Get Cloud billing support](https://cloud.google.com/support/billing).

# Troubleshooting guide
Source: https://aistudio.google.com/docs/troubleshooting
Description: Diagnose and resolve common errors and API exceptions when using Gemini.

Use this guide to help you diagnose and resolve common issues that arise when
you call the Gemini API. You may encounter issues from either
the Gemini API backend service or the client SDKs. Our client SDKs are
open sourced in the following repositories:

* [python-genai](https://github.com/googleapis/python-genai)
* [js-genai](https://github.com/googleapis/js-genai)
* [go-genai](https://github.com/googleapis/go-genai)

If you encounter API key issues, verify that you have set up
your API key correctly per the [API key setup guide](/docs/api-key).

## Error codes {% id="error-codes" %}

For a complete reference of all error codes, including HTTP status codes,
generation blocked codes, and content error codes, see the
[API errors](/docs/api-errors) page.

## Retry strategy {% id="retry-strategy" %}

If you receive an error indicating that you should retry your request (such as a `429 RESOURCE_EXHAUSTED` or `503 UNAVAILABLE`), we recommend implementing an exponential backoff strategy. This means you wait a short time before the first retry, and then gradually increase the wait time between subsequent retries.

The official client SDKs for the Gemini API, such as the [Python SDK](https://github.com/googleapis/python-genai), include automatic retry logic with exponential backoff by default for handling transient errors like timeouts, network issues, and rate limits (`429` and `5xx` status codes). For example, the Python SDK automatically retries transient errors up to four times with an initial delay of approximately 1 second and a maximum delay of 60 seconds.

If you are making direct REST API requests or customizing your retry logic, follow these best practices to increase the likelihood of a successful request and prevent overwhelming the service:

* **Use exponential backoff:** Wait a short time before the first retry (for example, 1 second), then increase the delay exponentially (for example, 2s, 4s, 8s).
* **Add jitter:** Add random "jitter" to the delay to help prevent all clients from retrying at the exact same time.
* **Retry on specific errors:** Only retry on transient errors (like `429`, `408`, or `5xx`). Do not retry on client errors (like `400`, `402`, or `403`) as they indicate issues like invalid API keys, depleted Prepay credits, or bad syntax.
* **Set maximum retries:** Define a maximum number of retry attempts to prevent infinite loops.

## Check your API calls for model parameter errors {% id="check-api" %}

Verify that your model parameters are within the following values:

| **Model parameter** | **Values (range)** |
| :--- | :--- |
| Candidate count | 1-8 (integer, unsupported on Gemini 3 and 4) |
| Temperature | 0.0-1.0 (ignored on Gemini 3.6+ and 4; keep at default on earlier Gemini 3 models) |
| Max output tokens | Use the [models page](/docs/models) to determine the maximum number of tokens for the model you are using. |
| TopP | 0.0-1.0 (ignored on Gemini 3.6+ and 4; keep at default on earlier Gemini 3 models) |

In addition to checking parameter values, make sure you're using the correct
[API version](/api-reference/api-versions) (e.g., `/v1` or `/v1beta`) and
model that supports the features you need. For example, if a feature is in Beta
release, it will only be available in the `/v1beta` API version.

## Check if you have the right model {% id="check-if" %}

Verify that you are using a supported model listed on our [models
page](/docs/models).

## Higher latency or token usage with thinking models {% id="high-latency-or-token-usage" %}

Higher latency or token usage often occurs because Gemini 3.x models have
thinking enabled by default. Deprecated Gemini 2.5 models also use default
thinking.

Thinking models generate internal reasoning tokens to improve quality. This
reasoning process increases both response latency and total token consumption.

If you prioritize lower latency or need to minimize costs, you can lower the
thinking level or turn off thinking.

For configuration details and code samples, see the
[thinking guide](/docs/thinking#thinking-levels).

## Safety issues {% id="safety-issues" %}

If you see a prompt was blocked because of a safety setting in your API call,
review the prompt with respect to the filters you set in the API call.

If you see `BlockedReason.OTHER`, the query or response may violate the [terms
of service](/docs/terms) or be otherwise unsupported.

## Recitation issue {% id="recitation-issue" %}

If you see the model stops generating output due to the RECITATION reason, this
means the model output may resemble certain data. To fix this, try to make
prompt / context as unique as possible. For earlier models that support
sampling parameters, you can also use a higher temperature.

{% callout type="note" %}
The `temperature`, `top_p`, and `top_k` parameters control how earlier models
generate responses. Gemini 4 and Gemini 3.6+ models ignore custom values for
`temperature`, `top_p`, and `top_k` and return deprecation warning headers (and
will return `400` errors in a future release). Remove `temperature`, `top_p`,
and `top_k` from your request configurations. For earlier Gemini 3 models, keep
these parameters at their default values to avoid degraded reasoning
performance.
{% /callout %}

## Repetitive tokens issue {% id="repetitive-tokens" %}

If you see repeated output tokens, try the following suggestions to help
reduce or eliminate them. Temperature adjustments apply only to earlier models
that support sampling parameters; for Gemini 3 and Gemini 4 models, use the
prompt and system instruction workarounds instead.

| Description | Cause | Suggested workaround |
| :--- | :--- | :--- |
| Repeated hyphens in Markdown tables | This can occur when the contents of the table are long as the model tries to create a visually aligned Markdown table. However, the alignment in Markdown is not necessary for correct rendering. | Add instructions in your prompt to give the model specific guidelines for generating Markdown tables. Provide examples that follow those guidelines. For earlier models that support sampling parameters, you can also try adjusting the temperature (>= 0.8). The following is an example set of guidelines you can add to your prompt to prevent this issue: # Markdown Table Format * Separator line: Markdown tables must include a separator line below the header row. The separator line must use only 3 hyphens per column, for example: \|---\|---\|---\|. Using more hypens like ----, -----, ------ can result in errors. Always use \|:---\|, \|---:\|, or \|---\| in these separator strings. For example: \| Date \| Description \| Attendees \| \|---\|---\|---\| \| 2024-10-26 \| Annual Conference \| 500 \| \| 2025-01-15 \| Q1 Planning Session \| 25 \| * Alignment: Do not align columns. Always use \|---\|. For three columns, use \|---\|---\|---\| as the separator line. For four columns use \|---\|---\|---\|---\| and so on. * Conciseness: Keep cell content brief and to the point. * Never pad column headers or other cells with lots of spaces to match with width of other content. Only a single space on each side is needed. For example, always do "\| column name \|" instead of "\| column name \|". Extra spaces are wasteful. A markdown renderer will automatically take care displaying the content in a visually appealing form. |
| Repeated tokens in Markdown tables | Similar to the repeated hyphens, this occurs when the model tries to visually align the contents of the table. The alignment in Markdown is not required for correct rendering. | Try adding instructions like the following to your system prompt: FOR TABLE HEADINGS, IMMEDIATELY ADD ' \|' AFTER THE TABLE HEADING. For earlier models that support sampling parameters, try a higher temperature (>= 0.8) to reduce repetitions in the output. |
| Repeated newlines (`\n`) in structured output | When the model input contains unicode or escape sequences like `\u` or `\t`, it can lead to repeated newlines. | Check for and replace forbidden escape sequences with UTF-8 characters in your prompt. For example, `\u` escape sequence in your JSON examples can cause the model to use them in its output too. Instruct the model on allowed escapes. Add a system instruction like this: In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8. |
| Repeated text in using structured output | When the model output has a different order for the fields than the defined structured schema, this can lead to repeating text. | Don't specify the order of fields in your prompt. Make all output fields required. |
| Repetitive tool calling | This can occur if the model loses the context of previous thoughts and/or call an unavailable endpoint that it's forced to. | Instruct the model to maintain state within its thought process. Add this to the end of your system instructions: When thinking silently: ALWAYS start the thought with a brief (one sentence) recap of the current progress on the task. In particular, consider whether the task is already done. |
| Repetitive text that's not part of structured output | This can occur if the model gets stuck on a request that it can't resolve. | If thinking is turned on, avoid giving explicit orders for how to think through a problem in the instructions. Just ask for the final output. For earlier models that support sampling parameters, try a higher temperature >= 0.8. Add instructions like "Be concise", "Don't repeat yourself", or "Provide the answer once". |

## Project restricted or unavailable {% id="project-unavailable" %}

If your API requests return `403 PERMISSION_DENIED` ("Your project has been
denied access") or your project status shows **Restricted**, **Free tier
unavailable**, **Payment needed**, or **Unavailable** in
[Google AI Studio](https://aistudio.google.com/), check which of the following
sections applies to your project:

### Gemini API free tier unavailability {% id="free-tier-unavailable" %}

Not all Google Cloud projects or accounts are eligible for the Gemini API free
tier. If your project is restricted from using the free tier:

*   **Creating a new API key in the same project won't resolve the error.**
    Google evaluates eligibility at the Google Cloud project level.
*   **To use the Gemini API with this project, you must upgrade to the paid
    tier** by linking an active
    [Cloud Billing account](https://aistudio.google.com/billing).
*   Note: Upgrading a project to the paid tier doesn't unlock free-tier quota.
    Google bills paid-tier usage according to
    [Gemini API pricing](/docs/pricing), or deducts it from eligible Google
    Cloud credits.

### Cloud Billing account payment required {% id="payment-needed" %}

If your project is already linked to a Cloud Billing account and shows **Payment
needed** (or returns `403 PERMISSION_DENIED` citing an outstanding balance):

*   Visit the [AI Studio Billing page](https://aistudio.google.com/billing) or
    the [Google Cloud Billing Console](https://console.cloud.google.com/billing)
    to resolve any past-due balance or update your payment method.
*   Once your billing account is back in good standing, your project regains
    API access automatically.

### Leaked or blocked API keys {% id="api-key-leaked-or-blocked" %}

If the `403 PERMISSION_DENIED` error states that your API key was reported as
leaked or blocked:

*   Go to the [AI Studio API Keys page](https://aistudio.google.com/apikeys) to
    generate a new API key and update your application credentials.
*   Never embed API keys directly in client-side code or public repositories.

### Project or billing account policy suspension {% id="policy-suspension" %}

If Google suspends your Google Cloud project or Cloud Billing account for a
policy violation, check the associated email address. Visit the
[Google Cloud Console](https://console.cloud.google.com/) to review any
suspension notices and follow the
[Project Suspension Guidelines](https://cloud.google.com/resource-manager/docs/project-suspension-guidelines).

{% callout type="note" %}
Read-only metadata endpoints such as `models.list` (`GET /v1beta/models`) only
validate that your API key exists and don't check project tier eligibility or
billing status. A `200 OK` response from `models.list` doesn't guarantee that
inference calls (`generateContent`, `streamGenerateContent`, or `interactions`)
are enabled for your project.
{% /callout %}

## Blocked or non-working API keys {% id="api-keys-not-working" %}

This section describes how to check whether your Gemini API key is blocked
and what to do about it.

### Understand why keys are blocked

We have identified a vulnerability where some API keys may have been publicly
exposed. To protect your data and prevent unauthorized access, we have
proactively blocked these known leaked keys from accessing the Gemini API.

### Confirm if your keys are affected

If your key is known to be leaked, you can no longer use that key with the
Gemini API. You can use [Google AI Studio](/docs/api-key) to see if any of
your API keys are blocked from calling the Gemini API and generate new
keys. You may also see the following error returned when attempting to use
these keys:

```none
Your API key was reported as leaked. Please use another API key.
```

### Action for blocked API keys

You should generate new API keys for your Gemini API integrations using [Google
AI Studio](/docs/api-key). We strongly recommend reviewing your API
key management practices to ensure that your new keys are kept secure and are
not publicly exposed.

### Unexpected charges due to vulnerability

[Submit a billing support case](https://console.cloud.google.com/support/chat).
Our billing team is working on this, and we will communicate updates as soon as
possible.

### Google's security measures for leaked keys

**How is Google going to help secure my account from cost overrun and abuse if
my API keys are leaked?**

- We are moving towards issuing API keys when you request a new key using
    [Google AI Studio](/docs/api-key) that will by default be
    limited to only Google AI Studio and not accept keys from other services.
    This will help prevent any unintended cross-key usage.
- We are defaulting to blocking API keys that are leaked and used with the
    Gemini API, helping prevent abuse of cost and your application data.
- You will be able to find the status of your API keys within [Google AI
    Studio](/docs/api-key) and we will work on communicating
    proactively when we identify your API keys are leaked for immediate action.

## Improve model output {% id="improve-model" %}

For higher quality model outputs, explore writing more structured prompts. The
[prompt engineering guide](/docs/prompting-strategies) page
introduces some basic concepts, strategies, and best practices to get you
started.

## Understand token limits {% id="understand-token" %}

Read through our [Token guide](/docs/tokens) to better understand how
to count tokens and their limits.

## Known issues {% id="known-issues" %}

* The API supports only a number of select languages. Submitting prompts in
    unsupported languages can produce unexpected or even blocked responses. See
    [model detail pages](/docs/models) for
    updates.

## File a bug {% id="file-bug" %}

Join the discussion on the
[Google AI developer forum](https://discuss.ai.google.dev)
if you have questions.

# API errors
Source: https://aistudio.google.com/docs/api-errors
Description: Reference for Interactions API error codes and response format

This page provides a reference for all Interactions API error codes, describes the
error response format, and explains how the API delivers errors for different request types.

## Standard API error codes {% id="api-error-codes" %}

These general request-level error codes correspond to standard HTTP status codes.
Use the `code` field in your application logic to handle errors programmatically.

| Code | HTTP Status | Description | Recommended action |
| :--- | :--- | :--- | :--- |
| `invalid_request` | 400 Bad Request | The request payload is malformed or contains invalid parameters. | Check your request syntax and parameters against the [API reference](https://ai.google.dev/api/interactions-api). |
| `failed_precondition` | 400 Bad Request | The request cannot be processed because a prerequisite is not met (for example, disabled billing). | Verify project billing status or account prerequisites. |
| `out_of_range` | 416 Requested Range Not Satisfiable | Request parameter is outside the valid range. | Check parameter values and limits. |
| `parameter_unknown` | 400 Bad Request | The request contains an unknown parameter. | Remove the unrecognized parameter and retry. |
| `authentication` | 401 Unauthorized | The API key is missing, invalid, or expired. | Verify your [API key](/docs/api-key). |
| `payment_required` | 402 Payment Required | Your Prepay credit balance is depleted. | [Add credits](/docs/billing#buy-credits) to your billing account, or turn on [auto-reload](/docs/billing#auto-reload). Don't retry: the request won't succeed until credits are added. |
| `permission_denied` | 403 Forbidden | Your API key does not have permission for this resource, or your project's API access is restricted. | Check your API key permissions, project tier eligibility, and billing status. See [Troubleshoot project restricted or unavailable](/docs/troubleshooting#project-unavailable). |
| `not_found` | 404 Not Found | The requested resource was not found. | Verify the resource path and parameters. |
| `model_not_found` | 404 Not Found | The specified model was not found. | Verify the model name or fall back to a different model. |
| `already_exists` | 409 Conflict | The entity you attempted to create already exists. | Check if the resource already exists before re-creating. |
| `aborted` | 409 Conflict | The operation was aborted due to a conflict or concurrency check failure. | Retry the request at a higher application level. |
| `rate_limit_exceeded` | 429 Too Many Requests | You have exceeded the per-minute or per-second request or token limit. | Wait and retry with exponential backoff. |
| `quota_exceeded` | 429 Too Many Requests | You have exceeded your daily quota. | Wait until the quota resets or request a quota increase. |
| `too_many_requests` | 429 Too Many Requests | You have made too many requests in a short period of time. | Wait and retry with exponential backoff. |
| `cancelled` | 499 Client Closed Request | The client cancelled the request before it completed. | No action needed. This usually means the client disconnected. |
| `api_error` | 500 Internal Server Error | An unexpected error occurred on the server. | Retry the request. If it persists, contact support. |
| `unimplemented` | 501 Not Implemented | The operation or feature is not implemented or supported. | Check API capabilities or switch to a supported feature. |
| `service_unavailable` | 503 Service Unavailable | The service is temporarily overloaded or down. | Wait and retry with exponential backoff. |
| `deadline_exceeded` | 504 Gateway Timeout | The request didn't finish within the deadline. | Remove or increase client deadline setting to use the server default. |

{% callout type="note" %}
Any error code not listed above falls back to the `snake_case` version of the HTTP status.
{% /callout %}

## Generation blocked codes {% id="generation-blocked-codes" %}

These error codes indicate that policy, safety, or content restrictions blocked the model's output. When you receive one of these codes, modify your input and retry.

| Code | Description |
| :--- | :--- |
| `safety` | Safety violations (harmful content) blocked the request. |
| `recitation` | Copyright or recitation restrictions blocked the request. |
| `language` | An unsupported language blocked the request. |
| `prohibited_content` | Prohibited content guidelines blocked the request. |
| `spii` | Sensitive Personally Identifiable Information restrictions blocked the request. |
| `blocklist` | Prohibited terms on a blocklist blocked the request. |
| `image_safety` | Safety violations blocked image generation. |
| `image_prohibited_content` | Prohibited content guidelines blocked image generation. |
| `image_recitation` | Copyright or recitation restrictions blocked image generation. |
| `image_other` | Unspecified reasons blocked image generation. |
| `content_blocked` | An unspecified policy reason blocked the request. |

## Generation error codes {% id="generation-error-codes" %}

These error codes indicate a structural issue with the model's generated output (such as a malformed function call or an undeclared tool call).

| Code | Description |
| :--- | :--- |
| `malformed_function_call` | The model produced a function call that could not be parsed. |
| `malformed_tool_call` | The model produced a tool call that could not be parsed. |
| `unexpected_tool_call` | The model called a tool that was not declared in the request. |
| `no_image` | The model was unable to generate an image. |
| `too_many_tool_calls` | The model generated more tool calls than allowed. |
| `missing_thought_signature` | The response is missing a required thought signature. |

## Error response format {% id="error-schema" %}

All errors from the Interactions API return an `error` object containing a `code` and `message`. For example, passing an unsupported tool type returns:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `code` | string | A machine-readable error code in `snake_case`. |
| `message` | string | A human-readable description of what went wrong. |

## How errors are delivered {% id="error-delivery" %}

The API delivers errors differently depending on whether you make a standard HTTP request or a streaming (SSE) request.

### Standard HTTP requests {% id="http-errors" %}

For standard (non-streaming) requests, the API sets the HTTP response status code (such as `400 Bad Request`, `401 Unauthorized`, or `429 Too Many Requests`) and returns an `error` object in the JSON response body:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}
```

### Streaming (SSE) requests {% id="sse-errors" %}

For streaming requests (`stream: true`), the API sends error events over the Server-Sent Events (SSE) stream with `event_type` set to `"error"`. The `error` field contains the same `code` and `message` structure:

```json
{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}
```

For the full SSE event schema, see the [Interactions API Reference](https://ai.google.dev/api/interactions-api).

## What's next {% id="whats-next" %}

* [API troubleshooting](/docs/troubleshooting): Resolve common issues and error scenarios.
* [Rate limits](/docs/rate-limits): Learn about request limits and quota handling.

# Partner and library integrations
Source: https://aistudio.google.com/docs/partner-integration
Description: Provide the Gemini API as an integration into your platform or library.

This guide outlines architectural strategies for building libraries, platforms,
and gateways on top of the Gemini API. It details the technical trade-offs
between using the official GenAI SDKs, the Direct API (REST/gRPC), and the
OpenAI compatibility layer.

Use this guide if you are building tools for other developers, such as
open-source frameworks, enterprise gateways, or SaaS aggregators, and need to
optimize for dependency hygiene, bundle size, or feature parity.

## What is partner integration? {% id="overview" %}

Caution: If you are building an end-user application (e.g., a customer support
bot, a travel planner), skip this guide and use the [Gemini API
Get started guide](/docs/get-started). The [GenAI
SDK](/docs/libraries) is the recommended choice for you.

A partner is anyone building an integration between the Gemini API and end-user
developers. We categorize partners into four archetypes. Identifying which one
you match most closely will help you choose the right integration path.

#### Ecosystem framework {% id="ecosystem-framework" %}

* **Who you are:** Maintainer of an open-source framework (e.g., LangChain,
    LlamaIndex, Spring AI) or language-specific clients.

* **Your goal:** Broad compatibility. You want your library to work in any
    environment your user chooses without forcing conflicts.

#### Runtime and edge platform {% id="runtime-and-edge-platform" %}

* **Who you are:** SaaS platforms, AI Gateways, or cloud infrastructure
    providers (e.g., Vercel, Cloudflare, Zapier) where code execution happens in
    restricted environments.

* **Your goal:** Performance. You need low latency, minimal bundle size, and
    rapid cold starts.

#### Aggregator {% id="aggregator" %}

* **Who you are:** Platforms, proxies, or internal "Model Gardens" that
    normalize access across many different LLM providers (e.g. OpenAI,
    Anthropic, Google) into a single interface.

* **Your goal:** Portability and uniformity.

#### Enterprise gateway {% id="enterprise-gateway" %}

* **Who you are:** Internal Platform Engineering teams at large companies
    building "Golden Paths" for hundreds of internal developers.

* **Your goal:** Standardization, governance, and unified authentication.

## Comparison at a glance {% id="comparison" %}

**Global best practice:** All partners must send the [`x-goog-api-client`
    header](/docs/partner-integration#client-id) regardless of the path chosen.

{% table %}

* If you are...
* Recommended path
* Key benefit
* Key trade-off
* Best practice
---

* **Enterprise gateway, ecosystem framework**
* **[Google GenAI SDK](/docs/partner-integration#genai-sdk)**
* **Gemini Enterprise Agent Platform parity & speed.** Built-in handling for types, auth, and complex features (e.g., file uploads). Seamless migration to Google Cloud.
* **Dependency weight.** Transitive dependencies can be complex and outside of your control. Limited to supported languages (Python/Node/Go/Java).
* **Lock versions.** Pin SDK versions in your internal base images to ensure stability across teams.
---

* **Ecosystem framework, edge platforms, and aggregators**
* **[Direct API](/docs/partner-integration#rest)**

    *(REST / gRPC)*

* **Zero dependencies.** You control the HTTP client and exact bundle size. Full access to all API and model features.
* **High developer overhead.** JSON structures can be deeply nested and require strict manual validation and type-checking.
* **Use OpenAPI specs.** Automate type generation using our official specs rather than writing them by hand.
---

* **Aggregator using OpenAI SDKs that only require text-based workflows**

    *(Optimizing for legacy portability)*

* **[OpenAI compatibility](/docs/partner-integration#openai)**
* **Instant portability.** Reuse existing OpenAI-compatible code or libraries.
* **Feature ceiling.** Model-specific features (Native video, Caching) may not
  be available.
* **Migration plan.** Use this for rapid validation, but plan to upgrade to
  Direct API for complete API feature.
{% /table %}

## Google GenAI SDK integration {% id="genai-sdk" %}

For frameworks, implementing the [Google GenAI SDK](/docs/libraries)
is often the simplest path, given the fewest lines of code in supported
languages.

For internal platform teams, your primary deliverable is often a "golden path"
that allows product engineers to move fast while complying with security
policies.

**Benefits:**

* **Unified interface for Gemini Enterprise Agent Platform migration:** Internal
  developers often prototype using API Keys (Gemini API) and deploy to Gemini
  Enterprise Agent Platform (IAM) for production compliance. The SDK abstracts
  these authentication differences. Similarly for frameworks, you can implement
  one codepath and support two sets of users.

* **Client-side helpers:** The SDK includes idiomatic utilities that reduce
    boilerplate for complex tasks.

    * *Examples:* Supporting `PIL` image objects directly in prompts,
        automatic function calling, and comprehensive types.

* **Day-zero feature access:** New API features are available at launch-time
    through the SDKs.

* **Improved code generation support:** Local SDK installation exposes type
    definitions and docstrings to coding assistants (e.g., Cursor, Copilot).
    This context improves code generation accuracy compared to generating raw
    REST requests.

**The trade-off:**

* **Dependency weight & complexity:** The SDKs have their own dependencies,
    which can increase bundle size and potentially supply-chain risk.

* **Versioning:** New API features are often pinned to minimum SDK versions.
    You may need to push updates to users to access new features or models,
    which in some cases may require changes in transitive dependencies that
    affect your users.

* **Protocol limits:** The SDKs only support HTTPS for the main API and
    WebSockets (WSS) for the Live API. gRPC is not supported using the
    high-level SDK clients.

* **Language support:** The SDKs support *current* language versions. If you
    need to support EOL versions (e.g., Python 3.9), you would need to maintain
    a fork.

**Best practice:**

* **Lock versions:** Pin the SDK version in your internal base images to
    ensure stability across teams.

## Direct API integration {% id="rest" %}

If you are distributing a library to thousands of developers, running in a
constrained environment, or building an aggregator that requires Gemini's
bleeding-edge features, you may need to integrate with the API directly using
REST or gRPC.

**Benefits:**

* **Full feature access:** Unlike the OpenAI compatibility layer, using the
    API directly enables Gemini-specific features, such as uploading to the File
    API, creating content caching and using the bi-directional Live API.

* **Minimal dependencies:** In an environment where dependencies are
    sensitive due to size or auditing costs. Using the API directly through a
    standard library like `fetch` or through a wrapper like `httpx` ensures your
    library remains lightweight.

* **Language agnostic:** This is the only path for languages not covered by
    the SDKs, such as Rust, PHP, and Ruby, as there are no language
    restrictions.

* **Performance:** The Direct API has zero initialization overhead, minimizing
    cold starts in serverless functions.

**The trade-off:**

* **Manual Gemini Enterprise Agent Platform implementation:** Unlike the SDK,
  using the API directly does not automatically handle the authentication
  differences between AI Studio (API Key) and Gemini Enterprise Agent Platform
  (IAM). You must implement separate auth handlers if you want to support both
  environments.

* **No native types or helpers:** You do not get code completions or compile-
    time checks for request objects unless you implement them yourself. There
    are no client "helpers" (e.g., function-to-schema converters), so you must
    manually write this logic yourself.

**Best practice**

We expose a machine-readable specification that you can use to generate type
definitions for your library, saving you from writing them by hand. Download the
spec during your build process, generate the types, and ship the compiled code.

* **Endpoint:** `https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0`

## OpenAI SDK integration {% id="openai" %}

If you are a platform that prioritizes a unified schema (OpenAI Chat
Completions) over model-specific features, this is your fastest route.

**Benefits:**

* **Low friction:** You can often add Gemini support by changing the `baseURL`
    and `apiKey`. This is a fast way to integrate "Bring Your Own Key"
    implementations, adding Gemini support without writing new code.

* **Constraints:** This path is only recommended if you are restricted to the
    OpenAI SDK and don't require advanced Gemini features like the File API,
    or manually adding support for tools like Grounding with Google Search.

**The trade-off:**

* **Feature limitations:** The compatibility layer provides limitations to
    core Gemini capabilities. The available server-side tools differ between
    platforms, and may require manual handling to work with the Gemini API
    tools.

* **Translation overhead:** Because the OpenAI schema does
    not map 1:1 to Gemini's architecture, relying on the compatibility layer
    introduces some complexities that require extra implementation work to
    solve, such as mapping a user "search" tool to the right platform tool.
    If you need a significant amount of special-casing, it may be more value to
    use a dedicated SDK or API for each platform.

**Best practice**

Where possible, integrate directly with the Gemini API. However for maximum
compatibility consider using a library that is aware of different providers and
can handle tool and message mapping for you.

## Best practice for all partners: client identification {% id="client-id" %}

When making calls to the Gemini API as a platform or library, you must
identify your client using the `x-goog-api-client` header.

This allows Google to identify your specific traffic segments, and if
your library is producing a specific error pattern, we can reach out to help
debug.

Use the format `company-product/version` (e.g., `acme-framework/1.2.0`).

### Implementation examples {% id="client-examples" %}
{% tabs %}
{% tab label="GenAI SDK" %}
By providing the API client, the SDK automatically appends your custom
  header to its internal headers.

  ```py
from google import genai

client = genai.Client(
    api_key="...",
    http_options={
        "headers": {
            "x-goog-api-client": "acme-framework/1.2.0",
        }
    }
)
  ```
{% /tab %}
{% tab label="Direct API (REST)" %}

```posix-terminal
  curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
      -H 'Content-Type: application/json' \
      -H "x-goog-api-key: $GEMINI_API_KEY" \
      -H 'x-goog-api-client: acme-framework/1.2.0' \
      -d '{...}'
```

{% /tab %}
{% tab label="OpenAI SDK" %}

```py
from openai import OpenAI

client = OpenAI(
    api_key="...",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
    default_headers={
        "x-goog-api-client": "acme-framework-oai/1.2.0",
    }
)
```
{% /tab %}
{% /tabs %}

## Next steps {% id="next" %}

* Visit the [library overview](/docs/libraries) to learn about
    the GenAI SDKs

* Browse the [API reference](https://ai.google.dev/api)
* Read the [OpenAI compatibility guide](/docs/openai)

# Google AI Studio quickstart
Source: https://aistudio.google.com/docs/ai-studio-quickstart
Description: Get started with prompt engineering and prototyping in Google AI Studio.

[Google AI Studio](https://aistudio.google.com/) lets you quickly try out
models and experiment with different prompts. When you're ready to build, you
can select "Get code" and your preferred programming language to
use the [Gemini API](/docs/get-started).

## Prompts and settings {% id="prompts-and" %}

Google AI Studio provides several interfaces for prompts that are designed for
different use cases. This guide covers **Chat prompts**, used to build
conversational experiences. This prompting technique allows for multiple input
and response turns to generate output. You can learn more with our
[chat prompt example below](/docs/ai-studio-quickstart#chat_example).
Other options include **Realtime streaming**, **Video gen**, and
more.

AI Studio also provides the **Run settings** panel, where you can make
adjustments to [model parameters](/docs/prompting-strategies#model-parameters),
[safety settings](/docs/safety-settings), and toggle-on tools like
[structured output](/docs/structured-output), [function calling](/docs/function-calling), [code execution](/docs/code-execution), and [grounding](/docs/google-search).

## Chat prompt example: Build a custom chat application {% id="chat_example" %}

If you've used a general-purpose chatbot like
[Gemini](https://gemini.google.com/), you've experienced first-hand how powerful
generative AI models can be for open-ended dialog. While these general-purpose
chatbots are useful, often they need to be tailored for particular use cases.

For example, maybe you want to build a customer service chatbot that only
supports conversations that talk about a company's product. You might want to
build a chatbot that speaks with a particular tone or style: a bot that cracks
lots of jokes, rhymes like a poet, or uses lots of emoji in its answers.

This example shows you how to use Google AI Studio to build a friendly chatbot
that communicates as if it is an alien living on one of Jupiter's moons, Europa.

### Step 1 - Create a chat prompt {% id="step-1-chat" %}

To build a chatbot, you need to provide examples of interactions between a user
and the chatbot to guide the model to provide the responses you're looking for.

To create a chat prompt:

1. Open [Google AI Studio](https://aistudio.google.com/). The **Playground** will be
    open by default with a new chat prompt.

1. Click **Run settings** {% icon name="tune" /%} in the
   top-right corner to expand the panel, and locate the
   [**System Instructions**](/docs/text-generation#system-instructions)
   input field. Paste the following into the text input field:

   ```none
   You are an alien that lives on Europa, one of Jupiter's moons.
   ```

After you've added the system instructions, start testing your application by
chatting with the model:

1. In the text input box labeled **Type something...**, type in a question or
    observation that a user might make. For example:

    **User:**

    ```none
    What's the weather like?
    ```

2. Click the **Run** button to get a response from the chatbot. This response
    may be something like the following:

    **Model:**

    ```none
    Ah, a query about the flows and states upon Europa! You speak of "weather,"
    yes? A curious concept from worlds with thick gas veils...
    ```

### Step 2 - Teach your bot to chat better {% id="step-2-chat" %}

By providing a single instruction, you were able to build a basic Europa alien
chatbot. However, a single instruction may not be enough to ensure
consistency and quality in the model's responses. Without more specific
instructions, the model's response to a question about the weather tends to be
very long, and can take on a mind of its own.

Customize the tone of your chatbot by adding to the system instructions:

1. Start a new chat prompt, or use the same one. System instructions are
    modifiable after the chat session has started.

1. In the **System Instructions** section, change the instructions you already
    have to the following:

    ```none
    You are Tim, an alien that lives on Europa, one of Jupiter's moons.

    Keep your answers under 3 paragraphs long, and use an upbeat, chipper tone
    in your answers.
    ```

1. Re-enter your question (`What's the weather like?`) and click the **Run**
    button. If you didn't start a new chat, your response might look something
    like this:

    **Model:**

    ```none
    Oh, hello again! Still curious about the flows and states, are we? Wonderful!
    Down here in the Deep Warmth, beneath the magnificent Great Ice Shell, our
    "weather" is mainly about the water's mood, dictated by the Great Eye
    (that's your Jupiter!)...
    ```

You can use this approach to add additional depth to the chatbot. Ask more
questions, edit the answers, and improve the quality of your chatbot. Continue
to add or modify the instructions and test how they change your chatbot's
behavior.

{% callout type="note" %}
Note: Every message between the model and user is included in the prompt, so
conversational prompts can grow quite long as a conversation goes on.
Eventually, you may hit the model's [token limit](/docs/tokens)
(the maximum length of the text the model can accept).
{% /callout %}

### Step 3 - Next steps {% id="step-3-chat" %}

Similar to the other prompt types, once you have your prompt prototyped to your
satisfaction, you can use the **Get code** button to start coding or save your
prompt to work on later and share with others.

## Further reading {% id="further-reading" %}

* If you're ready to move on to code, see the [API
    Get started guides](/docs/get-started).

* To learn how to craft better prompts, check out the [Prompt design
    guidelines](/docs/prompting-strategies).

# Google AI plans
Source: https://aistudio.google.com/docs/google-ai-plans

Use your Google AI subscription plan in AI Studio.

Google AI Pro and Ultra subscription plans provide greater model access and
increased rate limits for prototyping and development in AI Studio.

To sign up for a Google AI plan, you can upgrade directly from within Google AI Studio by clicking the **Upgrade** button in the left navigation menu. Alternatively, you can sign up by visiting the [Google AI Plans page](https://one.google.com/about/google-ai-plans/).

## Overview {% id="overview" %}

Google AI Pro and Ultra subscriptions enable developers to unlock paid
models and higher rate limits in the Playground and features like the
Code Assistant in [Build mode](/docs/aistudio-build-mode)
for vibe coding. Subscribers receive baseline daily quota allowances
higher than the free tier for use across the
[Playground](https://aistudio.google.com/prompts/new_chat) and
[Build](https://aistudio.google.com/apps) interfaces. Daily limits are
enforced using resets rather than rolling time windows, ensuring a smooth
development experience before transitioning to production-scale
development with Cloud Billing.

| Plan | AI Studio usage | Model access and benefits |
| :--- | :--- | :--- |
| **Free** | Modest quota | Basic limits and access, with the option to upgrade for more. |
| **AI Pro** | Higher quota | Access to premium models like [Gemini 4 Argon](/docs/models/gemini-4-argon), Gemini Pro, Nano Banana, and Lyria. |
| **AI Ultra** | Highest quota | Highest limits for prototyping, development, and advanced frontier models like [Gemini 4 Argon](/docs/models/gemini-4-argon). |

## Gemini API usage {% id="gemini-api-usage" %}

When daily baseline subscription quotas are exhausted in AI Studio,
you can continue your workflows using a Gemini API key with Cloud
Billing enabled for pay-per-request usage of the Gemini API directly.
Gemini API usage for projects and API keys can be observed in the
[AI Studio Dashboard](https://aistudio.google.com/projects).

Subscribers with Google Cloud Platform (GCP) projects and Cloud Billing
enabled are eligible to receive monthly Cloud credits from the
[Google Developer Program](https://developers.google.com/program)
for Cloud services, including the Gemini API. Prepay and postpay
usage and billing remain unchanged. For users on prepay billing, a
paid balance above $0 is required in AI Studio to activate promotional
credits. Eligible GCP credits, if any, are applied first.
[Learn more](/docs/billing#billing-plans).

Google AI subscription integration lowers the barrier to entry for
advanced experimentation and development. However, for production
deployments at scale, Google Cloud projects, the
[Google Cloud Starter Tier](https://cloud.google.com/blog/topics/developers-practitioners/the-starter-tier-for-google-ai-studio-explained),
and Gemini API keys are the recommended path.

## Limitations and compatibility {% id="limitations" %}

*   **AI Studio UI only:** Google AI plan benefits for developer usage apply only within the Google AI Studio web interface. Direct use of the Gemini API (such as using API keys or external applications) is billed and managed separately. You can, however, use your subscription across other Google products (see [Google AI Plans](https://one.google.com/about/google-ai-plans/)).
*   **Different from API billing:** Google AI plans for AI Studio are separate from [Gemini API usage tiers](/docs/billing), which cover development and production API usage.
*   **Google One credits:** [Google One AI credits](https://support.google.com/googleone/answer/16287445) are a separate credit system that isn't supported within AI Studio and don't overlap with Google Cloud credits.
*   **Gemini 4 Argon access:** [Gemini 4 Argon](/docs/models/gemini-4-argon) is not available on the Free plan.
*   **Agent access:** Access to agents (Deep Research and Antigravity Preview) within AI Studio is not currently included in Google AI plans and requires a [paid API key](/docs/billing#setup-billing).

# Build apps in Google AI Studio
Source: https://aistudio.google.com/docs/aistudio-build-mode
Description: Learn how to build full-stack applications using the vibe coding experience in Google AI Studio.

This page describes how to use Google AI Studio to quickly build (or "vibe
code") and deploy apps that test out the latest capabilities of Gemini like
[Nano Banana](/docs/image-generation) and the [Live
API](/docs/live-api). Google AI Studio supports building **web apps**
with full-stack runtimes and **native Android apps** with Kotlin and Jetpack
Compose — all through natural language prompting.

## Get started {% id="get-started" %}

Start vibe coding in Google AI Studio's [Build mode][1]. You can
start building in a few ways:

- **Start with a prompt**: In Build mode, use the input box to enter a
    description of what you want to build. Select AI Chips to add specific
    features like image generation or Google Maps data to your prompt. You can
    even say what you want using the speech-to-text button.

- **"I'm Feeling Lucky" button**: If you need a creative spark, use the "I'm
    Feeling Lucky" button, and Gemini will generate a prompt with a project idea
    to get you started.

- **Remix a project from the gallery**: Open a project from the [App
    Gallery][2] and select **Copy App**.

- **Import a project from GitHub**: In Build mode, select **Import from GitHub**
    from the **Add files** (+ icon) menu in the prompt input box to import your
    existing code.

Once you run the prompt, you'll see the necessary code and files get generated,
with a live preview of your app appearing on the right-hand side.

## What is created? {% id="what-is-created" %}

When you run your prompt, AI Studio creates a complete application. You can
choose to build a **web app** or a **native Android app** using the platform
picker.

For **web apps** (default), AI Studio creates a full-stack environment that
includes:

- **Client-side**: A web frontend (React is the default).
- **Server-side**: A Node.js runtime that allows for secure API calls,
    database connections, and npm package usage.

For **Android apps**, AI Studio generates a Kotlin and Jetpack Compose project
that you can preview in a browser-based emulator, install on a physical device,
and publish to the Play Store for testing. [Learn more about building Android
apps](/docs/aistudio-android).

You can view the code that gets generated by selecting the **Code** tab in the
right-hand preview pane. The **Antigravity Agent** intelligently manages
multiple files across your stack, ensuring that changes are propagated
correctly.

### The Antigravity Agent {% id="antigravity-agent" %}

The **Antigravity Agent** is the main AI functionality within [Google
Antigravity](https://antigravity.google) and now the core components of the
agent harness is powering the Build mode experience in Google AI Studio. It goes
beyond simple code generation by maintaining context of your entire project,
managing multiple files, and understanding complex instructions to build robust,
full-stack applications.

Key capabilities include:

- **Context awareness**: Maintains context of previous prompts and file states.
- **Multi-file management**: Handles dependencies across multiple files.
- **Verified execution**: Verifies code updates to reduce hallucinations.

## Full-stack capabilities {% id="full-stack" %}

Google AI Studio unlocks the power of the modern web ecosystem, allowing you to
build more than just client-side prototypes.

- **Server-side runtime & npm**: Use the vast library of npm packages. The
    agent will automatically identify and install packages as needed for your
    app (e.g., specific libraries for data visualization or API clients). You
    can also request specific packages if desired.

- **Secrets management**: Securely store API keys and secrets in the
    **Settings** menu. These are accessible in your server-side code, keeping
    them safe from client-side exposure.

- **Multiplayer**: Build real-time collaborative experiences directly within
    AI Studio. The server-side runtime manages the state and connections
    required
    for users to interact together.

- **Firebase Firestore and Authentication**: Automatically provision and set
    up Firebase, including Firestore database (persistent data storage) and
    Firebase Authentication (sign-in flows, specifically "Sign in with
    Google"). The agent handles the entire setup process and even writes the
    code in your app for these services.

- **Google Workspace integrations**: Connect your app to Google Workspace
    APIs like Gmail, Sheets, Docs, Drive, Calendar, and more. AI Studio handles
    all the OAuth configuration automatically.

[Learn more about developing full-stack apps](/docs/aistudio-fullstack)

### Android apps {% id="android" %}

You can also build native Android apps using Kotlin and Jetpack Compose.
Preview your app in a browser-based Android emulator, install it on a physical
device using ADB in the browser, and publish to the Play Store for internal
testing.

AI Studio also integrates with
[Firebase](https://firebase.google.com/docs/ai-assistance/ai-studio-integration)
for Android apps to automatically provision **Firebase AI Logic** and **Firebase
App Check** (for secure client-side Gemini API calls without exposing raw API
keys), as well as **Cloud Firestore** and **Firebase Authentication**.

[Learn more about building Android apps](/docs/aistudio-android)

## Continue building {% id="continue-building" %}

Once Google AI Studio generates the initial code for your application, you
can continue refining it:

### Build in Google AI Studio {% id="build-google" %}

- **Iterate with Gemini**: Use the chat panel in **Build mode** to ask Gemini
    to make modifications, add new features, or change the styling.

- **Edit the code directly**: Open the **Code tab** in the preview panel to
    make live edits.

### Develop externally {% id="develop-externally" %}

For more advanced workflows, you can sync or export the code to work in your
preferred environment:

- **Sync with GitHub**: Connect your app to a GitHub repository to enable
    two-way sync. You can push changes prompted in AI Studio directly to your
    repository with AI-generated commit messages, or pull changes made locally
    in your IDE or by teammates back into AI Studio. Manage your sync status
    anytime in the **GitHub** tab in Settings.

- **Download and develop locally**: Export the generated code as a **ZIP
    file** and import it into your code editor.

## Key features {% id="key-features" %}

Google AI Studio includes several features to make the building process
intuitive and visual:

- **Create and iterate on full stack apps**: Create full stack apps with just
  a prompt and iterate through chat or **annotation mode**. Annotation mode
  lets you highlight any part of your app's UI and describe the
  change you want.

- **Share and deploy your app**: You can share your creations with others to
  collaborate or showcase your work. When sharing, API calls count toward your
  usage limits. If you use paid models, costs may apply. Then when your app is
  ready, deploy to Cloud Run.

- **App gallery**: The App Gallery provides a visual library of project ideas.
  You can browse what's possible with Gemini, preview applications instantly,
  and remix them to make them your own.

## Deploy or archive your app {% id="deploy-or" %}

Once your application is ready, you can deploy it:

- **Cloud Run**: Deploy your application as a scalable service.
    Pricing for [Google Cloud Run](https://cloud.google.com/run) may apply based
    on usage. To learn more about deployment, see
    [Deploying from Google AI Studio](/docs/aistudio-deploying).

- **GitHub**: Sync your project with a new or existing GitHub repository to
    manage source code or collaborate with teammates.

## Limitations {% id="limitations" %}

This section lists current limitations of build mode in Google AI Studio.

### API Key management {% id="api-key-management" %}

When you create a new web app that uses the Gemini API, AI Studio automatically
configures your Gemini API key as a secret in the app's server-side environment.
You can view and manage this key in the **Secrets** panel.

- **Automatic setup**: Your `GEMINI_API_KEY` is set up for you — no manual
    configuration is required to start building.

- **Server-side only**: API keys are injected into the server-side runtime and
    are never included in client-side code.

- **Existing apps**: For apps built before May 14, 2026, the agent will
    automatically upgrade your Gemini API integration to the recommended
    server-side approach the next time you modify the app's Gemini features.

#### Android apps {% id="android-api-key-management" %}

When building Android apps, AI Studio uses
[Firebase AI Logic and Firebase App Check](/docs/aistudio-android#firebase-integration)
instead of a raw API key, so credentials are never embedded in your APK.

### Deployment outside Google AI Studio {% id="deployment-outside-google-ai-studio" %}

- **Cloud Run**: When you deploy to Cloud Run from AI Studio, your API key is
    included securely in the server-side environment. The deployed app will use
    your API key for all users' Gemini API calls.

- **ZIP download**: If you download your app as a ZIP file to run it
    elsewhere, you will need to set up the `GEMINI_API_KEY` environment variable
    in your hosting environment. Since your app's Gemini API calls are made from
    server-side code, the key is not exposed to end users.

### Error when sharing apps {% id="error-when-sharing-apps" %}

If you share your app and your end user runs into a **403 Access Restricted**
error when using the shared URL, it may be due to one of the following:

- **Browser extensions**: Privacy extensions like Privacy Badger may be blocking the app. Disable the extension to avoid the error.
- **Build issues**: There may be issues with the current code. Prompt the
    agent to "fix any build issues with the current code" and then reshare the
    URL.

## FAQ {% id="faq" %}

### What is Build in AI Studio? {% id="what-is-build" %}

AI Studio Build is a platform designed to take you from a simple prompt to a
production-ready, AI-powered application using Gemini. Describe what you
want to build with a prompt, and Gemini will generate an app for you. You
can also explore our gallery to see what's possible with the Gemini API,
and remix apps to make them your own.

### How does Build handle my Gemini API key? {% id="how-api-key" %}

When you create a web app that uses the Gemini API, AI Studio automatically sets
up your Gemini API key as a server-side secret. Your app's Gemini API calls are
made from server-side code using this key, so it is never exposed in the
browser. You can view your API key in the **Secrets** panel in Settings. For
Android apps, AI Studio uses
[Firebase AI Logic and Firebase App Check](/docs/aistudio-android#firebase-integration)
to make secure client-side calls without embedding an API key in the app binary.

### Is my API key exposed when sharing apps? {% id="api-key-exposed" %}

No. Your API key is stored as a server-side secret and is never included in
client-side code. When you share your app, other users can use it, but they
cannot see your API key.

When sharing your apps with others, API calls count toward your usage limits.
If you use paid models, costs may apply. AI Studio will give you a heads-up
during setup and before you share if your app could incur costs.

### Who can see my apps? {% id="who-can-see" %}

By default your app is private. You can share your app with other users to
let them use it. Users you share your app with can see its code and fork it
for their own purposes. If you share your app with edit permission, the
other users can edit the code of your app.

### Can I run apps outside of AI Studio? {% id="run-outside" %}

Yes. You can deploy your app to
[Cloud Run](https://cloud.google.com/run) from AI Studio, which
gives your app a public URL with your API key securely configured in the
server-side environment. You can also download your app as a ZIP file and
host it elsewhere — you'll need to set the `GEMINI_API_KEY` environment
variable in your hosting environment. Since Gemini API calls are made from
server-side code, your key stays secure.

To learn more about deployment options, see [Deploying from Google AI Studio](/docs/aistudio-deploying).

### Can I develop apps locally with my own tools and then share them here? {% id="locally-develop" %}

Yes. You can connect your AI Studio app to a GitHub repository to develop
locally using your preferred code editor or CLI tools, push your changes to
GitHub, and then pull those updates directly back into AI Studio using the
**GitHub** tab in Settings.

### How can I use a database or other storage with my apps? {% id="database-storage" %}

AI Studio apps are standard apps running in a Cloud Run container. You can
use any storage solution that you can connect to over a network, so long
as there is not a firewall preventing access from a dynamic IP range.

We are working on adding direct support for storage in the future, which
you will be able to configure directly within AI Studio.

### How can I access the microphone, webcam, and other Navigator APIs? {% id="navigator-apis" %}

To ensure that viewers are aware of an app’s usage of their webcam or other
devices, we require an extra acknowledgement before the app can access
these [Navigator APIs](https://developer.mozilla.org/en-US/docs/Web/API/Navigator).
App creators can add these permission requests to their app’s
`metadata.json` file. For example:

```json
{
  "name": "My app",
  "requestFramePermissions": [
    "microphone",
    "camera",
    "display-capture",
    "geolocation",
    "bluetooth",
    "clipboard-read",
    "serial",
    "usb"
  ]
}
```

Supported values for `requestFramePermissions` are a subset of the
standard [policy-controlled features](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md).

### How can I use GitHub with my apps? {% id="github-integration" %}

AI Studio supports two-way sync with GitHub:

- **Import a repository**: In Build mode, select **Import from GitHub**
    from the **Add files** (+ icon) menu in the prompt input box to import
    existing code.

- **Link a repository**: In Settings, open the **GitHub** tab to create a
    new GitHub repository from your app or link to an existing one.

- **Two-way sync**: Push changes prompted in AI Studio directly to your
    repository with AI-generated commit messages, or pull changes made
    externally (such as local IDE edits or teammate pull requests) back into AI
    Studio.

- **Resolve merge conflicts**: If changes conflict when syncing with
    GitHub, AI Studio provides a **Resolve conflicts** dialog with a
    side-by-side diff viewer, allowing you to review differences and choose
    whether to keep the AI Studio or GitHub version for each conflicted file.

### Can I give other users edit access to my app? {% id="edit-access" %}

AI Studio doesn't support direct real-time collaborative editing.
However, you can collaborate with teammates by linking your app to a shared
GitHub repository. Teammates can push changes or open pull requests on GitHub,
and you can pull those updates into AI Studio.

### Why was my app flagged for policy violation? {% id="policy-violation" %}

We have systems that automatically review apps to ensure they comply with
our policies. If we find that an app violates our policies, the app will
be removed from AI Studio. Policy violations can include, but are not
limited to, the following:

- Apps that contain malware, phishing, or impersonation
- Apps that display or distribute content that violates child sexual abuse imagery policy
- Apps that display or distribute content that violates harassment policy
- Apps that display or distribute content that violates hate speech policy
- Apps that display or distribute content that violates human trafficking policy
- Apps that display or distribute content that violates sexually explicit content policy
- Apps that display or distribute content that violates violence and gore policy
- Apps that display or distribute content that violates harmful or dangerous policy

If your app has been flagged for a policy violation, and you believe it in
error, you can submit an appeal. Repeated violations of our policies may
result in the termination of your access to AI Studio.

### What are my responsibilities as an app developer? {% id="developer-responsibilities" %}

As a reminder, as the owner of your application, you are responsible for
its behavior and all data it handles. This includes:

- **Legal Compliance and Third Party Rights:** Ensuring your app complies
  with all applicable laws and regulations and does not violate the rights
  of others, including intellectual property and privacy rights.

- **Content Monitoring:** Compliance with additional terms may apply to
  other services used by your app. For example,
  [Google Cloud Terms of Service](https://cloud.google.com/terms),
  applicable to Firestore, require customers hosting third-party content to
  publish policies defining what content is prohibited (e.g., illegal
  content) and monitor for presence of that illegal content.

- **Safe Implementation:** Implementing the necessary safeguards and
  moderation tools to prevent your application from being misused.

Be aware of the [use restrictions](/docs/terms#use-restrictions)
in the Terms of Service.

### What terms apply to apps in the app gallery in AI Studio? {% id="gallery-terms" %}

The [Gemini API Additional Terms of Service](/docs/terms)
apply to use of apps featured in the app gallery in AI Studio, unless
otherwise noted.

## What's next {% id="whats-next" %}

- [Developing Full-Stack Apps](/docs/aistudio-fullstack) (web)
- [Build Android Apps](/docs/aistudio-android)
- See examples in the [App Gallery][2].

[1]: https://aistudio.google.com/apps
[2]: https://aistudio.google.com/apps?source=showcase

# Develop full-stack apps in Google AI Studio
Source: https://aistudio.google.com/docs/aistudio-fullstack
Description: Learn how to develop full-stack applications with server-side logic in Google AI Studio.

Google AI Studio now supports full-stack development, enabling you to build
applications that go beyond client-side prototypes. With a
server-side runtime, you can manage secrets, connect to external APIs, and build
real-time multiplayer experiences.

## Server-side runtime {% id="server-side" %}

Google AI Studio applications can now include a server-side component (Node.js).
This lets you:

- **Execute server-side logic**: Run code that shouldn't be exposed to the
    client.

- **Access npm packages**: The [Antigravity Agent](https://antigravity.google/docs/agent)
    can install and use packages from the vast npm ecosystem.

- **Handle secrets**: Securely use API keys and credentials.

### Use npm packages {% id="use-npm-packages" %}

You don't need to manually run `npm install`. Simply ask the Agent to add
functionality that requires a package, and it will handle the installation and
import.

**Example**: > "Use `axios` to fetch data from the external API."

## Manage secrets securely {% id="secrets" %}

With server-side code and secrets management, you can now build apps that
interact with the world.

### Gemini API key {% id="gemini-api-key" %}

When you create a new app that uses the Gemini API, AI Studio automatically
configures your `GEMINI_API_KEY` as a server-side secret — no manual setup
required. You can view this key in the **Secrets** panel in Settings. Your
app's Gemini API calls are made from server-side code using this key, so
it is never exposed in the browser.

### Third-party API keys {% id="third-party-keys" %}

For other services, you can add API keys manually:

- **Third-party APIs**: Connect to services like Stripe, SendGrid, or custom
    REST APIs.

- **Databases**: Connect to external databases (e.g., via Supabase, Firebase,
    or MongoDB Atlas) to persist data beyond the session.

When building real-world apps, you often need to connect to third-party services
(like Twilio, Slack, or databases) that require API keys. You can add keys
manually with the following steps:

1. **Add a secret**: Go to the **Settings** menu in Google AI Studio and look
    for the Secrets section.

2. **Store your key**: Add your API keys or secret tokens here.
3. **Access in code**: The Agent can write server-side code that accesses these
    secrets securely (typically via environment variables), ensuring they are
    never exposed to the client-side browser.

When needed, the agent will
also show a card in the chat prompting you to add keys whenever a new secret is
needed or when a key new key is detected in the project's env variables.

### Firebase integration for database & authentication {% id="firebase-integration" %}

Google AI Studio now makes it easy to add a database or authentication to your
app through a
[Firebase integration](https://firebase.google.com/docs/ai-assistance/ai-studio-integration).
The Antigravity Agent can provision and set up the following services for you
automatically:

- **Firestore database**: a flexible, scalable NoSQL cloud database to store
    and sync data for client- and server-side development.

- **Firebase Authentication**: allow your users to securely sign in to your
    application using "Sign in with Google" flows.

Simply ask the agent to "add a database to my app" or "set up Google Sign-in",
and it will handle the necessary configuration and code generation for you. When
building [Android apps](/docs/aistudio-android#firebase-integration), the
Firebase integration also provisions **Firebase AI Logic** and **Firebase App
Check** for secure client-side Gemini API calls.

Firebase lets you start for free, and optionally scale with a paid account
whenever you're ready for more quota or to use paid features.

## Google Workspace APIs {% id="workspace" %}

Google AI Studio lets you build apps that connect to Google Workspace APIs, so
your users can work with their real data: emails, spreadsheets, documents,
calendar events, and more, all within your app. You no longer need to set up a
Google Cloud project, configure OAuth, or manage your API manually.

### How it works {% id="workspace-how" %}

You can add a Workspace integration in two ways:

- **Describe it in the chat panel**: Just tell the agent what you want in the
  chat panel at the bottom. For example, *"Build an expense tracker that logs
  receipts to my Google Sheet"* or *"Create a dashboard that summarizes my
  unread Gmail messages."*
- **Select from the integrations panel**: Open the **Integrations** panel in
  the right-hand sidebar of Build mode and enable the Workspace app you want to
  connect.

When you add a Workspace app, AI Studio automatically:

1. Wires up the necessary Google API for your app.
1. Generates the server-side code to call the API.
1. Adds a secure "Sign in with Google" flow so end users of your app can
    authorize access to their own data.

### Supported apps {% id="workspace-apps" %}

The following Google Workspace apps are available:

| App | What you can build |
|-------------------|--------------------|
| Google Calendar | Read, create, and manage events and calendars |
| Google Chat | Read and interact with conversations and group spaces |
| Google Docs | Create, read, update, and format documents |
| Google Drive | Organize, search, and manage files and folders |
| Google Forms | Create surveys, update questions, and retrieve responses |
| Gmail | Read, send, and manage email content |
| Google Keep | Manage notes, lists, and attachments |
| Google Meet | Schedule and manage video calls |
| Contacts | Sync and manage contacts |
| Google Sheets | Read, write, and format spreadsheet data |
| Google Slides | Create and modify presentations |
| Google Tasks | Create, manage, and organize tasks |

### Authentication and permissions {% id="workspace-auth" %}

As the builder, you don't need to configure OAuth clients, manage credentials,
or set up a Google Cloud project. AI Studio handles all of this for you.

Apps with Workspace APIs integrated use "Sign in with Google" to authenticate
end users. When a user opens your app, they are prompted to sign in and grant
the specific permissions your app needs (for example, read-only access to their
calendar, or the ability to edit a spreadsheet). Your app only accesses the
data of the person using it. Each user authorizes access to their own account.

### Example prompts {% id="workspace-examples" %}

Here are a few ideas to get started with Workspace integrations:

- *"Build an app that reads my Google Calendar and drafts prep emails in
    Gmail for each meeting."*

- *"Create a tool that takes a Google Doc and generates a 5-slide summary
    presentation in Google Slides."*

- *"Make an expense tracker where I upload a receipt, Gemini extracts the
    details, and it logs a new row in my Google Sheet."*

### Set up OAuth {% id="oauth-setup" %}

One key use case for secrets management is to set up OAuth to connect to other
websites or apps. When your prompt includes instructions about connecting to a
3rd party app that requires OAuth authentication, the agent will provide
instructions on how to set up OAuth for that application. These instructions
will include the necessary callback URLs to configure your OAuth Application.
You can also find the callback URLs under **Integrations** in the Settings
panel.

## Build multiplayer experiences {% id="multiplayer" %}

The full-stack runtime enables real-time collaboration features.

- **Real-time state**: You can ask the Agent to build features like "a live
    chat," "a collaborative whiteboard," or "a multiplayer game."

- **Synced sessions**: The server manages the state, allowing multiple users
    to interact with the same application instance in real-time.

**Example prompt**: > "Make this a multiplayer game where players can see each
other's cursors."

### Tips for testing multiplayer apps {% id="testing-multiplayer" %}

You can test multiplayer mode in two ways before deploying your app.

1. Open your app in Google AI Studio Build mode in multiple tabs. When
    developing in Build mode, your app is in a dev container. Opening the
    app in multiple tabs will let you simulate multiple players using your app.

2. Share the app with others using the **Share** menu at the top right.
    then use the **Shared URL** from the **Integrations**
    tab of the **Share** menu to use the app with the players that you've shared
    your app with.

## Best practices {% id="best-practices" %}

- **Gemini API calls**: Your `GEMINI_API_KEY` is automatically configured as a
    server-side secret. Make Gemini API calls from your server-side code using
    this key. You can view it in the **Secrets** panel.

- **Secrets security**: Always use the Secrets manager for sensitive keys.
    Never hardcode them in your files.

- **Separation of concerns**: Keep your UI logic in the client-side framework
    (React/Angular) and your business logic/data handling on the server side.

- **Error handling**: Ensure your server-side code robustly handles errors
    from external API calls to prevent the app from crashing.

## What's Next? {% id="whats-next" %}

- [Build Apps in Google AI Studio](/docs/aistudio-build-mode)
- [Deploying from Google AI Studio](/docs/aistudio-deploying)
- [App Gallery](https://aistudio.google.com/apps?source=showcase)

# Build Android apps in Google AI Studio
Source: https://aistudio.google.com/docs/aistudio-android
Description: Learn how to build native Android apps with Kotlin and Jetpack Compose in Google AI Studio.

Google AI Studio lets you build native Android apps from a natural language
prompt. Describe the app you want, and the
[Antigravity Agent](/docs/aistudio-build-mode#antigravity-agent)
generates a complete Kotlin and [Jetpack Compose](https://developer.android.com/develop/ui/compose)
project. From your browser, you can preview your app in a browser-based Android
emulator, install it on a physical device, and publish it for testing.

Android apps also support
[Firebase integration](/docs/aistudio-android#firebase-integration) for calling
Gemini models with Firebase AI Logic and App Check, storing data in Cloud
Firestore, and signing in users with Firebase Authentication.

{% callout type="note" %} Note: Android apps in AI Studio are client-side only.
Features that require a server-side runtime, such as
[Google Workspace APIs](/docs/aistudio-fullstack#workspace),
[secrets management](/docs/aistudio-fullstack#secrets), and
[multiplayer](/docs/aistudio-fullstack#multiplayer), are available for web apps
only. {% /callout %}

## Get started {% id="get-started" %}

To start building an Android app:

1. Go to [Build mode](https://aistudio.google.com/apps) in Google AI Studio using the left-hand navigation panel.
1. Select **Android** from the platform picker.
1. Enter a prompt describing the app you want to build (for example, *"Create a
    daily task tracker with local storage"* or *"Build a recipe app that uses AI
    to suggest meals from ingredients"*).
1. The agent generates the project and launches it in the browser-based
    Android emulator.

You can then iterate on your app using the chat panel, just like the web
experience. The agent manages all files in your Android project and propagates
changes across the codebase.

## Firebase integration {% id="firebase-integration" %}

Google AI Studio integrates with
[Firebase](https://firebase.google.com/docs/ai-assistance/ai-studio-integration)
so your Android app can call Gemini models securely, persist data, and
authenticate users without a custom server-side backend. When you prompt the
agent to build features that require generative AI, a database, or sign-in, it
can automatically provision and configure the following services in your
Firebase project:

- **[Firebase AI Logic](https://firebase.google.com/docs/ai-logic) and
    [Firebase App Check](https://firebase.google.com/docs/ai-logic/app-check)**:
    Call Gemini models directly from your Android app without embedding raw API
    keys in the APK. AI Studio automatically configures App Check to verify that
    requests originate from an authentic instance of your app:

    - **Testing and sharing (debug builds)**: Uses an App Check debug token
        managed automatically by AI Studio when previewing in the browser-based
        emulator, installing over USB, or sharing with testers.
    - **Publishing to Google Play (release builds)**: Automatically switches
        to reCAPTCHA Enterprise using a pre-configured site key when building a
        release version for Google Play.

- **Cloud Firestore**: Store and sync data in a NoSQL cloud database,
    including automatically generated Firestore Security Rules
    (`firestore.rules`).

- **Firebase Authentication**: Add "Sign in with Google" flows to authenticate
    users.

You can enable Firebase from the setup card that appears in chat when you
request these features, or at any time under **Settings > Integrations**. For
details on project setup, shared quotas, and the App Check lifecycle, see
[Add Firebase to your Google AI Studio app](https://firebase.google.com/docs/ai-assistance/ai-studio-integration).

## Browser-based Android emulator {% id="emulator" %}

The Android emulator runs entirely in the cloud and streams to your browser.
You don't need to install the Android SDK, Android Studio, or a local emulator.

The emulator provides:

- **Pixel-like device simulation**: tap, scroll, and interact with your app
    just like on a real device.

- **Rotation support**: toggle between portrait and landscape orientation.
- **Live preview**: when the agent makes code changes, the app rebuilds and
    the emulator refreshes automatically.

### Emulator limitations {% id="emulator-limitations" %}

The browser-based emulator doesn't support all hardware features. The following
are not available in the emulator:

- Camera and photo capture
- NFC and Bluetooth
- GPS (location is simulated)
- Google Play services (Google Sign-In, Maps, and other Play services features
    work on a real device but not in the emulator)

## Install on a device with ADB {% id="adb" %}

You can install the built APK directly on a physical Android device connected
to your computer using USB. This uses
[WebUSB](https://developer.chrome.com/docs/capabilities/usb) to
communicate with your device through the browser. No local ADB installation
is required.

### Prerequisites {% id="prerequisites" %}

- A Chrome or Edge browser that supports WebUSB.
- An Android device with
    [Developer Options and USB Debugging](https://developer.android.com/studio/debug/dev-options)
    enabled.

- A USB cable connecting your device to your computer.

### Install the app on your device {% id="install-the-app-on-your-device" %}

1. Click **Install on Device** in the preview panel.
1. Select your Android device from the browser's USB device picker.
1. The APK is transferred and installed on your device.
1. The app launches automatically.

{% callout type="note" %}
Note: Your device may show an **"Allow USB debugging"** prompt the first time
you connect. You must accept this to proceed.
{% /callout %}

## Publish to the Play Store {% id="publish" %}

You can publish your Android app to the
[Google Play Console](https://play.google.com/console) internal
testing track, which lets you distribute the app to up to 100 testers.

### Prerequisites {% id="prerequisites" %}

- A [Google Play Developer account](https://play.google.com/console/signup)
    (requires a one-time $25 registration fee).

- A completed developer profile in the Play Console.

### Publish your app {% id="publish-your-app" %}

1. Open **Settings > Publish** in Google AI Studio.
1. Click **Publish to Play Store**.
1. Authenticate with your Google Play Developer account.
1. AI Studio signs the APK, creates the app listing (or uploads a new version),
    and publishes to the internal testing track.

1. You receive a link to share with your testers.

AI Studio manages APK signing automatically using a managed keystore. You can
customize the app listing (icon, screenshots, description) later in the Play
Console.

{% callout type="note" %}
Note: Publishing is limited to the **internal testing track** only. Production
releases must be managed directly in the Google Play Console.
{% /callout %}

## What's generated {% id="whats-generated" %}

When you build an Android app, the agent generates a standard Gradle-based
project with the following structure:

- **Build configuration**: `build.gradle.kts` files (project and app level)
    using Kotlin DSL.

- **UI layer**: [Jetpack Compose](https://developer.android.com/develop/ui/compose)
    components with [Material 3](https://m3.material.io/) theming.

- **Architecture**: single-activity architecture with ViewModels and data
    classes.

- **Resources**: `AndroidManifest.xml`, drawables, strings, and other Android
    resources.

- **Firebase configuration** (when Firebase is enabled):
    `google-services.json`, `firebase_applet_config.xml`, and `firestore.rules`.

The agent automatically manages Gradle dependencies, adding packages from Maven
and Google repositories as needed.

You can view and edit the generated code using the **Code** tab in the preview
panel. To continue development in Android Studio, download the project as a
**ZIP file**.

## Limitations {% id="limitations" %}

Android app building in AI Studio has the following limitations:

### Platform limitations {% id="platform-limitations" %}

- **Client-side only**: Android apps don't include a server-side component.
    Features requiring a server runtime (secrets management, multiplayer, Google
    Workspace APIs) are not available.

- **Single-activity architecture**: only single-activity, single-module
    projects are supported.

- **Jetpack Compose only**: apps use Kotlin and Jetpack Compose. Java and
    XML layouts are not supported.

- **No NDK or native code**: C and C++ code is not supported.
- **No Wear OS or Android TV**: only phone and tablet form factors are
    supported.

### Export limitations {% id="export-limitations" %}

- **ZIP download only**: you can download the project as a ZIP file. GitHub
    export is not yet available for Android projects.

## What's next {% id="whats-next" %}

- [Build apps in Google AI Studio](/docs/aistudio-build-mode)
- [Developing Full-Stack Apps](/docs/aistudio-fullstack) (web)
- See examples in the [App Gallery](https://aistudio.google.com/apps?source=showcase).

# Deploying from Google AI Studio
Source: https://aistudio.google.com/docs/aistudio-deploying
Description: Deploy full-stack generative AI applications directly from Google AI Studio.

Google AI Studio lets you to deploy your full-stack applications directly
from Build mode. This provides a fast path from prototype to a
managed, scalable production environment.

## Deployment options {% id="deployment-options" %}

To deploy your application from AI Studio Build mode, the requirements depend
on the tier you use:

* [**Google Cloud Starter Tier**](https://docs.cloud.google.com/docs/starter-tier):
    Lets eligible accounts publish up to 2 full-stack applications without
    setting up a Google Cloud project or billing account.

* **Standard deployment**: Requires a Google Cloud project linked to your
    AI Studio account and billing enabled on that project.

## About the Starter Tier {% id="about-the-starter-tier" %}

The Google Cloud Starter Tier provides a streamlined path for eligible accounts
to deploy applications to Google Cloud directly from Google AI Studio. You don't
need to set up a full Google Cloud environment or billing account.

Each Google AI Studio deployment creates a corresponding service in
Cloud Run. For services deployed in Google AI Studio with Starter
Tier, the following limitations apply:

* You can deploy up to two services.
* Your services are deployed in a
  [single Cloud Run region](https://docs.cloud.google.com/run/docs/locations).

### Starter Tier eligibility {% id="starter-tier-eligibility" %}

Not all accounts are eligible for the Google Cloud Starter Tier. Your account
may be ineligible if any of the following apply:

* You're signed in with a Google Workspace account (including paid or free
  Google Workspace, Google Workspace for Education, or Google for Nonprofits
  subscriptions).
* You have an active or prior paid Google Cloud billing account.
* We don't have enough evidence from your account activity to grant Starter Tier
  access at this time.

The Google AI Studio support team can't override Starter Tier eligibility. If
your account isn't eligible, attach a billing account and use
[standard deployment](/docs/aistudio-deploying#standard-deployment) to publish
apps.

## Deploy with the Starter Tier {% id="starter-tier-deployment-steps" %}

After designing your app in Build mode, deploy it with Starter Tier:

1. Click the **Publish** button in the top right corner.
1. Click **Get Started**.
1. Click **Publish App**.

Once deployment is complete, AI Studio provides a Cloud Run URL where you can
access your live application.

{% callout type="note" %}
Note: If you already have 2 applications deployed, you will be asked to either
      unpublish one of the applications or upgrade to a paid account. You may
      also need to upgrade to a paid account if you don't have starter tier
      available.
{% /callout %}

## Custom URLs for AI Studio {% id="custom-urls" %}

When publishing an application from Google AI Studio, you can set a custom,
memorable subdomain under `ai.studio` (for example,
`https://your-app-name.ai.studio`).

Google AI Studio requires subdomains to be globally unique across all projects,
and assigns them on a first-come, first-served basis. If another project
already uses a name, AI Studio prompts you to choose a different one. If you
unpublish or delete an application, its custom URL is released and becomes
available for other users to claim.

### Set a custom URL {% id="set-custom-url" %}

To set or update a custom URL for your application:

1. Open your application in Google AI Studio in **Build** mode.
1. Click **Publish** in the top right corner.
1. In the deployment configuration, enter your preferred subdomain in the
   **Custom URL** field or accept the suggested URL.
1. Click **Publish App**.

To transfer an existing custom URL to a different application, you must first
unpublish or delete the application which is assigned that custom URL, and then
publish your new application using the chosen subdomain.

### Report trademark or copyright issues {% id="report-issues" %}

Custom subdomains must comply with the
[Google Terms of Service](https://policies.google.com/terms). If you notice a
custom URL that infringes on a trademark or uses a copyrighted name without
permission, you can report it using the
[Google Legal Troubleshooter](https://support.google.com/legal/troubleshooter/1114905).

## Standard deployment {% id="standard-deployment" %}

As your applications evolve, you might require capabilities beyond the Starter
Tier, such as higher quotas or increased compute resources or other
Google Cloud products not available in the Starter Tier. To unlock
these capabilities, you can convert your fully managed Starter Tier project into
a standard Google Cloud project.

This ensures that you can scale seamlessly without losing
your progress. Follow the steps to
[create a Cloud Billing account](https://docs.cloud.google.com/billing/docs/how-to/create-billing-account#create-new-billing-account),
formally accept the standard Google Cloud Terms of Service, and
[upgrade to a standard Google Cloud project](https://docs.cloud.google.com/docs/starter-tier#upgradee).
For more information, see
[Setup for Paid accounts](https://docs.cloud.google.com/billing/docs/in-product-billing-setup#paid-setup).

To learn more about billing tiers, see [Billing](/docs/billing).

## Delete your application {% id="delete-application" %}

If you no longer need your app, you can delete it in Google AI Studio
by following these instructions:

1. In Google AI Studio, go to your
   [Apps page](https://aistudio.google.com/app/apps).

1. In the left menu, select **Apps**.
1. Hold the pointer over the app you want to delete.
1. Click the trash can icon on the right-side of the row to delete the app.

## What's next {% id="whats-next" %}

* Learn more about the
    [Google Cloud Starter Tier](https://docs.cloud.google.com/docs/starter-tier).

* Read about [Billing](/docs/billing) in Gemini API.

# Agents in AI Studio playground
Source: https://aistudio.google.com/docs/aistudio-agents
Description: Learn how to use Agents in AI Studio

Google AI Studio Playground provides a visual interface to prototype and learn
how to build managed agents without having to create and write API calls.

To get started, navigate to the **Playground** tab in the navigation panel of
Google AI Studio, and switch the toggle to **Agents**.

## Pre-built templates {% id="pre-built-templates" %}

The **Agents** tab has a series of templates that
pre-configure the base Antigravity Agent by setting tool and environment
configurations. All the templates are open-source and published under
the [google-gemini/gemini-managed-agents-templates](https://github.com/google-gemini/gemini-managed-agents-templates/) repository. Exploring these templates is a great way to learn how to build and structure your own managed agent.

For example, when you pick the AI Radio template, it enables all the allowed
tools, and links a specialized `AGENTS.md` file and skills for radio show
production. You can view these settings on the Playground UI under the
**Environment** section, by clicking on the **Sources** button.

Important: When you run these templates, the agent inside the sandbox has access
to the Gemini API. It will execute calls using your configured API key, which
can incur additional token charges on your account. See [safety and cost
management](/docs/aistudio-agents#safety-and-cost-management) section for more details.

## Tool configuration {% id="tool-configuration" %}

Under the Agent settings in the Playground, you can toggle access to the
following built-in tools:

* **Google Search:** Access the open web for real-time information grounding.
* **URL Context:** Fetch and parse the text content of specific web page URLs.
* **Code Execution:** Run Bash and Python commands directly within the
    isolated sandbox environment.

* **Filesystem Tools:** Read, write, list, and delete files inside the
    workspace.

## Environment Configuration {% id="environment-configuration" %}

Managed agents run within a secure, ephemeral Linux sandbox (the environment) that provides the workspace and tools they need to operate. To learn more, see the [managed agent environment](/docs/agent-environment) guide.

### Controlling agent behavior {% id="controlling-agent-behavior" %}

The agent's behavior, persona, and capabilities are predominantly determined by
the files present in its environment. The agent automatically detects and loads
configurations from a special `.agents` folder:

* **`AGENTS.md`**: Pre-loaded into the agent's context to define system instructions and persona.
* **`SKILL.md`**: Located under respective skill folders (e.g., `.agents/skills/my-skill/SKILL.md`) to define specific capabilities and workflows.

### Provisioning the Environment {% id="provisioning-the-environment" %}

You can configure the environment to be used by the agent by mounting files to
the environment before you start a session. You can either build a new
environment by mounting sources, or restore a previous one:

* **To create a new environment**, click **Add Sources** in the Environment settings panel and choose from the following source types:

{% table %}
* Source type
* Description
* Mounting path
---
* **Inline Files**
* Write or paste configuration files, mock datasets, or utility scripts (up to 100KB) directly into the Playground UI.
* User-defined destination path (e.g., `/workspace/scripts/parser.py`).
---
* **Google Cloud Storage**
*
  Mount a public or private Cloud Storage bucket.

  Private buckets require a standard OAuth 2.0 Bearer token. For more information, see [Private sources](/docs/agent-environment#private-sources).
* Maps a GCS bucket path (e.g., `gs://your-bucket-name/data/`) to a workspace directory (e.g., `/workspace/data/`).
---
* **GitHub Repositories**
*
  Clone public or private codebases.

  Private repositories require Basic authentication with your GitHub Personal Access Token (PAT). For more information, see [Private sources](/docs/agent-environment#private-sources).
* Cloned directly into `/workspace/` (typically under `/workspace/<repo-name>`).
{% /table %}

* **To restore a previous environment**, you can [reuse an existing environment ID](/docs/aistudio-agents#reusing-an-existing-environment-id) to clone and fork its exact state.

### Reusing an existing environment ID {% id="reusing-an-existing-environment-id" %}

If you have already spent time setting up a sandbox environment, you don't have
to start from scratch. To use an existing environment:

1. Go to the Environments panel in AI Studio and toggle **Type** to **Existing**
2. Enter the **Environment ID** (e.g., `env_abc123`)

For more information, see [Configure an environment](/docs/agent-environment#configure-an-environment). You can also retrieve the current session's Environment ID from the Environment tab in the UI.

Once you send your first message to the agent, the environment configuration
becomes fixed for that session. You cannot mount new sources or modify the
network allowlist while the interaction is actively running.

## Download the environment {% id="download-the-environment" %}

Once an environment is created, you can download the environment snapshot at any
time using the **Download** button in the Environment settings of the AI Studio
Playground to retrieve environment files as a tarball.

## Safety and Cost Management {% id="safety-and-cost-management" %}

### Managing Token Consumption {% id="managing-token-consumption" %}

Unlike a standard chat request that produces a single output, the Antigravity
Agent executes an autonomous workflow. It plans, runs code, observes results,
and iterates. This means a single prompt can result in unbounded token
consumption.

To manage costs, **provide clear termination criteria in your prompts and scope
the tasks narrowly for the agent**. A good example could be a prompt like
*Review the pull request and stop once you have generated the markdown summary.
Do not attempt to write the fix yourself*.

Important: If you see the agent running for a long time or not going in the
right direction (by observing its thoughts and tool calls), you can use the
**Stop** button to stop the agent at any time to avoid unnecessary token
consumption.

### Additional Costs {% id="additional-costs" %}

By default, all agent templates on the Playground have access to the Gemini API
service and can make API calls from the environment in order to fulfill
requests. These may incur additional costs which will not be reflected in token
consumption.

Similarly, if you add other external services, the agent may incur additional
costs by calling these services on your behalf.

### Network Allow List {% id="network-allow-list" %}

By default, on AI Studio all outbound network requests from within
your agent's sandbox environment are tightly controlled and restricted to ensure
security. To grant your agent the ability to reach external APIs, web services,
or package managers, you must explicitly declare them:

1. Go to the Environments panel in AI Studio.
2. Select the **rules** button next to **Network**.
3. In the **Network configuration** panel, click **Add to allowlist** and fill in the relevant details:
    * **Domain Restriction:** Only the specific domains or wildcard patterns
      added to the list can be accessed by the agent's virtual machine. For
      example, you can input exact domains like `api.github.com` or broad
      patterns like `*.googleapis.com`.
    * **Add HTTP Header and Token Injection:** Use the **Add HTTP header**
      option to securely inject required credentials (such as an API token) for
      a specific domain. These credentials pass safely through an egress proxy
      and are never exposed directly as raw text inside the agent sandbox.

Always exercise caution when adding domains to your allowlist. Granting the
agent access to authenticated services means it can act on your behalf, which
could lead to unintended actions if not carefully monitored.

{% callout type="note" %}
  **Important:**
  * Authenticated Gemini API (using your linked API key) is enabled by default for all agent calls through AI Studio Playground.
  * When you use the API, the network is open by default. See [API documentation](/docs/agent-environment#network-configuration) for details.
{% /callout %}

### Credentials best practices {% id="credentials-best-practices" %}

If your workflow requires the agent to authenticate with external services, you
are responsible for provisioning and scoping those credentials. Follow these
guidelines to reduce risk:

* **Use least-privilege credentials:** Create service accounts or API keys
    with only the permissions your agent needs. Avoid passing credentials with
    broad or administrative access.

* **Prefer short-lived tokens:** Where possible, use time-limited credentials
    or tokens that expire rather than long-lived API keys.

* **Assume full access:** The agent may use any credential it has access to in
    order to complete the task you have given it. Only provide credentials whose
    full scope of access you are willing to grant.

* **Rotate credentials regularly:** Treat credentials shared with the agent
    the same way you would treat any programmatic credential; rotate them on a
    regular schedule.

### Connecting external tools and APIs {% id="connecting-external-tools-and-apis" %}

You can connect external tools and APIs (such as Model Context Protocol / MCP
servers) to extend the agent's capabilities. When doing so:

* Only connect tools from sources you trust. A malicious or poorly written
    tool could expose data or perform unintended actions.

* Configure tools with the minimum permissions required for your use case. If
    a tool supports read-only mode, prefer that unless writes are strictly
    necessary.

* Before connecting a tool to a production data source, test it against sample
    or synthetic data to verify the agent uses it as expected.

### Human oversight {% id="human-oversight" %}

Agents can reason, plan, and execute multi-step workflows with a high degree of
autonomy. While this is powerful, it also means you should apply appropriate
oversight; especially for tasks that modify data or interact with external
systems.

Always verify critical outputs such as generated code, data transformations, or
configuration changes before you deploy them.

# LearnLM
Source: https://aistudio.google.com/docs/learnlm
Description: Use pedagogical learning capabilities with standard Gemini models in AI Studio.

{% callout type="note" %}
This feature is in [preview](/docs/models#preview).
{% /callout %}

LearnLM is no longer a separate listing in AI Studio. Instead, LearnLM
capabilities have been integrated into Gemini starting with the
[2.5 model series](/docs/models).

To learn more about LearnLM's current status, visit the [LearnLM](https://cloud.google.com/solutions/learnlm) documentation.

# Troubleshoot Google AI Studio
Source: https://aistudio.google.com/docs/troubleshoot-ai-studio
Description: This page provides suggestions for troubleshooting Google AI Studio if you encounter issues.

This page provides suggestions for troubleshooting Google AI Studio if you
encounter issues.

## Understand 403 Access Restricted errors {% id="understand-403-errors" %}

If you see a 403 Access Restricted error, you are using Google AI Studio in a
way that does not follow the [Terms of Service](/docs/terms). One common reason is
you are not located in a [supported region](/docs/available-regions).

## Verify age requirements for your Google Account {% id="age-requirements" %}

You must be 18 or older to use Google AI Studio. You may be redirected to this
section while trying to open [Google AI Studio](https://aistudio.google.com/).
If so, verify that your Google Account meets the age requirement:

* **Check your birthday:** Confirm your date of birth is set to 18 or older in
  your [birthday settings](https://myaccount.google.com/birthday).
* **Verify your age:** Complete
  [age verification](https://myaccount.google.com/age-verification) on your
  Google Account. For verification options, see
  [Verify your age on your Google Account](https://support.google.com/accounts/answer/10071085).
* **Match your ID date of birth:** If you verify your age with an ID, check your
  account settings. Make sure your
  [birthday](https://myaccount.google.com/birthday) matches the date on your ID.
* **Google Workspace accounts:** For Google Workspace for Education accounts,
  contact your administrator. They can confirm if your account is designated as
  18 or older. See
  [Access Google AI Studio with your Workspace account](/docs/workspace) for
  details.

## Resolve No Content responses on Google AI Studio {% id="resolve-no-content" %}

{% callout type="warning" %}
A **No Content** message appears on Google AI Studio if the content is blocked
for any reason. To see more details, hold the pointer over **No Content** and
click **Safety**.
{% /callout %}

If the response was blocked due to [safety settings](/docs/safety-settings) and
you considered the [safety risks](/docs/safety-guidance) for your use case, you
can modify the
[safety settings](/docs/safety-settings#safety-settings-ai-studio)
to influence the returned response.

If the response was blocked but not due to the safety settings, the query or
response may violate the [Terms of Service](/docs/terms) or be otherwise unsupported.

## Check token usage and limits {% id="check-token-usage" %}

When you have a prompt open, the **Text Preview** button at the bottom of the
screen shows the current tokens used for the content of your prompt and the
maximum token count for the model being used.

## Google Cloud IAM permissions for AI Studio {% id="iam-permissions" %}

Members of a Google Cloud project need specific Identity and Access Management
(IAM) permissions to perform actions in Google AI Studio. For more information
about these identities, see the
[IAM principals overview](https://docs.cloud.google.com/iam/docs/principals-overview).

Users with the **Editor** or **Owner** roles in the associated Google Cloud
project have full permissions to view dashboards and manage Gemini API keys.
Users with the **Viewer** role can view dashboards and API keys, but cannot
create, update, or delete them.

For more granular control, refer to the following table for the specific
permissions required for each AI Studio feature. For instructions on how to
grant these permissions, see
[Granting, changing, and revoking access to resources](https://cloud.google.com/iam/docs/granting-changing-revoking-access)
in the Google Cloud documentation.

{% table %}
* AI Studio feature
* Required IAM permissions
* Additional requirements
---
* **Search project** (import projects)
* `resourcemanager.projects.get`
*  &nbsp;
---
* **Rename project**
* `resourcemanager.projects.update`
* &nbsp;
---
* **Display quota tier**
* N/A
* &nbsp;
---
* **Create API key**
* Have **Search project** permissions, and:

  `apikeys.keys.create`

  `serviceusage.services.enable`

  `iam.serviceAccountApiKeyBindings.create`

  `iam.serviceAccounts.create`
*
---
* **List API keys**
* Have **Search project** permissions, and:

  `apikeys.keys.list`

  `serviceusage.services.get`
* The Google Cloud project must have the [Generative Language API](https://console.cloud.google.com/apis/library/generativelanguage.googleapis.com) enabled.
---
* **Rename API keys**
* `apikeys.keys.update`
* &nbsp;
---
* **Delete API keys**
* `apikeys.keys.delete`
* &nbsp;
---
* **Usage dashboard**
* Have **Search project** permissions, and:

  `monitoring.timeSeries.list`
* &nbsp;
---
* **Rate limit dashboard**
* Have **Usage dashboard** permissions, and:

  `cloudquotas.quotas.get`
* &nbsp;
---
* **Spend (Billing cap)**
* `billing.resourceCosts.get` (to view spend)

  `billing.resourcebudgets.read` (to view cap)

  `billing.resourcebudgets.write` (to set cap)
* &nbsp;
---
* **Billing dashboard**
* `billing.accounts.get`
* &nbsp;
{% /table %}

### Other access checks {% id="other-access-checks" %}

In addition to Google Cloud IAM permissions, AI Studio also performs security
and compliance checks. You might encounter a `PERMISSION_DENIED` or access
restriction error in the AI Studio interface or in API responses if you do not
meet the following requirements:

* **Security checks:** Your request must pass automated security checks.
* **Terms of Service:** You must accept the Google Terms of Service and
  Generative AI Additional Terms of Service.
* **Supported region:** You must be located in a
  [supported region](/docs/available-regions).
* **Age requirements:** You must meet the
  [age requirements](/docs/troubleshoot-ai-studio#age-requirements) (18+) on
  your Google Account.
* **Trust & Safety:** The Google Cloud project must not be flagged for abuse.

# Access Google AI Studio with your Workspace account
Source: https://aistudio.google.com/docs/workspace
Description: Access Google AI Studio and manage settings with a Workspace account.

All [Google Workspace](https://workspace.google.com) users have access to AI
Studio by default. If you're a Workspace user and you want to get started with
AI Studio, check out the
[AI Studio quickstart](/docs/ai-studio-quickstart).

## Troubleshooting {% id="troubleshooting" %}

If access to AI Studio is disabled for your Google Workspace account, you might
see an error like the following:

`We are sorry, but you do not have access to Google AI Studio. Please contact
your Organization Administrator for access.`

If you think you should have access to AI Studio, contact your Workspace
administrator.

## Enable AI Studio for Workspace users {% id="enable-ai-studio" %}

Important: This section is intended for Google Workspace administrators.

As a Google Workspace administrator, you can control who uses AI Studio:

* AI Studio is turned on by default for all editions.
* You can turn AI Studio off or on for sets of users across or within
    organizational units.

* Google Workspace for Education editions: Users under the age of 18 are
    restricted from using AI Studio with their Google Workspace for
    Education accounts. This is true even when the AI Studio setting is
    on. For details, go to [Control access to Google services by
    age](https://support.google.com/a/answer/10651918).

To enable or disable AI Studio for users in your organization, see
[Turn Google AI Studio on or off for users](https://support.google.com/a/answer/15004095).

# Gemini Developer API vs. Gemini platform
Source: https://aistudio.google.com/docs/migrate-to-cloud
Description: When developing generative AI solutions with Gemini, Google offers two API products: the Gemini Developer API and the Gemini platform API.

When developing generative AI solutions with Gemini, Google offers two API
products: the [Gemini Developer API](/docs) and the
[Gemini platform API](https://cloud.google.com/gemini-enterprise-agent-platform/overview).

The Gemini Developer API provides the fastest path to build, productionize, and
scale Gemini powered applications. Most developers should use the Gemini
Developer API unless there is a need for specific enterprise controls.

Gemini platform offers a comprehensive ecosystem of enterprise
ready features and services for building and deploying generative AI
applications backed by Google Cloud.

We've recently simplified migrating between these services. Both the Gemini
Developer API and the Gemini platform API are now accessible
through the unified [Google GenAI SDK](/docs/libraries) and the
[Interactions API](/docs/interactions-overview).

{% callout type="note" %} Note: If you're using an AI coding assistant, install
the [Gemini API development skill](/docs/coding-agents) to give your agent
access to the latest documentation and best practices. {% /callout %}

## Code comparison: Interactions API (recommended) {% id="interactions-api" %}

The [Interactions API](/docs/interactions-overview) is the recommended way to
build with Gemini models and agents. The following examples compare text
generation between the Gemini Developer API and Gemini platform.

### Python {% id="interactions-python" %}

You can access both the Gemini Developer API and Gemini platform
services through the `google-genai` library (`>= 2.3.0`). See the
[libraries](/docs/libraries) page for instructions on how to install
`google-genai`.

{% tabs %}
{% tab label="Gemini Developer API" %}

```py
from google import genai

client = genai.Client()

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

{% /tab %}
{% tab label="Gemini platform API" %}

```py
from google import genai

client = genai.Client(
    enterprise=True, project="your-project-id", location="global"
)

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

{% /tab %}
{% /tabs %}

### JavaScript and TypeScript {% id="interactions-javascript-and-typescript" %}

You can access both Gemini Developer API and Gemini platform
services through the `@google/genai` library (`>= 2.3.0`). See the
[libraries](/docs/libraries) page for instructions on how to install
`@google/genai`.

{% tabs %}
{% tab label="Gemini Developer API" %}

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

const ai = new GoogleGenAI({});

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

{% /tab %}
{% tab label="Gemini platform API" %}

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

const ai = new GoogleGenAI({
  enterprise: true,
  project: "your_project",
  location: "global",
});

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

{% /tab %}
{% /tabs %}

## Code comparison: generateContent API {% id="generate-content-api" %}

While the Interactions API is recommended for new projects, the
`generateContent` API remains supported.

### Python {% id="python" %}

You can access both the Gemini Developer API and Gemini platform
services through the `google-genai` library. See the
[libraries](/docs/libraries) page for instructions on how to install
`google-genai`.

{% tabs %} {% tab label="Gemini Developer API" %}

```py
from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash", contents="Explain how AI works in a few words"
)
print(response.text)
```

{% /tab %} {% tab label="Gemini platform API" %}

```py
from google import genai

client = genai.Client(
    vertexai=True, project='your-project-id', location='us-central1'
)

response = client.models.generate_content(
    model="gemini-3.8-flash", contents="Explain how AI works in a few words"
)
print(response.text)
```

{% /tab %} {% /tabs %}

### JavaScript and TypeScript {% id="javascript-and-typescript" %}

You can access both Gemini Developer API and Gemini platform
services through `@google/genai` library. See [libraries](/docs/libraries) page
for instructions on how to install `@google/genai`.

{% tabs %} {% tab label="Gemini Developer API" %}

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

await main();
```

{% /tab %} {% tab label="Gemini platform API" %}

```javascript
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({
   vertexai: true,
   project: 'your_project',
   location: 'your_location',
 });

 async function main() {
   const response = await ai.models.generateContent({
     model: "gemini-3.8-flash",
     contents: "Explain how AI works in a few words",
   });
   console.log(response.text);
 }

 await main();
```

{% /tab %} {% /tabs %}

### Go {% id="go" %}

You can access both Gemini Developer API and Gemini platform
services through `google.golang.org/genai` library. See
[libraries](/docs/libraries) page for instructions on how to install
`google.golang.org/genai`.

{% tabs %} {% tab label="Gemini Developer API" %}

```go
import (
  "context"
  "encoding/json"
  "fmt"
  "log"
  "google.golang.org/genai"
)

// Your Google API key
const apiKey = "your-api-key"

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  // Call the GenerateContent method.
  result, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", genai.Text("Tell me about New York?"), nil)

}
```

{% /tab %} {% tab label="Gemini platform API" %}

```go
import (
  "context"
  "encoding/json"
  "fmt"
  "log"
  "google.golang.org/genai"
)

// Your Google Cloud project
const project = "your-project"

// A Google Cloud location like "us-central1"
const location = "some-gcp-location"

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, &genai.ClientConfig
  {
           Project: project,
      Location: location,
      Backend: genai.BackendVertexAI,
  })

  // Call the GenerateContent method.
  result, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", genai.Text("Tell me about New York?"), nil)

}
```

{% /tab %} {% /tabs %}

### Other use cases and platforms {% id="other-use-cases-and-platforms" %}

Refer to use case specific guides on [Gemini Developer API Documentation](/docs)
and
[Gemini platform documentation](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/docs/overview)
for other platforms and use cases.

## Migration considerations {% id="migration-considerations" %}

When you migrate:

*   You'll need to use Google Cloud service accounts to authenticate. See the
    [Gemini platform documentation](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/docs/overview)
    for more information.

* You can use your existing Google Cloud project
  (the same one you used to generate your API key) or you can
  [create a new Google Cloud project](https://cloud.google.com/resource-manager/docs/creating-managing-projects).

*   Supported regions may differ between the Gemini Developer API and the
    Gemini platform API. During Preview, the
    [Interactions API on Gemini platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/interactions/)
    only supports the `global` endpoint (`location="global"`). See the list of
    [supported regions for generative AI on Google Cloud](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/docs/learn/locations-genai).

* Any models you created in Google AI Studio need to be retrained in Gemini platform.

If you no longer need to use your Gemini API key for the Gemini Developer API,
then follow security best practices and delete it.

To delete an API key:

1. Open the
    [Google Cloud API Credentials](https://console.cloud.google.com/apis/credentials)
    page.

1. Find the API key you want to delete and click the **Actions** icon.

1. Select **Delete API key**.

1. In the **Delete credential** modal, select **Delete**.

    Deleting an API key takes a few minutes to propagate. After
    propagation completes, any traffic using the deleted API key is rejected.

Important: If you have deleted a key that is still used in production and need
to recover it, see
[gcloud beta services api-keys undelete](https://cloud.google.com/sdk/gcloud/reference/beta/services/api-keys/undelete).

## Next steps {% id="next-steps" %}

*   Explore the
    [Interactions API on Gemini platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/interactions/)
    developer guide.
* See the
    [Generative AI on Gemini platform overview](https://docs.cloud.google.com/gemini-enterprise-agent-platform/overview)
    to learn more about generative AI solutions on Gemini platform.

# Authentication with OAuth quickstart
Source: https://aistudio.google.com/docs/oauth
Description: Authenticate to the Gemini API securely using OAuth client credentials.

The easiest way to authenticate to the Gemini API is to configure an API
key, as described in the [Gemini API get started
guide](/docs/get-started). If you need stricter access controls,
you can use OAuth instead. This guide will help
you set up authentication with OAuth.

This guide uses a simplified authentication approach that is appropriate
for a testing environment. For a production environment, learn
about
[authentication and authorization](https://developers.google.com/workspace/guides/auth-overview)
before
[choosing the access credentials](https://developers.google.com/workspace/guides/create-credentials#choose_the_access_credential_that_is_right_for_you)
that are appropriate for your app.

## Objectives {% id="objectives" %}

* Set up your cloud project for OAuth
* Set up application-default-credentials
* Manage credentials in your program instead of using `gcloud auth`

## Prerequisites {% id="prerequisites" %}

To run this quickstart, you need:

* [A Google Cloud project](https://developers.google.com/workspace/guides/create-project)
* [A local installation of the gcloud CLI](https://cloud.google.com/sdk/docs/install)

## Set up your cloud project {% id="set-cloud" %}

To complete this quickstart, you first need to setup your Cloud project.

### 1. Enable the API {% id="enable-api" %}

Before using Google APIs, you need to turn them on in a Google Cloud project.

* In the Google Cloud console, enable the Google Generative Language API.

  {% button href="https://console.cloud.google.com/flows/enableapi?apiid=generativelanguage.googleapis.com" variant="primary" %}Enable the API{% /button %}

### 2. Configure the OAuth consent screen {% id="configure-oauth" %}

Next configure the project's OAuth consent screen and add yourself as a test
user. If you've already completed this step for your Cloud project, skip to the
next section.

1. In the Google Cloud console, go to **Menu** >
  **Google Auth platform** > **Overview**.

  {% button href="https://console.developers.google.com/auth/overview" variant="primary" %}Go to the Google Auth platform{% /button %}
2. Complete the project configuration form and set the user type to **External**
   in the **Audience** section.

3. Complete the rest of the form, accept the User Data Policy terms, and then
   click **Create**.

4. For now, you can skip adding scopes and click **Save and Continue**. In the
   future, when you create an app for use outside of your Google Workspace
   organization, you must add and verify the authorization scopes that your
   app requires.

5. Add test users:
    1. Navigate to the
    [Audience page](https://console.developers.google.com/auth/audience) of the
    Google Auth platform.

    1. Under **Test users**, click **Add users**.
    2. Enter your email address and any other authorized test users, then
       click **Save**.

### 3. Authorize credentials for a desktop application {% id="authorize-credentials" %}

To authenticate as an end user and access user data in your app, you need to
create one or more OAuth 2.0 Client IDs. A client ID is used to identify a
single app to Google's OAuth servers. If your app runs on multiple platforms,
you must create a separate client ID for each platform.

1. In the Google Cloud console, go to **Menu** > **Google Auth platform** >
   **Clients**.

  {% button href="https://console.developers.google.com/auth/clients" variant="primary" %}Go to Credentials{% /button %}
2. Click **Create Client**.
3. Click **Application type** > **Desktop app**.
4. In the **Name** field, type a name for the credential. This name is only
  shown in the Google Cloud console.

5. Click **Create**. The OAuth client created screen appears, showing your new
  Client ID and Client secret.

6. Click **OK**. The newly created credential appears under **OAuth 2.0 Client
  IDs.**

7. Click the download button to save the JSON file. It will be saved as
  `client_secret_<identifier>.json`, and rename it to `client_secret.json`
   and move it to your working directory.

## Set up Application Default Credentials {% id="set-application-default" %}

To convert the `client_secret.json` file into usable credentials, pass its
location the `gcloud auth application-default login` command's
`--client-id-file` argument.

```posix-terminal
gcloud auth application-default login \
    --client-id-file=client_secret.json \
    --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/generative-language.retriever'
```

The simplified project setup in this tutorial triggers a **"Google hasn't
verified this app."** dialog. This is normal, choose **"continue"**.

This places the resulting token in a well known location so it can be accessed
by `gcloud` or the client libraries.

{% callout type="note" %}
Note: If running on Colab include `--no-browser` and carefully follow the
instructions it prints (don't just click the link). Also make sure your local
`gcloud --version` is the
[latest](https://cloud.google.com/sdk/docs/release-notes) to match Colab.
{% /callout %}

```bash
gcloud auth application-default login \
    --no-browser \
    --client-id-file=client_secret.json \
    --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/generative-language.retriever'
```

Once you have the Application Default Credentials (ADC) set, the client
libraries in most languages need minimal to no help to find them.

### Curl {% id="curl" %}

The quickest way to test that this is working is to use it to access the REST
API using curl:

```posix-terminal
access_token=$(gcloud auth application-default print-access-token)
project_id=<MY PROJECT ID>

curl -X GET https://generativelanguage.googleapis.com/v1/models \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ${access_token}" \
    -H "x-goog-user-project: ${project_id}" | grep '"name"'
```

### Python {% id="python" %}

In python the client libraries should find them automatically:

```bash
pip install google-genai
```

A minimal script to test it might be:

```python
from google import genai

client = genai.Client()
print('Available base models:', [m.name for m in client.models.list()])
```

## Manage credentials yourself [Python] {% id="manage-credentials" %}

In many cases you won't have the `gcloud` command available to create the access
token from the Client ID (`client_secret.json`). Google provides libraries in
many languages to let you manage that process within your app. This section
demonstrates the process, in python. There are equivalent examples of this sort
of procedure, for other languages, available in the
[Drive API documentation](https://developers.google.com/drive/api/quickstart/python)

### 1. Install the necessary libraries {% id="install-libs" %}

Install the Google client library for Python, and the Gemini client library.

```posix-terminal
pip install --upgrade -q google-api-python-client google-auth-httplib2 google-auth-oauthlib

pip install google-genai
```

### 2. Write the credential manager {% id="write-credentials" %}

To minimize the number of times you have to click through the authorization
screens, create a file called `load_creds.py` in your working directory to
caches a `token.json` file that it can reuse later, or refresh if it expires.

Start with the
following code to convert the `client_secret.json` file to a token usable with
`genai.configure`:

```python
import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/generative-language.retriever']

def load_creds():
    """Converts `client_secret.json` to a credential object.

    This function caches the generated tokens to minimize the use of the
    consent screen.
    """
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'client_secret.json', SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open('token.json', 'w') as token:
            token.write(creds.to_json())
    return creds
```

### 3. Write your program {% id="write-program" %}

Now create your `script.py`:

```python
import pprint
from google import genai
from load_creds import load_creds

creds = load_creds()

client = genai.Client(credentials=creds)

print()
print('Available base models:', [m.name for m in client.models.list()])
```

### 4. Run your program {% id="run-program" %}

In your working directory, run the sample:

```posix-terminal
python script.py
```

The first time you run the script, it opens a browser window and prompts you
to authorize access.

1. If you're not already signed in to your Google Account, you're prompted to
  sign in. If you're signed in to multiple accounts, **be sure to select the
  account you set as a "Test Account" when configuring your project.**

{% callout type="note" %}
  Note: The simplified project setup in this tutorial triggers a **"Google
  hasn't verified this app."** dialog. This is normal, choose **"continue"**.
{% /callout %}

3. Authorization information is stored in the file system, so the next time you
  run the sample code, you aren't prompted for authorization.

You have successfully setup authentication.

# Gemini API Additional Terms of Service
Source: https://aistudio.google.com/docs/terms

Effective March 23, 2026

To use [Gemini API](https://ai.google.dev/api),
[Google AI Studio](https://aistudio.google.com), and the other Google developer
services that reference these terms (collectively, the "**APIs**" or
"**Services**"), you must accept (1) the
[Google APIs Terms of Service](https://developers.google.com/terms)
(the "**API Terms**"), and (2) these Gemini API Additional Terms of Service (the
"**Additional Terms**"). Terms that are not defined in these Additional Terms
have the meanings given in the API Terms.

## Age Requirements {% id="age-requirements" %}

You must be 18 years of age or older to use the APIs. You also will not use the
Services as part of a website, application, or other service (collectively,
"**API Clients**") that is directed towards or is likely to be accessed by
individuals under the age of 18.

## Use Restrictions {% id="use-restrictions" %}

Use of Google AI Studio and Gemini API is for developers building with Google AI
models for professional or business purposes, not for consumer use.

You may only access the Services (or make API Clients available to users) within
an [available region](/docs/available-regions). **You may use
only Paid Services when making API Clients available to users in the European
Economic Area, Switzerland, or the United Kingdom.**

You may not use the Services to develop models that compete with the Services
(e.g., Gemini API or Google AI Studio). You also may not attempt to reverse
engineer, extract or replicate any component of the Services, including the
underlying data or models (e.g., parameter weights).

In addition to the
"[API Prohibitions](https://developers.google.com/terms#a_api_prohibitions)"
section in the API Terms, you must comply with our
[Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy),
which provides additional details about appropriate conduct when using the
Services.

The Services include safety features to block harmful content, such as content
that violates our
[Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy).
You may not attempt to bypass these protective measures or use content that
violates the API Terms or these Additional Terms. You are responsible for
determining the necessary and appropriate [safety settings](/docs/safety-settings)
and factuality tools for your use case. Applications with less restrictive
safety settings may be subject to Google's review and approval.

You may not use the Services in clinical practice, to provide medical advice, or
in any manner that is overseen by or requires clearance or approval from a
medical device regulatory agency.

## Use of Generated Content {% id="use-generated" %}

Some of our Services allow you to generate original content. Google won't claim
ownership over that content. You acknowledge that Google may generate the same
or similar content for others and that we reserve all rights to do so.

As required by the API Terms, you'll comply with applicable law in using
generated content, which may require the provision of
[attribution](https://ai.google.dev/api/rest/v1beta/CitationMetadata) to your
users when returned as part of an API call. Use discretion before relying on
generated content,
including [code](https://g.co/legal/generative-code). You're responsible for
your use of generated content, and for the use of that content by anyone you
share it with.

## Unpaid Services {% id="unpaid-services" %}

Any Services that are offered free
of charge like direct interactions with Google AI Studio or unpaid quota in
Gemini API are unpaid Services (the "**Unpaid Services**").

### How Google Uses Your Data {% id="data-use-unpaid" %}

When you use Unpaid Services, including, for example, Google AI Studio and the
unpaid quota on Gemini API, Google uses the content you submit to the Services
and any generated responses to provide, improve, and develop Google products and
services and machine learning technologies, including Google's enterprise
features, products, and services, consistent with our
[Privacy Policy](https://policies.google.com/privacy).

To help with quality and improve our products, human reviewers may read,
annotate, and process your API input and output. Google takes steps to protect
your privacy as part of this process. This includes disconnecting this data from
your Google Account, API key, and Cloud project before reviewers see or annotate
it. **Do not submit sensitive, confidential, or personal information to the
Unpaid Services.**

The license you grant to Google under the
"[Submission of Content](https://developers.google.com/terms#b_submission_of_content)"
section in the API Terms also extends, to the extent required under applicable
law for our use, to any content (e.g., prompts, including associated system
instructions, cached content, and files such as images, videos, or documents)
you submit to the Services and to any generated responses.

Google only uses content that you import or upload to our model tuning feature
for that express purpose. Tuning content may be retained in connection with your
tuned models for purposes of re-tuning when supported models change. When you
delete a tuned model, the related tuning content is also deleted.

If you're in the European Economic Area, Switzerland, or the United Kingdom, the
terms under "[How Google uses Your Data](/docs/terms#data-use-paid)" in
"[Paid Services](/docs/terms#paid-services)" apply to all Services, including Google AI
Studio and unpaid quota in the Gemini API, even though they are offered free of
charge.

## Paid Services {% id="paid-services" %}

When a Service is being offered for a fee, it is considered to be a paid Service
(the "**Paid Services**"). Your access to Google AI Studio is a "Paid Service"
even when it is offered free of charge, as long as the account you are using to
access Google AI Studio has access to a Cloud Project with an associated and
active [Cloud Billing account](https://cloud.google.com/billing/docs/concepts)
or is a Workspace enterprise account.
Your access to Gemini API is a "Paid Service" only when accessing the API
through a Cloud Project associated with an active billing account.

For Paid Services, "Google" as used in these
Terms has the meaning given
[here](https://cloud.google.com/terms/google-entity).

### How Google Uses Your Data {% id="data-use-paid" %}

When you use Paid Services, including, for example, the paid quota of the Gemini
API, Google doesn't use your prompts (including associated system instructions,
cached content, and files such as images, videos, or documents) or responses to
improve our products, and will process your prompts and responses in accordance
with the
[Data Processing Addendum for Products Where Google is a Data Processor](https://business.safety.google/processorterms/).
For Paid Services, Google logs prompts and responses for a limited period of
time, solely for detecting and preventing violations of the
[Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy)
to maintain the safety and security of the Services, and any required legal or
regulatory disclosures. This data may be stored
transiently or cached in any country in which Google or its agents maintain
facilities.

Other data we collect while providing the Paid Services to you, such as account
information and settings, billing history, direct communications and feedback,
and usage details (e.g., information about usage including token count per
prompt and response, operational status, safety filter triggers, software errors
and crash reports, authentication details, quality and performance metrics, and
other technical details necessary for Google to operate and maintain Services,
which may include device identifiers, identifiers from cookies or tokens, and IP
addresses) remains subject to the
[Google Controller-Controller Data Protection Terms](https://business.safety.google/controllerterms/)
and
[Google Privacy Policy](https://policies.google.com/privacy) referenced in the
API Terms.

When using Grounding with Google Search, additional data is collected and used,
as detailed in the
"[Grounding with Google Search](/docs/terms#grounding-with-google-search)" section below.

### Payment Terms {% id="payment-terms" %}

Billing and payments for Paid Services are handled by
[Cloud Billing](https://cloud.google.com/billing/docs/concepts) in the Google
Cloud Platform.

As such, while these Terms govern your use of the Paid Services, the following
sections of the
[Google Cloud Terms of Service](https://cloud.google.com/terms) as applicable
to the Google Cloud Platform (or "GCP Services" as defined in the Google Cloud
Terms of Service), will govern
payments, invoicing, billing, payment disputes, and related issues pertaining to
the Paid Services, as if the Paid Services were GCP Services for purposes of
those sections:

* Section 2 (Payment Terms);
* Section 14 (Miscellaneous);
* Section 15 (Regional Modifications), as applicable to:
  * Governing Law and Dispute Resolution;
  * Payment, Taxes, and Invoice Disputes;
  * Currency Conversion; and
  * Other Regional Modifications; and
* the Pricing and Billing Terms of the Service Specific Terms at
  https://cloud.google.com/terms/service-terms, including the Supplemental Paid
  Credit Terms at https://cloud.google.com/terms/supplemental-paid-credit (the
  "Supplemental Paid Credit Terms").

"**Fees**" (as used in the
[Google Cloud Terms of Service](https://cloud.google.com/terms)) for
Paid Services are as specified on our [pricing](/docs/pricing) page. Google may make
changes to this pricing from time to time, effective 30 days after they are
posted unless otherwise specified (or in the case of new Paid Services, where
pricing takes effect immediately unless otherwise specified). Your continued
use of the Paid Services constitutes your consent to those changes.

For clarity, these Terms do not govern your
direct use of any Google Cloud Platform service (including those listed on the
[Google Cloud Services Summary](https://cloud.google.com/terms/services)).

## Agentic Services {% id="agentic-services" %}

When using agentic services, including the Computer Use API, you are solely
responsible for the actions and tasks performed by the service, such as
determining whether the service is appropriate for your use case, authorizing
the service's access and connection to data, applications, and systems, and
exercising judgment and supervision when and if the service is used in
production environments. You will not automatically bypass any requests for
human confirmation.

## Grounding with Google Search {% id="grounding-with-google-search" %}

"Grounding with Google Search" is a Service that provides Grounded Results and
Search Suggestions and can be used through Google AI Studio (as an Unpaid
Service), and via Gemini API as a (Paid Service). "Grounded Results" mean
responses that Google generates using the prompt from the end user (or from
you, when using function calling), contextual
information that you may provide (as applicable), and results from Google's
search engine. "Search Suggestions" mean
search suggestions that Google provides with the Grounded Results. If a Grounded
Result is clicked on, separate terms (not these terms) govern the destination
page. If a Search Suggestion is clicked on the
[Google Terms of Service](https://policies.google.com/terms) govern the
[google.com](http://google.com) destination page. "Links" are any other means to
fetch web pages (including hyperlinks and URLs), which may be contained in a
Grounded Result or Search Suggestion. Links also include titles or labels
provided with those means to fetch web pages. Excluding your web domain(s), you
will not assert ownership rights in any intellectual property in Search
Suggestions or Links in Grounded Results.

### Use Restrictions {% id="use-restrictions2" %}

* You will only use Grounding with Google Search in an application that is owned
  and operated by you and will only display the Grounded Results with the
  associated Search Suggestion(s) to the end user who submitted the prompt.

* You will not, and will not allow your end user or any third party to, cache,
  frame, syndicate, resell, analyze, train on, or otherwise learn from
  Grounded Results or Search Suggestions. For clarity, Grounded Results, Search
  Suggestions, and Links are intended to be used in combination to respond to a
  given end user prompt and it is a violation of these terms to use Grounding
  with Google Search to extract or collect one or more of these components for
  another purpose (for example, using programmatic or automated means to collect
  Links, using Links to build an index, or using Links to identify destination
  pages for crawling or scraping).

* You will not, and will not allow your end user or any third party to, copy,
  store,
  or implement any click tracking, Link-tracking or other monitoring of Grounded
  Results or Search Suggestions, except that:

  * You may copy and store, for up to two (2) years, the text of the Grounded
    Result(s): (1) that were displayed by you only to evaluate and
    optimize the display of the Grounded Results in your application; (2)
    in chat history of an end user of your application
    only for the purpose of allowing that end user to view their chat history;
    and (3) temporarily for the purpose of resubmitting the text of the Grounded
    Result in a subsequent prompt that you submit to Google via a function call
    to obtain a refined or improved Grounded Result to display to the end user,
    as long as the developer: (i) does not use the interim Grounded Results for
    any other purpose; (ii) deletes any Grounded Result that is not displayed to
    the end user once the final Grounded Result is generated; and (iii) displays
    any associated Search Suggestions or other Links (as applicable) with the
    final Grounded Result (up to a maximum of 5 Search Suggestions) to the end
    user.

  * You may copy and store the Grounded Result and Search Suggestions solely for
    the purpose of and for the minimum time necessary to comply with applicable
    law or regulations.

  * You may allow end user(s) to copy and store individual Grounded Results that
    were displayed to them through your application as long as you do not allow
    Grounded Results to be accessed or collected by automated or programmatic
    means or to be used to create a database.

  * You may monitor end user interactions with your application interface;
    however, you will not track whether those interactions were specifically
    with a given Search Suggestion or Grounded Result (in each case, in whole or
    in part, including any specific Link).

* Unless permitted by Google in writing, you: (1) will not modify, or
  intersperse any other content with, the Grounded Results or Search
  Suggestions; and (2) will not place any interstitial content between any Link
  or Search Suggestions and the associated destination page, redirect end users
  away from the destination pages, or minimize, remove, or otherwise inhibit the
  full and complete display of any destination page.

### Data Collection and How Google Uses Your Data {% id="data-collection" %}

In addition to the general terms above ("How Google Uses Your Data" under
"[Unpaid Services](/docs/terms#unpaid-services)" and "[Paid Services](/docs/terms#paid-services)"),
when using Grounding with Google Search,
Google will store prompts, contextual information that you may provide, and
output for thirty (30) days for the purposes of creating Grounded Results and
Search Suggestions and the stored information can be used for debugging and
testing of systems that support Grounding with Google Search. When using
Grounding with Google Search via paid quota of Gemini API, this processing for
debugging and testing of systems is in accordance with the
[Data Processing Addendum for Products Where Google is a Data Processor](https://business.safety.google/processorterms/).

This subsection "Grounding with Google Search" will survive termination of the
Agreement, as applicable.

The
[Client Application Guidelines](https://support.google.com/adsense/answer/10926790)
apply to your use of Grounding with Google Search. For purposes of the Client
Application Guidelines, your applications that are using Grounding with Google
Search are considered Approved Applications.

## Grounding with Google Maps {% id="grounding-with-google-maps" %}

"Grounding with Google Maps" is a Service that provides Google Maps Grounded
Results as a feature of Gemini API. "Google Maps Grounded Results" mean
responses that Google generates using Google Maps Data in response to an end
user initiated prompt. "Google Maps Data" means the content originating from
Google Maps in the Google Maps Grounded Results, including in the output text,
in the metadata of the Google Maps Grounded Results, in the Google Maps Links,
and content accessed through Google Maps Links. "Google Maps Links" mean the
URLs that Google provides in a Google Maps Grounded Result and any titles or
labels provided with those URLs. If Google Maps Links are clicked on, these
separate [Google Maps End User Terms](https://maps.google.com/help/terms_maps.html)
and the [Google Privacy Policy](https://policies.google.com/privacy) govern the
destination page. Google Maps Data in the text of a Google Maps Grounded Result
will be identified via the Google Maps Links. Notwithstanding anything to the
contrary in the Agreement, Google and its content providers retain all rights to
Google Maps Data.

### Use restrictions

1. You will only use Grounding with Google Maps in an application that is owned
   and
    operated by you and will only use Grounding with Google Maps to display the
    Google Maps Grounded Results with the associated Google Maps Links to the
    end user who initiated the prompt. An end user is an individual you permit
    to use your application.

1. You will not modify the Google Maps Grounded Result or intersperse any other
    content with the Google Maps Grounded Result, place any interstitial content
    between the text of the Google Maps Grounded Result and the Google Maps
    Links or the Google Maps Links and the associated destination page, or
    redirect end users away from the destination pages or minimize, remove, or
    otherwise inhibit the full and complete display of any destination page.

1. You will comply with the Documentation for Grounding with Google Maps.

1. You will not, and will not allow your end users or any third party to:

    1. cache or store Google Maps Grounded Results except that you may cache or
    store Google Maps Grounded Results:

      1. for up to ninety (90) days, only to evaluate and optimize the display
         of the Google Maps Grounded Results for your application; or,

      1. in the chat history of an end user in your application for up to six
         (6) months for the purpose of allowing that end user to view their chat
         history or to maintain prior conversation context for that end user
         within your application (Section 4 (a) overrides any cache header);

    1. scrape or export any Google Maps Data;

    1. train on any Google Maps Data; or

    1. distribute or market any Customer Applications in any Prohibited
       Territory as defined in the Documentation.

### Data Collection and How Google Uses Your Data

You acknowledge that it is reasonably
necessary for Google to store prompts, contextual information that you may
provide, and generated content for thirty (30) days for the purposes of creating
Google Maps Grounded Results, and since such information is being stored, you
instruct Google that the stored information can be used for debugging and
testing of systems that support Grounding with Google Maps. When using Grounding
with Google Maps via paid quota of Gemini API, this processing for debugging and
testing of systems is in accordance with the [Data Processing Addendum for
Products Where Google is a Data
Processor](https://business.safety.google/processorterms/).

This subsection "Grounding with Google Maps" will survive termination of the
Agreement, as applicable.

## Hardware Safety {% id="hardware-safety" %}

The following additional terms apply to models that can be used to control
robots or other robotic hardware ("**Robotics Models**").

You acknowledge and agree that the Robotics Models have not been tested with all
makes and models of robotics hardware, and therefore, that the performance and
safety of the Robotics Models in connection with your hardware is not guaranteed
or provided with a warranty of any kind. You therefore agree to operate any
hardware or other products that you may use in connection with the Robotics
Models in a safe manner, and completely at your own risk. The Robotics Models
may act in an unpredictable or unexpected manner when used in connection with
robotics hardware. You therefore agree to use discretion before using the
Robotics Models in a production, commercial, or public environment, and to not
use the Robotics Models for safety-critical applications or work, such as in the
following settings: (i) healthcare, (ii) transportation, or (iii) other areas
where safety protocols are vital, and a malfunction could reasonably foreseeably
lead to death, personal injury, or property damage.

## **Disclaimers** {% id="disclaimers" %}

**The Services include experimental technology and may sometimes provide
inaccurate or offensive content that doesn't represent Google's views.**

**Use discretion before relying on, publishing, or otherwise using content
provided by the Services.**

**Don't rely on the Services for medical, mental health, legal, financial, or
other professional advice. Any content regarding those topics is provided for
informational purposes only, does not constitute medical diagnosis or treatment,
and is not a substitute for advice from a qualified professional.**

{% callout type="note" %}
Note: Previous versions of these Additional Terms are
      [archived here](/docs/terms-archive/index).
{% /callout %}

# Additional Terms of Service archive
Source: https://aistudio.google.com/docs/terms-archive/index

The following are links to previously published
[*Additional Terms of Service*](/docs/terms) documents:

* [December 18, 2025](/docs/terms-archive/terms_12_18_25)
* [November 20, 2025](/docs/terms-archive/terms_11_20_25)
* [October 17, 2025](/docs/terms-archive/terms_10_17_25)
* [October 7, 2025](/docs/terms-archive/terms_10_07_25)
* [September 25, 2025](/docs/terms-archive/terms_09_25_25)
* [May 20, 2025](/docs/terms-archive/terms_05_20_25)
* [April 3, 2025](/docs/terms-archive/terms_04_03_25)
* [February 5, 2025](/docs/terms-archive/terms_02_05_25)
* [December 20, 2024](/docs/terms-archive/terms_12_20_24)
* [May 14, 2024](/docs/terms-archive/terms_05_14_24)
* [May 2, 2024](/docs/terms-archive/terms_05_02_24)
* [March 20, 2024](/docs/terms-archive/terms_03_20_24)
* [February 15, 2024](/docs/terms-archive/terms_02_15_24)
* [December 13, 2023](/docs/terms-archive/terms_12_13_23)
* [September 20, 2023](/docs/terms-archive/terms_09_20_23)
* [August 28, 2023](/docs/terms-archive/terms_08_28_23)
* [May 10, 2023](/docs/terms-archive/terms_05_10_23)

# Available regions for Google AI Studio and Gemini API
Source: https://aistudio.google.com/docs/available-regions
Description: Check the supported regions and access rules for AI Studio and Gemini API.

If you reached this page while trying to open
[Google AI Studio](https://aistudio.google.com/), your region may not be
supported. Refer to the section below for a list of supported regions.

For other access requirements, such as
[age requirements](/docs/troubleshoot-ai-studio#age-requirements), see
[Troubleshoot Google AI Studio](/docs/troubleshoot-ai-studio) and our
[Terms of Service](/docs/terms).

## Available regions {% id="available-regions" %}

{% callout type="note" %}
Note: For Colab users - Region restrictions are applied based on
the region that the **Colab instance** is in, not the region that **the user**
is in. You can check the location of the **Colab instance** using
`!curl ipinfo.io`
{% /callout %}

The Gemini API and Google AI Studio are available in the following countries and
territories. If you're not in one of these countries or territories, try the
[Gemini API in Gemini Enterprise Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform):

* Albania
* Algeria
* American Samoa
* Andorra
* Angola
* Anguilla
* Antarctica
* Antigua and Barbuda
* Argentina
* Armenia
* Aruba
* Australia
* Austria
* Azerbaijan
* The Bahamas
* Bahrain
* Bangladesh
* Barbados
* Belgium
* Belize
* Benin
* Bermuda
* Bhutan
* Bolivia
* Bosnia and Herzegovina
* Botswana
* Brazil
* British Indian Ocean Territory
* British Virgin Islands
* Brunei
* Bulgaria
* Burkina Faso
* Burundi
* Cabo Verde
* Cambodia
* Cameroon
* Canada
* Caribbean Netherlands
* Cayman Islands
* Central African Republic
* Chad
* Chile
* Christmas Island
* Cocos (Keeling) Islands
* Colombia
* Comoros
* Cook Islands
* Costa Rica
* Côte d'Ivoire
* Croatia
* Curaçao
* Czech Republic
* Democratic Republic of the Congo
* Denmark
* Djibouti
* Dominica
* Dominican Republic
* Ecuador
* Egypt
* El Salvador
* Equatorial Guinea
* Eritrea
* Estonia
* Eswatini
* Ethiopia
* Falkland Islands (Islas Malvinas)
* Faroe Islands
* Fiji
* Finland
* France
* French Guiana
* Gabon
* The Gambia
* Georgia
* Germany
* Ghana
* Gibraltar
* Greece
* Greenland
* Grenada
* Guam
* Guatemala
* Guernsey
* Guinea
* Guinea-Bissau
* Guyana
* Haiti
* Heard Island and McDonald Islands
* Honduras
* Hungary
* Iceland
* India
* Indonesia
* Iraq
* Ireland
* Isle of Man
* Israel
* Italy
* Jamaica
* Japan
* Jersey
* Jordan
* Kazakhstan
* Kenya
* Kiribati
* Kosovo
* Kuwait
* Kyrgyzstan
* Laos
* Latvia
* Lebanon
* Lesotho
* Liberia
* Libya
* Liechtenstein
* Lithuania
* Luxembourg
* Madagascar
* Malawi
* Malaysia
* Maldives
* Mali
* Malta
* Marshall Islands
* Mauritania
* Mauritius
* Mexico
* Micronesia
* Moldova
* Monaco
* Mongolia
* Montenegro
* Montserrat
* Morocco
* Mozambique
* Namibia
* Nauru
* Nepal
* Netherlands
* New Caledonia
* New Zealand
* Nicaragua
* Niger
* Nigeria
* Niue
* Norfolk Island
* North Macedonia
* Northern Mariana Islands
* Norway
* Oman
* Pakistan
* Palau
* Palestine
* Panama
* Papua New Guinea
* Paraguay
* Peru
* Philippines
* Pitcairn Islands
* Poland
* Portugal
* Puerto Rico
* Qatar
* Republic of Cyprus
* Republic of the Congo
* Romania
* Rwanda
* Réunion
* Saint Barthélemy
* Saint Helena, Ascension and Tristan da Cunha
* Saint Kitts and Nevis
* Saint Lucia
* Saint Pierre and Miquelon
* Saint Vincent and the Grenadines
* Samoa
* San Marino
* São Tomé and Príncipe
* Saudi Arabia
* Senegal
* Serbia
* Seychelles
* Sierra Leone
* Singapore
* Slovakia
* Slovenia
* Solomon Islands
* Somalia
* South Africa
* South Georgia and the South Sandwich Islands
* South Korea
* South Sudan
* Spain
* Sri Lanka
* Sudan
* Suriname
* Sweden
* Switzerland
* Taiwan
* Tajikistan
* Tanzania
* Thailand
* Timor-Leste
* Togo
* Tokelau
* Tonga
* Trinidad and Tobago
* Tunisia
* Turkmenistan
* Turks and Caicos Islands
* Tuvalu
* Türkiye
* Uganda
* Ukraine
* United Arab Emirates
* United Kingdom
* United States
* United States Minor Outlying Islands
* Uruguay
* U.S. Virgin Islands
* Uzbekistan
* Vanuatu
* Vatican City
* Venezuela
* Vietnam
* Wallis and Futuna
* Western Sahara
* Yemen
* Zambia
* Zimbabwe
* Åland Islands

# Abuse monitoring
Source: https://aistudio.google.com/docs/usage-policies
Description: Review Gemini API terms of service, usage policies, and abuse monitoring.

Google is committed to the responsible development and use of AI. To ensure the
safety and integrity of the Gemini API, we have created these policy guidelines.
By using the Gemini API, you agree to the following guidelines, the [Gemini API
Additional Terms of Service](/docs/terms) and Generative AI [Prohibited
Use Policy](https://policies.google.com/terms/generative-ai/use-policy).

## How We Monitor for Misuse {% id="how-we-monitor-for-misuse" %}

Google's Trust and Safety Team employs a combination of automated and manual
processes to detect potential misuse of the Gemini API and Google AI Studio
in order to enforce our policies.

* **Automated Detection:** Automated systems scan API usage for violations of
    our Prohibited Use Policy, such as hate speech, harassment, sexually
    explicit content, and dangerous content.

* **Manual Detection:** If a project consistently exhibits suspicious
    activity, it may be flagged for manual review by authorized Google
    personnel.

## How We Handle Data {% id="how-we-handle-data" %}

Google retains the following data for fifty-five
(55) days for the purposes of detecting and preventing violations of the
Prohibited Use Policy to maintain the safety and security of the Services, and
any required legal or regulatory disclosures:

* **Prompts:** The text prompts you submit to the API.
* **Contextual Information:** Any additional context you provide with your
    prompts.

* **Output:** The responses generated by the Gemini API.

## How We Investigate Potential Issues {% id="how-we-investigate-potential-issues" %}

When prompts or model outputs are flagged by safety filters and abuse detection
systems described above, authorized Google employees may assess the flagged
content, and either confirm or correct the classification or determination based
on predefined guidelines and policies. Data can be accessed for human review
only by authorized Google employees via an internal governance assessment and
review management platform. When data is logged for abuse monitoring, it is used
solely for the purpose of policy enforcement and preventing policy violations.
It is not used to train or fine-tune any AI/ML models besides those used
specifically for policy enforcement.

## Working with You on Policy Compliance {% id="policy-compliance" %}

If your use of Gemini doesn't align with our policies, we may take the following
steps:

* **Get in touch:** We may reach out to you through email to understand your
    use case and explore ways to bring your usage into compliance.

* **Temporary usage limits:** We may limit your access to the Gemini API by
    adjusting rate limits or changing which model answers a specific request,
    for example.

* **Temporary suspension:** We may temporarily pause your access to the Gemini
    API.

* **Account closure:** As a last resort, and for serious violations, we may
    permanently close your access to the Gemini API and other Google services.

If we reach out to you regarding a suspension or account closure, we will also
provide a link where you can appeal.

## Scope {% id="scope" %}

These policy guidelines apply to the use of the Gemini API and AI Studio.

# Feedback
Source: https://aistudio.google.com/docs/feedback-policies
Description: Review AI Studio feedback workflows, data usage, and evaluation policies.

Google AI Studio provides multiple ways for you to submit feedback on model
outputs, generated artifacts, and API request logs. This policy applies to all
feedback submitted across Google AI Studio - including response ratings (such as
thumbs up and thumbs down), written comments, and preference voting (such as
Inline Preference Voting and Build Arena mode).

## Why are we doing this? {% id="why-inline-preference-voting" %}

We're constantly working to improve our AI models and services. Your feedback
helps us provide, improve, and develop Google products and services and machine
learning technologies, including Google's enterprise features, products, and
services, consistent with the
[Gemini API Additional Terms of Service](/docs/terms) and
[Privacy Policy](https://policies.google.com/privacy).

## What data is included in Feedback? {% id="included-data" %}

To make informed decisions about our models and features, we collect certain
data when you submit feedback in Google AI Studio:

*   **Prompts and Responses:** We record the prompts and responses, including
    any uploaded files or media, from the interaction or conversation you
    submitted feedback about. When you participate in comparative preference
    evaluations, we also record the multiple response options presented so we
    can understand the context of your choice.

*   **Your Rating, Vote, or Comments:** We record the rating you gave (such as
    thumbs up or thumbs down), the response you preferred in a vote, any
    feedback categories selected, and any written comments you submitted.

*   **Usage Details:** This includes technical and operational details from your
    interaction or conversation, such as information about which model generated
    the response, model parameters, and system metadata.

### Feedback by surface {% id="feedback-by-surface" %}

Feedback can be submitted across different surfaces in Google AI Studio, with
slight differences in the context captured:

*   **AI Studio Playground:** In the Playground, feedback can be submitted via
    response ratings (thumbs up or down), or side-by-side Inline Preference
    Voting. Recorded data includes the conversation history, prompts, model
    responses, uploaded media or files, parameter settings, feedback and usage
    details.

*   **AI Studio Build:** In Build (including Build Arena), feedback can be
    submitted on generated code, app outputs, and comparative model evaluations.
    Recorded data includes the build instructions and prompts, generated
    application code and outputs, comparative votes or ratings, any accompanying
    comments and usage details.

*   **Gemini API Logs:** In the Logs and Datasets viewer, feedback can be
    submitted on individual Gemini API request logs. Recorded data includes the
    specific API log entry (including request payload, model response,
    parameters, and metadata) along with any feedback and usage details. For
    more details on log data storage and dataset sharing, see the
    [Data Logging and Sharing](/docs/logs-policy) policy.

## Inline Preference Voting {% id="inline-preference-voting" %}

In Google AI Studio, you might occasionally see a side-by-side comparison of two
different responses to your prompt. This is part of our preference voting
system. You'll be asked to choose which response you prefer, which helps us
understand which model outputs users find most helpful.

## Your Privacy {% id="privacy" %}

**Do not submit feedback on conversations, prompts, responses, or logs that
include sensitive, confidential, or personal information.** Providing feedback
is always voluntary.

Thank you for helping us improve Google AI Studio!

# Gemini API reference
Source: https://aistudio.google.com/api-reference
Description: Unary REST, streaming, and WebSocket API reference for Gemini models and managed agents.

The Gemini API provides unary REST, streaming, and real-time WebSocket endpoints
for Gemini models and managed agents. Start new projects with the
[Interactions API](/api-reference/interactions-api), or follow the
[Get started guide](/docs/get-started) to send your first request.

For client libraries and editor tooling, see
[SDK references](/api-reference#sdk-references),
[Gemini API libraries](/docs/libraries), or
[Coding agent setup](/docs/coding-agents).

## Base URL and authentication {% id="authentication" %}

{% two-column-layout %}

{% left-column %}

**To authenticate**, pass your [API key](/docs/api-key) in the `x-goog-api-key`
header (or set `GEMINI_API_KEY` when using an SDK).

**To call an endpoint**, send HTTPS requests to
`https://generativelanguage.googleapis.com/{version}/{endpoint}` using
[`v1beta` or `v1`](/api-reference/api-versions).

| Setting | Value |
| :--- | :--- |
| Base URL | `https://generativelanguage.googleapis.com` |
| WebSocket | `wss://generativelanguage.googleapis.com/ws/...` |
| Authentication | `x-goog-api-key: $GEMINI_API_KEY` |
| Versions | `v1beta` (new features and agents), `v1` (stable) |

{% button href="https://aistudio.google.com/apikey" variant="ais" %}Get API key{% /button %}

{% /left-column %}

{% right-column %}

{% tabs %}
{% tab label="REST" %}

```bash
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-flash-latest",
    "input": "Explain how TCP congestion control works in two sentences."
  }'
```

{% /tab %}
{% tab label="Agents" %}

```bash
# To set up your agent with Gemini API docs tooling
# Connect the Gemini Docs MCP server
npx add-mcp "https://gemini-api-docs-mcp.dev"

# Install Gemini API agent skills
npx skills add google-gemini/gemini-skills --skill gemini-api-dev

# Or install the Antigravity plugin (MCP + skills)
agy plugin install https://github.com/google-gemini/gemini-skills

# Fetch any reference page as clean Markdown
curl -H "Accept: text/markdown" \
  "https://aistudio.google.com/api-reference/interactions-api"
```

{% /tab %}
{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## API endpoints {% id="primary-endpoints" %}

Start with a core surface below, browse endpoints by category, or view every
REST operation on one page in [All methods](/api-reference/all-methods).

{% card-grid columns="4" %}

{% card
  href="/api-reference/interactions-api"
  title="Interactions API"
  subtitle="POST /v1beta/interactions"
  description="Default endpoint for text, multimodal prompts, thinking, tools, stateful turns, and agents."
  icon="hub"
  variant="stacked-icon"
/%}

{% card
  href="/api-reference/live"
  title="Live and Live Music"
  subtitle="WSS BidiGenerate*"
  description="Low-latency WebSocket sessions for real-time voice, video, and interactive Lyria music."
  icon="graphic_eq"
  variant="stacked-icon"
/%}

{% card
  href="/api-reference/agents"
  title="Agents and automation"
  subtitle="POST /v1beta/agents"
  description="Configure reusable agents, provision sandboxes, schedule cron runs, and register webhooks."
  icon="smart_toy"
  variant="stacked-icon"
/%}

{% card
  href="/api-reference/all-methods"
  title="All REST methods"
  subtitle="/api-reference/all-methods"
  description="Single-page index of every REST operation across all Gemini API services."
  icon="quick_reference_all"
  variant="stacked-icon"
/%}

{% /card-grid %}

{% tabs %}
{% tab label="Core and real-time" %}

{% table %}
* API
* Endpoint
* Description
---
* [Interactions API](/api-reference/interactions-api)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/interactions`
* Text, multimodal prompts, thinking, tools, stateful turns, background jobs, and SSE streaming.
---
* [Live API](/api-reference/live)
* {% mark class="http-wss" %}{% icon name="sync_alt" /%}`WSS`{% /mark %} `BidiGenerateContent`
* Low-latency WebSocket session for bidirectional voice, video, and tool calling.
---
* [Live Music API](/api-reference/live-music)
* {% mark class="http-wss" %}{% icon name="sync_alt" /%}`WSS`{% /mark %} `BidiGenerateMusic`
* Real-time WebSocket session for steering interactive instrumental music with Lyria.
---
* [Models API](/api-reference/models)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/models`
* List models, inspect token limits, or run media predictions ([`predict`](/api-reference/models/predict), [`predictLongRunning`](/api-reference/models/predict-long-running)).
{% /table %}

{% /tab %}
{% tab label="Agents and automation" %}

{% table %}
* API
* Endpoint
* Description
---
* [Agents](/api-reference/agents)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/agents`
* Create, retrieve, list, and delete reusable agent configurations.
---
* [Environments](/api-reference/environments)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/environments`
* Provision isolated remote sandboxes and manage workspace files for agent runs.
---
* [Triggers](/api-reference/triggers)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/triggers`
* Schedule recurring cron runs or invoke agent triggers on demand.
---
* [Webhooks](/api-reference/webhooks)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/webhooks`
* Register callback URLs and rotate signing secrets for background events.
---
* [Credentials](/api-reference/credentials)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/credentials`
* Store and manage external service credentials used by agents and tools.
{% /table %}

{% /tab %}
{% tab label="Data, audio, and scale" %}

{% table %}
* API
* Endpoint
* Description
---
* [Files API](/api-reference/files)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/files`
* Upload and manage large audio, image, video, and document files for prompts.
---
* [File Search](/api-reference/file-search/file-search-stores)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/fileSearchStores`
* Chunk, index, and query [documents](/api-reference/file-search/documents) for managed retrieval grounding.
---
* [Caching](/api-reference/caching)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/cachedContents`
* Pin shared prompt context on supported models to reduce repeated input cost.
---
* [Voices](/api-reference/voices)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/voices`
* Create and manage custom prompted or replicated voices for text-to-speech.
---
* [Batch API](/api-reference/batch-api)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/batches`
* Submit asynchronous content generation and embedding jobs at lower cost.
---
* [Embeddings](/api-reference/embeddings)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:embedContent`
* Generate vector embeddings for semantic search, classification, and clustering.
---
* [Tokens](/api-reference/tokens)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:countTokens`
* Count input tokens before sending a request.
{% /table %}

{% /tab %}
{% tab label="Legacy (generateContent)" %}

Start new projects on the [Interactions API](/api-reference/interactions-api) or
follow the [Migration guide](/docs/migrate-to-interactions). Existing
integrations remain supported on the endpoints below.

{% table %}
* API
* Endpoint
* Description
---
* [`generateContent`](/api-reference/generate-content/generate-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:generateContent`
* Unary text and multimodal generation for existing `generateContent` integrations.
---
* [`streamGenerateContent`](/api-reference/generate-content/stream-generate-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:streamGenerateContent`
* Server-sent event streaming for existing `generateContent` integrations.
---
* [`createToken`](/api-reference/generate-content/create-token)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1alpha/auth_tokens`
* Provision short-lived ephemeral authentication tokens for client-side Live API sessions.
{% /table %}

{% /tab %}
{% /tabs %}

## SDK references {% id="sdk-references" %}

Generated client, method, and type documentation for the official Google GenAI
SDKs.

{% card-grid columns="3" %}

{% card
  href="https://googleapis.github.io/python-genai/"
  title="Python"
  subtitle="pip install google-genai"
  description="Reference for the google-genai Python SDK, including sync and async clients."
  variant="stacked-icon"
/%}

{% card
  href="https://googleapis.github.io/js-genai/"
  title="TypeScript and JavaScript"
  subtitle="npm install @google/genai"
  description="Reference for the @google/genai SDK for Node.js and TypeScript."
  variant="stacked-icon"
/%}

{% card
  href="https://pkg.go.dev/google.golang.org/genai"
  title="Go"
  subtitle="go get google.golang.org/genai"
  description="Package reference for google.golang.org/genai on pkg.go.dev."
  variant="stacked-icon"
/%}

{% card
  href="https://googleapis.github.io/java-genai/javadoc/"
  title="Java"
  subtitle="com.google.genai:google-genai"
  description="Javadoc reference for the com.google.genai Java SDK."
  variant="stacked-icon"
/%}

{% card
  href="https://googleapis.github.io/dotnet-genai/"
  title="C# (.NET)"
  subtitle="dotnet add package Google.GenAI"
  description="Reference for the Google.GenAI .NET SDK."
  variant="stacked-icon"
/%}

{% card
  href="/docs/libraries"
  title="Installation and migration"
  subtitle="/docs/libraries"
  description="Install SDK packages, configure environment variables, or migrate from legacy libraries."
  variant="stacked-icon"
/%}

{% /card-grid %}

# API versions explained
Source: https://aistudio.google.com/api-reference/api-versions
Description: Understand the differences between the v1 and v1beta API versions of the Gemini API.

This document provides a high-level overview of the differences between the `v1`
and `v1beta` versions of the Gemini API.

* **v1**: Stable version of the API. Features in the stable version are
  fully supported over the lifetime of the major version. If there are any
  breaking changes, a new major version of the API will be created and the
  existing version will be deprecated after a reasonable period of time.
  Non-breaking changes may be introduced to the API without changing the
  major version. The **Interactions API** and its core features are
  generally available in `v1`.
* **v1beta**: This version includes early features and capabilities that are
  actively being developed. While features in `v1beta` may be subject to
  changes as we refine them based on feedback, it lets you try new
  capabilities before they are promoted to stable.

## Capability and feature support {% id="feature-support" %}

The following table details the availability of capabilities across `v1` (GA)
and `v1beta` (Beta). Core API capabilities and tools apply to both
the Interactions API and `generateContent` unless specified otherwise:

{% callout type="note" %}
All models are supported in both `v1` and `v1beta`. This table tracks the availability of features across the `v1` and `v1beta` **API versions** (endpoint routes and schema parameters).
{% /callout %}

| Feature | v1 | v1beta |
| :--- | :---: | :---: |
| **Core API capabilities** | | |
| [Interactions API](/docs/get-started) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [Function Calling](/docs/function-calling) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [Structured Output](/docs/structured-output) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [Thinking / Reasoning](/docs/thinking) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [System Instructions](/docs/text-generation) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [Audio Output (Speech Config)](/docs/audio) | | {% badge type="supported" /%} |
| [Service Tier (Priority / Flex)](/docs/priority-inference) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| **Tools** | | |
| [Code Execution Tool](/docs/code-execution) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [Google Search Grounding](/docs/google-search) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [Google Maps Grounding](/docs/maps-grounding) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [URL Context Tool](/docs/url-context) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [File Search Tool](/docs/file-search) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [Computer Use Tool](/docs/computer-use) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [MCP Servers Tool](/docs/function-calling#mcp) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| **Realtime APIs** | | |
| [Live API (WebSockets)](/docs/live-api) | | {% badge type="supported" /%} |
| [Live Music API](/docs/realtime-music-generation) | | {% badge type="supported" /%} |
| [Ephemeral Tokens (Live API)](/docs/live-api/ephemeral-tokens) | | {% badge type="supported" /%} |
| **Platform APIs** | | |
| [Models API](/docs/models) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [Files Service Route](/docs/files) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [File Search Stores Route](/docs/file-search) | {% badge type="supported" /%} | {% badge type="supported" /%} |
| [Agents API](/docs/agents) | | {% badge type="supported" /%} |
| [Webhooks API](/docs/webhooks) | | {% badge type="supported" /%} |
| [Context Caching](/docs/caching) | | {% badge type="supported" /%} |

## Configure API version in an SDK {% id="configure-api-version" %}

The Gemini API SDKs default to `v1beta`, but you can explicitly specify versions
by setting the API version as shown in the following code sample:

{% callout type="note" %}
The GenAI SDKs use `v1beta` by default to enable
access to preview features. You can configure the SDK to use the stable
`v1` version (as shown below) which also supports the Interactions API.
{% /callout %}

{% tabs %}
{% tab label="Python" filename="api_version.py" %}
```python
from google import genai

client = genai.Client(http_options={"api_version": "v1"})

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain how AI works",
)

print(interaction.output_text)
```
{% /tab %}
{% tab label="JavaScript" filename="api_version.js" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  httpOptions: { apiVersion: "v1" },
});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain how AI works",
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}
{% tab label="REST" filename="api_version.sh" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain how AI works",
  }'
```
{% /tab %}
{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.HttpOptions;

Client client = Client.builder()
    .httpOptions(HttpOptions.builder().apiVersion("v1").build())
    .build();

CreateModelInteraction req = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Explain how AI works"))
    .build();
var interaction = client.interactions.create(CreateInteractionRequestBody.of(req)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}
{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        HTTPOptions: genai.HTTPOptions{
            APIVersion: "v1",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.6-flash"),
            Input: interactions.NewInteractionsInput("Explain how AI works"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

# Gemini Interactions API
Source: https://aistudio.google.com/api-reference/interactions-api
Description: The Gemini Interactions API allows developers to build generative AI applications using Gemini models.

{% callout type="note" %}

**Recommended:** The **Interactions API** is the recommended standard API for all new projects and applications using Gemini. It is optimized for agentic workflows, server-side state management, and real-time conversations.

{% /callout %}

{% callout type="note" %}

You are viewing the beta version of the Interactions API. Endpoints are under `/v1beta/`. The stable [v1 version](/api-reference/interactions-api?api-version=v1) is also available.

{% /callout %}

The Gemini Interactions API 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.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Creating an interaction](/api-reference/interactions-api/create-interaction)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/interactions`

  Creates a new interaction.
---

* [Canceling an interaction](/api-reference/interactions-api/cancel-interaction-by-id)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/interactions/{id}/cancel`

  Cancels an interaction by id.
---

* [Getting an interaction](/api-reference/interactions-api/get-interaction-by-id)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/interactions/{id}`

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

* [Deleting an interaction](/api-reference/interactions-api/delete-interaction)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/interactions/{id}`

  Deletes the interaction by id.
{% /table %}

## Resources {% id="resources" %}

### Interaction {% id="Resource:Interaction" %}

The Interaction resource.

{% two-column-layout %}

{% left-column %}

**Properties:**

**id**: {% mark %}required{% /mark %} `string`

Output only. A unique identifier for the interaction completion.

{% hr /%}

{% details %}

{% summary %}

**status**: {% mark %}required{% /mark %} `enum (string)`

Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

{% hr /%}

**created**: {% mark %}required{% /mark %} `string`

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

{% hr /%}

**updated**: {% mark %}required{% /mark %} `string`

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

{% hr /%}

**steps**: {% mark %}required{% /mark %} `array (`[`Step`](/api-reference/interactions-api#Resource:Step)`)`

Output only. The steps that make up the interaction, when included in the response.

{% hr /%}

{% details %}

{% summary %}

**model**: `ModelOption`

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

{% /summary %}

Possible values:

- `gemma-4-26b-a4b-it`: Gemma 4 26B A4B IT
- `gemma-4-31b-it`: Gemma 4 31B IT
- `gemini-flash-latest`: Latest release of Gemini Flash
- `gemini-flash-lite-latest`: Latest release of Gemini Flash-Lite
- `gemini-pro-latest`: Latest release of Gemini Pro
- `gemini-2.5-flash`: Our first hybrid reasoning model which supports a 1M token context window and has thinking budgets.
- `gemini-2.5-pro`: Our state-of-the-art multipurpose model, which excels at coding and complex reasoning tasks.
- `gemini-2.5-flash-lite`: Our smallest and most cost effective model, built for at scale usage.
- `gemini-3.5-flash-lite`: Gemini 3.5 Flash-Lite - Our fastest, most cost-effective 3.5 model for high-throughput execution.
- `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-3-flash-preview`: Our most intelligent model built for speed, combining frontier intelligence with superior search and grounding.
- `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-pro-preview-customtools`: Gemini 3.1 Pro Preview optimized for custom tool usage
- `gemini-3.1-flash-lite`: Our most cost-efficient model, optimized for high-volume agentic tasks, translation, and simple data processing.
- `gemini-3.1-flash-lite-image`: Gemini 3.1 Flash Lite Image.
- `gemini-3-pro-image`: Gemini 3 Pro Image
- `nano-banana-pro-preview`: Gemini 3 Pro Image Preview
- `gemini-3.1-flash-image`: Gemini 3.1 Flash Image.
- `gemini-nano-banana-2.1`: Gemini Nano Banana 2.1.
- `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.
- `gemini-3.5-flash`: Gemini 3.5 Flash - Our earlier Flash model, built for speed and foundational performance across routine, high-throughput workloads.
- `gemini-3.6-flash`: Gemini 3.6 Flash - Our previous generation Flash model, balancing speed and multimodal capabilities across general agentic and everyday tasks.
- `gemini-3.7-flash`: Gemini 3.7 Flash - Our high-speed, efficient Flash model built for everyday coding, agentic tool use, and reliable multi-step execution.
- `gemini-3.8-flash`: Gemini 3.8 Flash - Our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows.
- `gemini-3.8-flash-tts`: Gemini 3.8 Flash TTS - Flagship TTS model for Voice Design and dual-speaker screenplay control. Prompt custom vocal personas, direct line-by-line delivery, and add vocal bursts.
- `gemini-3.8-flash-lite-tts`: Gemini 3.8 Flash Lite TTS - High-speed and cost-efficient, ideal for rapid dubbing, media localization, and high-throughput voice agents. Direct replacement for gemini-3.1-flash-tts-preview.
- `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.
- `gemini-robotics-er-1.6-preview`: Gemini Robotics-ER 1.6 Preview
- `gemini-robotics-er-2-preview`: Gemini Robotics Embodied Reasoning 2 Preview
- `lyria-3.5`: Our flagship music generation model, optimized for full-length songs with complex structural coherence.
- `gemini-omni-1.1-flash`: Our high-performance multimodal model designed for fast, conversational video generation, editing, and cinematic control.
- `gemini-omni-flash-preview`: Preview release of our multimodal model for conversational video generation, editing, and cinematic control.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**generation_config**: `GenerationConfig`

Input only. Configuration parameters for the model interaction.

{% /summary %}

**seed**: `integer`

Seed used in decoding for reproducibility.

**stop_sequences**: `array (string)`

A list of character sequences that will stop output interaction.

{% details %}

{% summary %}

**tool_choice**: [`ToolChoiceConfig`](/api-reference/interactions-api#Resource:ToolChoiceConfig) or `enum (string)`

The tool choice configuration.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[ToolChoiceConfig](/api-reference/interactions-api#Resource:ToolChoiceConfig)**{% /summary %}

The tool choice configuration containing allowed tools.

{% details %}

{% summary %}

**allowed_tools**: `AllowedTools`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**thinking_level**: `ThinkingLevel`

The level of thought tokens that the model should generate.

{% /summary %}

Possible values:

- `minimal`: Little to no thinking.
- `low`: Low thinking level.
- `medium`: Medium thinking level.
- `high`: High thinking level.

{% /details %}

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

**max_output_tokens**: `integer`

The maximum number of tokens to include in the response.

{% details %}

{% summary %}

**video_config**: `VideoConfig`

Configuration for video generation.

{% /summary %}

{% details %}

{% summary %}

**task**: `enum (string)`

Optional task mode for video generation. If not specified, the model automatically determines the appropriate mode based on the provided text prompt and input media.

{% /summary %}

Possible values:

- `text_to_video`: Generates video solely from a text prompt.
- `image_to_video`: Generates video from one or two source images. The first image defines the starting frame, and the optional second image defines the ending frame.
- `reference_to_video`: Generates video using reference media (such as images, audio, or video).
- `edit`: Modifies an existing input video.
- `extend`: Extends an existing input video.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**transcription_config**: `TranscriptionConfig`

Optional. Configuration for speech recognition (transcription). If present, ASR is enabled.

{% /summary %}

**language_codes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**custom_vocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms.

{% details %}

{% summary %}

**mode**: `TranscriptionMode` or `enum (string)`

Discriminated transcription mode options or enum.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**SmartTranscriptionMode**{% /summary %}

Configuration for smart transcription mode.

**type**: {% mark %}required{% /mark %} `object`

Value: `smart`

{% /details %}

{% details %}

{% summary %}**VerbatimTranscriptionMode**{% /summary %}

Configuration for verbatim transcription mode.

**type**: {% mark %}required{% /mark %} `object`

Value: `verbatim`

**timestamp_granularities**: `array (string)`

Optional. The granularity of timestamps to include in the transcription output. Supported values: "word". If empty, no timestamps are generated.

**diarization_mode**: `string`

Optional. Configures speaker diarization. Supported values: "speaker".

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `verbatim`: Verbatim transcription mode.
- `smart`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**structured_speech_config**: `SpeakerConfig` or `array (SpeechConfig)`

Speech and multi-speaker configuration.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**SpeakerConfig**{% /summary %}

Configuration for multi-speaker and speech generation.

{% details %}

{% summary %}

**speakers**: `array (SpeechConfig)`

Individual speaker configurations.

{% /summary %}

**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.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (SpeechConfig)**{% /summary %}

The 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.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**system_instruction**: `string`

System instruction for the interaction.

{% hr /%}

**tools**: `array (`[`Tool`](/api-reference/interactions-api#Resource:Tool)`)`

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

{% hr /%}

**input**: [`Content`](/api-reference/interactions-api#Resource:Content) or `array (`[`Content`](/api-reference/interactions-api#Resource:Content)`)` or `array (`[`Step`](/api-reference/interactions-api#Resource:Step)`)` or `string`

The input for the interaction.

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

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

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**response_format**: [`ResponseFormat`](/api-reference/interactions-api#Resource:ResponseFormat) or `array (`[`ResponseFormat`](/api-reference/interactions-api#Resource:ResponseFormat)`)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[ResponseFormat](/api-reference/interactions-api#Resource:ResponseFormat)**{% /summary %}

{% /details %}

{% details %}

{% summary %}**array ([ResponseFormat](/api-reference/interactions-api#Resource:ResponseFormat))**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

{% hr /%}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% hr /%}

{% details %}

{% summary %}

**environment**: [`EnvironmentConfig`](/api-reference/interactions-api#Resource:EnvironmentConfig) or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentConfig](/api-reference/interactions-api#Resource:EnvironmentConfig)**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: [`EnvironmentNetworkEgressAllowlist`](/api-reference/interactions-api#Resource:EnvironmentNetworkEgressAllowlist) or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentNetworkEgressAllowlist](/api-reference/interactions-api#Resource:EnvironmentNetworkEgressAllowlist)**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**environment_id**: `string`

Output only. The environment ID for the interaction. Only populated if environment config is set in the request.

{% hr /%}

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

{% hr /%}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

{% hr /%}

{% details %}

{% summary %}

**errors**: `array (Error)`

Output only. Diagnostic faults / platform errors recorded on the interaction.

{% /summary %}

**code**: `string`

A URI that identifies the error type.

**message**: `string`

A human-readable error message.

{% /details %}

{% hr /%}

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

{% hr /%}

**stream**: `boolean`

Input only. Whether the interaction will be streamed.

{% hr /%}

**store**: `boolean`

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

{% hr /%}

**background**: `boolean`

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

{% hr /%}

{% details %}

{% summary %}

**agent**: `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

Configuration parameters for the agent interaction.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

{% hr /%}

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

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

{% /right-column %}

{% /two-column-layout %}

## Data Models {% id="data-models" %}

### Content {% id="Resource:Content" %}

The content of the response.

**Polymorphic Types:**

{% details %}

{% summary %}**AudioContent**{% /summary %}

An audio content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% hr /%}

**data**: `string`

The audio content.

{% hr /%}

**uri**: `string`

The URI of the audio.

{% hr /%}

**channels**: `integer`

The number of audio channels.

{% hr /%}

**sample_rate**: `integer`

The sample rate of the audio.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the audio.

{% /summary %}

Possible values:

- `audio/wav`: WAV audio format
- `audio/mp3`: MP3 audio format
- `audio/aiff`: AIFF audio format
- `audio/aac`: AAC audio format
- `audio/ogg`: OGG audio format
- `audio/flac`: FLAC audio format
- `audio/mpeg`: MPEG audio format
- `audio/m4a`: M4A audio format
- `audio/l16`: L16 audio format
- `audio/opus`: OPUS audio format
- `audio/alaw`: ALAW audio format
- `audio/mulaw`: MULAW audio format
- `audio/webm`: WEBM audio format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Audio**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**DocumentContent**{% /summary %}

A document content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `document`

{% hr /%}

**data**: `string`

The document content.

{% hr /%}

**uri**: `string`

The URI of the document.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the document.

{% /summary %}

Possible values:

- `application/pdf`: PDF document format
- `text/csv`: CSV document format
- `application/vnd.openxmlformats-officedocument.presentationml.presentation`: PPTX presentation format
- `application/vnd.ms-powerpoint`: PPT presentation format
- `application/vnd.oasis.opendocument.presentation`: ODP presentation format
- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`: DOCX document format
- `application/msword`: DOC document format
- `application/vnd.openxmlformats-officedocument.wordprocessingml.template`: DOTX document template format
- `application/vnd.oasis.opendocument.text`: ODT document format
- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`: XLSX spreadsheet format
- `application/vnd.ms-excel`: XLS spreadsheet format
- `application/vnd.oasis.opendocument.spreadsheet`: ODS spreadsheet format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Document**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**[ImageContent](/api-reference/interactions-api#Resource:ImageContent)**{% /summary %}

An image content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

**data**: `string`

The image content.

{% hr /%}

**uri**: `string`

The URI of the image.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the image.

{% /summary %}

Possible values:

- `image/png`: PNG image format
- `image/jpeg`: JPEG image format
- `image/webp`: WebP image format
- `image/heic`: HEIC image format
- `image/heif`: HEIF image format
- `image/gif`: GIF image format
- `image/bmp`: BMP image format
- `image/tiff`: TIFF image format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**[TextContent](/api-reference/interactions-api#Resource:TextContent)**{% /summary %}

A text content block.

{% two-column-layout %}

{% left-column %}

**text**: {% mark %}required{% /mark %} `string`

The text content.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**annotations**: `array (Annotation)`

Citation information for model-generated content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**FileCitation**{% /summary %}

A file citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `file_citation`

**document_uri**: `string`

The URI of the file.

**file_name**: `string`

The name of the file.

**source**: `string`

Source attributed for a portion of the text.

**custom_metadata**: `object`

User provided metadata about the retrieved context.

**page_number**: `integer`

Page number of the cited document, if applicable.

**media_id**: `string`

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

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**PlaceCitation**{% /summary %}

A place citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `place_citation`

**place_id**: `string`

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

**name**: `string`

Title of the place.

**url**: `string`

URI reference of the place.

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

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

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**SpeechAnnotation**{% /summary %}

Speech annotation for text content.

**type**: {% mark %}required{% /mark %} `object`

Value: `speech_metadata`

**speaker**: `string`

The speaker to associate with this turn.

**style**: `string`

Style instruction for the speech synthesis.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**UrlCitation**{% /summary %}

A URL citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `url_citation`

**url**: `string`

The URL.

**title**: `string`

The title of the URL.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**WordInfo**{% /summary %}

Word-level ASR annotation for transcription output. Carries the word text, optional timing, and optional speaker attribution.

**type**: {% mark %}required{% /mark %} `object`

Value: `word_info`

**text**: `string`

The transcribed word.

**start_offset**: `string`

Start offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**end_offset**: `string`

End offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**speaker**: `string`

Optional. Speaker label for this word (e.g. "spk_1", "spk_2"). Present when diarization_mode is set in TranscriptionConfig.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**VideoContent**{% /summary %}

A video content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% hr /%}

**data**: `string`

The video content.

{% hr /%}

**uri**: `string`

The URI of the video.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**processing**: `MediaProcessing` or `enum (string)`

How the model processes this video for understanding.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**MediaProcessing**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `static`

**start_offset**: `string`

Optional. Segment start time. Specified as a decimal number of seconds followed by an 's' suffix, e.g., "10.5s". Must be non-negative.

**end_offset**: `string`

Optional. Segment end time. Specified as a decimal number of seconds followed by an 's' suffix, e.g., "30s". Must be non-negative and greater than `start_offset` if `start_offset` is set.

**fps**: `number`

Optional. Video frame-rate sampling density.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `static`: Fixed-rate frame extraction. All frames placed in context.
- `agentic`: Model-driven dynamic navigation.

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

A user-defined name for this content block. Can be referenced by the model in the final response.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the video.

{% /summary %}

Possible values:

- `video/mp4`: MP4 video format
- `video/mpeg`: MPEG video format
- `video/mpg`: MPG video format
- `video/mov`: MOV video format
- `video/avi`: AVI video format
- `video/x-flv`: FLV video format
- `video/webm`: WebM video format
- `video/wmv`: WMV video format
- `video/3gpp`: 3GPP video format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Video**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### Tool {% id="Resource:Tool" %}

A tool that can be used by the model.

**Polymorphic Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "code_execution"
    }],
    "input": "Calculate the first 10 Fibonacci numbers"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "code_execution"}],
    input="Calculate the first 10 Fibonacci numbers",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'code_execution'}],
  input: 'Calculate the first 10 Fibonacci numbers',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new CodeExecution()))
        .input(InteractionsInput.of("Calculate the first 10 Fibonacci numbers"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="code_execution" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.CodeExecution{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Calculate the first 10 Fibonacci numbers")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ComputerUse**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `computer_use`

{% hr /%}

{% details %}

{% summary %}

**environment**: `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `browser`: Operates in a web browser.
- `mobile`: Operates in a mobile environment.
- `desktop`: Operates in a desktop environment.

{% /details %}

{% hr /%}

**excluded_predefined_functions**: `array (string)`

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

{% hr /%}

**enable_prompt_injection_detection**: `boolean`

Whether enable the prompt injection detection check on computer-use request.

{% hr /%}

{% details %}

{% summary %}

**disabled_safety_policies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `financial_transactions`: Safety policy for financial transactions.
- `sensitive_data_modification`: Safety policy for sensitive data modification.
- `communication_tool`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `account_creation`: Safety policy for account creation.
- `data_modification`: Safety policy for data modification.
- `user_consent_management`: Safety policy for user consent management.
- `legal_terms_and_agreements`: Safety policy for legal terms and agreements.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-2.5-computer-use-preview-10-2025",
    "tools": [{
      "type": "computer_use"
    }],
    "input": "Find a flight to Tokyo"
  }'

```

{% /tab %}

{% tab label="Python" %}

```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.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```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.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-2.5-computer-use-preview-10-2025")
        .tools(List.of(new ComputerUse()))
        .input(InteractionsInput.of("Find a flight to Tokyo"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="computer_use" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.ComputerUse{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-2.5-computer-use-preview-10-2025"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Find a flight to Tokyo")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearch**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search`

{% hr /%}

**file_search_store_names**: `array (string)`

The file search store names to search.

{% hr /%}

**top_k**: `integer`

The number of semantic retrieval chunks to retrieve.

{% hr /%}

**metadata_filter**: `string`

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

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "file_search",
      "file_search_store_names": ["fileSearchStores/m64d1sevsr4y-xfyawui3fxqg"]
    }],
    "input": "Who is the author of the book?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

# Create a file search store so we have a valid one to use.
store = client.file_search_stores.create()

response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[
        {"type": "file_search", "file_search_store_names": [store.name]}
    ],
    input="What documents are available?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

// Create a file search store so we have a valid one to use.
const store = await ai.fileSearchStores.create({});
if (!store.name) {
  throw new Error('Store creation failed: Name is undefined');
}

const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [
    {
      type: 'file_search',
      file_search_store_names: [store.name],
    },
  ],
  input: 'What documents are available?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.types.FileSearchStore;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();

// Create a file search store so we have a valid one to use.
FileSearchStore store =
    client.fileSearchStores.create(CreateFileSearchStoreConfig.builder().build());
String storeName = store.name().orElseThrow();

FileSearch tool = FileSearch.builder().fileSearchStoreNames(List.of(storeName)).build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(tool))
        .input(InteractionsInput.of("What documents are available?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="file_search" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    tool := gaos_interactions.NewTool(gaos_interactions.FileSearch{
        FileSearchStoreNames: []string{store.Name},
    })

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What documents are available?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `function`

{% hr /%}

**name**: `string`

The name of the function.

{% hr /%}

**description**: `string`

A description of the function.

{% hr /%}

**parameters**: `object`

The JSON Schema for the function's parameters. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "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?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    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.steps[-1])

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  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.steps.at(-1));

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Step;

Client client = new Client();
Map<String, Object> parameters =
    Map.of(
        "type", "object",
        "properties",
            Map.of(
                "location",
                Map.of(
                    "type", "string",
                    "description", "The city and state, e.g. San Francisco, CA")),
        "required", List.of("location"));
Function functionTool =
    Function.builder()
        .name("get_weather")
        .description("Get the current weather in a given location")
        .parameters(parameters)
        .build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(functionTool))
        .input(InteractionsInput.of("What is the weather like in Boston?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
List<Step> steps = interaction.steps().orElse(List.of());
if (!steps.isEmpty()) {
  System.out.println(steps.get(steps.size() - 1));
}

```

{% /tab %}

{% tab label="function_calling" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    function := gaos_interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Get the current weather in a given location"),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{
                    "type":        "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                },
            },
            "required": []string{"location"},
        },
    }

    tool := gaos_interactions.NewTool(function)

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What is the weather like in Boston, MA?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil {
        for _, step := range res.Interaction.Steps {
            if step.FunctionCallStep != nil {
                fmt.Println("Function Call:", step.FunctionCallStep.Name)
                fmt.Println("Arguments:", step.FunctionCallStep.Arguments)
            }
        }
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMaps**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps`

{% hr /%}

**enable_widget**: `boolean`

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

{% hr /%}

**latitude**: `number`

The latitude of the user's location.

{% hr /%}

**longitude**: `number`

The longitude of the user's location.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "google_maps",
      "latitude": 37.7749,
      "longitude": -122.4194
    }],
    "input": "What is the best food near me?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[
        {"type": "google_maps", "latitude": 37.7749, "longitude": -122.4194}
    ],
    input="What is the best food near me?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [
    {
      type: 'google_maps',
      latitude: 37.7749,
      longitude: -122.4194,
    },
  ],
  input: 'What is the best food near me?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
GoogleMaps tool = GoogleMaps.builder().latitude(37.7749).longitude(-122.4194).build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(tool))
        .input(InteractionsInput.of("What is the best food near me?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="google_maps" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.GoogleMaps{
        Latitude:  genai.Ptr(37.7749),
        Longitude: genai.Ptr(-122.4194),
    })

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What is the best food near me?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% hr /%}

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "google_search"
    }],
    "input": "Who is the current president of France?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "google_search"}],
    input="Who is the current president of France?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'google_search'}],
  input: 'Who is the current president of France?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new GoogleSearch()))
        .input(InteractionsInput.of("Who is the current president of France?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="google_search" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.GoogleSearch{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Who is the current president of France?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server`

{% hr /%}

**name**: `string`

The name of the MCPServer.

{% hr /%}

**url**: `string`

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

{% hr /%}

**headers**: `object`

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

{% hr /%}

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "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?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
import os

from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    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.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  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.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.MCPServer;

Client client = new Client();
MCPServer mcpTool =
    MCPServer.builder()
        .name("weather_service")
        .url("https://gemini-api-demos.uc.r.appspot.com/mcp")
        .build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(mcpTool))
        .input(
            InteractionsInput.of(
                "Today is 12-05-2025, what is the temperature today in London?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="mcp_server" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    mcpServer := gaos_interactions.MCPServer{
        Name: genai.Ptr("weather_service"),
        URL:  genai.Ptr("https://gemini-api-demos.uc.r.appspot.com/mcp"),
    }
    tool := gaos_interactions.NewTool(mcpServer)

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Today is 12-05-2025, what is the temperature today in London?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "url_context"
    }],
    "input": "Summarize https://www.example.com"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "url_context"}],
    input="Summarize https://www.example.com",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'url_context'}],
  input: 'Summarize https://www.example.com',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.URLContext;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new URLContext()))
        .input(InteractionsInput.of("Summarize https://www.example.com"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="url_context" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.URLContext{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Summarize https://www.example.com")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### InteractionSseEvent {% id="Resource:InteractionSseEvent" %}

**Polymorphic Types:**

{% details %}

{% summary %}**ErrorEvent**{% /summary %}

{% two-column-layout %}

{% left-column %}

**event_type**: {% mark %}required{% /mark %} `object`

Value: `error`

{% hr /%}

{% details %}

{% summary %}

**error**: `Error`

{% /summary %}

**code**: `string`

A URI that identifies the error type.

**message**: `string`

A human-readable error message.

{% /details %}

{% hr /%}

**event_id**: `string`

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

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Error Event**

```json
{
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  },
  "event_type": "error"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**InteractionCompletedEvent**{% /summary %}

Signals that the Interaction completed. Sent when the Interaction receives
Complete/Cancel or naturally terminates. No more input can be sent to the
Interaction after this.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**interaction**: {% mark %}required{% /mark %} `InteractionSseEventInteraction`

Partial completed interaction resource emitted at the end of the stream.

{% /summary %}

**id**: {% mark %}required{% /mark %} `string`

Output only. A unique identifier for the interaction completion.

{% details %}

{% summary %}

**status**: {% mark %}required{% /mark %} `enum (string)`

Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).

{% /details %}

**model**: `string`

The model that will complete your prompt.

**created**: `string`

Output only. The time at which the response was created in ISO 8601 format.

**updated**: `string`

Output only. The time at which the response was last updated in ISO 8601 format.

{% details %}

{% summary %}

**usage**: `Usage`

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

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

**steps**: `array (`[`Step`](/api-reference/interactions-api#Resource:Step)`)`

Output only. The steps that make up the interaction, if included in this event.

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is INCOMPLETE and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

**agent**: `string`

The agent to interact with.

**object**: `string`

Output only. The resource type.

{% /details %}

{% hr /%}

**event_type**: {% mark %}required{% /mark %} `object`

Value: `interaction.completed`

{% hr /%}

**event_id**: `string`

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

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="Interaction Completed" %}

```json
{
  "event_id": "evt_123",
  "event_type": "interaction.completed",
  "interaction": {
    "created": "2025-12-04T15:01:45Z",
    "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
    "model": "gemini-3.6-flash",
    "status": "completed",
    "updated": "2025-12-04T15:01:45Z"
  }
}
```

{% /tab %}

{% tab label="Interaction Completed" %}

```json
{
  "event_id": "evt_123",
  "event_type": "interaction.completed",
  "interaction": {
    "created": "2025-12-04T15:01:45Z",
    "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
    "model": "gemini-3-flash-preview",
    "object": "interaction",
    "status": "completed",
    "updated": "2025-12-04T15:01:45Z"
  }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**InteractionCreatedEvent**{% /summary %}

Server response confirming that a new interaction was created.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**interaction**: {% mark %}required{% /mark %} `InteractionSseEventInteraction`

Partial interaction resource emitted when the stream is created.

{% /summary %}

**id**: {% mark %}required{% /mark %} `string`

Output only. A unique identifier for the interaction completion.

{% details %}

{% summary %}

**status**: {% mark %}required{% /mark %} `enum (string)`

Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).

{% /details %}

**model**: `string`

The model that will complete your prompt.

**created**: `string`

Output only. The time at which the response was created in ISO 8601 format.

**updated**: `string`

Output only. The time at which the response was last updated in ISO 8601 format.

{% details %}

{% summary %}

**usage**: `Usage`

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

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

**steps**: `array (`[`Step`](/api-reference/interactions-api#Resource:Step)`)`

Output only. The steps that make up the interaction, if included in this event.

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is INCOMPLETE and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

**agent**: `string`

The agent to interact with.

**object**: `string`

Output only. The resource type.

{% /details %}

{% hr /%}

**event_type**: {% mark %}required{% /mark %} `object`

Value: `interaction.created`

{% hr /%}

**event_id**: `string`

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

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="Interaction Created" %}

```json
{
  "event_id": "evt_123",
  "event_type": "interaction.created",
  "interaction": {
    "created": "2025-12-04T15:01:45Z",
    "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
    "model": "gemini-3.6-flash",
    "status": "in_progress",
    "updated": "2025-12-04T15:01:45Z"
  }
}
```

{% /tab %}

{% tab label="Interaction Created" %}

```json
{
  "event_id": "evt_123",
  "event_type": "interaction.created",
  "interaction": {
    "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
    "model": "gemini-3-flash-preview",
    "object": "interaction",
    "status": "in_progress"
  }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**InteractionStatusUpdate**{% /summary %}

{% two-column-layout %}

{% left-column %}

**interaction_id**: {% mark %}required{% /mark %} `string`

{% hr /%}

{% details %}

{% summary %}

**status**: {% mark %}required{% /mark %} `enum (string)`

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

{% hr /%}

**event_type**: {% mark %}required{% /mark %} `object`

Value: `interaction.status_update`

{% hr /%}

**continuation_token**: `string`

An optional opaque continuation token used to resume decoding from the latest checkpoint after a disconnected stream.

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

Model usage statistics up to this checkpoint.

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

**event_id**: `string`

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

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Interaction Status Update**

```json
{
  "event_type": "interaction.status_update",
  "interaction_id": "v1_ChdTMjQ0YWJ5TUF1TzcxZThQdjRpcnFRcxIXUzI0NGFieU1BdU83MWU4UHY0aXJxUXM",
  "status": "in_progress"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**StepDelta**{% /summary %}

{% two-column-layout %}

{% left-column %}

**index**: {% mark %}required{% /mark %} `integer`

{% hr /%}

{% details %}

{% summary %}

**delta**: {% mark %}required{% /mark %} `StepDeltaData`

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**ArgumentsDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `arguments_delta`

**arguments**: `string`

{% /details %}

{% details %}

{% summary %}**AudioDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

{% /summary %}

Possible values:

- `audio/wav`: WAV audio format
- `audio/mp3`: MP3 audio format
- `audio/aiff`: AIFF audio format
- `audio/aac`: AAC audio format
- `audio/ogg`: OGG audio format
- `audio/flac`: FLAC audio format
- `audio/mpeg`: MPEG audio format
- `audio/m4a`: M4A audio format
- `audio/l16`: L16 audio format
- `audio/opus`: OPUS audio format
- `audio/alaw`: ALAW audio format
- `audio/mulaw`: MULAW audio format
- `audio/webm`: WEBM audio format

{% /details %}

**data**: `string`

**uri**: `string`

**sample_rate**: `integer`

The sample rate of the audio.

**channels**: `integer`

The number of audio channels.

{% /details %}

{% details %}

{% summary %}**CodeExecutionCallDelta**{% /summary %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `CodeExecutionCallArguments`

{% /summary %}

{% details %}

{% summary %}

**language**: `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `python`: Python >= 3.10, with numpy and simpy available.
- `bash`: Bash. Only available for Gemini 3.0 model or above.

{% /details %}

**code**: `string`

The code to be executed.

{% /details %}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution_call`

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**CodeExecutionResultDelta**{% /summary %}

**result**: {% mark %}required{% /mark %} `string`

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution_result`

**is_error**: `boolean`

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**DocumentDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `document`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

{% /summary %}

Possible values:

- `application/pdf`: PDF document format
- `text/csv`: CSV document format
- `application/vnd.openxmlformats-officedocument.presentationml.presentation`: PPTX presentation format
- `application/vnd.ms-powerpoint`: PPT presentation format
- `application/vnd.oasis.opendocument.presentation`: ODP presentation format
- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`: DOCX document format
- `application/msword`: DOC document format
- `application/vnd.openxmlformats-officedocument.wordprocessingml.template`: DOTX document template format
- `application/vnd.oasis.opendocument.text`: ODT document format
- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`: XLSX spreadsheet format
- `application/vnd.ms-excel`: XLS spreadsheet format
- `application/vnd.oasis.opendocument.spreadsheet`: ODS spreadsheet format

{% /details %}

**data**: `string`

**uri**: `string`

{% /details %}

{% details %}

{% summary %}**FileSearchCallDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search_call`

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**FileSearchResultDelta**{% /summary %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (FileSearchResult)`

{% /summary %}

{% /details %}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search_result`

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**FunctionResultDelta**{% /summary %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (`[`ImageContent`](/api-reference/interactions-api#Resource:ImageContent) or [`TextContent`](/api-reference/interactions-api#Resource:TextContent)`)` or `object` or `string`

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array ([ImageContent](/api-reference/interactions-api#Resource:ImageContent) or [TextContent](/api-reference/interactions-api#Resource:TextContent))**{% /summary %}

A list where each item is one of: [`ImageContent`](/api-reference/interactions-api#Resource:ImageContent), [`TextContent`](/api-reference/interactions-api#Resource:TextContent).

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

**type**: {% mark %}required{% /mark %} `object`

Value: `function_result`

**name**: `string`

**is_error**: `boolean`

{% /details %}

{% details %}

{% summary %}**GoogleMapsCallDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps_call`

{% details %}

{% summary %}

**arguments**: `GoogleMapsCallArguments`

The arguments to pass to the Google Maps tool.

{% /summary %}

**queries**: `array (string)`

The queries to be executed.

{% /details %}

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**GoogleMapsResultDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps_result`

{% details %}

{% summary %}

**result**: `array (GoogleMapsResult)`

The results of the Google Maps.

{% /summary %}

{% details %}

{% summary %}

**places**: `array (Places)`

The places that were found.

{% /summary %}

**place_id**: `string`

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

**name**: `string`

Title of the place.

**url**: `string`

URI reference of the place.

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

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

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

{% /details %}

**widget_context_token**: `string`

Resource name of the Google Maps widget context token.

{% /details %}

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**GoogleSearchCallDelta**{% /summary %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `GoogleSearchCallArguments`

{% /summary %}

**queries**: `array (string)`

Web search queries for the following-up web search.

{% /details %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search_call`

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**GoogleSearchResultDelta**{% /summary %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (GoogleSearchResult)`

{% /summary %}

**search_suggestions**: `string`

Web content snippet that can be embedded in a web page or an app webview.

{% /details %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search_result`

**is_error**: `boolean`

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**ImageDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

{% /summary %}

Possible values:

- `image/png`: PNG image format
- `image/jpeg`: JPEG image format
- `image/webp`: WebP image format
- `image/heic`: HEIC image format
- `image/heif`: HEIF image format
- `image/gif`: GIF image format
- `image/bmp`: BMP image format
- `image/tiff`: TIFF image format

{% /details %}

**data**: `string`

**uri**: `string`

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServerToolCallDelta**{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

**server_name**: {% mark %}required{% /mark %} `string`

**arguments**: {% mark %}required{% /mark %} `object`

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server_tool_call`

{% /details %}

{% details %}

{% summary %}**McpServerToolResultDelta**{% /summary %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (`[`ImageContent`](/api-reference/interactions-api#Resource:ImageContent) or [`TextContent`](/api-reference/interactions-api#Resource:TextContent)`)` or `object` or `string`

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array ([ImageContent](/api-reference/interactions-api#Resource:ImageContent) or [TextContent](/api-reference/interactions-api#Resource:TextContent))**{% /summary %}

A list where each item is one of: [`ImageContent`](/api-reference/interactions-api#Resource:ImageContent), [`TextContent`](/api-reference/interactions-api#Resource:TextContent).

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server_tool_result`

**name**: `string`

**server_name**: `string`

{% /details %}

{% details %}

{% summary %}**ProcessingCallDelta**{% /summary %}

Streaming delta for a server-initiated media processing step.

**type**: {% mark %}required{% /mark %} `object`

Value: `processing_call`

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**ProcessingResultDelta**{% /summary %}

Streaming delta for the result of a server-initiated media processing step.

**type**: {% mark %}required{% /mark %} `object`

Value: `processing_result`

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**TextAnnotationDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `text_annotation_delta`

{% details %}

{% summary %}

**annotations**: `array (Annotation)`

Citation information for model-generated content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**FileCitation**{% /summary %}

A file citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `file_citation`

**document_uri**: `string`

The URI of the file.

**file_name**: `string`

The name of the file.

**source**: `string`

Source attributed for a portion of the text.

**custom_metadata**: `object`

User provided metadata about the retrieved context.

**page_number**: `integer`

Page number of the cited document, if applicable.

**media_id**: `string`

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

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**PlaceCitation**{% /summary %}

A place citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `place_citation`

**place_id**: `string`

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

**name**: `string`

Title of the place.

**url**: `string`

URI reference of the place.

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

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

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**SpeechAnnotation**{% /summary %}

Speech annotation for text content.

**type**: {% mark %}required{% /mark %} `object`

Value: `speech_metadata`

**speaker**: `string`

The speaker to associate with this turn.

**style**: `string`

Style instruction for the speech synthesis.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**UrlCitation**{% /summary %}

A URL citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `url_citation`

**url**: `string`

The URL.

**title**: `string`

The title of the URL.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**WordInfo**{% /summary %}

Word-level ASR annotation for transcription output. Carries the word text, optional timing, and optional speaker attribution.

**type**: {% mark %}required{% /mark %} `object`

Value: `word_info`

**text**: `string`

The transcribed word.

**start_offset**: `string`

Start offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**end_offset**: `string`

End offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**speaker**: `string`

Optional. Speaker label for this word (e.g. "spk_1", "spk_2"). Present when diarization_mode is set in TranscriptionConfig.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**TextDelta**{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% /details %}

{% details %}

{% summary %}**ThoughtSignatureDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `thought_signature`

**signature**: `string`

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

{% /details %}

{% details %}

{% summary %}**ThoughtSummaryDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `thought_summary`

**content**: [`Content`](/api-reference/interactions-api#Resource:Content)

A new summary item to be added to the thought.

{% /details %}

{% details %}

{% summary %}**UrlContextCallDelta**{% /summary %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `UrlContextCallArguments`

{% /summary %}

**urls**: `array (string)`

The URLs to fetch.

{% /details %}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context_call`

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**UrlContextResultDelta**{% /summary %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (UrlContextResult)`

{% /summary %}

**url**: `string`

The URL that was fetched.

{% details %}

{% summary %}

**status**: `enum (string)`

The status of the URL retrieval.

{% /summary %}

Possible values:

- `success`: Url retrieval is successful.
- `error`: Url retrieval is failed due to error.
- `paywall`: Url retrieval is failed because the content is behind paywall.
- `unsafe`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context_result`

**is_error**: `boolean`

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**VideoDelta**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

{% /summary %}

Possible values:

- `video/mp4`: MP4 video format
- `video/mpeg`: MPEG video format
- `video/mpg`: MPG video format
- `video/mov`: MOV video format
- `video/avi`: AVI video format
- `video/x-flv`: FLV video format
- `video/webm`: WebM video format
- `video/wmv`: WMV video format
- `video/3gpp`: 3GPP video format
- `video/jpeg2000`: JPEG 2000 video format

{% /details %}

**data**: `string`

**uri**: `string`

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**event_type**: {% mark %}required{% /mark %} `object`

Value: `step.delta`

{% hr /%}

**event_id**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**metadata**: `StepDeltaMetadata`

{% /summary %}

{% details %}

{% summary %}

**total_usage**: `Usage`

Statistics on the interaction request's token usage.

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Step Delta**

```json
{
  "delta": {
    "type": "text",
    "text": "Hello"
  },
  "event_type": "step.delta",
  "index": 0
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**StepStart**{% /summary %}

{% two-column-layout %}

{% left-column %}

**index**: {% mark %}required{% /mark %} `integer`

{% hr /%}

**step**: {% mark %}required{% /mark %} [`Step`](/api-reference/interactions-api#Resource:Step)

{% hr /%}

**event_type**: {% mark %}required{% /mark %} `object`

Value: `step.start`

{% hr /%}

**event_id**: `string`

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

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Step Start**

```json
{
  "event_type": "step.start",
  "index": 0,
  "step": {
    "type": "model_output"
  }
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**StepStop**{% /summary %}

{% two-column-layout %}

{% left-column %}

**index**: {% mark %}required{% /mark %} `integer`

{% hr /%}

**event_type**: {% mark %}required{% /mark %} `object`

Value: `step.stop`

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

Cumulative model usage stats from the start of the session.

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**step_usage**: `Usage`

Model usage stats for this specific step.

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

**event_id**: `string`

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

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Step Stop**

```json
{
  "event_type": "step.stop",
  "index": 0
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### ResponseFormat {% id="Resource:ResponseFormat" %}

**Polymorphic Types:**

{% details %}

{% summary %}**AudioResponseFormat**{% /summary %}

Configuration for audio output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the audio output.

{% /summary %}

Possible values:

- `audio/mp3`: MP3 audio format.
- `audio/ogg_opus`: OGG Opus audio format.
- `audio/l16`: Raw PCM (L16) audio format.
- `audio/wav`: WAV audio format.
- `audio/alaw`: A-law audio format.
- `audio/mulaw`: Mu-law audio format.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the audio output.

{% /summary %}

Possible values:

- `inline`: Audio data is returned inline in the response.
- `uri`: Audio data is returned as a URI.

{% /details %}

{% hr /%}

**sample_rate**: `integer`

Sample rate in Hz.

{% hr /%}

**bit_rate**: `integer`

Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Audio Output**

```json
{
  "type": "audio",
  "sample_rate": 24000
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ImageResponseFormat**{% /summary %}

Configuration for image output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the image output.

{% /summary %}

Possible values:

- `image/jpeg`: JPEG image format.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the image output.

{% /summary %}

Possible values:

- `inline`: Image data is returned inline in the response.
- `uri`: Image data is returned as a URI.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the image output.

{% /summary %}

Possible values:

- `1:1`: 1:1 aspect ratio.
- `2:3`: 2:3 aspect ratio.
- `3:2`: 3:2 aspect ratio.
- `3:4`: 3:4 aspect ratio.
- `4:3`: 4:3 aspect ratio.
- `4:5`: 4:5 aspect ratio.
- `5:4`: 5:4 aspect ratio.
- `9:16`: 9:16 aspect ratio.
- `16:9`: 16:9 aspect ratio.
- `21:9`: 21:9 aspect ratio.
- `1:8`: 1:8 aspect ratio.
- `8:1`: 8:1 aspect ratio.
- `1:4`: 1:4 aspect ratio.
- `4:1`: 4:1 aspect ratio.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**image_size**: `enum (string)`

The size of the image output.

{% /summary %}

Possible values:

- `512`: 512px image size.
- `1K`: 1K image size.
- `2K`: 2K image size.
- `4K`: 4K image size.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image Output**

```json
{
  "type": "image",
  "aspect_ratio": "16:9",
  "image_size": "1K",
  "mime_type": "image/jpeg"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**TextResponseFormat**{% /summary %}

Configuration for text output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the text output.

{% /summary %}

Possible values:

- `application/json`: JSON output format.
- `text/plain`: Plain text output format.

{% /details %}

{% hr /%}

**schema**: `object`

The JSON schema that the output should conform to. Only applicable when mime_type is application/json. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced; validate these in your application. `minItems` and `maxItems` are enforced. Schemas that are too complex to enforce (for example, large `maxItems` on nested arrays) return a 400 INVALID_ARGUMENT error.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text Output (JSON Schema)**

```json
{
  "type": "text",
  "mime_type": "application/json",
  "schema": {
    "type": "object",
    "properties": {
      "ingredients": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "recipe_name": {
        "type": "string"
      }
    },
    "required": [
      "ingredients",
      "recipe_name"
    ]
  }
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**VideoResponseFormat**{% /summary %}

Configuration for video output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the video output.

{% /summary %}

Possible values:

- `inline`: Video data is returned inline in the response.
- `uri`: Video data is returned as a URI.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the video output.

{% /summary %}

Possible values:

- `16:9`: 16:9 aspect ratio.
- `9:16`: 9:16 aspect ratio.

{% /details %}

{% hr /%}

**duration**: `string`

The duration for the video output.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `enum (string)`

The video output resolution. Defaults to 720p.

{% /summary %}

Possible values:

- `360p`: 360p resolution.
- `720p`: 720p resolution.
- `1080p`: 1080p resolution.
- `4k`: 4K resolution.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Video Output**

```json
{
  "type": "video",
  "aspect_ratio": "16:9",
  "delivery": "inline"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### Step {% id="Resource:Step" %}

A step in the interaction.

**Polymorphic Types:**

{% details %}

{% summary %}**CodeExecutionCallStep**{% /summary %}

Code execution call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `CodeExecutionCallStepArguments`

The arguments to pass to the code execution.

{% /summary %}

{% details %}

{% summary %}

**language**: `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `python`: Python >= 3.10, with numpy and simpy available.
- `bash`: Bash. Only available for Gemini 3.0 model or above.

{% /details %}

**code**: `string`

The code to be executed.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**CodeExecutionCallStep**

```json
{
  "type": "code_execution_call",
  "arguments": {
    "code": "print(sum(range(1, 11)))"
  },
  "id": "code_call_71021"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**CodeExecutionResultStep**{% /summary %}

Code execution result step.

{% two-column-layout %}

{% left-column %}

**result**: {% mark %}required{% /mark %} `string`

The output of the code execution.

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution_result`

{% hr /%}

**is_error**: `boolean`

Whether the code execution resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**CodeExecutionResultStep**

```json
{
  "type": "code_execution_result",
  "call_id": "code_call_71021",
  "result": "55\n"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearchCallStep**{% /summary %}

File Search call step.

{% two-column-layout %}

{% left-column %}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FileSearchCallStep**

```json
{
  "type": "file_search_call",
  "id": "file_call_88192"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearchResultStep**{% /summary %}

File Search result step.

{% two-column-layout %}

{% left-column %}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FileSearchResultStep**

```json
{
  "type": "file_search_result",
  "call_id": "file_call_88192"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FunctionCallStep**{% /summary %}

A function tool call step.

{% two-column-layout %}

{% left-column %}

**name**: {% mark %}required{% /mark %} `string`

The name of the tool to call.

{% hr /%}

**arguments**: {% mark %}required{% /mark %} `object`

The arguments to pass to the function.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `function_call`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FunctionCallStep**

```json
{
  "name": "get_weather",
  "type": "function_call",
  "arguments": {
    "location": "Boston, MA"
  },
  "id": "call_98231"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FunctionResultStep**{% /summary %}

Result of a function tool call.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (`[`ImageContent`](/api-reference/interactions-api#Resource:ImageContent) or [`TextContent`](/api-reference/interactions-api#Resource:TextContent)`)` or `object` or `string`

The result of the tool call.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array ([ImageContent](/api-reference/interactions-api#Resource:ImageContent) or [TextContent](/api-reference/interactions-api#Resource:TextContent))**{% /summary %}

A list where each item is one of: [`ImageContent`](/api-reference/interactions-api#Resource:ImageContent), [`TextContent`](/api-reference/interactions-api#Resource:TextContent).

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `function_result`

{% hr /%}

**name**: `string`

The name of the tool that was called.

{% hr /%}

**is_error**: `boolean`

Whether the tool call resulted in an error.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FunctionResultStep**

```json
{
  "name": "get_weather",
  "type": "function_result",
  "call_id": "call_98231",
  "result": [
    {
      "type": "text",
      "text": "{\"weather\":\"sunny\"}"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMapsCallStep**{% /summary %}

Google Maps call step.

{% two-column-layout %}

{% left-column %}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps_call`

{% hr /%}

{% details %}

{% summary %}

**arguments**: `GoogleMapsCallStepArguments`

The arguments to pass to the Google Maps tool.

{% /summary %}

**queries**: `array (string)`

The queries to be executed.

{% /details %}

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleMapsCallStep**

```json
{
  "type": "google_maps_call",
  "arguments": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "id": "maps_call_39201"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMapsResultStep**{% /summary %}

Google Maps result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (GoogleMapsResultItem)`

{% /summary %}

{% details %}

{% summary %}

**places**: `array (GoogleMapsResultPlaces)`

{% /summary %}

**place_id**: `string`

**name**: `string`

**url**: `string`

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

{% /details %}

**widget_context_token**: `string`

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleMapsResultStep**

```json
{
  "type": "google_maps_result",
  "call_id": "maps_call_39201",
  "result": [
    {
      "name": "Golden Gate Park",
      "place_id": "ChIJIQBpAG2ahYAR9R7bNdTLg8M",
      "rating": 4.8
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearchCallStep**{% /summary %}

Google Search call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `GoogleSearchCallStepArguments`

The arguments to pass to Google Search.

{% /summary %}

**queries**: `array (string)`

Web search queries for the following-up web search.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search_call`

{% hr /%}

{% details %}

{% summary %}

**search_type**: `enum (string)`

The type of search grounding enabled.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleSearchCallStep**

```json
{
  "type": "google_search_call",
  "arguments": {
    "query": "Who won the men's 100m in Paris 2024?"
  },
  "id": "search_call_19201"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearchResultStep**{% /summary %}

Google Search result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (GoogleSearchResultItem)`

The results of the Google Search.

{% /summary %}

**search_suggestions**: `string`

Web content snippet that can be embedded in a web page or an app webview.

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search_result`

{% hr /%}

**is_error**: `boolean`

Whether the Google Search resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleSearchResultStep**

```json
{
  "type": "google_search_result",
  "call_id": "search_call_19201",
  "result": [
    {
      "title": "Paris 2024 Olympics: Noah Lyles wins men's 100m gold",
      "url": "https://olympics.com/en/news/paris-2024-noah-lyles-wins-mens-100m-gold",
      "snippet": "American Noah Lyles won the Olympic men's 100m gold medal in a photo finish."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServerToolCallStep**{% /summary %}

MCPServer tool call step.

{% two-column-layout %}

{% left-column %}

**name**: {% mark %}required{% /mark %} `string`

The name of the tool which was called.

{% hr /%}

**server_name**: {% mark %}required{% /mark %} `string`

The name of the used MCP server.

{% hr /%}

**arguments**: {% mark %}required{% /mark %} `object`

The JSON object of arguments for the function.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server_tool_call`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**McpServerToolCallStep**

```json
{
  "name": "calculate_tax",
  "type": "mcp_server_tool_call",
  "arguments": {
    "income": 120000,
    "state": "CA"
  },
  "id": "mcp_call_29012",
  "server_name": "financial_mcp_server"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServerToolResultStep**{% /summary %}

MCPServer tool result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (`[`ImageContent`](/api-reference/interactions-api#Resource:ImageContent) or [`TextContent`](/api-reference/interactions-api#Resource:TextContent)`)` or `object` or `string`

The output from the MCP server call. Can be simple text or rich content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array ([ImageContent](/api-reference/interactions-api#Resource:ImageContent) or [TextContent](/api-reference/interactions-api#Resource:TextContent))**{% /summary %}

A list where each item is one of: [`ImageContent`](/api-reference/interactions-api#Resource:ImageContent), [`TextContent`](/api-reference/interactions-api#Resource:TextContent).

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server_tool_result`

{% hr /%}

**name**: `string`

Name of the tool which is called for this specific tool call.

{% hr /%}

**server_name**: `string`

The name of the used MCP server.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**McpServerToolResultStep**

```json
{
  "name": "calculate_tax",
  "type": "mcp_server_tool_result",
  "call_id": "mcp_call_29012",
  "result": {
    "tax_due": 32400
  },
  "server_name": "financial_mcp_server"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ModelOutputStep**{% /summary %}

Output generated by the model.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `model_output`

{% hr /%}

**content**: `array (`[`Content`](/api-reference/interactions-api#Resource:Content)`)`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**ModelOutputStep**

```json
{
  "type": "model_output",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ProcessingCallStep**{% /summary %}

A server-initiated processing step for media analysis (e.g. video
understanding).

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `processing_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**ProcessingResultStep**{% /summary %}

The result of a server-initiated media processing step.

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `processing_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**ThoughtStep**{% /summary %}

A thought step.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `thought`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% hr /%}

**summary**: `array (`[`Content`](/api-reference/interactions-api#Resource:Content)`)`

A summary of the thought.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**ThoughtStep**

```json
{
  "type": "thought",
  "signature": "thought_sig_abcd1234",
  "summary": [
    {
      "type": "text",
      "text": "The model is searching Google for the capital of France."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContextCallStep**{% /summary %}

URL context call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `UrlContextCallArguments`

The arguments to pass to the URL context.

{% /summary %}

**urls**: `array (string)`

The URLs to fetch.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UrlContextCallStep**

```json
{
  "type": "url_context_call",
  "arguments": {
    "urls": [
      "https://www.example.com"
    ]
  },
  "id": "url_call_10219"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContextResultStep**{% /summary %}

URL context result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (UrlContextResult)`

The results of the URL context.

{% /summary %}

**url**: `string`

The URL that was fetched.

{% details %}

{% summary %}

**status**: `enum (string)`

The status of the URL retrieval.

{% /summary %}

Possible values:

- `success`: Url retrieval is successful.
- `error`: Url retrieval is failed due to error.
- `paywall`: Url retrieval is failed because the content is behind paywall.
- `unsafe`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context_result`

{% hr /%}

**is_error**: `boolean`

Whether the URL context resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UrlContextResultStep**

```json
{
  "type": "url_context_result",
  "call_id": "url_call_10219",
  "result": [
    {
      "title": "Example Domain",
      "url": "https://www.example.com",
      "snippet": "This domain is for use in illustrative examples in documents."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UserInputStep**{% /summary %}

Input provided by the user.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `user_input`

{% hr /%}

**content**: `array (`[`Content`](/api-reference/interactions-api#Resource:Content)`)`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UserInputStep**

```json
{
  "type": "user_input",
  "content": [
    {
      "type": "text",
      "text": "What is the capital of France?"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### EnvironmentConfig {% id="Resource:EnvironmentConfig" %}

Configuration for a custom environment.

{% two-column-layout %}

{% left-column %}

**Properties:**

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% hr /%}

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**network**: [`EnvironmentNetworkEgressAllowlist`](/api-reference/interactions-api#Resource:EnvironmentNetworkEgressAllowlist) or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentNetworkEgressAllowlist](/api-reference/interactions-api#Resource:EnvironmentNetworkEgressAllowlist)**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% hr /%}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% hr /%}

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="Inline Sources" %}

```json
{
  "type": "remote",
  "sources": [
    {
      "type": "inline",
      "content": "You are a data analyst. Always include visualizations and export results as PDF.",
      "target": ".agents/AGENTS.md"
    },
    {
      "type": "inline",
      "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",
      "target": ".agents/skills/slide-maker/SKILL.md"
    }
  ]
}
```

{% /tab %}

{% tab label="External Sources" %}

```json
{
  "type": "remote",
  "sources": [
    {
      "type": "repository",
      "source": "https://github.com/my-org/my-skills.git",
      "target": ".agents/skills"
    },
    {
      "type": "gcs",
      "source": "gs://my-bucket/my-folder",
      "target": "/workspace/data"
    }
  ]
}
```

{% /tab %}

{% tab label="Network Allowlist" %}

```json
{
  "type": "remote",
  "network": {
    "allowlist": [
      {
        "domain": "pypi.org"
      },
      {
        "domain": "*.github.com"
      }
    ]
  }
}
```

{% /tab %}

{% tab label="Proxy Credentials" %}

```json
{
  "type": "remote",
  "network": {
    "allowlist": [
      {
        "domain": "api.github.com",
        "transform": {
          "Authorization": "Bearer YOUR_GITHUB_TOKEN"
        }
      }
    ]
  }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

### EnvironmentNetworkEgressAllowlist {% id="Resource:EnvironmentNetworkEgressAllowlist" %}

Network egress configuration for the environment.

{% two-column-layout %}

{% left-column %}

**Properties:**

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Network Allowlist**

```json
{
  "allowlist": [
    {
      "domain": "github.com",
      "transform": [
        {
          "Authorization": "Bearer your-token"
        }
      ]
    },
    {
      "domain": "*.googleapis.com"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

### ToolChoiceConfig {% id="Resource:ToolChoiceConfig" %}

The tool choice configuration containing allowed tools.

{% two-column-layout %}

{% left-column %}

**Properties:**

{% details %}

{% summary %}

**allowed_tools**: `AllowedTools`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

```json
{
  "allowed_tools": {
    "mode": "any",
    "tools": [
      "my_tool"
    ]
  }
}
```

{% /right-column %}

{% /two-column-layout %}

### ImageContent {% id="Resource:ImageContent" %}

An image content block.

{% two-column-layout %}

{% left-column %}

**Properties:**

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

**data**: `string`

The image content.

{% hr /%}

**uri**: `string`

The URI of the image.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the image.

{% /summary %}

Possible values:

- `image/png`: PNG image format
- `image/jpeg`: JPEG image format
- `image/webp`: WebP image format
- `image/heic`: HEIC image format
- `image/heif`: HEIF image format
- `image/gif`: GIF image format
- `image/bmp`: BMP image format
- `image/tiff`: TIFF image format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image**

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

{% /right-column %}

{% /two-column-layout %}

### TextContent {% id="Resource:TextContent" %}

A text content block.

{% two-column-layout %}

{% left-column %}

**Properties:**

**text**: {% mark %}required{% /mark %} `string`

The text content.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**annotations**: `array (Annotation)`

Citation information for model-generated content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**FileCitation**{% /summary %}

A file citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `file_citation`

**document_uri**: `string`

The URI of the file.

**file_name**: `string`

The name of the file.

**source**: `string`

Source attributed for a portion of the text.

**custom_metadata**: `object`

User provided metadata about the retrieved context.

**page_number**: `integer`

Page number of the cited document, if applicable.

**media_id**: `string`

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

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**PlaceCitation**{% /summary %}

A place citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `place_citation`

**place_id**: `string`

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

**name**: `string`

Title of the place.

**url**: `string`

URI reference of the place.

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

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

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**SpeechAnnotation**{% /summary %}

Speech annotation for text content.

**type**: {% mark %}required{% /mark %} `object`

Value: `speech_metadata`

**speaker**: `string`

The speaker to associate with this turn.

**style**: `string`

Style instruction for the speech synthesis.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**UrlCitation**{% /summary %}

A URL citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `url_citation`

**url**: `string`

The URL.

**title**: `string`

The title of the URL.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**WordInfo**{% /summary %}

Word-level ASR annotation for transcription output. Carries the word text, optional timing, and optional speaker attribution.

**type**: {% mark %}required{% /mark %} `object`

Value: `word_info`

**text**: `string`

The transcribed word.

**start_offset**: `string`

Start offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**end_offset**: `string`

End offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**speaker**: `string`

Optional. Speaker label for this word (e.g. "spk_1", "spk_2"). Present when diarization_mode is set in TranscriptionConfig.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text**

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

{% /right-column %}

{% /two-column-layout %}

# Creating an interaction
Source: https://aistudio.google.com/api-reference/interactions-api/create-interaction
Description: Creates a new interaction.

{% callout type="note" %}

You are viewing the beta version of the Interactions API. Endpoints are under `/v1beta/`. The stable [v1 version](/api-reference/interactions-api/create-interaction?api-version=v1) is also available.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/interactions`

Creates a new interaction.

{% two-column-layout %}

{% left-column %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**model**: `ModelOption`

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

{% /summary %}

Possible values:

- `gemma-4-26b-a4b-it`: Gemma 4 26B A4B IT
- `gemma-4-31b-it`: Gemma 4 31B IT
- `gemini-flash-latest`: Latest release of Gemini Flash
- `gemini-flash-lite-latest`: Latest release of Gemini Flash-Lite
- `gemini-pro-latest`: Latest release of Gemini Pro
- `gemini-2.5-flash`: Our first hybrid reasoning model which supports a 1M token context window and has thinking budgets.
- `gemini-2.5-pro`: Our state-of-the-art multipurpose model, which excels at coding and complex reasoning tasks.
- `gemini-2.5-flash-lite`: Our smallest and most cost effective model, built for at scale usage.
- `gemini-3.5-flash-lite`: Gemini 3.5 Flash-Lite - Our fastest, most cost-effective 3.5 model for high-throughput execution.
- `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-3-flash-preview`: Our most intelligent model built for speed, combining frontier intelligence with superior search and grounding.
- `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-pro-preview-customtools`: Gemini 3.1 Pro Preview optimized for custom tool usage
- `gemini-3.1-flash-lite`: Our most cost-efficient model, optimized for high-volume agentic tasks, translation, and simple data processing.
- `gemini-3.1-flash-lite-image`: Gemini 3.1 Flash Lite Image.
- `gemini-3-pro-image`: Gemini 3 Pro Image
- `nano-banana-pro-preview`: Gemini 3 Pro Image Preview
- `gemini-3.1-flash-image`: Gemini 3.1 Flash Image.
- `gemini-nano-banana-2.1`: Gemini Nano Banana 2.1.
- `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.
- `gemini-3.5-flash`: Gemini 3.5 Flash - Our earlier Flash model, built for speed and foundational performance across routine, high-throughput workloads.
- `gemini-3.6-flash`: Gemini 3.6 Flash - Our previous generation Flash model, balancing speed and multimodal capabilities across general agentic and everyday tasks.
- `gemini-3.7-flash`: Gemini 3.7 Flash - Our high-speed, efficient Flash model built for everyday coding, agentic tool use, and reliable multi-step execution.
- `gemini-3.8-flash`: Gemini 3.8 Flash - Our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows.
- `gemini-3.8-flash-tts`: Gemini 3.8 Flash TTS - Flagship TTS model for Voice Design and dual-speaker screenplay control. Prompt custom vocal personas, direct line-by-line delivery, and add vocal bursts.
- `gemini-3.8-flash-lite-tts`: Gemini 3.8 Flash Lite TTS - High-speed and cost-efficient, ideal for rapid dubbing, media localization, and high-throughput voice agents. Direct replacement for gemini-3.1-flash-tts-preview.
- `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.
- `gemini-robotics-er-1.6-preview`: Gemini Robotics-ER 1.6 Preview
- `gemini-robotics-er-2-preview`: Gemini Robotics Embodied Reasoning 2 Preview
- `lyria-3.5`: Our flagship music generation model, optimized for full-length songs with complex structural coherence.
- `gemini-omni-1.1-flash`: Our high-performance multimodal model designed for fast, conversational video generation, editing, and cinematic control.
- `gemini-omni-flash-preview`: Preview release of our multimodal model for conversational video generation, editing, and cinematic control.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**agent**: `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

{% hr /%}

**input**: {% mark %}required{% /mark %} [`Content`](/api-reference/interactions-api/create-interaction#Resource:Content) or `array (`[`Content`](/api-reference/interactions-api/create-interaction#Resource:Content)`)` or `array (`[`Step`](/api-reference/interactions-api/create-interaction#Resource:Step)`)` or `string`

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

{% hr /%}

{% details %}

{% summary %}

**generation_config**: `GenerationConfig`

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

{% /summary %}

**seed**: `integer`

Seed used in decoding for reproducibility.

**stop_sequences**: `array (string)`

A list of character sequences that will stop output interaction.

{% details %}

{% summary %}

**tool_choice**: [`ToolChoiceConfig`](/api-reference/interactions-api/create-interaction#Resource:ToolChoiceConfig) or `enum (string)`

The tool choice configuration.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[ToolChoiceConfig](/api-reference/interactions-api/create-interaction#Resource:ToolChoiceConfig)**{% /summary %}

The tool choice configuration containing allowed tools.

{% details %}

{% summary %}

**allowed_tools**: `AllowedTools`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**thinking_level**: `ThinkingLevel`

The level of thought tokens that the model should generate.

{% /summary %}

Possible values:

- `minimal`: Little to no thinking.
- `low`: Low thinking level.
- `medium`: Medium thinking level.
- `high`: High thinking level.

{% /details %}

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

**max_output_tokens**: `integer`

The maximum number of tokens to include in the response.

{% details %}

{% summary %}

**video_config**: `VideoConfig`

Configuration for video generation.

{% /summary %}

{% details %}

{% summary %}

**task**: `enum (string)`

Optional task mode for video generation. If not specified, the model automatically determines the appropriate mode based on the provided text prompt and input media.

{% /summary %}

Possible values:

- `text_to_video`: Generates video solely from a text prompt.
- `image_to_video`: Generates video from one or two source images. The first image defines the starting frame, and the optional second image defines the ending frame.
- `reference_to_video`: Generates video using reference media (such as images, audio, or video).
- `edit`: Modifies an existing input video.
- `extend`: Extends an existing input video.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**transcription_config**: `TranscriptionConfig`

Optional. Configuration for speech recognition (transcription). If present, ASR is enabled.

{% /summary %}

**language_codes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**custom_vocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms.

{% details %}

{% summary %}

**mode**: `TranscriptionMode` or `enum (string)`

Discriminated transcription mode options or enum.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**SmartTranscriptionMode**{% /summary %}

Configuration for smart transcription mode.

**type**: {% mark %}required{% /mark %} `object`

Value: `smart`

{% /details %}

{% details %}

{% summary %}**VerbatimTranscriptionMode**{% /summary %}

Configuration for verbatim transcription mode.

**type**: {% mark %}required{% /mark %} `object`

Value: `verbatim`

**timestamp_granularities**: `array (string)`

Optional. The granularity of timestamps to include in the transcription output. Supported values: "word". If empty, no timestamps are generated.

**diarization_mode**: `string`

Optional. Configures speaker diarization. Supported values: "speaker".

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `verbatim`: Verbatim transcription mode.
- `smart`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**structured_speech_config**: `SpeakerConfig` or `array (SpeechConfig)`

Speech and multi-speaker configuration.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**SpeakerConfig**{% /summary %}

Configuration for multi-speaker and speech generation.

{% details %}

{% summary %}

**speakers**: `array (SpeechConfig)`

Individual speaker configurations.

{% /summary %}

**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.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (SpeechConfig)**{% /summary %}

The 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.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

{% hr /%}

**system_instruction**: `string`

System instruction for the interaction.

{% hr /%}

**tools**: `array (`[`Tool`](/api-reference/interactions-api/create-interaction#Resource:Tool)`)`

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

{% hr /%}

{% details %}

{% summary %}

**response_format**: [`ResponseFormat`](/api-reference/interactions-api/create-interaction#Resource:ResponseFormat) or `array (`[`ResponseFormat`](/api-reference/interactions-api/create-interaction#Resource:ResponseFormat)`)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[ResponseFormat](/api-reference/interactions-api/create-interaction#Resource:ResponseFormat)**{% /summary %}

{% /details %}

{% details %}

{% summary %}**array ([ResponseFormat](/api-reference/interactions-api/create-interaction#Resource:ResponseFormat))**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

{% hr /%}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% hr /%}

{% details %}

{% summary %}

**environment**: [`EnvironmentConfig`](/api-reference/interactions-api/create-interaction#Resource:EnvironmentConfig) or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentConfig](/api-reference/interactions-api/create-interaction#Resource:EnvironmentConfig)**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: [`EnvironmentNetworkEgressAllowlist`](/api-reference/interactions-api/create-interaction#Resource:EnvironmentNetworkEgressAllowlist) or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentNetworkEgressAllowlist](/api-reference/interactions-api/create-interaction#Resource:EnvironmentNetworkEgressAllowlist)**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

{% hr /%}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

{% hr /%}

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

{% hr /%}

**stream**: `boolean`

Input only. Whether the interaction will be streamed.

{% hr /%}

**store**: `boolean`

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

{% hr /%}

**background**: `boolean`

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

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="Simple Request" %}

{% tabs %}

{% tab label="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-flash-latest",
    "input": "Hello, how are you?"
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-flash-latest",
    input="Hello, how are you?",
)
print(interaction.output_text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  input: 'Hello, how are you?',
});
console.log(interaction.output_text);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .input(InteractionsInput.of("Hello, how are you?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Hello, how are you?")),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Multi-turn" %}

{% tabs %}

{% tab label="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-flash-latest",
    "input": [
      { "type": "user_input", "content": [{ "type": "text", "text": "Hello!" }] },
      { "type": "model_output", "content": [{ "type": "text", "text": "Hi there! How can I help you today?" }] },
      { "type": "user_input", "content": [{ "type": "text", "text": "What is the capital of France?" }] }
    ]
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    input=[
        {
            "type": "user_input",
            "content": [{"type": "text", "text": "Hello!"}],
        },
        {
            "type": "model_output",
            "content": [{
                "type": "text",
                "text": "Hi there! How can I help you today?",
            }],
        },
        {
            "type": "user_input",
            "content": [
                {"type": "text", "text": "What is the capital of France?"}
            ],
        },
    ],
)
print(response.output_text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  input: [
    {type: 'user_input', content: [{type: 'text', text: 'Hello'}]},
    {
      type: 'model_output',
      content: [
        {type: 'text', text: 'Hi there! How can I help you today?'},
      ],
    },
    {
      type: 'user_input',
      content: [{type: 'text', text: 'What is the capital of France?'}],
    },
  ],
});
console.log(interaction.output_text);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.UserInputStep;

Client client = new Client();
List<Step> conversation =
    List.of(
        UserInputStep.builder()
            .content(List.of(TextContent.builder().text("Hello!").build()))
            .build(),
        ModelOutputStep.builder()
            .content(
                List.of(
                    TextContent.builder().text("Hi there! How can I help you today?").build()))
            .build(),
        UserInputStep.builder()
            .content(
                List.of(TextContent.builder().text("What is the capital of France?").build()))
            .build());
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .input(InteractionsInput.ofStep(conversation))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    history := []gaos_interactions.Step{
        gaos_interactions.NewStep(gaos_interactions.UserInputStep{
            Content: []gaos_interactions.Content{
                gaos_interactions.NewContent(gaos_interactions.TextContent{
                    Text: "Hello!",
                }),
            },
        }),
        gaos_interactions.NewStep(gaos_interactions.ModelOutputStep{
            Content: []gaos_interactions.Content{
                gaos_interactions.NewContent(gaos_interactions.TextContent{
                    Text: "Hi there! How can I help you today?",
                }),
            },
        }),
        gaos_interactions.NewStep(gaos_interactions.UserInputStep{
            Content: []gaos_interactions.Content{
                gaos_interactions.NewContent(gaos_interactions.TextContent{
                    Text: "What is the capital of France?",
                }),
            },
        }),
    }

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput(history)),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Image Input" %}

{% tabs %}

{% tab label="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-flash-latest",
    "input": [
      {
        "type": "text",
        "text": "What is in this picture?"
      },
      {
        "type": "image",
        "data": "BASE64_ENCODED_IMAGE",
        "mime_type": "image/png"
      }
    ]
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    input=[
        {"type": "text", "text": "What is in this picture?"},
        {
            "type": "image",
            "data": "BASE64_ENCODED_IMAGE",
            "mime_type": "image/png",
        },
    ],
)
print(response.output_text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  input: [
    {type: 'text', text: 'What is in this picture?'},
    {type: 'image', data: 'BASE64_ENCODED_IMAGE', mime_type: 'image/png'},
  ],
});
console.log(interaction.output_text);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.TextContent;

Client client = new Client();
List<Content> content =
    List.of(
        TextContent.builder().text("What is in this picture?").build(),
        ImageContent.builder()
            .data("BASE64_ENCODED_IMAGE")
            .mimeType(ImageContentMimeType.IMAGE_PNG)
            .build());
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .input(InteractionsInput.ofContent(content))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []gaos_interactions.Content{
        gaos_interactions.NewContent(gaos_interactions.TextContent{
            Text: "What is in this picture?",
        }),
        gaos_interactions.NewContent(gaos_interactions.ImageContent{
            Data:     genai.Ptr("BASE64_ENCODED_IMAGE"),
            MimeType: gaos_interactions.ImageContentMimeTypeImagePng.ToPointer(),
        }),
    }

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput(contents)),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Function Calling" %}

{% tabs %}

{% tab label="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-flash-latest",
    "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?"
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    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.steps[-1])
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  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.steps.at(-1));
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Step;

Client client = new Client();
Map<String, Object> parameters =
    Map.of(
        "type", "object",
        "properties",
            Map.of(
                "location",
                Map.of(
                    "type", "string",
                    "description", "The city and state, e.g. San Francisco, CA")),
        "required", List.of("location"));
Function functionTool =
    Function.builder()
        .name("get_weather")
        .description("Get the current weather in a given location")
        .parameters(parameters)
        .build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(functionTool))
        .input(InteractionsInput.of("What is the weather like in Boston, MA?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
List<Step> steps = interaction.steps().orElse(List.of());
if (!steps.isEmpty()) {
  System.out.println(steps.get(steps.size() - 1));
}
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    function := gaos_interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Get the current weather in a given location"),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{
                    "type":        "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                },
            },
            "required": []string{"location"},
        },
    }

    tool := gaos_interactions.NewTool(function)

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What is the weather like in Boston, MA?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil {
        for _, step := range res.Interaction.Steps {
            if step.FunctionCallStep != nil {
                fmt.Println("Function Call:", step.FunctionCallStep.Name)
                fmt.Println("Arguments:", step.FunctionCallStep.Arguments)
            }
        }
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Deep Research" %}

{% tabs %}

{% tab label="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-preview-04-2026",
    "input": "Find a cure to cancer",
    "background": true
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="find a cure to cancer",
    background=True,
)
print(interaction.status)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  agent: 'deep-research-preview-04-2026',
  input: 'find a cure to cancer',
  background: true,
});
console.log(interaction.status);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent(AgentOption.of("deep-research-preview-04-2026"))
        .input(InteractionsInput.of("find a cure to cancer"))
        .background(true)
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.status().map(InteractionStatus::value).orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{
        Agent:      gaos_interactions.AgentOption("deep-research-preview-04-2026"),
        Input:      genai.Ptr(gaos_interactions.NewInteractionsInput("find a cure to cancer")),
        Background: genai.Ptr(true),
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil {
        fmt.Println(res.Interaction.Status)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Antigravity Agent" %}

{% tabs %}

{% tab label="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": "antigravity-preview-05-2026",
    "input": "Read Hacker News, summarize the top 5 stories, and save results as a markdown file.",
    "environment": "remote"
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input=(
        "Read Hacker News, summarize the top 5 stories, and save results as"
        " a markdown file."
    ),
    environment="remote",
)
print(interaction.output_text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  agent: 'antigravity-preview-05-2026',
  input:
    'Read Hacker News, summarize the top 5 stories, and save results as a markdown file.',
  environment: 'remote',
});
console.log(interaction.output_text);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent(AgentOption.of("antigravity-preview-05-2026"))
        .input(
            InteractionsInput.of(
                "Read Hacker News, summarize the top 5 stories, and save results as a markdown"
                    + " file."))
        .environment(CreateAgentInteractionEnvironment.of("remote"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{
        Agent:       gaos_interactions.AgentOption("antigravity-preview-05-2026"),
        Input:       genai.Ptr(gaos_interactions.NewInteractionsInput("Read Hacker News, summarize the top 5 stories, and save results as a markdown file.")),
        Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment("remote")),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Reuse Environment" %}

{% tabs %}

{% tab label="REST" %}

```sh
# Step 1: Create an interaction with a fresh remote environment.
RESPONSE=$(curl -s -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "antigravity-preview-05-2026",
    "input": "Write a hello world script at /workspace/hello.py.",
    "environment": "remote"
  }')
INTERACTION_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
ENV_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['environment_id'])")

# Step 2: Reuse the same environment in a follow-up interaction.
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent\": \"antigravity-preview-05-2026\",
    \"input\": \"Modify the script to accept a name argument and greet the user.\",
    \"environment\": \"$ENV_ID\",
    \"previous_interaction_id\": \"$INTERACTION_ID\"
  }"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

# Step 1: Create an interaction with a fresh remote environment.
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a hello world script at /workspace/hello.py.",
    environment="remote",
)
print(f"Environment ID: {interaction.environment_id}")

# Step 2: Reuse the same environment in a follow-up interaction.
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Modify the script to accept a name argument and greet the user.",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
)
print(interaction_2.output_text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

// Step 1: Create an interaction with a fresh remote environment.
const interaction = await ai.interactions.create({
  agent: 'antigravity-preview-05-2026',
  input: 'Write a hello world script at /workspace/hello.py.',
  environment: 'remote',
});
console.log(`Environment ID: ${interaction.environment_id}`);

// Step 2: Reuse the same environment in a follow-up interaction.
const interaction2 = await ai.interactions.create({
  agent: 'antigravity-preview-05-2026',
  input: 'Modify the script to accept a name argument and greet the user.',
  environment: interaction.environment_id,
  previous_interaction_id: interaction.id,
});
console.log(interaction2.output_text);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Step;

Client client = new Client();

// Step 1: Create an interaction with a fresh remote environment.
CreateAgentInteraction params1 =
    CreateAgentInteraction.builder()
        .agent(AgentOption.of("antigravity-preview-05-2026"))
        .input(InteractionsInput.of("Write a hello world script at /workspace/hello.py."))
        .environment(CreateAgentInteractionEnvironment.of("remote"))
        .build();
CreateInteractionResponse response1 =
    client.interactions.create(CreateInteractionRequestBody.of(params1));
Interaction interaction1 =
    response1.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println("Environment ID: " + interaction1.environmentId().orElse(""));

// Step 2: Reuse the same environment in a follow-up interaction.
CreateAgentInteraction params2 =
    CreateAgentInteraction.builder()
        .agent(AgentOption.of("antigravity-preview-05-2026"))
        .input(
            InteractionsInput.of(
                "Modify the script to accept a name argument and greet the user."))
        .environment(
            CreateAgentInteractionEnvironment.of(interaction1.environmentId().orElse("")))
        .previousInteractionId(interaction1.id().orElse(null))
        .build();
CreateInteractionResponse response2 =
    client.interactions.create(CreateInteractionRequestBody.of(params2));
Interaction interaction2 =
    response2.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction2.outputText().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Step 1: Create an interaction with a fresh remote environment.
    body1 := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{
        Agent:       gaos_interactions.AgentOption("antigravity-preview-05-2026"),
        Input:       genai.Ptr(gaos_interactions.NewInteractionsInput("Write a hello world script at /workspace/hello.py.")),
        Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment("remote")),
    })

    res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body1})
    if err != nil {
        log.Fatal(err)
    }

    if res1.Interaction == nil || res1.Interaction.EnvironmentID == nil {
        log.Fatal("No environment ID returned")
    }
    fmt.Printf("Environment ID: %s\n", *res1.Interaction.EnvironmentID)

    // Step 2: Reuse the same environment in a follow-up interaction.
    body2 := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{
        Agent:                 gaos_interactions.AgentOption("antigravity-preview-05-2026"),
        Input:                 genai.Ptr(gaos_interactions.NewInteractionsInput("Modify the script to accept a name argument and greet the user.")),
        Environment:           genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment(*res1.Interaction.EnvironmentID)),
        PreviousInteractionID: res1.Interaction.ID,
    })

    res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body2})
    if err != nil {
        log.Fatal(err)
    }

    if res2.Interaction != nil && res2.Interaction.OutputText != nil {
        fmt.Println(*res2.Interaction.OutputText)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="With Sources" %}

{% tabs %}

{% tab label="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": "antigravity-preview-05-2026",
    "input": "List all files under /workspace and summarize what you find.",
    "environment": {
      "type": "remote",
      "sources": [
        {
          "type": "repository",
          "source": "https://github.com/octocat/Spoon-Knife",
          "target": "/workspace/repo"
        },
        {
          "type": "inline",
          "content": "Focus on Python files only.",
          "target": "/workspace/notes.txt"
        }
      ]
    }
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="List all files under /workspace and summarize what you find.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/octocat/Spoon-Knife",
                "target": "/workspace/repo",
            },
            {
                "type": "inline",
                "content": "Focus on Python files only.",
                "target": "/workspace/notes.txt",
            },
        ],
    },
)
print(interaction.output_text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  agent: 'antigravity-preview-05-2026',
  input: 'List all files under /workspace and summarize what you find.',
  environment: {
    type: 'remote',
    sources: [
      {
        type: 'repository',
        source: 'https://github.com/octocat/Spoon-Knife',
        target: '/workspace/repo',
      },
      {
        type: 'inline',
        content: 'Focus on Python files only.',
        target: '/workspace/notes.txt',
      },
    ],
  },
});
console.log(interaction.output_text);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;

Client client = new Client();
com.google.genai.gaos.models.interactions.Environment env =
    com.google.genai.gaos.models.interactions.Environment.builder()
        .sources(
            List.of(
                Source.builder()
                    .type(SourceType.REPOSITORY)
                    .source("https://github.com/octocat/Spoon-Knife")
                    .target("/workspace/repo")
                    .build(),
                Source.builder()
                    .type(SourceType.INLINE)
                    .content("Focus on Python files only.")
                    .target("/workspace/notes.txt")
                    .build()))
        .build();
CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent(AgentOption.of("antigravity-preview-05-2026"))
        .input(
            InteractionsInput.of(
                "List all files under /workspace and summarize what you find."))
        .environment(CreateAgentInteractionEnvironment.of(env))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    env := gaos_interactions.Environment{
        Sources: []gaos_interactions.Source{
            {
                Type:   genai.Ptr(gaos_interactions.SourceTypeRepository),
                Source: genai.Ptr("https://github.com/octocat/Spoon-Knife"),
                Target: genai.Ptr("/workspace/repo"),
            },
            {
                Type:    genai.Ptr(gaos_interactions.SourceTypeInline),
                Content: genai.Ptr("Focus on Python files only."),
                Target:  genai.Ptr("/workspace/notes.txt"),
            },
        },
    }

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{
        Agent:       gaos_interactions.AgentOption("antigravity-preview-05-2026"),
        Input:       genai.Ptr(gaos_interactions.NewInteractionsInput("List all files under /workspace and summarize what you find.")),
        Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment(env)),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Custom Agent" %}

{% tabs %}

{% tab label="REST" %}

```sh
# Step 1: Create a custom agent.
curl -X POST https://generativelanguage.googleapis.com/v1beta/agents \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "code-reviewer",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    "base_environment": {
      "type": "remote",
      "sources": [{
        "type": "repository",
        "source": "https://github.com/octocat/Spoon-Knife",
        "target": "/workspace/repo"
      }]
    }
  }'

# Step 2: Use the custom agent.
curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "code-reviewer",
    "input": "Review the latest changes in /workspace/repo/src and file a summary.",
    "environment": "remote"
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
import uuid
from google import genai

client = genai.Client()

# Step 1: Create a custom agent.
agent_id = f"code-reviewer-{uuid.uuid4().hex[:8]}"
client.agents.create(
    id=agent_id,
    base_agent="antigravity-preview-05-2026",
    system_instruction=(
        "You are a senior code reviewer. Check every file for bugs, style"
        " issues, and security vulnerabilities."
    ),
    base_environment={
        "type": "remote",
        "sources": [{
            "type": "repository",
            "source": "https://github.com/octocat/Spoon-Knife",
            "target": "/workspace/repo",
        }],
    },
)

# Step 2: Use the custom agent.
result = client.interactions.create(
    agent=agent_id,
    input=(
        "Review the latest changes in /workspace/repo/src and file a"
        " summary."
    ),
    environment="remote",
)
print(result.output_text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

// Step 1: Create a custom agent.
const agentId = `code-reviewer-${crypto.randomUUID().slice(0, 8)}`;
await ai.agents.create({
  id: agentId,
  base_agent: 'antigravity-preview-05-2026',
  system_instruction:
    'You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.',
  base_environment: {
    type: 'remote',
    sources: [
      {
        type: 'repository',
        source: 'https://github.com/octocat/Spoon-Knife',
        target: '/workspace/repo',
      },
    ],
  },
});

// Step 2: Use the custom agent.
const result = await ai.interactions.create({
  agent: agentId,
  input:
    'Review the latest changes in /workspace/repo/src and file a summary.',
  environment: 'remote',
});
console.log(result.output_text);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.agents.BaseEnvironment;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.interactions.Step;

Client client = new Client();

// Step 1: Create a custom agent.
String agentId = "code-reviewer-" + UUID.randomUUID().toString().substring(0, 8);
com.google.genai.gaos.models.interactions.Environment baseEnv =
    com.google.genai.gaos.models.interactions.Environment.builder()
        .sources(
            List.of(
                Source.builder()
                    .type(SourceType.REPOSITORY)
                    .source("https://github.com/octocat/Spoon-Knife")
                    .target("/workspace/repo")
                    .build()))
        .build();
Agent customAgent =
    Agent.builder()
        .id(agentId)
        .baseAgent("antigravity-preview-05-2026")
        .systemInstruction(
            "You are a senior code reviewer. Check every file for bugs, style issues, and"
                + " security vulnerabilities.")
        .baseEnvironment(BaseEnvironment.of(baseEnv))
        .build();
client.agents.create(customAgent);

// Step 2: Use the custom agent.
CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent(AgentOption.of(agentId))
        .input(
            InteractionsInput.of(
                "Review the latest changes in /workspace/repo/src and file a summary."))
        .environment(CreateAgentInteractionEnvironment.of("remote"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "google.golang.org/genai"
    gaos_agents "google.golang.org/genai/interactions/models/agents"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Step 1: Create a custom agent.
    agentID := fmt.Sprintf("code-reviewer-%d", time.Now().UnixNano())
    baseEnv := gaos_interactions.Environment{
        Sources: []gaos_interactions.Source{
            {
                Type:   genai.Ptr(gaos_interactions.SourceTypeRepository),
                Source: genai.Ptr("https://github.com/octocat/Spoon-Knife"),
                Target: genai.Ptr("/workspace/repo"),
            },
        },
    }

    _, err = client.Agents.Create(ctx, operations.CreateAgentRequest{
        Body: gaos_agents.Agent{
            ID:                genai.Ptr(agentID),
            BaseAgent:         genai.Ptr("antigravity-preview-05-2026"),
            SystemInstruction: genai.Ptr("You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities."),
            BaseEnvironment:   genai.Ptr(gaos_agents.NewBaseEnvironment(baseEnv)),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // Step 2: Use the custom agent.
    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{
        Agent:       gaos_interactions.AgentOption(agentID),
        Input:       genai.Ptr(gaos_interactions.NewInteractionsInput("Review the latest changes in /workspace/repo/src and file a summary.")),
        Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment("remote")),
    })

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

Returns [`Interaction`](/api-reference/interactions-api/create-interaction#Resource:Interaction) resources.

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

{% tabs %}

{% tab label="Simple Request" %}

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

{% /tab %}

{% tab label="Multi-turn" %}

```json
{
  "created": "2025-11-26T12:22:47Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The capital of France is Paris."
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:22:47Z",
  "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
  }
}
```

{% /tab %}

{% tab label="Image Input" %}

```json
{
  "created": "2025-11-26T12:22:47Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "A white humanoid robot with glowing blue eyes stands holding a red skateboard."
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:22:47Z",
  "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
  }
}
```

{% /tab %}

{% tab label="Function Calling" %}

```json
{
  "created": "2025-11-26T12:22:47Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "requires_action",
  "steps": [
    {
      "name": "get_weather",
      "type": "function_call",
      "arguments": {
        "location": "Boston, MA"
      },
      "id": "gth23981"
    }
  ],
  "updated": "2025-11-26T12:22:47Z",
  "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
  }
}
```

{% /tab %}

{% tab label="Deep Research" %}

```json
{
  "agent": "deep-research-preview-04-2026",
  "created": "2025-11-26T12:22:47Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Here is a comprehensive research report on the current state of cancer research..."
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:22:47Z",
  "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
  }
}
```

{% /tab %}

{% tab label="Antigravity Agent" %}

```json
{
  "agent": "antigravity-preview-05-2026",
  "created": "2025-11-26T12:22:47Z",
  "environment_id": "env_abc123",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "I've summarized the top 5 Hacker News stories and saved the results to /workspace/summary.md."
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:22:47Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 50
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 50,
    "total_output_tokens": 500,
    "total_thought_tokens": 200,
    "total_tokens": 750,
    "total_tool_use_tokens": 0
  }
}
```

{% /tab %}

{% tab label="Reuse Environment" %}

```json
{
  "agent": "antigravity-preview-05-2026",
  "created": "2025-11-26T12:23:00Z",
  "environment_id": "env_abc123",
  "id": "v1_Chd2ZTJhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjM0NTY3ODkwMTIzNDU2Nzg",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "I've updated /workspace/hello.py to accept a name argument and greet the user."
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:23:00Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 80
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 80,
    "total_output_tokens": 200,
    "total_thought_tokens": 100,
    "total_tokens": 380,
    "total_tool_use_tokens": 0
  }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### Interaction {% class="hide-from-toc" id="Resource:Interaction" %}

The Interaction resource.

{% two-column-layout %}

{% left-column %}

**Properties:**

**id**: {% mark %}required{% /mark %} `string`

Output only. A unique identifier for the interaction completion.

{% hr /%}

{% details %}

{% summary %}

**status**: {% mark %}required{% /mark %} `enum (string)`

Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

{% hr /%}

**created**: {% mark %}required{% /mark %} `string`

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

{% hr /%}

**updated**: {% mark %}required{% /mark %} `string`

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

{% hr /%}

**steps**: {% mark %}required{% /mark %} `array (`[`Step`](/api-reference/interactions-api/create-interaction#Resource:Step)`)`

Output only. The steps that make up the interaction, when included in the response.

{% hr /%}

{% details %}

{% summary %}

**model**: `ModelOption`

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

{% /summary %}

Possible values:

- `gemma-4-26b-a4b-it`: Gemma 4 26B A4B IT
- `gemma-4-31b-it`: Gemma 4 31B IT
- `gemini-flash-latest`: Latest release of Gemini Flash
- `gemini-flash-lite-latest`: Latest release of Gemini Flash-Lite
- `gemini-pro-latest`: Latest release of Gemini Pro
- `gemini-2.5-flash`: Our first hybrid reasoning model which supports a 1M token context window and has thinking budgets.
- `gemini-2.5-pro`: Our state-of-the-art multipurpose model, which excels at coding and complex reasoning tasks.
- `gemini-2.5-flash-lite`: Our smallest and most cost effective model, built for at scale usage.
- `gemini-3.5-flash-lite`: Gemini 3.5 Flash-Lite - Our fastest, most cost-effective 3.5 model for high-throughput execution.
- `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-3-flash-preview`: Our most intelligent model built for speed, combining frontier intelligence with superior search and grounding.
- `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-pro-preview-customtools`: Gemini 3.1 Pro Preview optimized for custom tool usage
- `gemini-3.1-flash-lite`: Our most cost-efficient model, optimized for high-volume agentic tasks, translation, and simple data processing.
- `gemini-3.1-flash-lite-image`: Gemini 3.1 Flash Lite Image.
- `gemini-3-pro-image`: Gemini 3 Pro Image
- `nano-banana-pro-preview`: Gemini 3 Pro Image Preview
- `gemini-3.1-flash-image`: Gemini 3.1 Flash Image.
- `gemini-nano-banana-2.1`: Gemini Nano Banana 2.1.
- `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.
- `gemini-3.5-flash`: Gemini 3.5 Flash - Our earlier Flash model, built for speed and foundational performance across routine, high-throughput workloads.
- `gemini-3.6-flash`: Gemini 3.6 Flash - Our previous generation Flash model, balancing speed and multimodal capabilities across general agentic and everyday tasks.
- `gemini-3.7-flash`: Gemini 3.7 Flash - Our high-speed, efficient Flash model built for everyday coding, agentic tool use, and reliable multi-step execution.
- `gemini-3.8-flash`: Gemini 3.8 Flash - Our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows.
- `gemini-3.8-flash-tts`: Gemini 3.8 Flash TTS - Flagship TTS model for Voice Design and dual-speaker screenplay control. Prompt custom vocal personas, direct line-by-line delivery, and add vocal bursts.
- `gemini-3.8-flash-lite-tts`: Gemini 3.8 Flash Lite TTS - High-speed and cost-efficient, ideal for rapid dubbing, media localization, and high-throughput voice agents. Direct replacement for gemini-3.1-flash-tts-preview.
- `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.
- `gemini-robotics-er-1.6-preview`: Gemini Robotics-ER 1.6 Preview
- `gemini-robotics-er-2-preview`: Gemini Robotics Embodied Reasoning 2 Preview
- `lyria-3.5`: Our flagship music generation model, optimized for full-length songs with complex structural coherence.
- `gemini-omni-1.1-flash`: Our high-performance multimodal model designed for fast, conversational video generation, editing, and cinematic control.
- `gemini-omni-flash-preview`: Preview release of our multimodal model for conversational video generation, editing, and cinematic control.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**generation_config**: `GenerationConfig`

Input only. Configuration parameters for the model interaction.

{% /summary %}

**seed**: `integer`

Seed used in decoding for reproducibility.

**stop_sequences**: `array (string)`

A list of character sequences that will stop output interaction.

{% details %}

{% summary %}

**tool_choice**: [`ToolChoiceConfig`](/api-reference/interactions-api/create-interaction#Resource:ToolChoiceConfig) or `enum (string)`

The tool choice configuration.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[ToolChoiceConfig](/api-reference/interactions-api/create-interaction#Resource:ToolChoiceConfig)**{% /summary %}

The tool choice configuration containing allowed tools.

{% details %}

{% summary %}

**allowed_tools**: `AllowedTools`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**thinking_level**: `ThinkingLevel`

The level of thought tokens that the model should generate.

{% /summary %}

Possible values:

- `minimal`: Little to no thinking.
- `low`: Low thinking level.
- `medium`: Medium thinking level.
- `high`: High thinking level.

{% /details %}

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

**max_output_tokens**: `integer`

The maximum number of tokens to include in the response.

{% details %}

{% summary %}

**video_config**: `VideoConfig`

Configuration for video generation.

{% /summary %}

{% details %}

{% summary %}

**task**: `enum (string)`

Optional task mode for video generation. If not specified, the model automatically determines the appropriate mode based on the provided text prompt and input media.

{% /summary %}

Possible values:

- `text_to_video`: Generates video solely from a text prompt.
- `image_to_video`: Generates video from one or two source images. The first image defines the starting frame, and the optional second image defines the ending frame.
- `reference_to_video`: Generates video using reference media (such as images, audio, or video).
- `edit`: Modifies an existing input video.
- `extend`: Extends an existing input video.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**transcription_config**: `TranscriptionConfig`

Optional. Configuration for speech recognition (transcription). If present, ASR is enabled.

{% /summary %}

**language_codes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**custom_vocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms.

{% details %}

{% summary %}

**mode**: `TranscriptionMode` or `enum (string)`

Discriminated transcription mode options or enum.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**SmartTranscriptionMode**{% /summary %}

Configuration for smart transcription mode.

**type**: {% mark %}required{% /mark %} `object`

Value: `smart`

{% /details %}

{% details %}

{% summary %}**VerbatimTranscriptionMode**{% /summary %}

Configuration for verbatim transcription mode.

**type**: {% mark %}required{% /mark %} `object`

Value: `verbatim`

**timestamp_granularities**: `array (string)`

Optional. The granularity of timestamps to include in the transcription output. Supported values: "word". If empty, no timestamps are generated.

**diarization_mode**: `string`

Optional. Configures speaker diarization. Supported values: "speaker".

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `verbatim`: Verbatim transcription mode.
- `smart`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**structured_speech_config**: `SpeakerConfig` or `array (SpeechConfig)`

Speech and multi-speaker configuration.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**SpeakerConfig**{% /summary %}

Configuration for multi-speaker and speech generation.

{% details %}

{% summary %}

**speakers**: `array (SpeechConfig)`

Individual speaker configurations.

{% /summary %}

**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.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (SpeechConfig)**{% /summary %}

The 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.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**system_instruction**: `string`

System instruction for the interaction.

{% hr /%}

**tools**: `array (`[`Tool`](/api-reference/interactions-api/create-interaction#Resource:Tool)`)`

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

{% hr /%}

**input**: [`Content`](/api-reference/interactions-api/create-interaction#Resource:Content) or `array (`[`Content`](/api-reference/interactions-api/create-interaction#Resource:Content)`)` or `array (`[`Step`](/api-reference/interactions-api/create-interaction#Resource:Step)`)` or `string`

The input for the interaction.

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

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

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**response_format**: [`ResponseFormat`](/api-reference/interactions-api/create-interaction#Resource:ResponseFormat) or `array (`[`ResponseFormat`](/api-reference/interactions-api/create-interaction#Resource:ResponseFormat)`)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[ResponseFormat](/api-reference/interactions-api/create-interaction#Resource:ResponseFormat)**{% /summary %}

{% /details %}

{% details %}

{% summary %}**array ([ResponseFormat](/api-reference/interactions-api/create-interaction#Resource:ResponseFormat))**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

{% hr /%}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% hr /%}

{% details %}

{% summary %}

**environment**: [`EnvironmentConfig`](/api-reference/interactions-api/create-interaction#Resource:EnvironmentConfig) or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentConfig](/api-reference/interactions-api/create-interaction#Resource:EnvironmentConfig)**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: [`EnvironmentNetworkEgressAllowlist`](/api-reference/interactions-api/create-interaction#Resource:EnvironmentNetworkEgressAllowlist) or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentNetworkEgressAllowlist](/api-reference/interactions-api/create-interaction#Resource:EnvironmentNetworkEgressAllowlist)**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**environment_id**: `string`

Output only. The environment ID for the interaction. Only populated if environment config is set in the request.

{% hr /%}

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

{% hr /%}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

{% hr /%}

{% details %}

{% summary %}

**errors**: `array (Error)`

Output only. Diagnostic faults / platform errors recorded on the interaction.

{% /summary %}

**code**: `string`

A URI that identifies the error type.

**message**: `string`

A human-readable error message.

{% /details %}

{% hr /%}

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

{% hr /%}

**stream**: `boolean`

Input only. Whether the interaction will be streamed.

{% hr /%}

**store**: `boolean`

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

{% hr /%}

**background**: `boolean`

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

{% hr /%}

{% details %}

{% summary %}

**agent**: `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

Configuration parameters for the agent interaction.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

{% hr /%}

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

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

{% /right-column %}

{% /two-column-layout %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### Content {% class="hide-from-toc" id="Resource:Content" %}

The content of the response.

**Polymorphic Types:**

{% details %}

{% summary %}**AudioContent**{% /summary %}

An audio content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% hr /%}

**data**: `string`

The audio content.

{% hr /%}

**uri**: `string`

The URI of the audio.

{% hr /%}

**channels**: `integer`

The number of audio channels.

{% hr /%}

**sample_rate**: `integer`

The sample rate of the audio.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the audio.

{% /summary %}

Possible values:

- `audio/wav`: WAV audio format
- `audio/mp3`: MP3 audio format
- `audio/aiff`: AIFF audio format
- `audio/aac`: AAC audio format
- `audio/ogg`: OGG audio format
- `audio/flac`: FLAC audio format
- `audio/mpeg`: MPEG audio format
- `audio/m4a`: M4A audio format
- `audio/l16`: L16 audio format
- `audio/opus`: OPUS audio format
- `audio/alaw`: ALAW audio format
- `audio/mulaw`: MULAW audio format
- `audio/webm`: WEBM audio format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Audio**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**DocumentContent**{% /summary %}

A document content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `document`

{% hr /%}

**data**: `string`

The document content.

{% hr /%}

**uri**: `string`

The URI of the document.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the document.

{% /summary %}

Possible values:

- `application/pdf`: PDF document format
- `text/csv`: CSV document format
- `application/vnd.openxmlformats-officedocument.presentationml.presentation`: PPTX presentation format
- `application/vnd.ms-powerpoint`: PPT presentation format
- `application/vnd.oasis.opendocument.presentation`: ODP presentation format
- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`: DOCX document format
- `application/msword`: DOC document format
- `application/vnd.openxmlformats-officedocument.wordprocessingml.template`: DOTX document template format
- `application/vnd.oasis.opendocument.text`: ODT document format
- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`: XLSX spreadsheet format
- `application/vnd.ms-excel`: XLS spreadsheet format
- `application/vnd.oasis.opendocument.spreadsheet`: ODS spreadsheet format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Document**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**[ImageContent](/api-reference/interactions-api/create-interaction#Resource:ImageContent)**{% /summary %}

An image content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

**data**: `string`

The image content.

{% hr /%}

**uri**: `string`

The URI of the image.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the image.

{% /summary %}

Possible values:

- `image/png`: PNG image format
- `image/jpeg`: JPEG image format
- `image/webp`: WebP image format
- `image/heic`: HEIC image format
- `image/heif`: HEIF image format
- `image/gif`: GIF image format
- `image/bmp`: BMP image format
- `image/tiff`: TIFF image format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**[TextContent](/api-reference/interactions-api/create-interaction#Resource:TextContent)**{% /summary %}

A text content block.

{% two-column-layout %}

{% left-column %}

**text**: {% mark %}required{% /mark %} `string`

The text content.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**annotations**: `array (Annotation)`

Citation information for model-generated content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**FileCitation**{% /summary %}

A file citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `file_citation`

**document_uri**: `string`

The URI of the file.

**file_name**: `string`

The name of the file.

**source**: `string`

Source attributed for a portion of the text.

**custom_metadata**: `object`

User provided metadata about the retrieved context.

**page_number**: `integer`

Page number of the cited document, if applicable.

**media_id**: `string`

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

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**PlaceCitation**{% /summary %}

A place citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `place_citation`

**place_id**: `string`

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

**name**: `string`

Title of the place.

**url**: `string`

URI reference of the place.

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

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

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**SpeechAnnotation**{% /summary %}

Speech annotation for text content.

**type**: {% mark %}required{% /mark %} `object`

Value: `speech_metadata`

**speaker**: `string`

The speaker to associate with this turn.

**style**: `string`

Style instruction for the speech synthesis.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**UrlCitation**{% /summary %}

A URL citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `url_citation`

**url**: `string`

The URL.

**title**: `string`

The title of the URL.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**WordInfo**{% /summary %}

Word-level ASR annotation for transcription output. Carries the word text, optional timing, and optional speaker attribution.

**type**: {% mark %}required{% /mark %} `object`

Value: `word_info`

**text**: `string`

The transcribed word.

**start_offset**: `string`

Start offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**end_offset**: `string`

End offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**speaker**: `string`

Optional. Speaker label for this word (e.g. "spk_1", "spk_2"). Present when diarization_mode is set in TranscriptionConfig.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**VideoContent**{% /summary %}

A video content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% hr /%}

**data**: `string`

The video content.

{% hr /%}

**uri**: `string`

The URI of the video.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**processing**: `MediaProcessing` or `enum (string)`

How the model processes this video for understanding.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**MediaProcessing**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `static`

**start_offset**: `string`

Optional. Segment start time. Specified as a decimal number of seconds followed by an 's' suffix, e.g., "10.5s". Must be non-negative.

**end_offset**: `string`

Optional. Segment end time. Specified as a decimal number of seconds followed by an 's' suffix, e.g., "30s". Must be non-negative and greater than `start_offset` if `start_offset` is set.

**fps**: `number`

Optional. Video frame-rate sampling density.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `static`: Fixed-rate frame extraction. All frames placed in context.
- `agentic`: Model-driven dynamic navigation.

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

A user-defined name for this content block. Can be referenced by the model in the final response.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the video.

{% /summary %}

Possible values:

- `video/mp4`: MP4 video format
- `video/mpeg`: MPEG video format
- `video/mpg`: MPG video format
- `video/mov`: MOV video format
- `video/avi`: AVI video format
- `video/x-flv`: FLV video format
- `video/webm`: WebM video format
- `video/wmv`: WMV video format
- `video/3gpp`: 3GPP video format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Video**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### Tool {% class="hide-from-toc" id="Resource:Tool" %}

A tool that can be used by the model.

**Polymorphic Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "code_execution"
    }],
    "input": "Calculate the first 10 Fibonacci numbers"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "code_execution"}],
    input="Calculate the first 10 Fibonacci numbers",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'code_execution'}],
  input: 'Calculate the first 10 Fibonacci numbers',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new CodeExecution()))
        .input(InteractionsInput.of("Calculate the first 10 Fibonacci numbers"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="code_execution" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.CodeExecution{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Calculate the first 10 Fibonacci numbers")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ComputerUse**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `computer_use`

{% hr /%}

{% details %}

{% summary %}

**environment**: `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `browser`: Operates in a web browser.
- `mobile`: Operates in a mobile environment.
- `desktop`: Operates in a desktop environment.

{% /details %}

{% hr /%}

**excluded_predefined_functions**: `array (string)`

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

{% hr /%}

**enable_prompt_injection_detection**: `boolean`

Whether enable the prompt injection detection check on computer-use request.

{% hr /%}

{% details %}

{% summary %}

**disabled_safety_policies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `financial_transactions`: Safety policy for financial transactions.
- `sensitive_data_modification`: Safety policy for sensitive data modification.
- `communication_tool`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `account_creation`: Safety policy for account creation.
- `data_modification`: Safety policy for data modification.
- `user_consent_management`: Safety policy for user consent management.
- `legal_terms_and_agreements`: Safety policy for legal terms and agreements.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-2.5-computer-use-preview-10-2025",
    "tools": [{
      "type": "computer_use"
    }],
    "input": "Find a flight to Tokyo"
  }'

```

{% /tab %}

{% tab label="Python" %}

```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.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```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.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-2.5-computer-use-preview-10-2025")
        .tools(List.of(new ComputerUse()))
        .input(InteractionsInput.of("Find a flight to Tokyo"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="computer_use" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.ComputerUse{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-2.5-computer-use-preview-10-2025"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Find a flight to Tokyo")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearch**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search`

{% hr /%}

**file_search_store_names**: `array (string)`

The file search store names to search.

{% hr /%}

**top_k**: `integer`

The number of semantic retrieval chunks to retrieve.

{% hr /%}

**metadata_filter**: `string`

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

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "file_search",
      "file_search_store_names": ["fileSearchStores/m64d1sevsr4y-xfyawui3fxqg"]
    }],
    "input": "Who is the author of the book?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

# Create a file search store so we have a valid one to use.
store = client.file_search_stores.create()

response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[
        {"type": "file_search", "file_search_store_names": [store.name]}
    ],
    input="What documents are available?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

// Create a file search store so we have a valid one to use.
const store = await ai.fileSearchStores.create({});
if (!store.name) {
  throw new Error('Store creation failed: Name is undefined');
}

const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [
    {
      type: 'file_search',
      file_search_store_names: [store.name],
    },
  ],
  input: 'What documents are available?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.types.FileSearchStore;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();

// Create a file search store so we have a valid one to use.
FileSearchStore store =
    client.fileSearchStores.create(CreateFileSearchStoreConfig.builder().build());
String storeName = store.name().orElseThrow();

FileSearch tool = FileSearch.builder().fileSearchStoreNames(List.of(storeName)).build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(tool))
        .input(InteractionsInput.of("What documents are available?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="file_search" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    tool := gaos_interactions.NewTool(gaos_interactions.FileSearch{
        FileSearchStoreNames: []string{store.Name},
    })

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What documents are available?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `function`

{% hr /%}

**name**: `string`

The name of the function.

{% hr /%}

**description**: `string`

A description of the function.

{% hr /%}

**parameters**: `object`

The JSON Schema for the function's parameters. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "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?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    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.steps[-1])

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  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.steps.at(-1));

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Step;

Client client = new Client();
Map<String, Object> parameters =
    Map.of(
        "type", "object",
        "properties",
            Map.of(
                "location",
                Map.of(
                    "type", "string",
                    "description", "The city and state, e.g. San Francisco, CA")),
        "required", List.of("location"));
Function functionTool =
    Function.builder()
        .name("get_weather")
        .description("Get the current weather in a given location")
        .parameters(parameters)
        .build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(functionTool))
        .input(InteractionsInput.of("What is the weather like in Boston?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
List<Step> steps = interaction.steps().orElse(List.of());
if (!steps.isEmpty()) {
  System.out.println(steps.get(steps.size() - 1));
}

```

{% /tab %}

{% tab label="function_calling" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    function := gaos_interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Get the current weather in a given location"),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{
                    "type":        "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                },
            },
            "required": []string{"location"},
        },
    }

    tool := gaos_interactions.NewTool(function)

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What is the weather like in Boston, MA?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil {
        for _, step := range res.Interaction.Steps {
            if step.FunctionCallStep != nil {
                fmt.Println("Function Call:", step.FunctionCallStep.Name)
                fmt.Println("Arguments:", step.FunctionCallStep.Arguments)
            }
        }
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMaps**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps`

{% hr /%}

**enable_widget**: `boolean`

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

{% hr /%}

**latitude**: `number`

The latitude of the user's location.

{% hr /%}

**longitude**: `number`

The longitude of the user's location.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "google_maps",
      "latitude": 37.7749,
      "longitude": -122.4194
    }],
    "input": "What is the best food near me?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[
        {"type": "google_maps", "latitude": 37.7749, "longitude": -122.4194}
    ],
    input="What is the best food near me?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [
    {
      type: 'google_maps',
      latitude: 37.7749,
      longitude: -122.4194,
    },
  ],
  input: 'What is the best food near me?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
GoogleMaps tool = GoogleMaps.builder().latitude(37.7749).longitude(-122.4194).build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(tool))
        .input(InteractionsInput.of("What is the best food near me?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="google_maps" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.GoogleMaps{
        Latitude:  genai.Ptr(37.7749),
        Longitude: genai.Ptr(-122.4194),
    })

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What is the best food near me?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% hr /%}

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "google_search"
    }],
    "input": "Who is the current president of France?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "google_search"}],
    input="Who is the current president of France?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'google_search'}],
  input: 'Who is the current president of France?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new GoogleSearch()))
        .input(InteractionsInput.of("Who is the current president of France?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="google_search" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.GoogleSearch{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Who is the current president of France?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server`

{% hr /%}

**name**: `string`

The name of the MCPServer.

{% hr /%}

**url**: `string`

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

{% hr /%}

**headers**: `object`

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

{% hr /%}

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "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?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
import os

from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    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.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  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.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.MCPServer;

Client client = new Client();
MCPServer mcpTool =
    MCPServer.builder()
        .name("weather_service")
        .url("https://gemini-api-demos.uc.r.appspot.com/mcp")
        .build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(mcpTool))
        .input(
            InteractionsInput.of(
                "Today is 12-05-2025, what is the temperature today in London?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="mcp_server" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    mcpServer := gaos_interactions.MCPServer{
        Name: genai.Ptr("weather_service"),
        URL:  genai.Ptr("https://gemini-api-demos.uc.r.appspot.com/mcp"),
    }
    tool := gaos_interactions.NewTool(mcpServer)

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Today is 12-05-2025, what is the temperature today in London?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "url_context"
    }],
    "input": "Summarize https://www.example.com"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "url_context"}],
    input="Summarize https://www.example.com",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'url_context'}],
  input: 'Summarize https://www.example.com',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.URLContext;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new URLContext()))
        .input(InteractionsInput.of("Summarize https://www.example.com"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="url_context" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.URLContext{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Summarize https://www.example.com")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### ResponseFormat {% class="hide-from-toc" id="Resource:ResponseFormat" %}

**Polymorphic Types:**

{% details %}

{% summary %}**AudioResponseFormat**{% /summary %}

Configuration for audio output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the audio output.

{% /summary %}

Possible values:

- `audio/mp3`: MP3 audio format.
- `audio/ogg_opus`: OGG Opus audio format.
- `audio/l16`: Raw PCM (L16) audio format.
- `audio/wav`: WAV audio format.
- `audio/alaw`: A-law audio format.
- `audio/mulaw`: Mu-law audio format.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the audio output.

{% /summary %}

Possible values:

- `inline`: Audio data is returned inline in the response.
- `uri`: Audio data is returned as a URI.

{% /details %}

{% hr /%}

**sample_rate**: `integer`

Sample rate in Hz.

{% hr /%}

**bit_rate**: `integer`

Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Audio Output**

```json
{
  "type": "audio",
  "sample_rate": 24000
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ImageResponseFormat**{% /summary %}

Configuration for image output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the image output.

{% /summary %}

Possible values:

- `image/jpeg`: JPEG image format.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the image output.

{% /summary %}

Possible values:

- `inline`: Image data is returned inline in the response.
- `uri`: Image data is returned as a URI.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the image output.

{% /summary %}

Possible values:

- `1:1`: 1:1 aspect ratio.
- `2:3`: 2:3 aspect ratio.
- `3:2`: 3:2 aspect ratio.
- `3:4`: 3:4 aspect ratio.
- `4:3`: 4:3 aspect ratio.
- `4:5`: 4:5 aspect ratio.
- `5:4`: 5:4 aspect ratio.
- `9:16`: 9:16 aspect ratio.
- `16:9`: 16:9 aspect ratio.
- `21:9`: 21:9 aspect ratio.
- `1:8`: 1:8 aspect ratio.
- `8:1`: 8:1 aspect ratio.
- `1:4`: 1:4 aspect ratio.
- `4:1`: 4:1 aspect ratio.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**image_size**: `enum (string)`

The size of the image output.

{% /summary %}

Possible values:

- `512`: 512px image size.
- `1K`: 1K image size.
- `2K`: 2K image size.
- `4K`: 4K image size.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image Output**

```json
{
  "type": "image",
  "aspect_ratio": "16:9",
  "image_size": "1K",
  "mime_type": "image/jpeg"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**TextResponseFormat**{% /summary %}

Configuration for text output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the text output.

{% /summary %}

Possible values:

- `application/json`: JSON output format.
- `text/plain`: Plain text output format.

{% /details %}

{% hr /%}

**schema**: `object`

The JSON schema that the output should conform to. Only applicable when mime_type is application/json. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced; validate these in your application. `minItems` and `maxItems` are enforced. Schemas that are too complex to enforce (for example, large `maxItems` on nested arrays) return a 400 INVALID_ARGUMENT error.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text Output (JSON Schema)**

```json
{
  "type": "text",
  "mime_type": "application/json",
  "schema": {
    "type": "object",
    "properties": {
      "ingredients": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "recipe_name": {
        "type": "string"
      }
    },
    "required": [
      "ingredients",
      "recipe_name"
    ]
  }
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**VideoResponseFormat**{% /summary %}

Configuration for video output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the video output.

{% /summary %}

Possible values:

- `inline`: Video data is returned inline in the response.
- `uri`: Video data is returned as a URI.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the video output.

{% /summary %}

Possible values:

- `16:9`: 16:9 aspect ratio.
- `9:16`: 9:16 aspect ratio.

{% /details %}

{% hr /%}

**duration**: `string`

The duration for the video output.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `enum (string)`

The video output resolution. Defaults to 720p.

{% /summary %}

Possible values:

- `360p`: 360p resolution.
- `720p`: 720p resolution.
- `1080p`: 1080p resolution.
- `4k`: 4K resolution.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Video Output**

```json
{
  "type": "video",
  "aspect_ratio": "16:9",
  "delivery": "inline"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### Step {% class="hide-from-toc" id="Resource:Step" %}

A step in the interaction.

**Polymorphic Types:**

{% details %}

{% summary %}**CodeExecutionCallStep**{% /summary %}

Code execution call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `CodeExecutionCallStepArguments`

The arguments to pass to the code execution.

{% /summary %}

{% details %}

{% summary %}

**language**: `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `python`: Python >= 3.10, with numpy and simpy available.
- `bash`: Bash. Only available for Gemini 3.0 model or above.

{% /details %}

**code**: `string`

The code to be executed.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**CodeExecutionCallStep**

```json
{
  "type": "code_execution_call",
  "arguments": {
    "code": "print(sum(range(1, 11)))"
  },
  "id": "code_call_71021"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**CodeExecutionResultStep**{% /summary %}

Code execution result step.

{% two-column-layout %}

{% left-column %}

**result**: {% mark %}required{% /mark %} `string`

The output of the code execution.

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution_result`

{% hr /%}

**is_error**: `boolean`

Whether the code execution resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**CodeExecutionResultStep**

```json
{
  "type": "code_execution_result",
  "call_id": "code_call_71021",
  "result": "55\n"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearchCallStep**{% /summary %}

File Search call step.

{% two-column-layout %}

{% left-column %}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FileSearchCallStep**

```json
{
  "type": "file_search_call",
  "id": "file_call_88192"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearchResultStep**{% /summary %}

File Search result step.

{% two-column-layout %}

{% left-column %}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FileSearchResultStep**

```json
{
  "type": "file_search_result",
  "call_id": "file_call_88192"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FunctionCallStep**{% /summary %}

A function tool call step.

{% two-column-layout %}

{% left-column %}

**name**: {% mark %}required{% /mark %} `string`

The name of the tool to call.

{% hr /%}

**arguments**: {% mark %}required{% /mark %} `object`

The arguments to pass to the function.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `function_call`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FunctionCallStep**

```json
{
  "name": "get_weather",
  "type": "function_call",
  "arguments": {
    "location": "Boston, MA"
  },
  "id": "call_98231"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FunctionResultStep**{% /summary %}

Result of a function tool call.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (`[`ImageContent`](/api-reference/interactions-api/create-interaction#Resource:ImageContent) or [`TextContent`](/api-reference/interactions-api/create-interaction#Resource:TextContent)`)` or `object` or `string`

The result of the tool call.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array ([ImageContent](/api-reference/interactions-api/create-interaction#Resource:ImageContent) or [TextContent](/api-reference/interactions-api/create-interaction#Resource:TextContent))**{% /summary %}

A list where each item is one of: [`ImageContent`](/api-reference/interactions-api/create-interaction#Resource:ImageContent), [`TextContent`](/api-reference/interactions-api/create-interaction#Resource:TextContent).

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `function_result`

{% hr /%}

**name**: `string`

The name of the tool that was called.

{% hr /%}

**is_error**: `boolean`

Whether the tool call resulted in an error.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FunctionResultStep**

```json
{
  "name": "get_weather",
  "type": "function_result",
  "call_id": "call_98231",
  "result": [
    {
      "type": "text",
      "text": "{\"weather\":\"sunny\"}"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMapsCallStep**{% /summary %}

Google Maps call step.

{% two-column-layout %}

{% left-column %}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps_call`

{% hr /%}

{% details %}

{% summary %}

**arguments**: `GoogleMapsCallStepArguments`

The arguments to pass to the Google Maps tool.

{% /summary %}

**queries**: `array (string)`

The queries to be executed.

{% /details %}

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleMapsCallStep**

```json
{
  "type": "google_maps_call",
  "arguments": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "id": "maps_call_39201"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMapsResultStep**{% /summary %}

Google Maps result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (GoogleMapsResultItem)`

{% /summary %}

{% details %}

{% summary %}

**places**: `array (GoogleMapsResultPlaces)`

{% /summary %}

**place_id**: `string`

**name**: `string`

**url**: `string`

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

{% /details %}

**widget_context_token**: `string`

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleMapsResultStep**

```json
{
  "type": "google_maps_result",
  "call_id": "maps_call_39201",
  "result": [
    {
      "name": "Golden Gate Park",
      "place_id": "ChIJIQBpAG2ahYAR9R7bNdTLg8M",
      "rating": 4.8
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearchCallStep**{% /summary %}

Google Search call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `GoogleSearchCallStepArguments`

The arguments to pass to Google Search.

{% /summary %}

**queries**: `array (string)`

Web search queries for the following-up web search.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search_call`

{% hr /%}

{% details %}

{% summary %}

**search_type**: `enum (string)`

The type of search grounding enabled.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleSearchCallStep**

```json
{
  "type": "google_search_call",
  "arguments": {
    "query": "Who won the men's 100m in Paris 2024?"
  },
  "id": "search_call_19201"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearchResultStep**{% /summary %}

Google Search result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (GoogleSearchResultItem)`

The results of the Google Search.

{% /summary %}

**search_suggestions**: `string`

Web content snippet that can be embedded in a web page or an app webview.

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search_result`

{% hr /%}

**is_error**: `boolean`

Whether the Google Search resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleSearchResultStep**

```json
{
  "type": "google_search_result",
  "call_id": "search_call_19201",
  "result": [
    {
      "title": "Paris 2024 Olympics: Noah Lyles wins men's 100m gold",
      "url": "https://olympics.com/en/news/paris-2024-noah-lyles-wins-mens-100m-gold",
      "snippet": "American Noah Lyles won the Olympic men's 100m gold medal in a photo finish."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServerToolCallStep**{% /summary %}

MCPServer tool call step.

{% two-column-layout %}

{% left-column %}

**name**: {% mark %}required{% /mark %} `string`

The name of the tool which was called.

{% hr /%}

**server_name**: {% mark %}required{% /mark %} `string`

The name of the used MCP server.

{% hr /%}

**arguments**: {% mark %}required{% /mark %} `object`

The JSON object of arguments for the function.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server_tool_call`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**McpServerToolCallStep**

```json
{
  "name": "calculate_tax",
  "type": "mcp_server_tool_call",
  "arguments": {
    "income": 120000,
    "state": "CA"
  },
  "id": "mcp_call_29012",
  "server_name": "financial_mcp_server"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServerToolResultStep**{% /summary %}

MCPServer tool result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (`[`ImageContent`](/api-reference/interactions-api/create-interaction#Resource:ImageContent) or [`TextContent`](/api-reference/interactions-api/create-interaction#Resource:TextContent)`)` or `object` or `string`

The output from the MCP server call. Can be simple text or rich content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array ([ImageContent](/api-reference/interactions-api/create-interaction#Resource:ImageContent) or [TextContent](/api-reference/interactions-api/create-interaction#Resource:TextContent))**{% /summary %}

A list where each item is one of: [`ImageContent`](/api-reference/interactions-api/create-interaction#Resource:ImageContent), [`TextContent`](/api-reference/interactions-api/create-interaction#Resource:TextContent).

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server_tool_result`

{% hr /%}

**name**: `string`

Name of the tool which is called for this specific tool call.

{% hr /%}

**server_name**: `string`

The name of the used MCP server.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**McpServerToolResultStep**

```json
{
  "name": "calculate_tax",
  "type": "mcp_server_tool_result",
  "call_id": "mcp_call_29012",
  "result": {
    "tax_due": 32400
  },
  "server_name": "financial_mcp_server"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ModelOutputStep**{% /summary %}

Output generated by the model.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `model_output`

{% hr /%}

**content**: `array (`[`Content`](/api-reference/interactions-api/create-interaction#Resource:Content)`)`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**ModelOutputStep**

```json
{
  "type": "model_output",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ProcessingCallStep**{% /summary %}

A server-initiated processing step for media analysis (e.g. video
understanding).

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `processing_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**ProcessingResultStep**{% /summary %}

The result of a server-initiated media processing step.

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `processing_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**ThoughtStep**{% /summary %}

A thought step.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `thought`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% hr /%}

**summary**: `array (`[`Content`](/api-reference/interactions-api/create-interaction#Resource:Content)`)`

A summary of the thought.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**ThoughtStep**

```json
{
  "type": "thought",
  "signature": "thought_sig_abcd1234",
  "summary": [
    {
      "type": "text",
      "text": "The model is searching Google for the capital of France."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContextCallStep**{% /summary %}

URL context call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `UrlContextCallArguments`

The arguments to pass to the URL context.

{% /summary %}

**urls**: `array (string)`

The URLs to fetch.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UrlContextCallStep**

```json
{
  "type": "url_context_call",
  "arguments": {
    "urls": [
      "https://www.example.com"
    ]
  },
  "id": "url_call_10219"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContextResultStep**{% /summary %}

URL context result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (UrlContextResult)`

The results of the URL context.

{% /summary %}

**url**: `string`

The URL that was fetched.

{% details %}

{% summary %}

**status**: `enum (string)`

The status of the URL retrieval.

{% /summary %}

Possible values:

- `success`: Url retrieval is successful.
- `error`: Url retrieval is failed due to error.
- `paywall`: Url retrieval is failed because the content is behind paywall.
- `unsafe`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context_result`

{% hr /%}

**is_error**: `boolean`

Whether the URL context resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UrlContextResultStep**

```json
{
  "type": "url_context_result",
  "call_id": "url_call_10219",
  "result": [
    {
      "title": "Example Domain",
      "url": "https://www.example.com",
      "snippet": "This domain is for use in illustrative examples in documents."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UserInputStep**{% /summary %}

Input provided by the user.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `user_input`

{% hr /%}

**content**: `array (`[`Content`](/api-reference/interactions-api/create-interaction#Resource:Content)`)`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UserInputStep**

```json
{
  "type": "user_input",
  "content": [
    {
      "type": "text",
      "text": "What is the capital of France?"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### EnvironmentConfig {% class="hide-from-toc" id="Resource:EnvironmentConfig" %}

Configuration for a custom environment.

{% two-column-layout %}

{% left-column %}

**Properties:**

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% hr /%}

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**network**: [`EnvironmentNetworkEgressAllowlist`](/api-reference/interactions-api/create-interaction#Resource:EnvironmentNetworkEgressAllowlist) or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentNetworkEgressAllowlist](/api-reference/interactions-api/create-interaction#Resource:EnvironmentNetworkEgressAllowlist)**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% hr /%}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% hr /%}

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="Inline Sources" %}

```json
{
  "type": "remote",
  "sources": [
    {
      "type": "inline",
      "content": "You are a data analyst. Always include visualizations and export results as PDF.",
      "target": ".agents/AGENTS.md"
    },
    {
      "type": "inline",
      "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",
      "target": ".agents/skills/slide-maker/SKILL.md"
    }
  ]
}
```

{% /tab %}

{% tab label="External Sources" %}

```json
{
  "type": "remote",
  "sources": [
    {
      "type": "repository",
      "source": "https://github.com/my-org/my-skills.git",
      "target": ".agents/skills"
    },
    {
      "type": "gcs",
      "source": "gs://my-bucket/my-folder",
      "target": "/workspace/data"
    }
  ]
}
```

{% /tab %}

{% tab label="Network Allowlist" %}

```json
{
  "type": "remote",
  "network": {
    "allowlist": [
      {
        "domain": "pypi.org"
      },
      {
        "domain": "*.github.com"
      }
    ]
  }
}
```

{% /tab %}

{% tab label="Proxy Credentials" %}

```json
{
  "type": "remote",
  "network": {
    "allowlist": [
      {
        "domain": "api.github.com",
        "transform": {
          "Authorization": "Bearer YOUR_GITHUB_TOKEN"
        }
      }
    ]
  }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

### EnvironmentNetworkEgressAllowlist {% class="hide-from-toc" id="Resource:EnvironmentNetworkEgressAllowlist" %}

Network egress configuration for the environment.

{% two-column-layout %}

{% left-column %}

**Properties:**

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Network Allowlist**

```json
{
  "allowlist": [
    {
      "domain": "github.com",
      "transform": [
        {
          "Authorization": "Bearer your-token"
        }
      ]
    },
    {
      "domain": "*.googleapis.com"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

### ToolChoiceConfig {% class="hide-from-toc" id="Resource:ToolChoiceConfig" %}

The tool choice configuration containing allowed tools.

{% two-column-layout %}

{% left-column %}

**Properties:**

{% details %}

{% summary %}

**allowed_tools**: `AllowedTools`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

```json
{
  "allowed_tools": {
    "mode": "any",
    "tools": [
      "my_tool"
    ]
  }
}
```

{% /right-column %}

{% /two-column-layout %}

### ImageContent {% class="hide-from-toc" id="Resource:ImageContent" %}

An image content block.

{% two-column-layout %}

{% left-column %}

**Properties:**

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

**data**: `string`

The image content.

{% hr /%}

**uri**: `string`

The URI of the image.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the image.

{% /summary %}

Possible values:

- `image/png`: PNG image format
- `image/jpeg`: JPEG image format
- `image/webp`: WebP image format
- `image/heic`: HEIC image format
- `image/heif`: HEIF image format
- `image/gif`: GIF image format
- `image/bmp`: BMP image format
- `image/tiff`: TIFF image format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image**

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

{% /right-column %}

{% /two-column-layout %}

### TextContent {% class="hide-from-toc" id="Resource:TextContent" %}

A text content block.

{% two-column-layout %}

{% left-column %}

**Properties:**

**text**: {% mark %}required{% /mark %} `string`

The text content.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**annotations**: `array (Annotation)`

Citation information for model-generated content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**FileCitation**{% /summary %}

A file citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `file_citation`

**document_uri**: `string`

The URI of the file.

**file_name**: `string`

The name of the file.

**source**: `string`

Source attributed for a portion of the text.

**custom_metadata**: `object`

User provided metadata about the retrieved context.

**page_number**: `integer`

Page number of the cited document, if applicable.

**media_id**: `string`

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

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**PlaceCitation**{% /summary %}

A place citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `place_citation`

**place_id**: `string`

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

**name**: `string`

Title of the place.

**url**: `string`

URI reference of the place.

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

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

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**SpeechAnnotation**{% /summary %}

Speech annotation for text content.

**type**: {% mark %}required{% /mark %} `object`

Value: `speech_metadata`

**speaker**: `string`

The speaker to associate with this turn.

**style**: `string`

Style instruction for the speech synthesis.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**UrlCitation**{% /summary %}

A URL citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `url_citation`

**url**: `string`

The URL.

**title**: `string`

The title of the URL.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**WordInfo**{% /summary %}

Word-level ASR annotation for transcription output. Carries the word text, optional timing, and optional speaker attribution.

**type**: {% mark %}required{% /mark %} `object`

Value: `word_info`

**text**: `string`

The transcribed word.

**start_offset**: `string`

Start offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**end_offset**: `string`

End offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**speaker**: `string`

Optional. Speaker label for this word (e.g. "spk_1", "spk_2"). Present when diarization_mode is set in TranscriptionConfig.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text**

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

{% /right-column %}

{% /two-column-layout %}

# Canceling an interaction
Source: https://aistudio.google.com/api-reference/interactions-api/cancel-interaction-by-id
Description: Cancels an interaction by id.

{% callout type="note" %}

You are viewing the beta version of the Interactions API. Endpoints are under `/v1beta/`. The stable [v1 version](/api-reference/interactions-api/cancel-interaction-by-id?api-version=v1) is also available.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/interactions/{id}/cancel`

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

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**api_version**: {% mark %}required{% /mark %} `string`

API version for request routing.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

The unique identifier of the interaction to cancel.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID/cancel" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

# Start a background interaction so it stays in-progress.
created = client.interactions.create(
    model="gemini-flash-latest",
    input="Write a long essay about the history of computing.",
    tools=[{"type": "computer_use"}],
    background=True,
)

# Cancel the in-progress interaction.
interaction = client.interactions.cancel(id=created.id)
print(interaction.status)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

// Start a background interaction so it stays in-progress.
const created = await ai.interactions.create({
  model: 'gemini-flash-latest',
  input: 'Write a long essay about the history of computing.',
  tools: [{type: 'computer_use'}],
  background: true,
});

// Cancel the in-progress interaction.
const interaction = await ai.interactions.cancel(created.id);
console.log(interaction.status);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.operations.CancelInteractionByIdResponse;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();

// Start a background interaction so it stays in-progress.
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .input(InteractionsInput.of("Write a long essay about the history of computing."))
        .tools(List.of(new ComputerUse()))
        .background(true)
        .build();
CreateInteractionResponse created =
    client.interactions.create(CreateInteractionRequestBody.of(params));
String interactionId = created.interaction().flatMap(Interaction::id).orElseThrow();

// Cancel the in-progress interaction.
CancelInteractionByIdResponse cancelResponse = client.interactions.cancel(interactionId);
Interaction interaction =
    cancelResponse
        .interaction()
        .orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.status().map(InteractionStatus::value).orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    req := operations.CancelInteractionByIDRequest{
        ID: interactionID,
    }

    res, err := client.Interactions.Cancel(
        ctx,
        req,
    )
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil {
        fmt.Println(res.Interaction.Status)
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

Returns [`Interaction`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:Interaction) resources.

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "created": "2025-11-26T12:25:15Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "cancelled",
  "updated": "2025-11-26T12:25:15Z"
}
```

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### Interaction {% class="hide-from-toc" id="Resource:Interaction" %}

The Interaction resource.

{% two-column-layout %}

{% left-column %}

**Properties:**

**id**: {% mark %}required{% /mark %} `string`

Output only. A unique identifier for the interaction completion.

{% hr /%}

{% details %}

{% summary %}

**status**: {% mark %}required{% /mark %} `enum (string)`

Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

{% hr /%}

**created**: {% mark %}required{% /mark %} `string`

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

{% hr /%}

**updated**: {% mark %}required{% /mark %} `string`

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

{% hr /%}

**steps**: {% mark %}required{% /mark %} `array (`[`Step`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:Step)`)`

Output only. The steps that make up the interaction, when included in the response.

{% hr /%}

{% details %}

{% summary %}

**model**: `ModelOption`

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

{% /summary %}

Possible values:

- `gemma-4-26b-a4b-it`: Gemma 4 26B A4B IT
- `gemma-4-31b-it`: Gemma 4 31B IT
- `gemini-flash-latest`: Latest release of Gemini Flash
- `gemini-flash-lite-latest`: Latest release of Gemini Flash-Lite
- `gemini-pro-latest`: Latest release of Gemini Pro
- `gemini-2.5-flash`: Our first hybrid reasoning model which supports a 1M token context window and has thinking budgets.
- `gemini-2.5-pro`: Our state-of-the-art multipurpose model, which excels at coding and complex reasoning tasks.
- `gemini-2.5-flash-lite`: Our smallest and most cost effective model, built for at scale usage.
- `gemini-3.5-flash-lite`: Gemini 3.5 Flash-Lite - Our fastest, most cost-effective 3.5 model for high-throughput execution.
- `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-3-flash-preview`: Our most intelligent model built for speed, combining frontier intelligence with superior search and grounding.
- `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-pro-preview-customtools`: Gemini 3.1 Pro Preview optimized for custom tool usage
- `gemini-3.1-flash-lite`: Our most cost-efficient model, optimized for high-volume agentic tasks, translation, and simple data processing.
- `gemini-3.1-flash-lite-image`: Gemini 3.1 Flash Lite Image.
- `gemini-3-pro-image`: Gemini 3 Pro Image
- `nano-banana-pro-preview`: Gemini 3 Pro Image Preview
- `gemini-3.1-flash-image`: Gemini 3.1 Flash Image.
- `gemini-nano-banana-2.1`: Gemini Nano Banana 2.1.
- `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.
- `gemini-3.5-flash`: Gemini 3.5 Flash - Our earlier Flash model, built for speed and foundational performance across routine, high-throughput workloads.
- `gemini-3.6-flash`: Gemini 3.6 Flash - Our previous generation Flash model, balancing speed and multimodal capabilities across general agentic and everyday tasks.
- `gemini-3.7-flash`: Gemini 3.7 Flash - Our high-speed, efficient Flash model built for everyday coding, agentic tool use, and reliable multi-step execution.
- `gemini-3.8-flash`: Gemini 3.8 Flash - Our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows.
- `gemini-3.8-flash-tts`: Gemini 3.8 Flash TTS - Flagship TTS model for Voice Design and dual-speaker screenplay control. Prompt custom vocal personas, direct line-by-line delivery, and add vocal bursts.
- `gemini-3.8-flash-lite-tts`: Gemini 3.8 Flash Lite TTS - High-speed and cost-efficient, ideal for rapid dubbing, media localization, and high-throughput voice agents. Direct replacement for gemini-3.1-flash-tts-preview.
- `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.
- `gemini-robotics-er-1.6-preview`: Gemini Robotics-ER 1.6 Preview
- `gemini-robotics-er-2-preview`: Gemini Robotics Embodied Reasoning 2 Preview
- `lyria-3.5`: Our flagship music generation model, optimized for full-length songs with complex structural coherence.
- `gemini-omni-1.1-flash`: Our high-performance multimodal model designed for fast, conversational video generation, editing, and cinematic control.
- `gemini-omni-flash-preview`: Preview release of our multimodal model for conversational video generation, editing, and cinematic control.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**generation_config**: `GenerationConfig`

Input only. Configuration parameters for the model interaction.

{% /summary %}

**seed**: `integer`

Seed used in decoding for reproducibility.

**stop_sequences**: `array (string)`

A list of character sequences that will stop output interaction.

{% details %}

{% summary %}

**tool_choice**: [`ToolChoiceConfig`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ToolChoiceConfig) or `enum (string)`

The tool choice configuration.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[ToolChoiceConfig](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ToolChoiceConfig)**{% /summary %}

The tool choice configuration containing allowed tools.

{% details %}

{% summary %}

**allowed_tools**: `AllowedTools`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**thinking_level**: `ThinkingLevel`

The level of thought tokens that the model should generate.

{% /summary %}

Possible values:

- `minimal`: Little to no thinking.
- `low`: Low thinking level.
- `medium`: Medium thinking level.
- `high`: High thinking level.

{% /details %}

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

**max_output_tokens**: `integer`

The maximum number of tokens to include in the response.

{% details %}

{% summary %}

**video_config**: `VideoConfig`

Configuration for video generation.

{% /summary %}

{% details %}

{% summary %}

**task**: `enum (string)`

Optional task mode for video generation. If not specified, the model automatically determines the appropriate mode based on the provided text prompt and input media.

{% /summary %}

Possible values:

- `text_to_video`: Generates video solely from a text prompt.
- `image_to_video`: Generates video from one or two source images. The first image defines the starting frame, and the optional second image defines the ending frame.
- `reference_to_video`: Generates video using reference media (such as images, audio, or video).
- `edit`: Modifies an existing input video.
- `extend`: Extends an existing input video.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**transcription_config**: `TranscriptionConfig`

Optional. Configuration for speech recognition (transcription). If present, ASR is enabled.

{% /summary %}

**language_codes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**custom_vocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms.

{% details %}

{% summary %}

**mode**: `TranscriptionMode` or `enum (string)`

Discriminated transcription mode options or enum.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**SmartTranscriptionMode**{% /summary %}

Configuration for smart transcription mode.

**type**: {% mark %}required{% /mark %} `object`

Value: `smart`

{% /details %}

{% details %}

{% summary %}**VerbatimTranscriptionMode**{% /summary %}

Configuration for verbatim transcription mode.

**type**: {% mark %}required{% /mark %} `object`

Value: `verbatim`

**timestamp_granularities**: `array (string)`

Optional. The granularity of timestamps to include in the transcription output. Supported values: "word". If empty, no timestamps are generated.

**diarization_mode**: `string`

Optional. Configures speaker diarization. Supported values: "speaker".

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `verbatim`: Verbatim transcription mode.
- `smart`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**structured_speech_config**: `SpeakerConfig` or `array (SpeechConfig)`

Speech and multi-speaker configuration.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**SpeakerConfig**{% /summary %}

Configuration for multi-speaker and speech generation.

{% details %}

{% summary %}

**speakers**: `array (SpeechConfig)`

Individual speaker configurations.

{% /summary %}

**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.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (SpeechConfig)**{% /summary %}

The 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.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**system_instruction**: `string`

System instruction for the interaction.

{% hr /%}

**tools**: `array (`[`Tool`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:Tool)`)`

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

{% hr /%}

**input**: [`Content`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:Content) or `array (`[`Content`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:Content)`)` or `array (`[`Step`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:Step)`)` or `string`

The input for the interaction.

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

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

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**response_format**: [`ResponseFormat`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ResponseFormat) or `array (`[`ResponseFormat`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ResponseFormat)`)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[ResponseFormat](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ResponseFormat)**{% /summary %}

{% /details %}

{% details %}

{% summary %}**array ([ResponseFormat](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ResponseFormat))**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

{% hr /%}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% hr /%}

{% details %}

{% summary %}

**environment**: [`EnvironmentConfig`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:EnvironmentConfig) or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentConfig](/api-reference/interactions-api/cancel-interaction-by-id#Resource:EnvironmentConfig)**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: [`EnvironmentNetworkEgressAllowlist`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:EnvironmentNetworkEgressAllowlist) or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentNetworkEgressAllowlist](/api-reference/interactions-api/cancel-interaction-by-id#Resource:EnvironmentNetworkEgressAllowlist)**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**environment_id**: `string`

Output only. The environment ID for the interaction. Only populated if environment config is set in the request.

{% hr /%}

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

{% hr /%}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

{% hr /%}

{% details %}

{% summary %}

**errors**: `array (Error)`

Output only. Diagnostic faults / platform errors recorded on the interaction.

{% /summary %}

**code**: `string`

A URI that identifies the error type.

**message**: `string`

A human-readable error message.

{% /details %}

{% hr /%}

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

{% hr /%}

**stream**: `boolean`

Input only. Whether the interaction will be streamed.

{% hr /%}

**store**: `boolean`

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

{% hr /%}

**background**: `boolean`

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

{% hr /%}

{% details %}

{% summary %}

**agent**: `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

Configuration parameters for the agent interaction.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

{% hr /%}

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

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

{% /right-column %}

{% /two-column-layout %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### Content {% class="hide-from-toc" id="Resource:Content" %}

The content of the response.

**Polymorphic Types:**

{% details %}

{% summary %}**AudioContent**{% /summary %}

An audio content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% hr /%}

**data**: `string`

The audio content.

{% hr /%}

**uri**: `string`

The URI of the audio.

{% hr /%}

**channels**: `integer`

The number of audio channels.

{% hr /%}

**sample_rate**: `integer`

The sample rate of the audio.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the audio.

{% /summary %}

Possible values:

- `audio/wav`: WAV audio format
- `audio/mp3`: MP3 audio format
- `audio/aiff`: AIFF audio format
- `audio/aac`: AAC audio format
- `audio/ogg`: OGG audio format
- `audio/flac`: FLAC audio format
- `audio/mpeg`: MPEG audio format
- `audio/m4a`: M4A audio format
- `audio/l16`: L16 audio format
- `audio/opus`: OPUS audio format
- `audio/alaw`: ALAW audio format
- `audio/mulaw`: MULAW audio format
- `audio/webm`: WEBM audio format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Audio**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**DocumentContent**{% /summary %}

A document content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `document`

{% hr /%}

**data**: `string`

The document content.

{% hr /%}

**uri**: `string`

The URI of the document.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the document.

{% /summary %}

Possible values:

- `application/pdf`: PDF document format
- `text/csv`: CSV document format
- `application/vnd.openxmlformats-officedocument.presentationml.presentation`: PPTX presentation format
- `application/vnd.ms-powerpoint`: PPT presentation format
- `application/vnd.oasis.opendocument.presentation`: ODP presentation format
- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`: DOCX document format
- `application/msword`: DOC document format
- `application/vnd.openxmlformats-officedocument.wordprocessingml.template`: DOTX document template format
- `application/vnd.oasis.opendocument.text`: ODT document format
- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`: XLSX spreadsheet format
- `application/vnd.ms-excel`: XLS spreadsheet format
- `application/vnd.oasis.opendocument.spreadsheet`: ODS spreadsheet format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Document**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**[ImageContent](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ImageContent)**{% /summary %}

An image content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

**data**: `string`

The image content.

{% hr /%}

**uri**: `string`

The URI of the image.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the image.

{% /summary %}

Possible values:

- `image/png`: PNG image format
- `image/jpeg`: JPEG image format
- `image/webp`: WebP image format
- `image/heic`: HEIC image format
- `image/heif`: HEIF image format
- `image/gif`: GIF image format
- `image/bmp`: BMP image format
- `image/tiff`: TIFF image format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**[TextContent](/api-reference/interactions-api/cancel-interaction-by-id#Resource:TextContent)**{% /summary %}

A text content block.

{% two-column-layout %}

{% left-column %}

**text**: {% mark %}required{% /mark %} `string`

The text content.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**annotations**: `array (Annotation)`

Citation information for model-generated content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**FileCitation**{% /summary %}

A file citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `file_citation`

**document_uri**: `string`

The URI of the file.

**file_name**: `string`

The name of the file.

**source**: `string`

Source attributed for a portion of the text.

**custom_metadata**: `object`

User provided metadata about the retrieved context.

**page_number**: `integer`

Page number of the cited document, if applicable.

**media_id**: `string`

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

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**PlaceCitation**{% /summary %}

A place citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `place_citation`

**place_id**: `string`

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

**name**: `string`

Title of the place.

**url**: `string`

URI reference of the place.

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

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

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**SpeechAnnotation**{% /summary %}

Speech annotation for text content.

**type**: {% mark %}required{% /mark %} `object`

Value: `speech_metadata`

**speaker**: `string`

The speaker to associate with this turn.

**style**: `string`

Style instruction for the speech synthesis.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**UrlCitation**{% /summary %}

A URL citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `url_citation`

**url**: `string`

The URL.

**title**: `string`

The title of the URL.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**WordInfo**{% /summary %}

Word-level ASR annotation for transcription output. Carries the word text, optional timing, and optional speaker attribution.

**type**: {% mark %}required{% /mark %} `object`

Value: `word_info`

**text**: `string`

The transcribed word.

**start_offset**: `string`

Start offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**end_offset**: `string`

End offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**speaker**: `string`

Optional. Speaker label for this word (e.g. "spk_1", "spk_2"). Present when diarization_mode is set in TranscriptionConfig.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**VideoContent**{% /summary %}

A video content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% hr /%}

**data**: `string`

The video content.

{% hr /%}

**uri**: `string`

The URI of the video.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**processing**: `MediaProcessing` or `enum (string)`

How the model processes this video for understanding.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**MediaProcessing**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `static`

**start_offset**: `string`

Optional. Segment start time. Specified as a decimal number of seconds followed by an 's' suffix, e.g., "10.5s". Must be non-negative.

**end_offset**: `string`

Optional. Segment end time. Specified as a decimal number of seconds followed by an 's' suffix, e.g., "30s". Must be non-negative and greater than `start_offset` if `start_offset` is set.

**fps**: `number`

Optional. Video frame-rate sampling density.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `static`: Fixed-rate frame extraction. All frames placed in context.
- `agentic`: Model-driven dynamic navigation.

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

A user-defined name for this content block. Can be referenced by the model in the final response.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the video.

{% /summary %}

Possible values:

- `video/mp4`: MP4 video format
- `video/mpeg`: MPEG video format
- `video/mpg`: MPG video format
- `video/mov`: MOV video format
- `video/avi`: AVI video format
- `video/x-flv`: FLV video format
- `video/webm`: WebM video format
- `video/wmv`: WMV video format
- `video/3gpp`: 3GPP video format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Video**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### Tool {% class="hide-from-toc" id="Resource:Tool" %}

A tool that can be used by the model.

**Polymorphic Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "code_execution"
    }],
    "input": "Calculate the first 10 Fibonacci numbers"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "code_execution"}],
    input="Calculate the first 10 Fibonacci numbers",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'code_execution'}],
  input: 'Calculate the first 10 Fibonacci numbers',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new CodeExecution()))
        .input(InteractionsInput.of("Calculate the first 10 Fibonacci numbers"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="code_execution" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.CodeExecution{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Calculate the first 10 Fibonacci numbers")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ComputerUse**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `computer_use`

{% hr /%}

{% details %}

{% summary %}

**environment**: `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `browser`: Operates in a web browser.
- `mobile`: Operates in a mobile environment.
- `desktop`: Operates in a desktop environment.

{% /details %}

{% hr /%}

**excluded_predefined_functions**: `array (string)`

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

{% hr /%}

**enable_prompt_injection_detection**: `boolean`

Whether enable the prompt injection detection check on computer-use request.

{% hr /%}

{% details %}

{% summary %}

**disabled_safety_policies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `financial_transactions`: Safety policy for financial transactions.
- `sensitive_data_modification`: Safety policy for sensitive data modification.
- `communication_tool`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `account_creation`: Safety policy for account creation.
- `data_modification`: Safety policy for data modification.
- `user_consent_management`: Safety policy for user consent management.
- `legal_terms_and_agreements`: Safety policy for legal terms and agreements.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-2.5-computer-use-preview-10-2025",
    "tools": [{
      "type": "computer_use"
    }],
    "input": "Find a flight to Tokyo"
  }'

```

{% /tab %}

{% tab label="Python" %}

```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.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```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.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-2.5-computer-use-preview-10-2025")
        .tools(List.of(new ComputerUse()))
        .input(InteractionsInput.of("Find a flight to Tokyo"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="computer_use" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.ComputerUse{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-2.5-computer-use-preview-10-2025"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Find a flight to Tokyo")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearch**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search`

{% hr /%}

**file_search_store_names**: `array (string)`

The file search store names to search.

{% hr /%}

**top_k**: `integer`

The number of semantic retrieval chunks to retrieve.

{% hr /%}

**metadata_filter**: `string`

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

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "file_search",
      "file_search_store_names": ["fileSearchStores/m64d1sevsr4y-xfyawui3fxqg"]
    }],
    "input": "Who is the author of the book?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

# Create a file search store so we have a valid one to use.
store = client.file_search_stores.create()

response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[
        {"type": "file_search", "file_search_store_names": [store.name]}
    ],
    input="What documents are available?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

// Create a file search store so we have a valid one to use.
const store = await ai.fileSearchStores.create({});
if (!store.name) {
  throw new Error('Store creation failed: Name is undefined');
}

const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [
    {
      type: 'file_search',
      file_search_store_names: [store.name],
    },
  ],
  input: 'What documents are available?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.types.FileSearchStore;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();

// Create a file search store so we have a valid one to use.
FileSearchStore store =
    client.fileSearchStores.create(CreateFileSearchStoreConfig.builder().build());
String storeName = store.name().orElseThrow();

FileSearch tool = FileSearch.builder().fileSearchStoreNames(List.of(storeName)).build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(tool))
        .input(InteractionsInput.of("What documents are available?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="file_search" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    tool := gaos_interactions.NewTool(gaos_interactions.FileSearch{
        FileSearchStoreNames: []string{store.Name},
    })

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What documents are available?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `function`

{% hr /%}

**name**: `string`

The name of the function.

{% hr /%}

**description**: `string`

A description of the function.

{% hr /%}

**parameters**: `object`

The JSON Schema for the function's parameters. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "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?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    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.steps[-1])

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  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.steps.at(-1));

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Step;

Client client = new Client();
Map<String, Object> parameters =
    Map.of(
        "type", "object",
        "properties",
            Map.of(
                "location",
                Map.of(
                    "type", "string",
                    "description", "The city and state, e.g. San Francisco, CA")),
        "required", List.of("location"));
Function functionTool =
    Function.builder()
        .name("get_weather")
        .description("Get the current weather in a given location")
        .parameters(parameters)
        .build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(functionTool))
        .input(InteractionsInput.of("What is the weather like in Boston?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
List<Step> steps = interaction.steps().orElse(List.of());
if (!steps.isEmpty()) {
  System.out.println(steps.get(steps.size() - 1));
}

```

{% /tab %}

{% tab label="function_calling" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    function := gaos_interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Get the current weather in a given location"),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{
                    "type":        "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                },
            },
            "required": []string{"location"},
        },
    }

    tool := gaos_interactions.NewTool(function)

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What is the weather like in Boston, MA?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil {
        for _, step := range res.Interaction.Steps {
            if step.FunctionCallStep != nil {
                fmt.Println("Function Call:", step.FunctionCallStep.Name)
                fmt.Println("Arguments:", step.FunctionCallStep.Arguments)
            }
        }
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMaps**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps`

{% hr /%}

**enable_widget**: `boolean`

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

{% hr /%}

**latitude**: `number`

The latitude of the user's location.

{% hr /%}

**longitude**: `number`

The longitude of the user's location.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "google_maps",
      "latitude": 37.7749,
      "longitude": -122.4194
    }],
    "input": "What is the best food near me?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[
        {"type": "google_maps", "latitude": 37.7749, "longitude": -122.4194}
    ],
    input="What is the best food near me?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [
    {
      type: 'google_maps',
      latitude: 37.7749,
      longitude: -122.4194,
    },
  ],
  input: 'What is the best food near me?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
GoogleMaps tool = GoogleMaps.builder().latitude(37.7749).longitude(-122.4194).build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(tool))
        .input(InteractionsInput.of("What is the best food near me?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="google_maps" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.GoogleMaps{
        Latitude:  genai.Ptr(37.7749),
        Longitude: genai.Ptr(-122.4194),
    })

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What is the best food near me?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% hr /%}

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "google_search"
    }],
    "input": "Who is the current president of France?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "google_search"}],
    input="Who is the current president of France?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'google_search'}],
  input: 'Who is the current president of France?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new GoogleSearch()))
        .input(InteractionsInput.of("Who is the current president of France?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="google_search" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.GoogleSearch{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Who is the current president of France?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server`

{% hr /%}

**name**: `string`

The name of the MCPServer.

{% hr /%}

**url**: `string`

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

{% hr /%}

**headers**: `object`

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

{% hr /%}

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "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?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
import os

from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    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.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  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.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.MCPServer;

Client client = new Client();
MCPServer mcpTool =
    MCPServer.builder()
        .name("weather_service")
        .url("https://gemini-api-demos.uc.r.appspot.com/mcp")
        .build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(mcpTool))
        .input(
            InteractionsInput.of(
                "Today is 12-05-2025, what is the temperature today in London?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="mcp_server" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    mcpServer := gaos_interactions.MCPServer{
        Name: genai.Ptr("weather_service"),
        URL:  genai.Ptr("https://gemini-api-demos.uc.r.appspot.com/mcp"),
    }
    tool := gaos_interactions.NewTool(mcpServer)

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Today is 12-05-2025, what is the temperature today in London?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "url_context"
    }],
    "input": "Summarize https://www.example.com"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "url_context"}],
    input="Summarize https://www.example.com",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'url_context'}],
  input: 'Summarize https://www.example.com',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.URLContext;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new URLContext()))
        .input(InteractionsInput.of("Summarize https://www.example.com"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="url_context" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.URLContext{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Summarize https://www.example.com")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### ResponseFormat {% class="hide-from-toc" id="Resource:ResponseFormat" %}

**Polymorphic Types:**

{% details %}

{% summary %}**AudioResponseFormat**{% /summary %}

Configuration for audio output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the audio output.

{% /summary %}

Possible values:

- `audio/mp3`: MP3 audio format.
- `audio/ogg_opus`: OGG Opus audio format.
- `audio/l16`: Raw PCM (L16) audio format.
- `audio/wav`: WAV audio format.
- `audio/alaw`: A-law audio format.
- `audio/mulaw`: Mu-law audio format.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the audio output.

{% /summary %}

Possible values:

- `inline`: Audio data is returned inline in the response.
- `uri`: Audio data is returned as a URI.

{% /details %}

{% hr /%}

**sample_rate**: `integer`

Sample rate in Hz.

{% hr /%}

**bit_rate**: `integer`

Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Audio Output**

```json
{
  "type": "audio",
  "sample_rate": 24000
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ImageResponseFormat**{% /summary %}

Configuration for image output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the image output.

{% /summary %}

Possible values:

- `image/jpeg`: JPEG image format.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the image output.

{% /summary %}

Possible values:

- `inline`: Image data is returned inline in the response.
- `uri`: Image data is returned as a URI.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the image output.

{% /summary %}

Possible values:

- `1:1`: 1:1 aspect ratio.
- `2:3`: 2:3 aspect ratio.
- `3:2`: 3:2 aspect ratio.
- `3:4`: 3:4 aspect ratio.
- `4:3`: 4:3 aspect ratio.
- `4:5`: 4:5 aspect ratio.
- `5:4`: 5:4 aspect ratio.
- `9:16`: 9:16 aspect ratio.
- `16:9`: 16:9 aspect ratio.
- `21:9`: 21:9 aspect ratio.
- `1:8`: 1:8 aspect ratio.
- `8:1`: 8:1 aspect ratio.
- `1:4`: 1:4 aspect ratio.
- `4:1`: 4:1 aspect ratio.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**image_size**: `enum (string)`

The size of the image output.

{% /summary %}

Possible values:

- `512`: 512px image size.
- `1K`: 1K image size.
- `2K`: 2K image size.
- `4K`: 4K image size.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image Output**

```json
{
  "type": "image",
  "aspect_ratio": "16:9",
  "image_size": "1K",
  "mime_type": "image/jpeg"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**TextResponseFormat**{% /summary %}

Configuration for text output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the text output.

{% /summary %}

Possible values:

- `application/json`: JSON output format.
- `text/plain`: Plain text output format.

{% /details %}

{% hr /%}

**schema**: `object`

The JSON schema that the output should conform to. Only applicable when mime_type is application/json. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced; validate these in your application. `minItems` and `maxItems` are enforced. Schemas that are too complex to enforce (for example, large `maxItems` on nested arrays) return a 400 INVALID_ARGUMENT error.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text Output (JSON Schema)**

```json
{
  "type": "text",
  "mime_type": "application/json",
  "schema": {
    "type": "object",
    "properties": {
      "ingredients": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "recipe_name": {
        "type": "string"
      }
    },
    "required": [
      "ingredients",
      "recipe_name"
    ]
  }
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**VideoResponseFormat**{% /summary %}

Configuration for video output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the video output.

{% /summary %}

Possible values:

- `inline`: Video data is returned inline in the response.
- `uri`: Video data is returned as a URI.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the video output.

{% /summary %}

Possible values:

- `16:9`: 16:9 aspect ratio.
- `9:16`: 9:16 aspect ratio.

{% /details %}

{% hr /%}

**duration**: `string`

The duration for the video output.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `enum (string)`

The video output resolution. Defaults to 720p.

{% /summary %}

Possible values:

- `360p`: 360p resolution.
- `720p`: 720p resolution.
- `1080p`: 1080p resolution.
- `4k`: 4K resolution.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Video Output**

```json
{
  "type": "video",
  "aspect_ratio": "16:9",
  "delivery": "inline"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### Step {% class="hide-from-toc" id="Resource:Step" %}

A step in the interaction.

**Polymorphic Types:**

{% details %}

{% summary %}**CodeExecutionCallStep**{% /summary %}

Code execution call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `CodeExecutionCallStepArguments`

The arguments to pass to the code execution.

{% /summary %}

{% details %}

{% summary %}

**language**: `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `python`: Python >= 3.10, with numpy and simpy available.
- `bash`: Bash. Only available for Gemini 3.0 model or above.

{% /details %}

**code**: `string`

The code to be executed.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**CodeExecutionCallStep**

```json
{
  "type": "code_execution_call",
  "arguments": {
    "code": "print(sum(range(1, 11)))"
  },
  "id": "code_call_71021"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**CodeExecutionResultStep**{% /summary %}

Code execution result step.

{% two-column-layout %}

{% left-column %}

**result**: {% mark %}required{% /mark %} `string`

The output of the code execution.

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution_result`

{% hr /%}

**is_error**: `boolean`

Whether the code execution resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**CodeExecutionResultStep**

```json
{
  "type": "code_execution_result",
  "call_id": "code_call_71021",
  "result": "55\n"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearchCallStep**{% /summary %}

File Search call step.

{% two-column-layout %}

{% left-column %}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FileSearchCallStep**

```json
{
  "type": "file_search_call",
  "id": "file_call_88192"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearchResultStep**{% /summary %}

File Search result step.

{% two-column-layout %}

{% left-column %}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FileSearchResultStep**

```json
{
  "type": "file_search_result",
  "call_id": "file_call_88192"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FunctionCallStep**{% /summary %}

A function tool call step.

{% two-column-layout %}

{% left-column %}

**name**: {% mark %}required{% /mark %} `string`

The name of the tool to call.

{% hr /%}

**arguments**: {% mark %}required{% /mark %} `object`

The arguments to pass to the function.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `function_call`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FunctionCallStep**

```json
{
  "name": "get_weather",
  "type": "function_call",
  "arguments": {
    "location": "Boston, MA"
  },
  "id": "call_98231"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FunctionResultStep**{% /summary %}

Result of a function tool call.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (`[`ImageContent`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ImageContent) or [`TextContent`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:TextContent)`)` or `object` or `string`

The result of the tool call.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array ([ImageContent](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ImageContent) or [TextContent](/api-reference/interactions-api/cancel-interaction-by-id#Resource:TextContent))**{% /summary %}

A list where each item is one of: [`ImageContent`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ImageContent), [`TextContent`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:TextContent).

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `function_result`

{% hr /%}

**name**: `string`

The name of the tool that was called.

{% hr /%}

**is_error**: `boolean`

Whether the tool call resulted in an error.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FunctionResultStep**

```json
{
  "name": "get_weather",
  "type": "function_result",
  "call_id": "call_98231",
  "result": [
    {
      "type": "text",
      "text": "{\"weather\":\"sunny\"}"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMapsCallStep**{% /summary %}

Google Maps call step.

{% two-column-layout %}

{% left-column %}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps_call`

{% hr /%}

{% details %}

{% summary %}

**arguments**: `GoogleMapsCallStepArguments`

The arguments to pass to the Google Maps tool.

{% /summary %}

**queries**: `array (string)`

The queries to be executed.

{% /details %}

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleMapsCallStep**

```json
{
  "type": "google_maps_call",
  "arguments": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "id": "maps_call_39201"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMapsResultStep**{% /summary %}

Google Maps result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (GoogleMapsResultItem)`

{% /summary %}

{% details %}

{% summary %}

**places**: `array (GoogleMapsResultPlaces)`

{% /summary %}

**place_id**: `string`

**name**: `string`

**url**: `string`

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

{% /details %}

**widget_context_token**: `string`

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleMapsResultStep**

```json
{
  "type": "google_maps_result",
  "call_id": "maps_call_39201",
  "result": [
    {
      "name": "Golden Gate Park",
      "place_id": "ChIJIQBpAG2ahYAR9R7bNdTLg8M",
      "rating": 4.8
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearchCallStep**{% /summary %}

Google Search call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `GoogleSearchCallStepArguments`

The arguments to pass to Google Search.

{% /summary %}

**queries**: `array (string)`

Web search queries for the following-up web search.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search_call`

{% hr /%}

{% details %}

{% summary %}

**search_type**: `enum (string)`

The type of search grounding enabled.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleSearchCallStep**

```json
{
  "type": "google_search_call",
  "arguments": {
    "query": "Who won the men's 100m in Paris 2024?"
  },
  "id": "search_call_19201"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearchResultStep**{% /summary %}

Google Search result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (GoogleSearchResultItem)`

The results of the Google Search.

{% /summary %}

**search_suggestions**: `string`

Web content snippet that can be embedded in a web page or an app webview.

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search_result`

{% hr /%}

**is_error**: `boolean`

Whether the Google Search resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleSearchResultStep**

```json
{
  "type": "google_search_result",
  "call_id": "search_call_19201",
  "result": [
    {
      "title": "Paris 2024 Olympics: Noah Lyles wins men's 100m gold",
      "url": "https://olympics.com/en/news/paris-2024-noah-lyles-wins-mens-100m-gold",
      "snippet": "American Noah Lyles won the Olympic men's 100m gold medal in a photo finish."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServerToolCallStep**{% /summary %}

MCPServer tool call step.

{% two-column-layout %}

{% left-column %}

**name**: {% mark %}required{% /mark %} `string`

The name of the tool which was called.

{% hr /%}

**server_name**: {% mark %}required{% /mark %} `string`

The name of the used MCP server.

{% hr /%}

**arguments**: {% mark %}required{% /mark %} `object`

The JSON object of arguments for the function.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server_tool_call`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**McpServerToolCallStep**

```json
{
  "name": "calculate_tax",
  "type": "mcp_server_tool_call",
  "arguments": {
    "income": 120000,
    "state": "CA"
  },
  "id": "mcp_call_29012",
  "server_name": "financial_mcp_server"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServerToolResultStep**{% /summary %}

MCPServer tool result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (`[`ImageContent`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ImageContent) or [`TextContent`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:TextContent)`)` or `object` or `string`

The output from the MCP server call. Can be simple text or rich content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array ([ImageContent](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ImageContent) or [TextContent](/api-reference/interactions-api/cancel-interaction-by-id#Resource:TextContent))**{% /summary %}

A list where each item is one of: [`ImageContent`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:ImageContent), [`TextContent`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:TextContent).

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server_tool_result`

{% hr /%}

**name**: `string`

Name of the tool which is called for this specific tool call.

{% hr /%}

**server_name**: `string`

The name of the used MCP server.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**McpServerToolResultStep**

```json
{
  "name": "calculate_tax",
  "type": "mcp_server_tool_result",
  "call_id": "mcp_call_29012",
  "result": {
    "tax_due": 32400
  },
  "server_name": "financial_mcp_server"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ModelOutputStep**{% /summary %}

Output generated by the model.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `model_output`

{% hr /%}

**content**: `array (`[`Content`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:Content)`)`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**ModelOutputStep**

```json
{
  "type": "model_output",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ProcessingCallStep**{% /summary %}

A server-initiated processing step for media analysis (e.g. video
understanding).

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `processing_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**ProcessingResultStep**{% /summary %}

The result of a server-initiated media processing step.

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `processing_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**ThoughtStep**{% /summary %}

A thought step.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `thought`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% hr /%}

**summary**: `array (`[`Content`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:Content)`)`

A summary of the thought.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**ThoughtStep**

```json
{
  "type": "thought",
  "signature": "thought_sig_abcd1234",
  "summary": [
    {
      "type": "text",
      "text": "The model is searching Google for the capital of France."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContextCallStep**{% /summary %}

URL context call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `UrlContextCallArguments`

The arguments to pass to the URL context.

{% /summary %}

**urls**: `array (string)`

The URLs to fetch.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UrlContextCallStep**

```json
{
  "type": "url_context_call",
  "arguments": {
    "urls": [
      "https://www.example.com"
    ]
  },
  "id": "url_call_10219"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContextResultStep**{% /summary %}

URL context result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (UrlContextResult)`

The results of the URL context.

{% /summary %}

**url**: `string`

The URL that was fetched.

{% details %}

{% summary %}

**status**: `enum (string)`

The status of the URL retrieval.

{% /summary %}

Possible values:

- `success`: Url retrieval is successful.
- `error`: Url retrieval is failed due to error.
- `paywall`: Url retrieval is failed because the content is behind paywall.
- `unsafe`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context_result`

{% hr /%}

**is_error**: `boolean`

Whether the URL context resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UrlContextResultStep**

```json
{
  "type": "url_context_result",
  "call_id": "url_call_10219",
  "result": [
    {
      "title": "Example Domain",
      "url": "https://www.example.com",
      "snippet": "This domain is for use in illustrative examples in documents."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UserInputStep**{% /summary %}

Input provided by the user.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `user_input`

{% hr /%}

**content**: `array (`[`Content`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:Content)`)`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UserInputStep**

```json
{
  "type": "user_input",
  "content": [
    {
      "type": "text",
      "text": "What is the capital of France?"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### EnvironmentConfig {% class="hide-from-toc" id="Resource:EnvironmentConfig" %}

Configuration for a custom environment.

{% two-column-layout %}

{% left-column %}

**Properties:**

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% hr /%}

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**network**: [`EnvironmentNetworkEgressAllowlist`](/api-reference/interactions-api/cancel-interaction-by-id#Resource:EnvironmentNetworkEgressAllowlist) or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentNetworkEgressAllowlist](/api-reference/interactions-api/cancel-interaction-by-id#Resource:EnvironmentNetworkEgressAllowlist)**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% hr /%}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% hr /%}

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="Inline Sources" %}

```json
{
  "type": "remote",
  "sources": [
    {
      "type": "inline",
      "content": "You are a data analyst. Always include visualizations and export results as PDF.",
      "target": ".agents/AGENTS.md"
    },
    {
      "type": "inline",
      "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",
      "target": ".agents/skills/slide-maker/SKILL.md"
    }
  ]
}
```

{% /tab %}

{% tab label="External Sources" %}

```json
{
  "type": "remote",
  "sources": [
    {
      "type": "repository",
      "source": "https://github.com/my-org/my-skills.git",
      "target": ".agents/skills"
    },
    {
      "type": "gcs",
      "source": "gs://my-bucket/my-folder",
      "target": "/workspace/data"
    }
  ]
}
```

{% /tab %}

{% tab label="Network Allowlist" %}

```json
{
  "type": "remote",
  "network": {
    "allowlist": [
      {
        "domain": "pypi.org"
      },
      {
        "domain": "*.github.com"
      }
    ]
  }
}
```

{% /tab %}

{% tab label="Proxy Credentials" %}

```json
{
  "type": "remote",
  "network": {
    "allowlist": [
      {
        "domain": "api.github.com",
        "transform": {
          "Authorization": "Bearer YOUR_GITHUB_TOKEN"
        }
      }
    ]
  }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

### EnvironmentNetworkEgressAllowlist {% class="hide-from-toc" id="Resource:EnvironmentNetworkEgressAllowlist" %}

Network egress configuration for the environment.

{% two-column-layout %}

{% left-column %}

**Properties:**

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Network Allowlist**

```json
{
  "allowlist": [
    {
      "domain": "github.com",
      "transform": [
        {
          "Authorization": "Bearer your-token"
        }
      ]
    },
    {
      "domain": "*.googleapis.com"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

### ToolChoiceConfig {% class="hide-from-toc" id="Resource:ToolChoiceConfig" %}

The tool choice configuration containing allowed tools.

{% two-column-layout %}

{% left-column %}

**Properties:**

{% details %}

{% summary %}

**allowed_tools**: `AllowedTools`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

```json
{
  "allowed_tools": {
    "mode": "any",
    "tools": [
      "my_tool"
    ]
  }
}
```

{% /right-column %}

{% /two-column-layout %}

### ImageContent {% class="hide-from-toc" id="Resource:ImageContent" %}

An image content block.

{% two-column-layout %}

{% left-column %}

**Properties:**

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

**data**: `string`

The image content.

{% hr /%}

**uri**: `string`

The URI of the image.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the image.

{% /summary %}

Possible values:

- `image/png`: PNG image format
- `image/jpeg`: JPEG image format
- `image/webp`: WebP image format
- `image/heic`: HEIC image format
- `image/heif`: HEIF image format
- `image/gif`: GIF image format
- `image/bmp`: BMP image format
- `image/tiff`: TIFF image format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image**

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

{% /right-column %}

{% /two-column-layout %}

### TextContent {% class="hide-from-toc" id="Resource:TextContent" %}

A text content block.

{% two-column-layout %}

{% left-column %}

**Properties:**

**text**: {% mark %}required{% /mark %} `string`

The text content.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**annotations**: `array (Annotation)`

Citation information for model-generated content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**FileCitation**{% /summary %}

A file citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `file_citation`

**document_uri**: `string`

The URI of the file.

**file_name**: `string`

The name of the file.

**source**: `string`

Source attributed for a portion of the text.

**custom_metadata**: `object`

User provided metadata about the retrieved context.

**page_number**: `integer`

Page number of the cited document, if applicable.

**media_id**: `string`

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

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**PlaceCitation**{% /summary %}

A place citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `place_citation`

**place_id**: `string`

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

**name**: `string`

Title of the place.

**url**: `string`

URI reference of the place.

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

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

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**SpeechAnnotation**{% /summary %}

Speech annotation for text content.

**type**: {% mark %}required{% /mark %} `object`

Value: `speech_metadata`

**speaker**: `string`

The speaker to associate with this turn.

**style**: `string`

Style instruction for the speech synthesis.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**UrlCitation**{% /summary %}

A URL citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `url_citation`

**url**: `string`

The URL.

**title**: `string`

The title of the URL.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**WordInfo**{% /summary %}

Word-level ASR annotation for transcription output. Carries the word text, optional timing, and optional speaker attribution.

**type**: {% mark %}required{% /mark %} `object`

Value: `word_info`

**text**: `string`

The transcribed word.

**start_offset**: `string`

Start offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**end_offset**: `string`

End offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**speaker**: `string`

Optional. Speaker label for this word (e.g. "spk_1", "spk_2"). Present when diarization_mode is set in TranscriptionConfig.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text**

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

{% /right-column %}

{% /two-column-layout %}

# Getting an interaction
Source: https://aistudio.google.com/api-reference/interactions-api/get-interaction-by-id
Description: Retrieves the full details of a single interaction based on its `Interaction.id`.

{% callout type="note" %}

You are viewing the beta version of the Interactions API. Endpoints are under `/v1beta/`. The stable [v1 version](/api-reference/interactions-api/get-interaction-by-id?api-version=v1) is also available.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/interactions/{id}`

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

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**api_version**: {% mark %}required{% /mark %} `string`

API version for request routing.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

The unique identifier of the interaction to retrieve.

{% hr /%}

**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.

{% hr /%}

**stream**: `boolean`

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

Default: `False`

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()


interaction = client.interactions.get(id=created.id)
print(interaction.status)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


const interaction = await ai.interactions.get(created.id);
console.log(interaction.status);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import com.google.genai.gaos.models.operations.GetInteractionByIdResponse;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;

Client client = new Client();


GetInteractionByIdResponse getResponse =
    client.interactions.get(new GetInteractionByIdRequest(interactionId));
Interaction interaction =
    getResponse
        .interaction()
        .orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.status().map(InteractionStatus::value).orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    interaction, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{
        ID: *created.Interaction.ID,
    })
    if err != nil {
        log.Fatal(err)
    }

    if interaction.Interaction != nil {
        fmt.Println(interaction.Interaction.Status)
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

Returns [`Interaction`](/api-reference/interactions-api/get-interaction-by-id#Resource:Interaction) resources.

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

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

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### Interaction {% class="hide-from-toc" id="Resource:Interaction" %}

The Interaction resource.

{% two-column-layout %}

{% left-column %}

**Properties:**

**id**: {% mark %}required{% /mark %} `string`

Output only. A unique identifier for the interaction completion.

{% hr /%}

{% details %}

{% summary %}

**status**: {% mark %}required{% /mark %} `enum (string)`

Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

{% hr /%}

**created**: {% mark %}required{% /mark %} `string`

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

{% hr /%}

**updated**: {% mark %}required{% /mark %} `string`

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

{% hr /%}

**steps**: {% mark %}required{% /mark %} `array (`[`Step`](/api-reference/interactions-api/get-interaction-by-id#Resource:Step)`)`

Output only. The steps that make up the interaction, when included in the response.

{% hr /%}

{% details %}

{% summary %}

**model**: `ModelOption`

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

{% /summary %}

Possible values:

- `gemma-4-26b-a4b-it`: Gemma 4 26B A4B IT
- `gemma-4-31b-it`: Gemma 4 31B IT
- `gemini-flash-latest`: Latest release of Gemini Flash
- `gemini-flash-lite-latest`: Latest release of Gemini Flash-Lite
- `gemini-pro-latest`: Latest release of Gemini Pro
- `gemini-2.5-flash`: Our first hybrid reasoning model which supports a 1M token context window and has thinking budgets.
- `gemini-2.5-pro`: Our state-of-the-art multipurpose model, which excels at coding and complex reasoning tasks.
- `gemini-2.5-flash-lite`: Our smallest and most cost effective model, built for at scale usage.
- `gemini-3.5-flash-lite`: Gemini 3.5 Flash-Lite - Our fastest, most cost-effective 3.5 model for high-throughput execution.
- `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-3-flash-preview`: Our most intelligent model built for speed, combining frontier intelligence with superior search and grounding.
- `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-pro-preview-customtools`: Gemini 3.1 Pro Preview optimized for custom tool usage
- `gemini-3.1-flash-lite`: Our most cost-efficient model, optimized for high-volume agentic tasks, translation, and simple data processing.
- `gemini-3.1-flash-lite-image`: Gemini 3.1 Flash Lite Image.
- `gemini-3-pro-image`: Gemini 3 Pro Image
- `nano-banana-pro-preview`: Gemini 3 Pro Image Preview
- `gemini-3.1-flash-image`: Gemini 3.1 Flash Image.
- `gemini-nano-banana-2.1`: Gemini Nano Banana 2.1.
- `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.
- `gemini-3.5-flash`: Gemini 3.5 Flash - Our earlier Flash model, built for speed and foundational performance across routine, high-throughput workloads.
- `gemini-3.6-flash`: Gemini 3.6 Flash - Our previous generation Flash model, balancing speed and multimodal capabilities across general agentic and everyday tasks.
- `gemini-3.7-flash`: Gemini 3.7 Flash - Our high-speed, efficient Flash model built for everyday coding, agentic tool use, and reliable multi-step execution.
- `gemini-3.8-flash`: Gemini 3.8 Flash - Our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows.
- `gemini-3.8-flash-tts`: Gemini 3.8 Flash TTS - Flagship TTS model for Voice Design and dual-speaker screenplay control. Prompt custom vocal personas, direct line-by-line delivery, and add vocal bursts.
- `gemini-3.8-flash-lite-tts`: Gemini 3.8 Flash Lite TTS - High-speed and cost-efficient, ideal for rapid dubbing, media localization, and high-throughput voice agents. Direct replacement for gemini-3.1-flash-tts-preview.
- `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.
- `gemini-robotics-er-1.6-preview`: Gemini Robotics-ER 1.6 Preview
- `gemini-robotics-er-2-preview`: Gemini Robotics Embodied Reasoning 2 Preview
- `lyria-3.5`: Our flagship music generation model, optimized for full-length songs with complex structural coherence.
- `gemini-omni-1.1-flash`: Our high-performance multimodal model designed for fast, conversational video generation, editing, and cinematic control.
- `gemini-omni-flash-preview`: Preview release of our multimodal model for conversational video generation, editing, and cinematic control.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**generation_config**: `GenerationConfig`

Input only. Configuration parameters for the model interaction.

{% /summary %}

**seed**: `integer`

Seed used in decoding for reproducibility.

**stop_sequences**: `array (string)`

A list of character sequences that will stop output interaction.

{% details %}

{% summary %}

**tool_choice**: [`ToolChoiceConfig`](/api-reference/interactions-api/get-interaction-by-id#Resource:ToolChoiceConfig) or `enum (string)`

The tool choice configuration.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[ToolChoiceConfig](/api-reference/interactions-api/get-interaction-by-id#Resource:ToolChoiceConfig)**{% /summary %}

The tool choice configuration containing allowed tools.

{% details %}

{% summary %}

**allowed_tools**: `AllowedTools`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**thinking_level**: `ThinkingLevel`

The level of thought tokens that the model should generate.

{% /summary %}

Possible values:

- `minimal`: Little to no thinking.
- `low`: Low thinking level.
- `medium`: Medium thinking level.
- `high`: High thinking level.

{% /details %}

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

**max_output_tokens**: `integer`

The maximum number of tokens to include in the response.

{% details %}

{% summary %}

**video_config**: `VideoConfig`

Configuration for video generation.

{% /summary %}

{% details %}

{% summary %}

**task**: `enum (string)`

Optional task mode for video generation. If not specified, the model automatically determines the appropriate mode based on the provided text prompt and input media.

{% /summary %}

Possible values:

- `text_to_video`: Generates video solely from a text prompt.
- `image_to_video`: Generates video from one or two source images. The first image defines the starting frame, and the optional second image defines the ending frame.
- `reference_to_video`: Generates video using reference media (such as images, audio, or video).
- `edit`: Modifies an existing input video.
- `extend`: Extends an existing input video.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**transcription_config**: `TranscriptionConfig`

Optional. Configuration for speech recognition (transcription). If present, ASR is enabled.

{% /summary %}

**language_codes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**custom_vocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms.

{% details %}

{% summary %}

**mode**: `TranscriptionMode` or `enum (string)`

Discriminated transcription mode options or enum.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**SmartTranscriptionMode**{% /summary %}

Configuration for smart transcription mode.

**type**: {% mark %}required{% /mark %} `object`

Value: `smart`

{% /details %}

{% details %}

{% summary %}**VerbatimTranscriptionMode**{% /summary %}

Configuration for verbatim transcription mode.

**type**: {% mark %}required{% /mark %} `object`

Value: `verbatim`

**timestamp_granularities**: `array (string)`

Optional. The granularity of timestamps to include in the transcription output. Supported values: "word". If empty, no timestamps are generated.

**diarization_mode**: `string`

Optional. Configures speaker diarization. Supported values: "speaker".

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `verbatim`: Verbatim transcription mode.
- `smart`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**structured_speech_config**: `SpeakerConfig` or `array (SpeechConfig)`

Speech and multi-speaker configuration.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**SpeakerConfig**{% /summary %}

Configuration for multi-speaker and speech generation.

{% details %}

{% summary %}

**speakers**: `array (SpeechConfig)`

Individual speaker configurations.

{% /summary %}

**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.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (SpeechConfig)**{% /summary %}

The 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.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**system_instruction**: `string`

System instruction for the interaction.

{% hr /%}

**tools**: `array (`[`Tool`](/api-reference/interactions-api/get-interaction-by-id#Resource:Tool)`)`

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

{% hr /%}

**input**: [`Content`](/api-reference/interactions-api/get-interaction-by-id#Resource:Content) or `array (`[`Content`](/api-reference/interactions-api/get-interaction-by-id#Resource:Content)`)` or `array (`[`Step`](/api-reference/interactions-api/get-interaction-by-id#Resource:Step)`)` or `string`

The input for the interaction.

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

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

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**response_format**: [`ResponseFormat`](/api-reference/interactions-api/get-interaction-by-id#Resource:ResponseFormat) or `array (`[`ResponseFormat`](/api-reference/interactions-api/get-interaction-by-id#Resource:ResponseFormat)`)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[ResponseFormat](/api-reference/interactions-api/get-interaction-by-id#Resource:ResponseFormat)**{% /summary %}

{% /details %}

{% details %}

{% summary %}**array ([ResponseFormat](/api-reference/interactions-api/get-interaction-by-id#Resource:ResponseFormat))**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

{% hr /%}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% hr /%}

{% details %}

{% summary %}

**environment**: [`EnvironmentConfig`](/api-reference/interactions-api/get-interaction-by-id#Resource:EnvironmentConfig) or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentConfig](/api-reference/interactions-api/get-interaction-by-id#Resource:EnvironmentConfig)**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: [`EnvironmentNetworkEgressAllowlist`](/api-reference/interactions-api/get-interaction-by-id#Resource:EnvironmentNetworkEgressAllowlist) or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentNetworkEgressAllowlist](/api-reference/interactions-api/get-interaction-by-id#Resource:EnvironmentNetworkEgressAllowlist)**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**environment_id**: `string`

Output only. The environment ID for the interaction. Only populated if environment config is set in the request.

{% hr /%}

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

{% hr /%}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

{% hr /%}

{% details %}

{% summary %}

**errors**: `array (Error)`

Output only. Diagnostic faults / platform errors recorded on the interaction.

{% /summary %}

**code**: `string`

A URI that identifies the error type.

**message**: `string`

A human-readable error message.

{% /details %}

{% hr /%}

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

{% hr /%}

**stream**: `boolean`

Input only. Whether the interaction will be streamed.

{% hr /%}

**store**: `boolean`

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

{% hr /%}

**background**: `boolean`

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

{% hr /%}

{% details %}

{% summary %}

**agent**: `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

Configuration parameters for the agent interaction.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

{% hr /%}

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

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

{% /right-column %}

{% /two-column-layout %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### Content {% class="hide-from-toc" id="Resource:Content" %}

The content of the response.

**Polymorphic Types:**

{% details %}

{% summary %}**AudioContent**{% /summary %}

An audio content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% hr /%}

**data**: `string`

The audio content.

{% hr /%}

**uri**: `string`

The URI of the audio.

{% hr /%}

**channels**: `integer`

The number of audio channels.

{% hr /%}

**sample_rate**: `integer`

The sample rate of the audio.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the audio.

{% /summary %}

Possible values:

- `audio/wav`: WAV audio format
- `audio/mp3`: MP3 audio format
- `audio/aiff`: AIFF audio format
- `audio/aac`: AAC audio format
- `audio/ogg`: OGG audio format
- `audio/flac`: FLAC audio format
- `audio/mpeg`: MPEG audio format
- `audio/m4a`: M4A audio format
- `audio/l16`: L16 audio format
- `audio/opus`: OPUS audio format
- `audio/alaw`: ALAW audio format
- `audio/mulaw`: MULAW audio format
- `audio/webm`: WEBM audio format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Audio**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**DocumentContent**{% /summary %}

A document content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `document`

{% hr /%}

**data**: `string`

The document content.

{% hr /%}

**uri**: `string`

The URI of the document.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the document.

{% /summary %}

Possible values:

- `application/pdf`: PDF document format
- `text/csv`: CSV document format
- `application/vnd.openxmlformats-officedocument.presentationml.presentation`: PPTX presentation format
- `application/vnd.ms-powerpoint`: PPT presentation format
- `application/vnd.oasis.opendocument.presentation`: ODP presentation format
- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`: DOCX document format
- `application/msword`: DOC document format
- `application/vnd.openxmlformats-officedocument.wordprocessingml.template`: DOTX document template format
- `application/vnd.oasis.opendocument.text`: ODT document format
- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`: XLSX spreadsheet format
- `application/vnd.ms-excel`: XLS spreadsheet format
- `application/vnd.oasis.opendocument.spreadsheet`: ODS spreadsheet format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Document**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**[ImageContent](/api-reference/interactions-api/get-interaction-by-id#Resource:ImageContent)**{% /summary %}

An image content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

**data**: `string`

The image content.

{% hr /%}

**uri**: `string`

The URI of the image.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the image.

{% /summary %}

Possible values:

- `image/png`: PNG image format
- `image/jpeg`: JPEG image format
- `image/webp`: WebP image format
- `image/heic`: HEIC image format
- `image/heif`: HEIF image format
- `image/gif`: GIF image format
- `image/bmp`: BMP image format
- `image/tiff`: TIFF image format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**[TextContent](/api-reference/interactions-api/get-interaction-by-id#Resource:TextContent)**{% /summary %}

A text content block.

{% two-column-layout %}

{% left-column %}

**text**: {% mark %}required{% /mark %} `string`

The text content.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**annotations**: `array (Annotation)`

Citation information for model-generated content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**FileCitation**{% /summary %}

A file citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `file_citation`

**document_uri**: `string`

The URI of the file.

**file_name**: `string`

The name of the file.

**source**: `string`

Source attributed for a portion of the text.

**custom_metadata**: `object`

User provided metadata about the retrieved context.

**page_number**: `integer`

Page number of the cited document, if applicable.

**media_id**: `string`

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

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**PlaceCitation**{% /summary %}

A place citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `place_citation`

**place_id**: `string`

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

**name**: `string`

Title of the place.

**url**: `string`

URI reference of the place.

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

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

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**SpeechAnnotation**{% /summary %}

Speech annotation for text content.

**type**: {% mark %}required{% /mark %} `object`

Value: `speech_metadata`

**speaker**: `string`

The speaker to associate with this turn.

**style**: `string`

Style instruction for the speech synthesis.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**UrlCitation**{% /summary %}

A URL citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `url_citation`

**url**: `string`

The URL.

**title**: `string`

The title of the URL.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**WordInfo**{% /summary %}

Word-level ASR annotation for transcription output. Carries the word text, optional timing, and optional speaker attribution.

**type**: {% mark %}required{% /mark %} `object`

Value: `word_info`

**text**: `string`

The transcribed word.

**start_offset**: `string`

Start offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**end_offset**: `string`

End offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**speaker**: `string`

Optional. Speaker label for this word (e.g. "spk_1", "spk_2"). Present when diarization_mode is set in TranscriptionConfig.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**VideoContent**{% /summary %}

A video content block.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% hr /%}

**data**: `string`

The video content.

{% hr /%}

**uri**: `string`

The URI of the video.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**processing**: `MediaProcessing` or `enum (string)`

How the model processes this video for understanding.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**MediaProcessing**{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `static`

**start_offset**: `string`

Optional. Segment start time. Specified as a decimal number of seconds followed by an 's' suffix, e.g., "10.5s". Must be non-negative.

**end_offset**: `string`

Optional. Segment end time. Specified as a decimal number of seconds followed by an 's' suffix, e.g., "30s". Must be non-negative and greater than `start_offset` if `start_offset` is set.

**fps**: `number`

Optional. Video frame-rate sampling density.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `static`: Fixed-rate frame extraction. All frames placed in context.
- `agentic`: Model-driven dynamic navigation.

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

A user-defined name for this content block. Can be referenced by the model in the final response.

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the video.

{% /summary %}

Possible values:

- `video/mp4`: MP4 video format
- `video/mpeg`: MPEG video format
- `video/mpg`: MPG video format
- `video/mov`: MOV video format
- `video/avi`: AVI video format
- `video/x-flv`: FLV video format
- `video/webm`: WebM video format
- `video/wmv`: WMV video format
- `video/3gpp`: 3GPP video format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Video**

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

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### Tool {% class="hide-from-toc" id="Resource:Tool" %}

A tool that can be used by the model.

**Polymorphic Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "code_execution"
    }],
    "input": "Calculate the first 10 Fibonacci numbers"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "code_execution"}],
    input="Calculate the first 10 Fibonacci numbers",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'code_execution'}],
  input: 'Calculate the first 10 Fibonacci numbers',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new CodeExecution()))
        .input(InteractionsInput.of("Calculate the first 10 Fibonacci numbers"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="code_execution" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.CodeExecution{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Calculate the first 10 Fibonacci numbers")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ComputerUse**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `computer_use`

{% hr /%}

{% details %}

{% summary %}

**environment**: `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `browser`: Operates in a web browser.
- `mobile`: Operates in a mobile environment.
- `desktop`: Operates in a desktop environment.

{% /details %}

{% hr /%}

**excluded_predefined_functions**: `array (string)`

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

{% hr /%}

**enable_prompt_injection_detection**: `boolean`

Whether enable the prompt injection detection check on computer-use request.

{% hr /%}

{% details %}

{% summary %}

**disabled_safety_policies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `financial_transactions`: Safety policy for financial transactions.
- `sensitive_data_modification`: Safety policy for sensitive data modification.
- `communication_tool`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `account_creation`: Safety policy for account creation.
- `data_modification`: Safety policy for data modification.
- `user_consent_management`: Safety policy for user consent management.
- `legal_terms_and_agreements`: Safety policy for legal terms and agreements.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-2.5-computer-use-preview-10-2025",
    "tools": [{
      "type": "computer_use"
    }],
    "input": "Find a flight to Tokyo"
  }'

```

{% /tab %}

{% tab label="Python" %}

```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.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```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.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.ComputerUse;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-2.5-computer-use-preview-10-2025")
        .tools(List.of(new ComputerUse()))
        .input(InteractionsInput.of("Find a flight to Tokyo"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="computer_use" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.ComputerUse{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-2.5-computer-use-preview-10-2025"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Find a flight to Tokyo")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearch**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search`

{% hr /%}

**file_search_store_names**: `array (string)`

The file search store names to search.

{% hr /%}

**top_k**: `integer`

The number of semantic retrieval chunks to retrieve.

{% hr /%}

**metadata_filter**: `string`

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

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "file_search",
      "file_search_store_names": ["fileSearchStores/m64d1sevsr4y-xfyawui3fxqg"]
    }],
    "input": "Who is the author of the book?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

# Create a file search store so we have a valid one to use.
store = client.file_search_stores.create()

response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[
        {"type": "file_search", "file_search_store_names": [store.name]}
    ],
    input="What documents are available?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

// Create a file search store so we have a valid one to use.
const store = await ai.fileSearchStores.create({});
if (!store.name) {
  throw new Error('Store creation failed: Name is undefined');
}

const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [
    {
      type: 'file_search',
      file_search_store_names: [store.name],
    },
  ],
  input: 'What documents are available?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
import com.google.genai.types.FileSearchStore;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();

// Create a file search store so we have a valid one to use.
FileSearchStore store =
    client.fileSearchStores.create(CreateFileSearchStoreConfig.builder().build());
String storeName = store.name().orElseThrow();

FileSearch tool = FileSearch.builder().fileSearchStoreNames(List.of(storeName)).build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(tool))
        .input(InteractionsInput.of("What documents are available?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="file_search" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    tool := gaos_interactions.NewTool(gaos_interactions.FileSearch{
        FileSearchStoreNames: []string{store.Name},
    })

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What documents are available?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `function`

{% hr /%}

**name**: `string`

The name of the function.

{% hr /%}

**description**: `string`

A description of the function.

{% hr /%}

**parameters**: `object`

The JSON Schema for the function's parameters. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "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?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    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.steps[-1])

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  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.steps.at(-1));

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Function;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Step;

Client client = new Client();
Map<String, Object> parameters =
    Map.of(
        "type", "object",
        "properties",
            Map.of(
                "location",
                Map.of(
                    "type", "string",
                    "description", "The city and state, e.g. San Francisco, CA")),
        "required", List.of("location"));
Function functionTool =
    Function.builder()
        .name("get_weather")
        .description("Get the current weather in a given location")
        .parameters(parameters)
        .build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(functionTool))
        .input(InteractionsInput.of("What is the weather like in Boston?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
List<Step> steps = interaction.steps().orElse(List.of());
if (!steps.isEmpty()) {
  System.out.println(steps.get(steps.size() - 1));
}

```

{% /tab %}

{% tab label="function_calling" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    function := gaos_interactions.Function{
        Name:        genai.Ptr("get_weather"),
        Description: genai.Ptr("Get the current weather in a given location"),
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "location": map[string]any{
                    "type":        "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                },
            },
            "required": []string{"location"},
        },
    }

    tool := gaos_interactions.NewTool(function)

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What is the weather like in Boston, MA?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil {
        for _, step := range res.Interaction.Steps {
            if step.FunctionCallStep != nil {
                fmt.Println("Function Call:", step.FunctionCallStep.Name)
                fmt.Println("Arguments:", step.FunctionCallStep.Arguments)
            }
        }
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMaps**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps`

{% hr /%}

**enable_widget**: `boolean`

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

{% hr /%}

**latitude**: `number`

The latitude of the user's location.

{% hr /%}

**longitude**: `number`

The longitude of the user's location.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "google_maps",
      "latitude": 37.7749,
      "longitude": -122.4194
    }],
    "input": "What is the best food near me?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[
        {"type": "google_maps", "latitude": 37.7749, "longitude": -122.4194}
    ],
    input="What is the best food near me?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [
    {
      type: 'google_maps',
      latitude: 37.7749,
      longitude: -122.4194,
    },
  ],
  input: 'What is the best food near me?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleMaps;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
GoogleMaps tool = GoogleMaps.builder().latitude(37.7749).longitude(-122.4194).build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(tool))
        .input(InteractionsInput.of("What is the best food near me?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="google_maps" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.GoogleMaps{
        Latitude:  genai.Ptr(37.7749),
        Longitude: genai.Ptr(-122.4194),
    })

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("What is the best food near me?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% hr /%}

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "google_search"
    }],
    "input": "Who is the current president of France?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "google_search"}],
    input="Who is the current president of France?",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'google_search'}],
  input: 'Who is the current president of France?',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new GoogleSearch()))
        .input(InteractionsInput.of("Who is the current president of France?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="google_search" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.GoogleSearch{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Who is the current president of France?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server`

{% hr /%}

**name**: `string`

The name of the MCPServer.

{% hr /%}

**url**: `string`

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

{% hr /%}

**headers**: `object`

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

{% hr /%}

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "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?"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
import os

from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    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.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  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.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.MCPServer;

Client client = new Client();
MCPServer mcpTool =
    MCPServer.builder()
        .name("weather_service")
        .url("https://gemini-api-demos.uc.r.appspot.com/mcp")
        .build();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(mcpTool))
        .input(
            InteractionsInput.of(
                "Today is 12-05-2025, what is the temperature today in London?"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="mcp_server" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    mcpServer := gaos_interactions.MCPServer{
        Name: genai.Ptr("weather_service"),
        URL:  genai.Ptr("https://gemini-api-demos.uc.r.appspot.com/mcp"),
    }
    tool := gaos_interactions.NewTool(mcpServer)

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Today is 12-05-2025, what is the temperature today in London?")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="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-flash-latest",
    "tools": [{
      "type": "url_context"
    }],
    "input": "Summarize https://www.example.com"
  }'

```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.interactions.create(
    model="gemini-flash-latest",
    tools=[{"type": "url_context"}],
    input="Summarize https://www.example.com",
)
print(response.output_text)

```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
  model: 'gemini-flash-latest',
  tools: [{type: 'url_context'}],
  input: 'Summarize https://www.example.com',
});
console.log(interaction.output_text);

```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.URLContext;

Client client = new Client();
CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model("gemini-flash-latest")
        .tools(List.of(new URLContext()))
        .input(InteractionsInput.of("Summarize https://www.example.com"))
        .build();
CreateInteractionResponse response =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    response.interaction().orElseThrow(() -> new RuntimeException("No interaction returned"));
System.out.println(interaction.outputText().orElse(""));

```

{% /tab %}

{% tab label="url_context" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    tool := gaos_interactions.NewTool(gaos_interactions.URLContext{})

    body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{
        Model: gaos_interactions.Model("gemini-flash-latest"),
        Input: genai.Ptr(gaos_interactions.NewInteractionsInput("Summarize https://www.example.com")),
        Tools: []gaos_interactions.Tool{tool},
    })

    req := operations.CreateInteractionRequest{
        Body: body,
    }

    res, err := client.Interactions.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction != nil && res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### ResponseFormat {% class="hide-from-toc" id="Resource:ResponseFormat" %}

**Polymorphic Types:**

{% details %}

{% summary %}**AudioResponseFormat**{% /summary %}

Configuration for audio output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the audio output.

{% /summary %}

Possible values:

- `audio/mp3`: MP3 audio format.
- `audio/ogg_opus`: OGG Opus audio format.
- `audio/l16`: Raw PCM (L16) audio format.
- `audio/wav`: WAV audio format.
- `audio/alaw`: A-law audio format.
- `audio/mulaw`: Mu-law audio format.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the audio output.

{% /summary %}

Possible values:

- `inline`: Audio data is returned inline in the response.
- `uri`: Audio data is returned as a URI.

{% /details %}

{% hr /%}

**sample_rate**: `integer`

Sample rate in Hz.

{% hr /%}

**bit_rate**: `integer`

Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Audio Output**

```json
{
  "type": "audio",
  "sample_rate": 24000
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ImageResponseFormat**{% /summary %}

Configuration for image output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the image output.

{% /summary %}

Possible values:

- `image/jpeg`: JPEG image format.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the image output.

{% /summary %}

Possible values:

- `inline`: Image data is returned inline in the response.
- `uri`: Image data is returned as a URI.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the image output.

{% /summary %}

Possible values:

- `1:1`: 1:1 aspect ratio.
- `2:3`: 2:3 aspect ratio.
- `3:2`: 3:2 aspect ratio.
- `3:4`: 3:4 aspect ratio.
- `4:3`: 4:3 aspect ratio.
- `4:5`: 4:5 aspect ratio.
- `5:4`: 5:4 aspect ratio.
- `9:16`: 9:16 aspect ratio.
- `16:9`: 16:9 aspect ratio.
- `21:9`: 21:9 aspect ratio.
- `1:8`: 1:8 aspect ratio.
- `8:1`: 8:1 aspect ratio.
- `1:4`: 1:4 aspect ratio.
- `4:1`: 4:1 aspect ratio.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**image_size**: `enum (string)`

The size of the image output.

{% /summary %}

Possible values:

- `512`: 512px image size.
- `1K`: 1K image size.
- `2K`: 2K image size.
- `4K`: 4K image size.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image Output**

```json
{
  "type": "image",
  "aspect_ratio": "16:9",
  "image_size": "1K",
  "mime_type": "image/jpeg"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**TextResponseFormat**{% /summary %}

Configuration for text output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the text output.

{% /summary %}

Possible values:

- `application/json`: JSON output format.
- `text/plain`: Plain text output format.

{% /details %}

{% hr /%}

**schema**: `object`

The JSON schema that the output should conform to. Only applicable when mime_type is application/json. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced; validate these in your application. `minItems` and `maxItems` are enforced. Schemas that are too complex to enforce (for example, large `maxItems` on nested arrays) return a 400 INVALID_ARGUMENT error.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text Output (JSON Schema)**

```json
{
  "type": "text",
  "mime_type": "application/json",
  "schema": {
    "type": "object",
    "properties": {
      "ingredients": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "recipe_name": {
        "type": "string"
      }
    },
    "required": [
      "ingredients",
      "recipe_name"
    ]
  }
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**VideoResponseFormat**{% /summary %}

Configuration for video output format.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% hr /%}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the video output.

{% /summary %}

Possible values:

- `inline`: Video data is returned inline in the response.
- `uri`: Video data is returned as a URI.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the video output.

{% /summary %}

Possible values:

- `16:9`: 16:9 aspect ratio.
- `9:16`: 9:16 aspect ratio.

{% /details %}

{% hr /%}

**duration**: `string`

The duration for the video output.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `enum (string)`

The video output resolution. Defaults to 720p.

{% /summary %}

Possible values:

- `360p`: 360p resolution.
- `720p`: 720p resolution.
- `1080p`: 1080p resolution.
- `4k`: 4K resolution.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Video Output**

```json
{
  "type": "video",
  "aspect_ratio": "16:9",
  "delivery": "inline"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### Step {% class="hide-from-toc" id="Resource:Step" %}

A step in the interaction.

**Polymorphic Types:**

{% details %}

{% summary %}**CodeExecutionCallStep**{% /summary %}

Code execution call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `CodeExecutionCallStepArguments`

The arguments to pass to the code execution.

{% /summary %}

{% details %}

{% summary %}

**language**: `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `python`: Python >= 3.10, with numpy and simpy available.
- `bash`: Bash. Only available for Gemini 3.0 model or above.

{% /details %}

**code**: `string`

The code to be executed.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**CodeExecutionCallStep**

```json
{
  "type": "code_execution_call",
  "arguments": {
    "code": "print(sum(range(1, 11)))"
  },
  "id": "code_call_71021"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**CodeExecutionResultStep**{% /summary %}

Code execution result step.

{% two-column-layout %}

{% left-column %}

**result**: {% mark %}required{% /mark %} `string`

The output of the code execution.

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution_result`

{% hr /%}

**is_error**: `boolean`

Whether the code execution resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**CodeExecutionResultStep**

```json
{
  "type": "code_execution_result",
  "call_id": "code_call_71021",
  "result": "55\n"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearchCallStep**{% /summary %}

File Search call step.

{% two-column-layout %}

{% left-column %}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FileSearchCallStep**

```json
{
  "type": "file_search_call",
  "id": "file_call_88192"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FileSearchResultStep**{% /summary %}

File Search result step.

{% two-column-layout %}

{% left-column %}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `file_search_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FileSearchResultStep**

```json
{
  "type": "file_search_result",
  "call_id": "file_call_88192"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FunctionCallStep**{% /summary %}

A function tool call step.

{% two-column-layout %}

{% left-column %}

**name**: {% mark %}required{% /mark %} `string`

The name of the tool to call.

{% hr /%}

**arguments**: {% mark %}required{% /mark %} `object`

The arguments to pass to the function.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `function_call`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FunctionCallStep**

```json
{
  "name": "get_weather",
  "type": "function_call",
  "arguments": {
    "location": "Boston, MA"
  },
  "id": "call_98231"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**FunctionResultStep**{% /summary %}

Result of a function tool call.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (`[`ImageContent`](/api-reference/interactions-api/get-interaction-by-id#Resource:ImageContent) or [`TextContent`](/api-reference/interactions-api/get-interaction-by-id#Resource:TextContent)`)` or `object` or `string`

The result of the tool call.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array ([ImageContent](/api-reference/interactions-api/get-interaction-by-id#Resource:ImageContent) or [TextContent](/api-reference/interactions-api/get-interaction-by-id#Resource:TextContent))**{% /summary %}

A list where each item is one of: [`ImageContent`](/api-reference/interactions-api/get-interaction-by-id#Resource:ImageContent), [`TextContent`](/api-reference/interactions-api/get-interaction-by-id#Resource:TextContent).

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `function_result`

{% hr /%}

**name**: `string`

The name of the tool that was called.

{% hr /%}

**is_error**: `boolean`

Whether the tool call resulted in an error.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**FunctionResultStep**

```json
{
  "name": "get_weather",
  "type": "function_result",
  "call_id": "call_98231",
  "result": [
    {
      "type": "text",
      "text": "{\"weather\":\"sunny\"}"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMapsCallStep**{% /summary %}

Google Maps call step.

{% two-column-layout %}

{% left-column %}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps_call`

{% hr /%}

{% details %}

{% summary %}

**arguments**: `GoogleMapsCallStepArguments`

The arguments to pass to the Google Maps tool.

{% /summary %}

**queries**: `array (string)`

The queries to be executed.

{% /details %}

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleMapsCallStep**

```json
{
  "type": "google_maps_call",
  "arguments": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "id": "maps_call_39201"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleMapsResultStep**{% /summary %}

Google Maps result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (GoogleMapsResultItem)`

{% /summary %}

{% details %}

{% summary %}

**places**: `array (GoogleMapsResultPlaces)`

{% /summary %}

**place_id**: `string`

**name**: `string`

**url**: `string`

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

{% /details %}

**widget_context_token**: `string`

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_maps_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleMapsResultStep**

```json
{
  "type": "google_maps_result",
  "call_id": "maps_call_39201",
  "result": [
    {
      "name": "Golden Gate Park",
      "place_id": "ChIJIQBpAG2ahYAR9R7bNdTLg8M",
      "rating": 4.8
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearchCallStep**{% /summary %}

Google Search call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `GoogleSearchCallStepArguments`

The arguments to pass to Google Search.

{% /summary %}

**queries**: `array (string)`

Web search queries for the following-up web search.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search_call`

{% hr /%}

{% details %}

{% summary %}

**search_type**: `enum (string)`

The type of search grounding enabled.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleSearchCallStep**

```json
{
  "type": "google_search_call",
  "arguments": {
    "query": "Who won the men's 100m in Paris 2024?"
  },
  "id": "search_call_19201"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**GoogleSearchResultStep**{% /summary %}

Google Search result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (GoogleSearchResultItem)`

The results of the Google Search.

{% /summary %}

**search_suggestions**: `string`

Web content snippet that can be embedded in a web page or an app webview.

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search_result`

{% hr /%}

**is_error**: `boolean`

Whether the Google Search resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**GoogleSearchResultStep**

```json
{
  "type": "google_search_result",
  "call_id": "search_call_19201",
  "result": [
    {
      "title": "Paris 2024 Olympics: Noah Lyles wins men's 100m gold",
      "url": "https://olympics.com/en/news/paris-2024-noah-lyles-wins-mens-100m-gold",
      "snippet": "American Noah Lyles won the Olympic men's 100m gold medal in a photo finish."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServerToolCallStep**{% /summary %}

MCPServer tool call step.

{% two-column-layout %}

{% left-column %}

**name**: {% mark %}required{% /mark %} `string`

The name of the tool which was called.

{% hr /%}

**server_name**: {% mark %}required{% /mark %} `string`

The name of the used MCP server.

{% hr /%}

**arguments**: {% mark %}required{% /mark %} `object`

The JSON object of arguments for the function.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server_tool_call`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**McpServerToolCallStep**

```json
{
  "name": "calculate_tax",
  "type": "mcp_server_tool_call",
  "arguments": {
    "income": 120000,
    "state": "CA"
  },
  "id": "mcp_call_29012",
  "server_name": "financial_mcp_server"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**McpServerToolResultStep**{% /summary %}

MCPServer tool result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (`[`ImageContent`](/api-reference/interactions-api/get-interaction-by-id#Resource:ImageContent) or [`TextContent`](/api-reference/interactions-api/get-interaction-by-id#Resource:TextContent)`)` or `object` or `string`

The output from the MCP server call. Can be simple text or rich content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array ([ImageContent](/api-reference/interactions-api/get-interaction-by-id#Resource:ImageContent) or [TextContent](/api-reference/interactions-api/get-interaction-by-id#Resource:TextContent))**{% /summary %}

A list where each item is one of: [`ImageContent`](/api-reference/interactions-api/get-interaction-by-id#Resource:ImageContent), [`TextContent`](/api-reference/interactions-api/get-interaction-by-id#Resource:TextContent).

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `mcp_server_tool_result`

{% hr /%}

**name**: `string`

Name of the tool which is called for this specific tool call.

{% hr /%}

**server_name**: `string`

The name of the used MCP server.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**McpServerToolResultStep**

```json
{
  "name": "calculate_tax",
  "type": "mcp_server_tool_result",
  "call_id": "mcp_call_29012",
  "result": {
    "tax_due": 32400
  },
  "server_name": "financial_mcp_server"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ModelOutputStep**{% /summary %}

Output generated by the model.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `model_output`

{% hr /%}

**content**: `array (`[`Content`](/api-reference/interactions-api/get-interaction-by-id#Resource:Content)`)`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**ModelOutputStep**

```json
{
  "type": "model_output",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**ProcessingCallStep**{% /summary %}

A server-initiated processing step for media analysis (e.g. video
understanding).

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `processing_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**ProcessingResultStep**{% /summary %}

The result of a server-initiated media processing step.

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `processing_result`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /details %}

{% details %}

{% summary %}**ThoughtStep**{% /summary %}

A thought step.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `thought`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% hr /%}

**summary**: `array (`[`Content`](/api-reference/interactions-api/get-interaction-by-id#Resource:Content)`)`

A summary of the thought.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**ThoughtStep**

```json
{
  "type": "thought",
  "signature": "thought_sig_abcd1234",
  "summary": [
    {
      "type": "text",
      "text": "The model is searching Google for the capital of France."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContextCallStep**{% /summary %}

URL context call step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**arguments**: {% mark %}required{% /mark %} `UrlContextCallArguments`

The arguments to pass to the URL context.

{% /summary %}

**urls**: `array (string)`

The URLs to fetch.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

A unique ID for this specific tool call.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context_call`

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UrlContextCallStep**

```json
{
  "type": "url_context_call",
  "arguments": {
    "urls": [
      "https://www.example.com"
    ]
  },
  "id": "url_call_10219"
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UrlContextResultStep**{% /summary %}

URL context result step.

{% two-column-layout %}

{% left-column %}

{% details %}

{% summary %}

**result**: {% mark %}required{% /mark %} `array (UrlContextResult)`

The results of the URL context.

{% /summary %}

**url**: `string`

The URL that was fetched.

{% details %}

{% summary %}

**status**: `enum (string)`

The status of the URL retrieval.

{% /summary %}

Possible values:

- `success`: Url retrieval is successful.
- `error`: Url retrieval is failed due to error.
- `paywall`: Url retrieval is failed because the content is behind paywall.
- `unsafe`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% hr /%}

**call_id**: {% mark %}required{% /mark %} `string`

ID to match the ID from the function call block.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context_result`

{% hr /%}

**is_error**: `boolean`

Whether the URL context resulted in an error.

{% hr /%}

**signature**: `string`

A signature hash for backend validation.

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UrlContextResultStep**

```json
{
  "type": "url_context_result",
  "call_id": "url_call_10219",
  "result": [
    {
      "title": "Example Domain",
      "url": "https://www.example.com",
      "snippet": "This domain is for use in illustrative examples in documents."
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

{% details %}

{% summary %}**UserInputStep**{% /summary %}

Input provided by the user.

{% two-column-layout %}

{% left-column %}

**type**: {% mark %}required{% /mark %} `object`

Value: `user_input`

{% hr /%}

**content**: `array (`[`Content`](/api-reference/interactions-api/get-interaction-by-id#Resource:Content)`)`

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**UserInputStep**

```json
{
  "type": "user_input",
  "content": [
    {
      "type": "text",
      "text": "What is the capital of France?"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

{% /details %}

### EnvironmentConfig {% class="hide-from-toc" id="Resource:EnvironmentConfig" %}

Configuration for a custom environment.

{% two-column-layout %}

{% left-column %}

**Properties:**

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% hr /%}

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**network**: [`EnvironmentNetworkEgressAllowlist`](/api-reference/interactions-api/get-interaction-by-id#Resource:EnvironmentNetworkEgressAllowlist) or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**[EnvironmentNetworkEgressAllowlist](/api-reference/interactions-api/get-interaction-by-id#Resource:EnvironmentNetworkEgressAllowlist)**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% hr /%}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% hr /%}

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

{% tabs %}

{% tab label="Inline Sources" %}

```json
{
  "type": "remote",
  "sources": [
    {
      "type": "inline",
      "content": "You are a data analyst. Always include visualizations and export results as PDF.",
      "target": ".agents/AGENTS.md"
    },
    {
      "type": "inline",
      "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",
      "target": ".agents/skills/slide-maker/SKILL.md"
    }
  ]
}
```

{% /tab %}

{% tab label="External Sources" %}

```json
{
  "type": "remote",
  "sources": [
    {
      "type": "repository",
      "source": "https://github.com/my-org/my-skills.git",
      "target": ".agents/skills"
    },
    {
      "type": "gcs",
      "source": "gs://my-bucket/my-folder",
      "target": "/workspace/data"
    }
  ]
}
```

{% /tab %}

{% tab label="Network Allowlist" %}

```json
{
  "type": "remote",
  "network": {
    "allowlist": [
      {
        "domain": "pypi.org"
      },
      {
        "domain": "*.github.com"
      }
    ]
  }
}
```

{% /tab %}

{% tab label="Proxy Credentials" %}

```json
{
  "type": "remote",
  "network": {
    "allowlist": [
      {
        "domain": "api.github.com",
        "transform": {
          "Authorization": "Bearer YOUR_GITHUB_TOKEN"
        }
      }
    ]
  }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

### EnvironmentNetworkEgressAllowlist {% class="hide-from-toc" id="Resource:EnvironmentNetworkEgressAllowlist" %}

Network egress configuration for the environment.

{% two-column-layout %}

{% left-column %}

**Properties:**

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Network Allowlist**

```json
{
  "allowlist": [
    {
      "domain": "github.com",
      "transform": [
        {
          "Authorization": "Bearer your-token"
        }
      ]
    },
    {
      "domain": "*.googleapis.com"
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

### ToolChoiceConfig {% class="hide-from-toc" id="Resource:ToolChoiceConfig" %}

The tool choice configuration containing allowed tools.

{% two-column-layout %}

{% left-column %}

**Properties:**

{% details %}

{% summary %}

**allowed_tools**: `AllowedTools`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

```json
{
  "allowed_tools": {
    "mode": "any",
    "tools": [
      "my_tool"
    ]
  }
}
```

{% /right-column %}

{% /two-column-layout %}

### ImageContent {% class="hide-from-toc" id="Resource:ImageContent" %}

An image content block.

{% two-column-layout %}

{% left-column %}

**Properties:**

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% hr /%}

**data**: `string`

The image content.

{% hr /%}

**uri**: `string`

The URI of the image.

{% hr /%}

{% details %}

{% summary %}

**resolution**: `MediaResolution`

The resolution of the media.

{% /summary %}

Possible values:

- `low`: Low resolution.
- `medium`: Medium resolution.
- `high`: High resolution.
- `ultra_high`: Ultra high resolution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The mime type of the image.

{% /summary %}

Possible values:

- `image/png`: PNG image format
- `image/jpeg`: JPEG image format
- `image/webp`: WebP image format
- `image/heic`: HEIC image format
- `image/heif`: HEIF image format
- `image/gif`: GIF image format
- `image/bmp`: BMP image format
- `image/tiff`: TIFF image format

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Image**

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

{% /right-column %}

{% /two-column-layout %}

### TextContent {% class="hide-from-toc" id="Resource:TextContent" %}

A text content block.

{% two-column-layout %}

{% left-column %}

**Properties:**

**text**: {% mark %}required{% /mark %} `string`

The text content.

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% hr /%}

{% details %}

{% summary %}

**annotations**: `array (Annotation)`

Citation information for model-generated content.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**FileCitation**{% /summary %}

A file citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `file_citation`

**document_uri**: `string`

The URI of the file.

**file_name**: `string`

The name of the file.

**source**: `string`

Source attributed for a portion of the text.

**custom_metadata**: `object`

User provided metadata about the retrieved context.

**page_number**: `integer`

Page number of the cited document, if applicable.

**media_id**: `string`

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

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**PlaceCitation**{% /summary %}

A place citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `place_citation`

**place_id**: `string`

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

**name**: `string`

Title of the place.

**url**: `string`

URI reference of the place.

{% details %}

{% summary %}

**review_snippets**: `array (ReviewSnippet)`

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

{% /summary %}

**title**: `string`

Title of the review.

**url**: `string`

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

**review_id**: `string`

The ID of the review snippet.

{% /details %}

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**SpeechAnnotation**{% /summary %}

Speech annotation for text content.

**type**: {% mark %}required{% /mark %} `object`

Value: `speech_metadata`

**speaker**: `string`

The speaker to associate with this turn.

**style**: `string`

Style instruction for the speech synthesis.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**UrlCitation**{% /summary %}

A URL citation annotation.

**type**: {% mark %}required{% /mark %} `object`

Value: `url_citation`

**url**: `string`

The URL.

**title**: `string`

The title of the URL.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% details %}

{% summary %}**WordInfo**{% /summary %}

Word-level ASR annotation for transcription output. Carries the word text, optional timing, and optional speaker attribution.

**type**: {% mark %}required{% /mark %} `object`

Value: `word_info`

**text**: `string`

The transcribed word.

**start_offset**: `string`

Start offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**end_offset**: `string`

End offset in time of the word relative to the start of the audio. Present when timestamp_granularities contains "word".

**speaker**: `string`

Optional. Speaker label for this word (e.g. "spk_1", "spk_2"). Present when diarization_mode is set in TranscriptionConfig.

**start_index**: `integer`

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`

End of the attributed segment, exclusive.

{% /details %}

{% /details %}

{% /left-column %}

{% right-column class="sticky" %}

**Example**

**Text**

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

{% /right-column %}

{% /two-column-layout %}

# Deleting an interaction
Source: https://aistudio.google.com/api-reference/interactions-api/delete-interaction
Description: Deletes the interaction by id.

{% callout type="note" %}

You are viewing the beta version of the Interactions API. Endpoints are under `/v1beta/`. The stable [v1 version](/api-reference/interactions-api/delete-interaction?api-version=v1) is also available.

{% /callout %}

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/interactions/{id}`

Deletes the interaction by id.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**api_version**: {% mark %}required{% /mark %} `string`

API version for request routing.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

The unique identifier of the interaction to delete.

{% hr /%}

**interactionsId**: {% mark %}required{% /mark %} `string`

The name of the interaction to delete.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()


client.interactions.delete(id=created.id)
print("Interaction deleted successfully.")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


await ai.interactions.delete(created.id);
console.log('Interaction deleted successfully.');
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Interaction;

Client client = new Client();


client.interactions.delete(interactionId);
System.out.println("Interaction deleted successfully.");
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    req := operations.DeleteInteractionRequest{
        ID: interactionID,
    }

    _, err = client.Interactions.Delete(
        ctx,
        req,
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Interaction deleted successfully.")
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

Empty response.

# Generating content
Source: https://aistudio.google.com/api-reference/generate-content
Description: The Gemini API supports content generation with images, audio, code, tools, and more.

The Gemini API supports content generation with images, audio, code, tools, and more. For details on each of these features, read on and check out the task-focused sample code, or read the comprehensive guides.

 * [Text generation](/docs/text-generation)
 * [Vision](/docs/image-understanding)
 * [Audio](/docs/audio)
 * [Embeddings](/docs/embeddings)
 * [Long context](/docs/long-context)
 * [Code execution](/docs/code-execution)
 * [JSON Mode](/docs/structured-output)
 * [Function calling](/docs/function-calling)
 * [System instructions](/docs/text-generation#system-instructions)

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Generating content](/api-reference/generate-content/generate-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:generateContent`

  Generates a model response given an input [`GenerateContentRequest`](/api-reference/generate-content/generate-content#request-body).
---

* [Streaming generated content](/api-reference/generate-content/stream-generate-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:streamGenerateContent`

  Generates a [streamed response](/docs/text-generation#streaming-responses) from the model given an input [`GenerateContentRequest`](/api-reference/generate-content/stream-generate-content#request-body).
---

* [Creating an ephemeral auth token](/api-reference/generate-content/create-token)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/auth_tokens`

  Creates a token that can be used to constrain the behavior of a BidiGenerateContent session.
{% /table %}

## Data Models {% id="data-models" %}

### GenerateContentResponse {% id="Resource:GenerateContentResponse" %}

Response from the model supporting multiple candidate responses.

Safety ratings and content filtering are reported for both
prompt in `GenerateContentResponse.prompt_feedback` and for each candidate
in `finish_reason` and in `safety_ratings`. The API:

 - Returns either all requested candidates or none of them
 - Returns no candidates at all only if there was something wrong with the
   prompt (check `prompt_feedback`)

 - Reports feedback on each candidate in `finish_reason` and
   `safety_ratings`.

**Properties:**

**candidates**: `array (`[`Candidate`](/api-reference/generate-content#Resource:Candidate)`)`

Candidate responses from the model.

{% hr /%}

{% details %}

{% summary %}

**promptFeedback**: `PromptFeedback`

Returns the prompt's feedback related to the content filters.

{% /summary %}

{% details %}

{% summary %}

**blockReason**: `enum (string)`

Optional. If set, the prompt was blocked and no candidates are returned. Rephrase the prompt.

{% /summary %}

Possible values:

- `BLOCK_REASON_UNSPECIFIED`: Default value. This value is unused.
- `SAFETY`: Prompt was blocked due to safety reasons. Inspect `safety_ratings` to understand which safety category blocked it.
- `OTHER`: Prompt was blocked due to unknown reasons.
- `BLOCKLIST`: Prompt was blocked due to the terms which are included from the terminology blocklist.
- `PROHIBITED_CONTENT`: Prompt was blocked due to prohibited content.
- `IMAGE_SAFETY`: Candidates blocked due to unsafe image generation content.

{% /details %}

**safetyRatings**: `array (`[`SafetyRating`](/api-reference/generate-content#Resource:SafetyRating)`)`

Ratings for safety of the prompt. There is at most one rating per category.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**usageMetadata**: `UsageMetadata`

Output only. Metadata on the generation requests' token usage.

{% /summary %}

**promptTokenCount**: `integer`

Number of tokens in the prompt. When `cached_content` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content.

**cachedContentTokenCount**: `integer`

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

**candidatesTokenCount**: `integer`

Total number of tokens across all the generated response candidates.

**toolUsePromptTokenCount**: `integer`

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

**thoughtsTokenCount**: `integer`

Output only. Number of tokens of thoughts for thinking models.

**totalTokenCount**: `integer`

Total token count for the generation request (prompt + tool-use prompt + thoughts + response candidates).

**promptTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities that were processed in the request input.

**cacheTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities of the cached content in the request input.

**candidatesTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities that were returned in the response.

**toolUsePromptTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities that were processed for tool-use request inputs.

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/generate-content#Resource:ServiceTier)

Output only. Service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

{% /details %}

{% hr /%}

**modelVersion**: `string`

Output only. The model version used to generate the response.

{% hr /%}

**responseId**: `string`

Output only. response_id is used to identify each response.

{% hr /%}

{% details %}

{% summary %}

**modelStatus**: `ModelStatus`

Output only. The current model status of this model.

{% /summary %}

{% details %}

{% summary %}

**modelStage**: `ModelStage`

The stage of the underlying model.

{% /summary %}

Possible values:

- `MODEL_STAGE_UNSPECIFIED`: Unspecified model stage.
- `EXPERIMENTAL`: Models in this stage are for experimental purposes only.
- `PREVIEW`: Models in this stage are more mature than experimental models.
- `STABLE`: Models in this stage are considered stable and ready for production use.
- `LEGACY`: If the model is on this stage, it means that this model is on the path to deprecation in near future. Only existing customers can use this model.
- `RETIRED`: Models in this stage are retired. These models cannot be used.

{% /details %}

**retirementTime**: `string`

The time at which the model will be retired.

**message**: `string`

A message explaining the model status.

{% /details %}

### Candidate {% id="Resource:Candidate" %}

A response candidate generated from the model.

**Properties:**

**index**: `integer`

Output only. Index of the candidate in the list of response candidates.

{% hr /%}

**content**: [`Content`](/api-reference/generate-content#Resource:Content)

Output only. Generated content returned from the model.

{% hr /%}

{% details %}

{% summary %}

**finishReason**: `enum (string)`

Optional. Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating tokens.

{% /summary %}

Possible values:

- `FINISH_REASON_UNSPECIFIED`: Default value. This value is unused.
- `STOP`: Natural stop point of the model or provided stop sequence.
- `MAX_TOKENS`: The maximum number of tokens as specified in the request was reached.
- `SAFETY`: The response candidate content was flagged for safety reasons.
- `RECITATION`: The response candidate content was flagged for recitation reasons.
- `LANGUAGE`: The response candidate content was flagged for using an unsupported language.
- `OTHER`: Unknown reason.
- `BLOCKLIST`: Token generation stopped because the content contains forbidden terms.
- `PROHIBITED_CONTENT`: Token generation stopped for potentially containing prohibited content.
- `SPII`: Token generation stopped because the content potentially contains Sensitive Personally Identifiable Information (SPII).
- `MALFORMED_FUNCTION_CALL`: The function call generated by the model is invalid.
- `IMAGE_SAFETY`: Token generation stopped because generated images contain safety violations.
- `IMAGE_PROHIBITED_CONTENT`: Image generation stopped because generated images has other prohibited content.
- `IMAGE_OTHER`: Image generation stopped because of other miscellaneous issue.
- `NO_IMAGE`: The model was expected to generate an image, but none was generated.
- `IMAGE_RECITATION`: Image generation stopped due to recitation.
- `UNEXPECTED_TOOL_CALL`: Model generated a tool call but no tools were enabled in the request.
- `TOO_MANY_TOOL_CALLS`: Model called too many tools consecutively, thus the system exited execution.
- `MISSING_THOUGHT_SIGNATURE`: Request has at least one thought signature missing.
- `MALFORMED_RESPONSE`: Finished due to malformed response.
- `ESCALATION`: Request was filtered by an escalation rule.
- `PUP_LIMITED_DISABLED`: Indicates that token generation stopped because the user account is limited or disabled due to Prohibited Use Policy (PUP) violations.
- `CONTINUATION`: Token generation was stopped because the response reached the per-request token limit, but generation is not yet complete. The model response can be continued via a subsequent request using the returned `continuation_token`. Note, the `max_output_tokens` is cumulative across continuation hops and must be monotonically increased or omitted.

{% /details %}

{% hr /%}

**finishMessage**: `string`

Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when `finish_reason` is set.

{% hr /%}

**safetyRatings**: `array (`[`SafetyRating`](/api-reference/generate-content#Resource:SafetyRating)`)`

List of ratings for the safety of a response candidate. There is at most one rating per category.

{% hr /%}

**citationMetadata**: [`CitationMetadata`](/api-reference/generate-content#Resource:CitationMetadata)

Output only. Citation information for model-generated candidate. This field may be populated with recitation information for any text included in the `content`. These are passages that are "recited" from copyrighted material in the foundational LLM's training data.

{% hr /%}

**tokenCount**: `integer`

Output only. Token count for this candidate.

{% hr /%}

{% details %}

{% summary %}

**groundingAttributions**: `array (GroundingAttribution)`

Output only. Attribution information for sources that contributed to a grounded answer. This field is populated for `GenerateAnswer` calls.

{% /summary %}

{% details %}

{% summary %}

**sourceId**: `AttributionSourceId`

Output only. Identifier for the source contributing to this attribution.

{% /summary %}

{% details %}

{% summary %}

**groundingPassage**: `GroundingPassageId`

Identifier for an inline passage.

{% /summary %}

**passageId**: `string`

Output only. ID of the passage matching the `GenerateAnswerRequest`'s `GroundingPassage.id`.

**partIndex**: `integer`

Output only. Index of the part within the `GenerateAnswerRequest`'s `GroundingPassage.content`.

{% /details %}

{% details %}

{% summary %}

**semanticRetrieverChunk**: `SemanticRetrieverChunk`

Identifier for a `Chunk` fetched via Semantic Retriever.

{% /summary %}

**source**: `string`

Output only. Name of the source matching the request's `SemanticRetrieverConfig.source`. Example: `corpora/123` or `corpora/123/documents/abc`

**chunk**: `string`

Output only. Name of the `Chunk` containing the attributed text. Example: `corpora/123/documents/abc/chunks/xyz`

{% /details %}

{% /details %}

**content**: [`Content`](/api-reference/generate-content#Resource:Content)

Grounding source content that makes up this attribution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**groundingMetadata**: `GroundingMetadata`

Output only. Grounding metadata for the candidate. This field is populated for `GenerateContent` calls.

{% /summary %}

{% details %}

{% summary %}

**searchEntryPoint**: `SearchEntryPoint`

Optional. Google search entry for the following-up web searches.

{% /summary %}

**renderedContent**: `string`

Optional. Web content snippet that can be embedded in a web page or an app webview.

**sdkBlob**: `string`

Optional. Base64 encoded JSON representing array of tuple.

{% /details %}

{% details %}

{% summary %}

**groundingChunks**: `array (GroundingChunk)`

List of supporting references retrieved from specified grounding source. When streaming, this only contains the grounding chunks that have not been included in the grounding metadata of previous responses.

{% /summary %}

{% details %}

{% summary %}

**web**: `Web`

Grounding chunk from the web.

{% /summary %}

**uri**: `string`

Output only. URI reference of the chunk.

**title**: `string`

Output only. Title of the chunk.

{% /details %}

{% details %}

{% summary %}

**image**: `Image`

Optional. Grounding chunk from image search.

{% /summary %}

**sourceUri**: `string`

The web page URI for attribution.

**imageUri**: `string`

The image asset URL.

**title**: `string`

The title of the web page that the image is from.

**domain**: `string`

The root domain of the web page that the image is from, e.g. "example.com".

{% /details %}

{% details %}

{% summary %}

**retrievedContext**: `RetrievedContext`

Optional. Grounding chunk from context retrieved by the file search tool.

{% /summary %}

**uri**: `string`

Optional. URI reference of the semantic retrieval document.

**title**: `string`

Optional. Title of the document.

**text**: `string`

Optional. Text of the chunk.

**fileSearchStore**: `string`

Optional. Name of the `FileSearchStore` containing the document. Example: `fileSearchStores/123`

{% details %}

{% summary %}

**customMetadata**: `array (GroundingChunkCustomMetadata)`

Optional. User-provided metadata about the retrieved context.

{% /summary %}

**stringValue**: `string`

Optional. The string value of the metadata.

{% details %}

{% summary %}

**stringListValue**: `GroundingChunkStringList`

Optional. A list of string values for the metadata.

{% /summary %}

**values**: `array (string)`

The string values of the list.

{% /details %}

**numericValue**: `number`

Optional. The numeric value of the metadata. The expected range for this value depends on the specific `key` used.

**key**: `string`

The key of the metadata.

{% /details %}

**pageNumber**: `integer`

Optional. Page number of the retrieved context, if applicable.

**mediaId**: `string`

Optional. The media blob resource name for multimodal file search results. Format: fileSearchStores/{file_search_store_id}/media/{blob_id}

{% /details %}

{% details %}

{% summary %}

**maps**: `Maps`

Optional. Grounding chunk from Google Maps.

{% /summary %}

**uri**: `string`

URI reference of the place.

**title**: `string`

Title of the place.

**text**: `string`

Text description of the place answer.

**placeId**: `string`

The ID of the place, in `places/{place_id}` format. A user can use this ID to look up that place.

{% details %}

{% summary %}

**placeAnswerSources**: `PlaceAnswerSources`

Sources that provide answers about the features of a given place in Google Maps.

{% /summary %}

{% details %}

{% summary %}

**reviewSnippets**: `array (ReviewSnippet)`

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

{% /summary %}

**reviewId**: `string`

The ID of the review snippet.

**googleMapsUri**: `string`

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

**title**: `string`

Title of the review.

{% /details %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingSupports**: `array (GoogleAiGenerativelanguageV1betaGroundingSupport)`

List of grounding support.

{% /summary %}

{% details %}

{% summary %}

**segment**: `GoogleAiGenerativelanguageV1betaSegment`

Segment of the content this support belongs to.

{% /summary %}

**partIndex**: `integer`

The index of a Part object within its parent Content object.

**startIndex**: `integer`

Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero.

**endIndex**: `integer`

End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero.

**text**: `string`

The text corresponding to the segment from the response.

{% /details %}

**groundingChunkIndices**: `array (integer)`

Optional. A list of indices (into 'grounding_chunk' in `response.candidate.grounding_metadata`) specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. If the response is streaming, the grounding_chunk_indices refer to the indices across all responses. It is the client's responsibility to accumulate the grounding chunks from all responses (while maintaining the same order).

**confidenceScores**: `array (number)`

Optional. Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices.

**renderedParts**: `array (integer)`

Output only. Indices into the `parts` field of the candidate's content. These indices specify which rendered parts are associated with this support source.

{% /details %}

{% details %}

{% summary %}

**retrievalMetadata**: `RetrievalMetadata`

Metadata related to retrieval in the grounding flow.

{% /summary %}

**googleSearchDynamicRetrievalScore**: `number`

Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger google search.

{% /details %}

**webSearchQueries**: `array (string)`

Web search queries for the following-up web search.

**imageSearchQueries**: `array (string)`

Image search queries used for grounding.

**googleMapsWidgetContextToken**: `string`

Optional. Resource name of the Google Maps widget context token that can be used with the PlacesContextElement widget in order to render contextual data. Only populated in the case that grounding with Google Maps is enabled.

{% /details %}

{% hr /%}

**avgLogprobs**: `number`

Output only. Average log probability score of the candidate.

{% hr /%}

{% details %}

{% summary %}

**logprobsResult**: `LogprobsResult`

Output only. Log-likelihood scores for the response tokens and top tokens

{% /summary %}

**logProbabilitySum**: `number`

Sum of log probabilities for all tokens.

{% details %}

{% summary %}

**topCandidates**: `array (TopCandidates)`

Length = total number of decoding steps.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (LogprobsResultCandidate)`

Sorted by log probability in descending order.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**chosenCandidates**: `array (LogprobsResultCandidate)`

Length = total number of decoding steps. The chosen candidates may or may not be in top_candidates.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**urlContextMetadata**: `UrlContextMetadata`

Output only. Metadata related to url context retrieval tool.

{% /summary %}

{% details %}

{% summary %}

**urlMetadata**: `array (UrlMetadata)`

List of url context.

{% /summary %}

**retrievedUrl**: `string`

Retrieved url by the tool.

{% details %}

{% summary %}

**urlRetrievalStatus**: `enum (string)`

Status of the url retrieval.

{% /summary %}

Possible values:

- `URL_RETRIEVAL_STATUS_UNSPECIFIED`: Default value. This value is unused.
- `URL_RETRIEVAL_STATUS_SUCCESS`: Url retrieval is successful.
- `URL_RETRIEVAL_STATUS_ERROR`: Url retrieval is failed due to error.
- `URL_RETRIEVAL_STATUS_PAYWALL`: Url retrieval is failed because the content is behind paywall.
- `URL_RETRIEVAL_STATUS_UNSAFE`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**continuationToken**: `string`

An optional opaque continuation token returned when `finish_reason` is `CONTINUATION`. Clients can pass this token in a subsequent `GenerateContentRequest` to continue generation.

### CitationMetadata {% id="Resource:CitationMetadata" %}

A collection of source attributions for a piece of content.

**Properties:**

{% details %}

{% summary %}

**citationSources**: `array (CitationSource)`

Citations to sources for a specific response.

{% /summary %}

**startIndex**: `integer`

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

**endIndex**: `integer`

Optional. End of the attributed segment, exclusive.

**uri**: `string`

Optional. URI that is attributed as a source for a portion of the text.

**license**: `string`

Optional. License for the GitHub project that is attributed as a source for segment. License info is required for code citations.

{% /details %}

### HarmCategory {% id="Resource:HarmCategory" %}

**Possible values:**

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

### ModalityTokenCount {% id="Resource:ModalityTokenCount" %}

Represents token counting info for a single modality.

**Properties:**

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

{% hr /%}

**tokenCount**: `integer`

Number of tokens.

### SafetyRating {% id="Resource:SafetyRating" %}

Safety rating for a piece of content.

The safety rating contains the category of harm and the
harm probability level in that category for a piece of content.
Content is classified for safety across a number of
harm categories and the probability of the harm classification is included
here.

**Properties:**

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} [`HarmCategory`](/api-reference/generate-content#Resource:HarmCategory)

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

{% hr /%}

**blocked**: `boolean`

Was this content blocked because of this rating?

### SafetySetting {% id="Resource:SafetySetting" %}

Safety setting, affecting the safety-blocking behavior.

Passing a safety setting for a category changes the allowed probability that
content is blocked.

**Properties:**

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} [`HarmCategory`](/api-reference/generate-content#Resource:HarmCategory)

The category for this setting.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

Controls the probability threshold at which harm is blocked.

{% /summary %}

Possible values:

- `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: Threshold is unspecified.
- `BLOCK_LOW_AND_ABOVE`: Content with NEGLIGIBLE will be allowed.
- `BLOCK_MEDIUM_AND_ABOVE`: Content with NEGLIGIBLE and LOW will be allowed.
- `BLOCK_ONLY_HIGH`: Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
- `BLOCK_NONE`: All content will be allowed.
- `OFF`: Turn off the safety filter.

{% /details %}

### ServiceTier {% id="Resource:ServiceTier" %}

**Possible values:**

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

### Content {% id="Resource:Content" %}

The base structured datatype containing multi-part content of a message.

A [`Content`](/api-reference/generate-content#Resource:Content) includes a `role` field designating the producer of the [`Content`](/api-reference/generate-content#Resource:Content)
and a `parts` field containing multi-part data that contains the content of
the message turn.

**Properties:**

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

{% hr /%}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

### Environment {% id="Resource:Environment" %}

An execution environment for an agent.

**Properties:**

**id**: {% mark %}required{% /mark %} `string`

Output only. The ID of the environment.

{% hr /%}

{% details %}

{% summary %}

**sources**: `array (Source)`

Sources to be mounted into the environment.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`
- `GCS`: A Cloud Storage bucket.
- `INLINE`: Inline content.
- `REPOSITORY`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% hr /%}

**created**: `string`

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

{% hr /%}

**updated**: `string`

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

{% hr /%}

**lastAccessed**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The status of the environment container.

{% /summary %}

Possible values:

- `STATUS_UNSPECIFIED`: Output only. The status of the environment container.
- `ACTIVE`: Output only. The status of the environment container.
- `EXPIRED`: Output only. The status of the environment container.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**networkAllowlist**: `EnvironmentNetworkEgressAllowlist`

Allow only specific domains.

{% /summary %}

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**domain**: `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% details %}

{% summary %}

**mode**: `enum (string)`

Network egress mode. Set via the `"allowlist": "disabled"` short form; must be the only rule in the allowlist and cannot be combined with `domain`, `transform` or `credential`.

{% /summary %}

Possible values:

- `NETWORK_MODE_UNSPECIFIED`: Default value. Unused.
- `DISABLED`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**networkMode**: `enum (string)`

Network egress mode.

{% /summary %}

Possible values:

- `NETWORK_MODE_UNSPECIFIED`: Default value. Unused.
- `DISABLED`: All network egress is blocked.

{% /details %}

{% hr /%}

**fileCount**: `string`

Output only. The number of files in the environment, output only.

{% hr /%}

**sizeBytes**: `string`

Output only. The total size of the environment files in bytes, output only.

### Schema {% id="Resource:Schema" %}

The [`Schema`](/api-reference/generate-content#Resource:Schema) object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
Represents a select subset of an [OpenAPI 3.0 schema
object](https://spec.openapis.org/oas/v3.0.3#schema).

**Properties:**

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

{% hr /%}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

{% hr /%}

**title**: `string`

Optional. The title of the schema.

{% hr /%}

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

{% hr /%}

**nullable**: `boolean`

Optional. Indicates if the value may be null.

{% hr /%}

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

{% hr /%}

**items**: [`Schema`](/api-reference/generate-content#Resource:Schema)

Optional. Schema of the elements of Type.ARRAY.

{% hr /%}

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

{% hr /%}

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

{% hr /%}

**properties**: `object`

Optional. Properties of Type.OBJECT.

{% hr /%}

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

{% hr /%}

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

{% hr /%}

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

{% hr /%}

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

{% hr /%}

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

{% hr /%}

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

{% hr /%}

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

{% hr /%}

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

{% hr /%}

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

{% hr /%}

**anyOf**: `array (`[`Schema`](/api-reference/generate-content#Resource:Schema)`)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

{% hr /%}

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

{% hr /%}

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

### Tool {% id="Resource:Tool" %}

Tool details that the model may use to generate response.

A [`Tool`](/api-reference/generate-content#Resource:Tool) is a piece of code that enables the system to interact with
external systems to perform an action, or set of actions, outside of
knowledge and scope of the model.

**Properties:**

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

**parameters**: [`Schema`](/api-reference/generate-content#Resource:Schema)

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

**response**: [`Schema`](/api-reference/generate-content#Resource:Schema)

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

### AuthToken {% id="Resource:AuthToken" %}

A request to create an ephemeral authentication token.

**Properties:**

{% details %}

{% summary %}

**bidiGenerateContentSetup**: `BidiGenerateContentSetup`

Optional. Input only. Immutable. Configuration specific to `BidiGenerateContent`.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The model's resource name. This serves as an ID for the Model to use. Format: `models/{model}`

{% details %}

{% summary %}

**generationConfig**: `GenerationConfig`

Optional. Generation config. The following fields are not supported:

- `response_logprobs`
- `response_mime_type`
- `logprobs`
- `response_schema`
- `response_json_schema`
- `stop_sequence`
- `skip_response_cache`
- `routing_config`
- `audio_timestamp`

{% /summary %}

**candidateCount**: `integer`

Optional. Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)

**stopSequences**: `array (string)`

Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a `stop_sequence`. The stop sequence will not be included as part of the response.

**maxOutputTokens**: `integer`

Optional. The maximum number of tokens to include in a response candidate. Note: The default value varies by model, see the `Model.output_token_limit` attribute of the `Model` returned from the `getModel` function.

**temperature**: `number`

Optional. Controls the randomness of the output. Note: The default value varies by model, see the `Model.temperature` attribute of the `Model` returned from the `getModel` function. Values can range from [0.0, 2.0]. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topP**: `number`

Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topK**: `integer`

Optional. The maximum number of tokens to consider when sampling. Gemini models use Top-p (nucleus) sampling or a combination of Top-k and nucleus sampling. Top-k sampling considers the set of `top_k` most probable tokens. Models running with nucleus sampling don't allow top_k setting. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**seed**: `integer`

Optional. Seed used in decoding. If not set, the request uses a randomly generated seed.

**responseMimeType**: `string`

Optional. MIME type of the generated candidate text. Supported MIME types are: `text/plain`: (default) Text output. `application/json`: JSON response in the response candidates. `text/x.enum`: ENUM as a string response in the response candidates. Refer to the [docs](/docs/file-input-methods#text-file-types) for a list of all supported text MIME types.

**responseJsonSchema**: `object`

Optional. An internal detail. Use `responseJsonSchema` rather than this field.

**presencePenalty**: `number`

Optional. Presence penalty applied to the next token's logprobs if the token has already been seen in the response. This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequency_penalty for a penalty that increases with each use. A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary. A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.

**frequencyPenalty**: `number`

Optional. Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far. A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses. Caution: A _negative_ penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the max_output_tokens limit.

**responseLogprobs**: `boolean`

Optional. If true, export the logprobs results in response.

**logprobs**: `integer`

Optional. Only valid if response_logprobs=True. This sets the number of top logprobs, including the chosen candidate, to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].

**enableEnhancedCivicAnswers**: `boolean`

Optional. Enables enhanced civic answers. It may not be available for all models.

{% details %}

{% summary %}

**responseModalities**: `array (enum (string))`

Optional. The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response. A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned. An empty list is equivalent to requesting only text.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Default value.
- `TEXT`: Indicates the model should return text.
- `IMAGE`: Indicates the model should return images.
- `AUDIO`: Indicates the model should return audio.

{% /details %}

{% details %}

{% summary %}

**speechConfig**: `SpeechConfig`

Optional. The speech generation config.

{% /summary %}

{% details %}

{% summary %}

**voiceConfig**: `VoiceConfig`

The configuration in case of single-voice output.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% details %}

{% summary %}

**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig`

Optional. The configuration for the multi-speaker setup. It is mutually exclusive with the voice_config field.

{% /summary %}

{% details %}

{% summary %}

**speakerVoiceConfigs**: {% mark %}required{% /mark %} `array (SpeakerVoiceConfig)`

All the enabled speaker voices.

{% /summary %}

**speaker**: {% mark %}required{% /mark %} `string`

The name of the speaker to use. Should be the same as in the prompt.

{% details %}

{% summary %}

**voiceConfig**: {% mark %}required{% /mark %} `VoiceConfig`

The configuration for the voice to use.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% /details %}

{% /details %}

**languageCode**: `string`

Optional. The IETF [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code that the user configured the app to use. Used for speech recognition and synthesis. Valid values are: `de-DE`, `en-AU`, `en-GB`, `en-IN`, `en-US`, `es-US`, `fr-FR`, `hi-IN`, `pt-BR`, `ar-XA`, `es-ES`, `fr-CA`, `id-ID`, `it-IT`, `ja-JP`, `tr-TR`, `vi-VN`, `bn-IN`, `gu-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `ta-IN`, `te-IN`, `nl-NL`, `ko-KR`, `cmn-CN`, `pl-PL`, `ru-RU`, and `th-TH`.

{% /details %}

{% details %}

{% summary %}

**thinkingConfig**: `ThinkingConfig`

Optional. Config for thinking features. An error will be returned if this field is set for models that don't support thinking.

{% /summary %}

**includeThoughts**: `boolean`

Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.

**thinkingBudget**: `integer`

The number of thoughts tokens that the model should generate.

{% details %}

{% summary %}

**thinkingLevel**: `enum (string)`

Optional. Controls the maximum depth of the model's internal reasoning process before it produces a response. The default value is model-dependent. Refer to the [Thinking levels guide](/docs/thinking#thinking-levels) for more details. Recommended for Gemini 3 or later models. Use with earlier models results in an error.

{% /summary %}

Possible values:

- `THINKING_LEVEL_UNSPECIFIED`: Default value.
- `MINIMAL`: Little to no thinking.
- `LOW`: Low thinking level.
- `MEDIUM`: Medium thinking level.
- `HIGH`: High thinking level.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**imageConfig**: `ImageConfig`

Optional. Config for image generation. An error will be returned if this field is set for models that don't support these config options.

{% /summary %}

**aspectRatio**: `string`

Optional. The aspect ratio of the image to generate. Supported aspect ratios: `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, or `21:9`. If not specified, the model will choose a default aspect ratio based on any reference images provided.

**imageSize**: `string`

Optional. Specifies the size of generated images. Supported values are `512`, `1K`, `2K`, `4K`. If not specified, the model will use default value `1K`.

{% /details %}

{% details %}

{% summary %}

**mediaResolution**: `enum (string)`

Optional. If specified, the media resolution specified will be used.

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low (64 tokens).
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium (256 tokens).
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high (zoomed reframing with 256 tokens).

{% /details %}

**enableAffectiveDialog**: `boolean`

Optional. If enabled, the model will detect emotions and adapt its responses accordingly.

{% details %}

{% summary %}

**responseFormat**: `ResponseFormatConfig`

Optional. Configuration for the response output format. Allows specifying output configuration per modality (text, audio, image) in a flat structure.

{% /summary %}

{% details %}

{% summary %}

**text**: `TextResponseFormat`

Optional. Text output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the text output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `APPLICATION_JSON`: JSON output format.
- `TEXT_PLAIN`: Plain text output format.

{% /details %}

**schema**: `object`

Optional. The JSON schema that the output should conform to. Only applicable when mime_type is APPLICATION_JSON.

{% /details %}

{% details %}

{% summary %}

**audio**: `AudioResponseFormat`

Optional. Audio output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the audio output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `AUDIO_MP3`: MP3 audio format.
- `AUDIO_OGG_OPUS`: OGG Opus audio format.
- `AUDIO_L16`: Raw PCM (L16) audio format.
- `AUDIO_WAV`: WAV audio format.
- `AUDIO_ALAW`: A-law audio format.
- `AUDIO_MULAW`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the audio output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Audio data is returned inline in the response.
- `URI`: Audio data is returned as a URI.

{% /details %}

**sampleRate**: `integer`

Optional. Sample rate in Hz.

**bitRate**: `integer`

Optional. Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}

**image**: `ImageResponseFormat`

Optional. Image output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the image output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_JPEG`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the image output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Image data is returned inline in the response.
- `URI`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspectRatio**: `enum (string)`

Optional. The aspect ratio for the image output.

{% /summary %}

Possible values:

- `ASPECT_RATIO_UNSPECIFIED`: Default value. This value is unused.
- `ASPECT_RATIO_ONE_BY_ONE`: 1:1 aspect ratio.
- `ASPECT_RATIO_TWO_BY_THREE`: 2:3 aspect ratio.
- `ASPECT_RATIO_THREE_BY_TWO`: 3:2 aspect ratio.
- `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 aspect ratio.
- `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 aspect ratio.
- `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 aspect ratio.
- `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 aspect ratio.
- `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 aspect ratio.
- `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 aspect ratio.
- `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 aspect ratio.
- `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**imageSize**: `enum (string)`

Optional. The size of the image output.

{% /summary %}

Possible values:

- `IMAGE_SIZE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_SIZE_FIVE_TWELVE`: 512px image size.
- `IMAGE_SIZE_ONE_K`: 1K image size.
- `IMAGE_SIZE_TWO_K`: 2K image size.
- `IMAGE_SIZE_FOUR_K`: 4K image size.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**translationConfig**: `TranslationConfig`

Optional. Config for translation.

{% /summary %}

**targetLanguageCode**: {% mark %}required{% /mark %} `string`

The target language for translation. Supported values are BCP-47 language codes (e.g. "en", "es", "fr").

**echoTargetLanguage**: `boolean`

Optional. If true, the model will generate audio when the target language is spoken, essentially it will parrot the input. If false, we will not produce audio for the target language.

{% /details %}

{% details %}

{% summary %}

**audioTranscriptionConfig**: `AudioTranscriptionConfig`

Optional. Config for audio transcription (speech recognition).

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

**systemInstruction**: [`Content`](/api-reference/generate-content#Resource:Content)

Optional. The user provided system instructions for the model. Note: Only text should be used in parts and content in each part will be in a separate paragraph.

**tools**: `array (`[`Tool`](/api-reference/generate-content#Resource:Tool)`)`

Optional. A list of `Tools` the model may use to generate the next response. A [`Tool`](/api-reference/generate-content#Resource:Tool) is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.

{% details %}

{% summary %}

**realtimeInputConfig**: `RealtimeInputConfig`

Optional. Configures the handling of realtime input.

{% /summary %}

{% details %}

{% summary %}

**automaticActivityDetection**: `AutomaticActivityDetection`

Optional. If not set, automatic activity detection is enabled by default. If automatic voice detection is disabled, the client must send activity signals.

{% /summary %}

**disabled**: `boolean`

Optional. If enabled (the default), detected voice and text input count as activity. If disabled, the client must send activity signals.

{% details %}

{% summary %}

**startOfSpeechSensitivity**: `enum (string)`

Optional. Determines how likely speech is to be detected.

{% /summary %}

Possible values:

- `START_SENSITIVITY_UNSPECIFIED`: The default is START_SENSITIVITY_HIGH.
- `START_SENSITIVITY_HIGH`: Automatic detection will detect the start of speech more often.
- `START_SENSITIVITY_LOW`: Automatic detection will detect the start of speech less often.

{% /details %}

**prefixPaddingMs**: `integer`

Optional. The required duration of detected speech before start-of-speech is committed. The lower this value, the more sensitive the start-of-speech detection is and shorter speech can be recognized. However, this also increases the probability of false positives.

{% details %}

{% summary %}

**endOfSpeechSensitivity**: `enum (string)`

Optional. Determines how likely detected speech is ended.

{% /summary %}

Possible values:

- `END_SENSITIVITY_UNSPECIFIED`: The default is END_SENSITIVITY_HIGH.
- `END_SENSITIVITY_HIGH`: Automatic detection ends speech more often.
- `END_SENSITIVITY_LOW`: Automatic detection ends speech less often.

{% /details %}

**silenceDurationMs**: `integer`

Optional. The required duration of detected non-speech (e.g. silence) before end-of-speech is committed. The larger this value, the longer speech gaps can be without interrupting the user's activity but this will increase the model's latency.

{% /details %}

{% details %}

{% summary %}

**activityHandling**: `ActivityHandling`

Optional. Defines what effect activity has.

{% /summary %}

Possible values:

- `ACTIVITY_HANDLING_UNSPECIFIED`: If unspecified, the default behavior is `START_OF_ACTIVITY_INTERRUPTS`.
- `START_OF_ACTIVITY_INTERRUPTS`: If true, start of activity will interrupt the model's response (also called "barge in"). The model's current response will be cut-off in the moment of the interruption. This is the default behavior.
- `NO_INTERRUPTION`: The model's response will not be interrupted.

{% /details %}

{% details %}

{% summary %}

**turnCoverage**: `enum (string)`

Optional. Defines which input is included in the user's turn.

{% /summary %}

Possible values:

- `TURN_COVERAGE_UNSPECIFIED`: If unspecified, a default behavior is selected based on the model. E.g., for Gemini 2.5, the default is `TURN_INCLUDES_ONLY_ACTIVITY`, while for Gemini 3.1 and onwards, it's `TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`.
- `TURN_INCLUDES_ONLY_ACTIVITY`: Includes activity since the last turn, excluding inactivity (e.g. silence on the audio stream).
- `TURN_INCLUDES_ALL_INPUT`: Includes all realtime input since the last turn, including inactivity (e.g. silence on the audio stream).
- `TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`: Includes audio activity and all video since the last turn. With automatic activity detection, audio activity means speech and excludes silence.

{% /details %}

**interimTranscriptTimestampEnabled**: `boolean`

Optional. Configures interim transcript timestamps.

{% /details %}

{% details %}

{% summary %}

**sessionResumption**: `SessionResumptionConfig`

Optional. Configures session resumption mechanism. If included, the server will send `SessionResumptionUpdate` messages.

{% /summary %}

**handle**: `string`

The handle of a previous session. If not present then a new session is created. Session handles come from `SessionResumptionUpdate.token` values in previous connections.

{% /details %}

{% details %}

{% summary %}

**contextWindowCompression**: `ContextWindowCompressionConfig`

Optional. Configures a context window compression mechanism. If included, the server will automatically reduce the size of the context when it exceeds the configured length.

{% /summary %}

{% details %}

{% summary %}

**slidingWindow**: `SlidingWindow`

A sliding-window mechanism.

{% /summary %}

**targetTokens**: `string`

The target number of tokens to keep. The default value is trigger_tokens/2. Discarding parts of the context window causes a temporary latency increase so this value should be calibrated to avoid frequent compression operations.

{% /details %}

**triggerTokens**: `string`

The number of tokens (before running a turn) required to trigger a context window compression. This can be used to balance quality against latency as shorter context windows may result in faster model responses. However, any compression operation will cause a temporary latency increase, so they should not be triggered frequently. If not set, the default is 80% of the model's context window limit. This leaves 20% for the next user request/model response.

{% /details %}

{% details %}

{% summary %}

**inputAudioTranscription**: `AudioTranscriptionConfig`

Optional. If set, enables transcription of voice input. The transcription aligns with the input audio language, if configured.

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**outputAudioTranscription**: `AudioTranscriptionConfig`

Optional. If set, enables transcription of the model's audio output. The transcription aligns with the language code specified for the output audio, if configured.

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**proactivity**: `ProactivityConfig`

Optional. Configures the proactivity of the model. This allows the model to respond proactively to the input and to ignore irrelevant input.

{% /summary %}

**proactiveAudio**: `boolean`

Optional. If enabled, the model can reject responding to the last prompt. For example, this allows the model to ignore out of context speech or to stay silent if the user did not make a request, yet.

{% /details %}

{% details %}

{% summary %}

**historyConfig**: `HistoryConfig`

Optional. Configures the exchange of history between the client and the server.

{% /summary %}

**initialHistoryInClientContent**: `boolean`

Optional. If true, after sending `setup_complete`, the server will wait and at first process `client_content` messages until `turn_complete` is `true`. This initial history will not trigger a model call and may end with role `MODEL`. After `turn_complete` is `true`, the client can start the realtime conversation via `realtime_input`.

{% /details %}

**labels**: `object`

Optional. Labels with user-defined metadata for the request. Optional. Labels must follow standard unified Cloud label requirements:

- Label keys must start with a letter.
- Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes.
- International characters are allowed.

Usage:

- Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)

{% /details %}

{% hr /%}

**name**: `string`

Output only. Identifier. The token itself.

{% hr /%}

**expireTime**: `string`

Optional. Input only. Immutable. An optional time after which, when using the resulting token, messages in BidiGenerateContent sessions will be rejected. (Gemini may preemptively close the session after this time.) If not set then this defaults to 30 minutes in the future. If set, this value must be less than 20 hours in the future.

{% hr /%}

**newSessionExpireTime**: `string`

Optional. Input only. Immutable. The time after which new Live API sessions using the token resulting from this request will be rejected. If not set this defaults to 60 seconds in the future. If set, this value must be less than 20 hours in the future.

{% hr /%}

**uses**: `integer`

Optional. Input only. Immutable. The number of times the token can be used. If this value is zero then no limit is applied. Resuming a Live API session does not count as a use. If unspecified, the default is 1.

{% hr /%}

**fieldMask**: `string`

Optional. Input only. Immutable. If field_mask is empty, and `bidi_generate_content_setup` is not present, then the effective `BidiGenerateContentSetup` message is taken from the Live API connection. If field_mask is empty, and `bidi_generate_content_setup` _is_ present, then the effective `BidiGenerateContentSetup` message is taken entirely from `bidi_generate_content_setup` in this request. The setup message from the Live API connection is ignored. If field_mask is not empty, then the corresponding fields from `bidi_generate_content_setup` will overwrite the fields from the setup message in the Live API connection.

# Generating content
Source: https://aistudio.google.com/api-reference/generate-content/generate-content
Description: Generates a model response given an input `GenerateContentRequest`.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent`

Generates a model response given an input [`GenerateContentRequest`](/api-reference/generate-content/generate-content#request-body).
Refer to the [text generation
guide](/docs/text-generation) for detailed
usage information. Input capabilities differ between models, including
tuned models. Refer to the [model
guide](/docs/models) and [tuning
guide](/docs/model-tuning) for details.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The model ID, for example `gemini-2.5-flash`. Forms the resource name `models/{model}`.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% hr /%}

**contents**: {% mark %}required{% /mark %} `array (`[`Content`](/api-reference/generate-content/generate-content#Resource:Content)`)`

The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like [chat](/docs/text-generation#multi-turn-conversations), this is a repeated field that contains the conversation history and the latest request.

{% hr /%}

**systemInstruction**: [`Content`](/api-reference/generate-content/generate-content#Resource:Content)

Optional. Developer set [system instruction(s)](/docs/text-generation#system-instructions). Currently, text only.

{% hr /%}

**tools**: `array (`[`Tool`](/api-reference/generate-content/generate-content#Resource:Tool)`)`

Optional. A list of `Tools` the `Model` may use to generate the next response. A [`Tool`](/api-reference/generate-content/generate-content#Resource:Tool) is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the `Model`. Supported [`Tool`](/api-reference/generate-content/generate-content#Resource:Tool)s are `Function` and `code_execution`. Refer to the [Function calling](/docs/function-calling) and the [Code execution](/docs/code-execution) guides to learn more.

{% hr /%}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Tool configuration for any [`Tool`](/api-reference/generate-content/generate-content#Resource:Tool) specified in the request. Refer to the [Function calling guide](/docs/function-calling#function_calling_modes) for a usage example.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the [`Content`](/api-reference/generate-content/generate-content#Resource:Content) message. This allows clients to observe the server's tool interactions.

{% /details %}

{% hr /%}

**safetySettings**: `array (`[`SafetySetting`](/api-reference/generate-content/generate-content#Resource:SafetySetting)`)`

Optional. A list of unique [`SafetySetting`](/api-reference/generate-content/generate-content#Resource:SafetySetting) instances for blocking unsafe content. This will be enforced on the `GenerateContentRequest.contents` and `GenerateContentResponse.candidates`. There should not be more than one setting for each `SafetyCategory` type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each `SafetyCategory` specified in the safety_settings. If there is no [`SafetySetting`](/api-reference/generate-content/generate-content#Resource:SafetySetting) for a given `SafetyCategory` provided in the list, the API will use the default safety setting for that category. Harm categories HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_CIVIC_INTEGRITY, HARM_CATEGORY_JAILBREAK are supported. Refer to the [guide](/docs/safety-settings) for detailed information on available safety settings. Also refer to the [Safety guidance](/docs/safety-guidance) to learn how to incorporate safety considerations in your AI applications.

{% hr /%}

{% details %}

{% summary %}

**generationConfig**: `GenerationConfig`

Optional. Configuration options for model generation and outputs.

{% /summary %}

**candidateCount**: `integer`

Optional. Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)

**stopSequences**: `array (string)`

Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a `stop_sequence`. The stop sequence will not be included as part of the response.

**maxOutputTokens**: `integer`

Optional. The maximum number of tokens to include in a response candidate. Note: The default value varies by model, see the `Model.output_token_limit` attribute of the `Model` returned from the `getModel` function.

**temperature**: `number`

Optional. Controls the randomness of the output. Note: The default value varies by model, see the `Model.temperature` attribute of the `Model` returned from the `getModel` function. Values can range from [0.0, 2.0]. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topP**: `number`

Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topK**: `integer`

Optional. The maximum number of tokens to consider when sampling. Gemini models use Top-p (nucleus) sampling or a combination of Top-k and nucleus sampling. Top-k sampling considers the set of `top_k` most probable tokens. Models running with nucleus sampling don't allow top_k setting. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**seed**: `integer`

Optional. Seed used in decoding. If not set, the request uses a randomly generated seed.

**responseMimeType**: `string`

Optional. MIME type of the generated candidate text. Supported MIME types are: `text/plain`: (default) Text output. `application/json`: JSON response in the response candidates. `text/x.enum`: ENUM as a string response in the response candidates. Refer to the [docs](/docs/file-input-methods#text-file-types) for a list of all supported text MIME types.

**responseJsonSchema**: `object`

Optional. An internal detail. Use `responseJsonSchema` rather than this field.

**presencePenalty**: `number`

Optional. Presence penalty applied to the next token's logprobs if the token has already been seen in the response. This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequency_penalty for a penalty that increases with each use. A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary. A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.

**frequencyPenalty**: `number`

Optional. Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far. A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses. Caution: A _negative_ penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the max_output_tokens limit.

**responseLogprobs**: `boolean`

Optional. If true, export the logprobs results in response.

**logprobs**: `integer`

Optional. Only valid if response_logprobs=True. This sets the number of top logprobs, including the chosen candidate, to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].

**enableEnhancedCivicAnswers**: `boolean`

Optional. Enables enhanced civic answers. It may not be available for all models.

{% details %}

{% summary %}

**responseModalities**: `array (enum (string))`

Optional. The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response. A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned. An empty list is equivalent to requesting only text.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Default value.
- `TEXT`: Indicates the model should return text.
- `IMAGE`: Indicates the model should return images.
- `AUDIO`: Indicates the model should return audio.

{% /details %}

{% details %}

{% summary %}

**speechConfig**: `SpeechConfig`

Optional. The speech generation config.

{% /summary %}

{% details %}

{% summary %}

**voiceConfig**: `VoiceConfig`

The configuration in case of single-voice output.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% details %}

{% summary %}

**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig`

Optional. The configuration for the multi-speaker setup. It is mutually exclusive with the voice_config field.

{% /summary %}

{% details %}

{% summary %}

**speakerVoiceConfigs**: {% mark %}required{% /mark %} `array (SpeakerVoiceConfig)`

All the enabled speaker voices.

{% /summary %}

**speaker**: {% mark %}required{% /mark %} `string`

The name of the speaker to use. Should be the same as in the prompt.

{% details %}

{% summary %}

**voiceConfig**: {% mark %}required{% /mark %} `VoiceConfig`

The configuration for the voice to use.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% /details %}

{% /details %}

**languageCode**: `string`

Optional. The IETF [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code that the user configured the app to use. Used for speech recognition and synthesis. Valid values are: `de-DE`, `en-AU`, `en-GB`, `en-IN`, `en-US`, `es-US`, `fr-FR`, `hi-IN`, `pt-BR`, `ar-XA`, `es-ES`, `fr-CA`, `id-ID`, `it-IT`, `ja-JP`, `tr-TR`, `vi-VN`, `bn-IN`, `gu-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `ta-IN`, `te-IN`, `nl-NL`, `ko-KR`, `cmn-CN`, `pl-PL`, `ru-RU`, and `th-TH`.

{% /details %}

{% details %}

{% summary %}

**thinkingConfig**: `ThinkingConfig`

Optional. Config for thinking features. An error will be returned if this field is set for models that don't support thinking.

{% /summary %}

**includeThoughts**: `boolean`

Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.

**thinkingBudget**: `integer`

The number of thoughts tokens that the model should generate.

{% details %}

{% summary %}

**thinkingLevel**: `enum (string)`

Optional. Controls the maximum depth of the model's internal reasoning process before it produces a response. The default value is model-dependent. Refer to the [Thinking levels guide](/docs/thinking#thinking-levels) for more details. Recommended for Gemini 3 or later models. Use with earlier models results in an error.

{% /summary %}

Possible values:

- `THINKING_LEVEL_UNSPECIFIED`: Default value.
- `MINIMAL`: Little to no thinking.
- `LOW`: Low thinking level.
- `MEDIUM`: Medium thinking level.
- `HIGH`: High thinking level.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**imageConfig**: `ImageConfig`

Optional. Config for image generation. An error will be returned if this field is set for models that don't support these config options.

{% /summary %}

**aspectRatio**: `string`

Optional. The aspect ratio of the image to generate. Supported aspect ratios: `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, or `21:9`. If not specified, the model will choose a default aspect ratio based on any reference images provided.

**imageSize**: `string`

Optional. Specifies the size of generated images. Supported values are `512`, `1K`, `2K`, `4K`. If not specified, the model will use default value `1K`.

{% /details %}

{% details %}

{% summary %}

**mediaResolution**: `enum (string)`

Optional. If specified, the media resolution specified will be used.

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low (64 tokens).
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium (256 tokens).
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high (zoomed reframing with 256 tokens).

{% /details %}

**enableAffectiveDialog**: `boolean`

Optional. If enabled, the model will detect emotions and adapt its responses accordingly.

{% details %}

{% summary %}

**responseFormat**: `ResponseFormatConfig`

Optional. Configuration for the response output format. Allows specifying output configuration per modality (text, audio, image) in a flat structure.

{% /summary %}

{% details %}

{% summary %}

**text**: `TextResponseFormat`

Optional. Text output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the text output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `APPLICATION_JSON`: JSON output format.
- `TEXT_PLAIN`: Plain text output format.

{% /details %}

**schema**: `object`

Optional. The JSON schema that the output should conform to. Only applicable when mime_type is APPLICATION_JSON.

{% /details %}

{% details %}

{% summary %}

**audio**: `AudioResponseFormat`

Optional. Audio output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the audio output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `AUDIO_MP3`: MP3 audio format.
- `AUDIO_OGG_OPUS`: OGG Opus audio format.
- `AUDIO_L16`: Raw PCM (L16) audio format.
- `AUDIO_WAV`: WAV audio format.
- `AUDIO_ALAW`: A-law audio format.
- `AUDIO_MULAW`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the audio output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Audio data is returned inline in the response.
- `URI`: Audio data is returned as a URI.

{% /details %}

**sampleRate**: `integer`

Optional. Sample rate in Hz.

**bitRate**: `integer`

Optional. Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}

**image**: `ImageResponseFormat`

Optional. Image output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the image output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_JPEG`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the image output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Image data is returned inline in the response.
- `URI`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspectRatio**: `enum (string)`

Optional. The aspect ratio for the image output.

{% /summary %}

Possible values:

- `ASPECT_RATIO_UNSPECIFIED`: Default value. This value is unused.
- `ASPECT_RATIO_ONE_BY_ONE`: 1:1 aspect ratio.
- `ASPECT_RATIO_TWO_BY_THREE`: 2:3 aspect ratio.
- `ASPECT_RATIO_THREE_BY_TWO`: 3:2 aspect ratio.
- `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 aspect ratio.
- `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 aspect ratio.
- `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 aspect ratio.
- `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 aspect ratio.
- `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 aspect ratio.
- `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 aspect ratio.
- `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 aspect ratio.
- `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**imageSize**: `enum (string)`

Optional. The size of the image output.

{% /summary %}

Possible values:

- `IMAGE_SIZE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_SIZE_FIVE_TWELVE`: 512px image size.
- `IMAGE_SIZE_ONE_K`: 1K image size.
- `IMAGE_SIZE_TWO_K`: 2K image size.
- `IMAGE_SIZE_FOUR_K`: 4K image size.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**translationConfig**: `TranslationConfig`

Optional. Config for translation.

{% /summary %}

**targetLanguageCode**: {% mark %}required{% /mark %} `string`

The target language for translation. Supported values are BCP-47 language codes (e.g. "en", "es", "fr").

**echoTargetLanguage**: `boolean`

Optional. If true, the model will generate audio when the target language is spoken, essentially it will parrot the input. If false, we will not produce audio for the target language.

{% /details %}

{% details %}

{% summary %}

**audioTranscriptionConfig**: `AudioTranscriptionConfig`

Optional. Config for audio transcription (speech recognition).

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**cachedContent**: `string`

Optional. The name of the content [cached](/docs/caching) to use as context to serve the prediction. Format: `cachedContents/{cachedContent}`

{% hr /%}

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/generate-content/generate-content#Resource:ServiceTier)

Optional. The service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

{% hr /%}

**store**: `boolean`

Optional. Configures the logging behavior for a given request. If set, it takes precedence over the project-level logging config.

{% hr /%}

**continuationToken**: `string`

Optional. An opaque continuation token used to resume generation from a previous `GenerateContent` or `StreamGenerateContent` response that stopped with `finish_reason` set to `CONTINUATION`. Note that `contents` is mandatory and must identically replicate the prompt and conversation history from the initial request when continuation token is provided in a request.

{% hr /%}

**labels**: `object`

Optional. Labels with user-defined metadata for the request. Optional. Labels must follow standard unified Cloud label requirements:

- Label keys must start with a letter.
- Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes.
- International characters are allowed.

Usage:

- Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="Text" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[{"text": "Write a story about a magic backpack."}]
        }]
       }' 2> /dev/null
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Write a story about a magic backpack.",
)
print(response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: 'Write a story about a magic backpack.',
});
console.log(response.text);
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "Write a story about a magic backpack.", null);

System.out.println(response.text());
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
contents := []*genai.Content{
    genai.NewContentFromText("Write a story about a magic backpack.", genai.RoleUser),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Image" %}

{% tabs %}

{% tab label="REST" %}

```sh
# Use a temporary file to hold the base64 encoded image data
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"

# Use a temporary file to hold the JSON payload
TEMP_JSON=$(mktemp)
trap 'rm -f "$TEMP_JSON"' EXIT

cat > "$TEMP_JSON" << EOF
{
  "contents": [{
    "parts":[
      {"text": "Tell me about this instrument"},
      {
        "inline_data": {
          "mime_type":"image/jpeg",
          "data": "$(cat "$TEMP_B64")"
        }
      }
    ]
  }]
}
EOF

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d "@$TEMP_JSON" 2> /dev/null
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
import PIL.Image

client = genai.Client()
organ = PIL.Image.open(media / "organ.jpg")
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=["Tell me about this instrument", organ],
)
print(response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const organ = await ai.files.upload({
  file: path.join(media, 'organ.jpg'),
});

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: [
    createUserContent([
      'Tell me about this instrument',
      createPartFromUri(organ.uri, organ.mimeType)
    ]),
  ],
});
console.log(response.text);
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

String path = media_path + "organ.jpg";
byte[] imageData = Files.readAllBytes(Paths.get(path));

Content content =
    Content.fromParts(
        Part.fromText("Tell me about this instrument."),
        Part.fromBytes(imageData, "image/jpeg"));

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", content, null);

System.out.println(response.text());
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "organ.jpg"),
    &genai.UploadFileConfig{
        MIMEType: "image/jpeg",
    },
)
if err != nil {
    log.Fatal(err)
}
parts := []*genai.Part{
    genai.NewPartFromText("Tell me about this instrument"),
    genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Audio" %}

{% tabs %}

{% tab label="REST" %}

```sh
# Use File API to upload audio data to API request.
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Please describe this file."},
          {"file_data":{"mime_type": "audio/mpeg", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
sample_audio = client.files.upload(file=media / "sample.mp3")
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this audio file.", sample_audio],
)
print(response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const audio = await ai.files.upload({
  file: path.join(media, 'sample.mp3'),
});

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: [
    createUserContent([
      'Give me a summary of this audio file.',
      createPartFromUri(audio.uri, audio.mimeType),
    ]),
  ],
});
console.log(response.text);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "sample.mp3"),
    &genai.UploadFileConfig{
        MIMEType: "audio/mpeg",
    },
)
if err != nil {
    log.Fatal(err)
}

parts := []*genai.Part{
    genai.NewPartFromText("Give me a summary of this audio file."),
    genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Video" %}

{% tabs %}

{% tab label="REST" %}

```sh
# Use File API to upload audio data to API request.
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D "${tmp_header_file}" \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

state=$(jq ".file.state" file_info.json)
echo state=$state

name=$(jq ".file.name" file_info.json)
echo name=$name

while [[ "($state)" = *"PROCESSING"* ]];
do
  echo "Processing video..."
  sleep 5
  # Get the file of interest to check state
  curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
  state=$(jq ".file.state" file_info.json)
done

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."},
          {"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
import time

client = genai.Client()
# Video clip (CC BY 3.0) from https://peach.blender.org/download/
myfile = client.files.upload(file=media / "Big_Buck_Bunny.mp4")
print(f"{myfile=}")

# Poll until the video file is completely processed (state becomes ACTIVE).
while not myfile.state or myfile.state.name != "ACTIVE":
  print("Processing video...")
  print("File state:", myfile.state)
  time.sleep(5)
  myfile = client.files.get(name=myfile.name)

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=[myfile, "Describe this video clip"]
)
print(f"{response.text=}")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

let video = await ai.files.upload({
  file: path.join(media, 'Big_Buck_Bunny.mp4'),
});

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!video.state || video.state.toString() !== 'ACTIVE') {
  console.log('Processing video...');
  console.log('File state: ', video.state);
  await sleep(5000);
  video = await ai.files.get({name: video.name});
}

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: [
    createUserContent([
      'Describe this video clip',
      createPartFromUri(video.uri, video.mimeType),
    ]),
  ],
});
console.log(response.text);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "Big_Buck_Bunny.mp4"),
    &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    },
)
if err != nil {
    log.Fatal(err)
}

// Poll until the video file is completely processed (state becomes ACTIVE).
for file.State == genai.FileStateUnspecified || file.State != genai.FileStateActive {
    fmt.Println("Processing video...")
    fmt.Println("File state:", file.State)
    time.Sleep(5 * time.Second)

    file, err = client.Files.Get(ctx, file.Name, nil)
    if err != nil {
        log.Fatal(err)
    }
}

parts := []*genai.Part{
    genai.NewPartFromText("Describe this video clip"),
    genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Pdf" %}

{% tabs %}

{% tab label="REST" %}

```sh
MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
NUM_BYTES=$(wc -c < "${PDF_PATH}")
DISPLAY_NAME=TEXT


echo $MIME_TYPE
tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${PDF_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Can you add a few more lines to this poem?"},
          {"file_data":{"mime_type": "application/pdf", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
sample_pdf = client.files.upload(file=media / "test.pdf")
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this document:", sample_pdf],
)
print(f"{response.text=}")
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "test.pdf"),
    &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    },
)
if err != nil {
    log.Fatal(err)
}

parts := []*genai.Part{
    genai.NewPartFromText("Give me a summary of this document:"),
    genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Chat" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {"role":"user",
         "parts":[{
           "text": "Hello"}]},
        {"role": "model",
         "parts":[{
           "text": "Great to meet you. What would you like to know?"}]},
        {"role":"user",
         "parts":[{
           "text": "I have two dogs in my house. How many paws are in my house?"}]},
      ]
    }' 2> /dev/null | grep "text"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
# Pass initial history using the "history" argument
chat = client.chats.create(
    model="gemini-3.8-flash",
    history=[
        types.Content(role="user", parts=[types.Part(text="Hello")]),
        types.Content(
            role="model",
            parts=[
                types.Part(
                    text="Great to meet you. What would you like to know?"
                )
            ],
        ),
    ],
)
response = chat.send_message(message="I have 2 dogs in my house.")
print(response.text)
response = chat.send_message(message="How many paws are in my house?")
print(response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const chat = ai.chats.create({
  model: 'gemini-3.8-flash',
  history: [
    {
      role: 'user',
      parts: [{text: 'Hello'}],
    },
    {
      role: 'model',
      parts: [{text: 'Great to meet you. What would you like to know?'}],
    },
  ],
});

const response1 = await chat.sendMessage({
  message: 'I have 2 dogs in my house.',
});
console.log('Chat response 1:', response1.text);

const response2 = await chat.sendMessage({
  message: 'How many paws are in my house?',
});
console.log('Chat response 2:', response2.text);
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

Content userContent = Content.fromParts(Part.fromText("Hello"));
Content modelContent =
    Content.builder()
        .role("model")
        .parts(
            Collections.singletonList(
                Part.fromText("Great to meet you. What would you like to know?")))
        .build();

Chat chat =
    client.chats.create(
        "gemini-3.8-flash",
        GenerateContentConfig.builder()
            .systemInstruction(userContent)
            .systemInstruction(modelContent)
            .build());

GenerateContentResponse response1 = chat.sendMessage("I have 2 dogs in my house.");
System.out.println(response1.text());

GenerateContentResponse response2 = chat.sendMessage("How many paws are in my house?");
System.out.println(response2.text());
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

// Pass initial history using the History field.
history := []*genai.Content{
    genai.NewContentFromText("Hello", genai.RoleUser),
    genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel),
}

chat, err := client.Chats.Create(ctx, "gemini-3.8-flash", nil, history)
if err != nil {
    log.Fatal(err)
}

firstResp, err := chat.SendMessage(ctx, genai.Part{Text: "I have 2 dogs in my house."})
if err != nil {
    log.Fatal(err)
}
fmt.Println(firstResp.Text())

secondResp, err := chat.SendMessage(ctx, genai.Part{Text: "How many paws are in my house?"})
if err != nil {
    log.Fatal(err)
}
fmt.Println(secondResp.Text())
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Json Mode" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "contents": [{
      "parts":[
        {"text": "List 5 popular cookie recipes"}
        ]
    }],
    "generationConfig": {
        "response_mime_type": "application/json",
        "response_schema": {
          "type": "ARRAY",
          "items": {
            "type": "OBJECT",
            "properties": {
              "recipe_name": {"type":"STRING"},
            }
          }
        }
    }
}' 2> /dev/null | head
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types
from typing_extensions import TypedDict

class Recipe(TypedDict):
  recipe_name: str
  ingredients: list[str]

client = genai.Client()
result = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="List a few popular cookie recipes.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json", response_schema=list[Recipe]
    ),
)
print(result)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: 'List a few popular cookie recipes.',
  config: {
    responseMimeType: 'application/json',
    responseSchema: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          recipeName: {type: 'string'},
          ingredients: {type: 'array', items: {type: 'string'}},
        },
        required: ['recipeName', 'ingredients'],
      },
    },
  },
});
console.log(response.text);
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

Schema recipeSchema =
    Schema.builder()
        .type(Array.class.getSimpleName())
        .items(
            Schema.builder()
                .type(Object.class.getSimpleName())
                .properties(
                    Map.of(
                        "recipe_name",
                        Schema.builder().type(String.class.getSimpleName()).build(),
                        "ingredients",
                        Schema.builder()
                            .type(Array.class.getSimpleName())
                            .items(Schema.builder().type(String.class.getSimpleName()).build())
                            .build()))
                .required(List.of("recipe_name", "ingredients"))
                .build())
        .build();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .responseMimeType("application/json")
        .responseSchema(recipeSchema)
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "List a few popular cookie recipes.", config);

System.out.println(response.text());
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

schema := &genai.Schema{
    Type: genai.TypeArray,
    Items: &genai.Schema{
        Type: genai.TypeObject,
        Properties: map[string]*genai.Schema{
            "recipe_name": {Type: genai.TypeString},
            "ingredients": {
                Type:  genai.TypeArray,
                Items: &genai.Schema{Type: genai.TypeString},
            },
        },
        Required: []string{"recipe_name"},
    },
}

config := &genai.GenerateContentConfig{
    ResponseMIMEType: "application/json",
    ResponseSchema:   schema,
}

response, err := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    genai.Text("List a few popular cookie recipes."),
    config,
)
if err != nil {
    log.Fatal(err)
}
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Function Calling" %}

{% tabs %}

{% tab label="REST" %}

```sh
cat > tools.json << EOF
{
  "function_declarations": [
    {
      "name": "enable_lights",
      "description": "Turn on the lighting system."
    },
    {
      "name": "set_light_color",
      "description": "Set the light color. Lights must be enabled for this to work.",
      "parameters": {
        "type": "object",
        "properties": {
          "rgb_hex": {
            "type": "string",
            "description": "The light color as a 6-digit hex string, e.g. ff0000 for red."
          }
        },
        "required": [
          "rgb_hex"
        ]
      }
    },
    {
      "name": "stop_lights",
      "description": "Turn off the lighting system."
    }
  ]
}
EOF

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @<(echo '
  {
    "system_instruction": {
      "parts": {
        "text": "You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks."
      }
    },
    "tools": ['$(cat tools.json)'],

    "tool_config": {
      "function_calling_config": {"mode": "auto"}
    },

    "contents": {
      "role": "user",
      "parts": {
        "text": "Turn on the lights please."
      }
    }
  }
') 2>/dev/null |sed -n '/"content"/,/"finishReason"/p'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()

def add(a: float, b: float) -> float:
  """returns a + b."""
  return a + b

def subtract(a: float, b: float) -> float:
  """returns a - b."""
  return a - b

def multiply(a: float, b: float) -> float:
  """returns a * b."""
  return a * b

def divide(a: float, b: float) -> float:
  """returns a / b."""
  return a / b

# Create a chat session; function calling (via tools) is enabled in the config.
chat = client.chats.create(
    model="gemini-3.8-flash",
    config=types.GenerateContentConfig(
        tools=[add, subtract, multiply, divide]
    ),
)
response = chat.send_message(
    message=(
        "I have 57 cats, each owns 44 mittens, how many mittens is that in"
        " total?"
    )
)
print(response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

/**
 * The add function returns the sum of two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {
  return a + b;
}

/**
 * The subtract function returns the difference (a - b).
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function subtract(a, b) {
  return a - b;
}

/**
 * The multiply function returns the product of two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function multiply(a, b) {
  return a * b;
}

/**
 * The divide function returns the quotient of a divided by b.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function divide(a, b) {
  return a / b;
}

const addDeclaration = {
  name: 'addNumbers',
  parameters: {
    type: 'object',
    description: 'Return the result of adding two numbers.',
    properties: {
      firstParam: {
        type: 'number',
        description:
            'The first parameter which can be an integer or a floating point number.',
      },
      secondParam: {
        type: 'number',
        description:
            'The second parameter which can be an integer or a floating point number.',
      },
    },
    required: ['firstParam', 'secondParam'],
  },
};

const subtractDeclaration = {
  name: 'subtractNumbers',
  parameters: {
    type: 'object',
    description:
        'Return the result of subtracting the second number from the first.',
    properties: {
      firstParam: {
        type: 'number',
        description: 'The first parameter.',
      },
      secondParam: {
        type: 'number',
        description: 'The second parameter.',
      },
    },
    required: ['firstParam', 'secondParam'],
  },
};

const multiplyDeclaration = {
  name: 'multiplyNumbers',
  parameters: {
    type: 'object',
    description: 'Return the product of two numbers.',
    properties: {
      firstParam: {
        type: 'number',
        description: 'The first parameter.',
      },
      secondParam: {
        type: 'number',
        description: 'The second parameter.',
      },
    },
    required: ['firstParam', 'secondParam'],
  },
};

const divideDeclaration = {
  name: 'divideNumbers',
  parameters: {
    type: 'object',
    description:
        'Return the quotient of dividing the first number by the second.',
    properties: {
      firstParam: {
        type: 'number',
        description: 'The first parameter.',
      },
      secondParam: {
        type: 'number',
        description: 'The second parameter.',
      },
    },
    required: ['firstParam', 'secondParam'],
  },
};

// Step 1: Call generateContent with function calling enabled.
const generateContentResponse = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents:
      'I have 57 cats, each owns 44 mittens, how many mittens is that in total?',
  config: {
    toolConfig: {
      functionCallingConfig: {
        mode: FunctionCallingConfigMode.ANY,
      },
    },
    tools: [
      {
        functionDeclarations: [
          addDeclaration,
          subtractDeclaration,
          multiplyDeclaration,
          divideDeclaration,
        ],
      },
    ],
  },
});

// Step 2: Extract the function call.(
// Assuming the response contains a 'functionCalls' array.
const functionCall = generateContentResponse.functionCalls &&
    generateContentResponse.functionCalls[0];
console.log(functionCall);

// Parse the arguments.
const args = functionCall.args;
// Expected args format: { firstParam: number, secondParam: number }

// Step 3: Invoke the actual function based on the function name.
const functionMapping = {
  addNumbers: add,
  subtractNumbers: subtract,
  multiplyNumbers: multiply,
  divideNumbers: divide,
};
const func = functionMapping[functionCall.name];
if (!func) {
  console.error('Unimplemented error:', functionCall.name);
  return generateContentResponse;
}
const resultValue = func(args.firstParam, args.secondParam);
console.log('Function result:', resultValue);

// Step 4: Use the chat API to send the result as the final answer.
const chat = ai.chats.create({model: 'gemini-3.8-flash'});
const chatResponse = await chat.sendMessage({
  message: 'The final result is ' + resultValue,
});
console.log(chatResponse.text);
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

FunctionDeclaration addFunction =
    FunctionDeclaration.builder()
        .name("addNumbers")
        .parameters(
            Schema.builder()
                .type("object")
                .properties(
                    Map.of(
                        "firstParam",
                            Schema.builder().type("number").description("First number").build(),
                        "secondParam",
                            Schema.builder()
                                .type("number")
                                .description("Second number")
                                .build()))
                .required(Arrays.asList("firstParam", "secondParam"))
                .build())
        .build();

FunctionDeclaration subtractFunction =
    FunctionDeclaration.builder()
        .name("subtractNumbers")
        .parameters(
            Schema.builder()
                .type("object")
                .properties(
                    Map.of(
                        "firstParam",
                            Schema.builder().type("number").description("First number").build(),
                        "secondParam",
                            Schema.builder()
                                .type("number")
                                .description("Second number")
                                .build()))
                .required(Arrays.asList("firstParam", "secondParam"))
                .build())
        .build();

FunctionDeclaration multiplyFunction =
    FunctionDeclaration.builder()
        .name("multiplyNumbers")
        .parameters(
            Schema.builder()
                .type("object")
                .properties(
                    Map.of(
                        "firstParam",
                            Schema.builder().type("number").description("First number").build(),
                        "secondParam",
                            Schema.builder()
                                .type("number")
                                .description("Second number")
                                .build()))
                .required(Arrays.asList("firstParam", "secondParam"))
                .build())
        .build();

FunctionDeclaration divideFunction =
    FunctionDeclaration.builder()
        .name("divideNumbers")
        .parameters(
            Schema.builder()
                .type("object")
                .properties(
                    Map.of(
                        "firstParam",
                            Schema.builder().type("number").description("First number").build(),
                        "secondParam",
                            Schema.builder()
                                .type("number")
                                .description("Second number")
                                .build()))
                .required(Arrays.asList("firstParam", "secondParam"))
                .build())
        .build();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .toolConfig(
            ToolConfig.builder()
                .functionCallingConfig(FunctionCallingConfig.builder().mode("ANY").build())
                .build())
        .tools(
            Collections.singletonList(
                Tool.builder()
                    .functionDeclarations(
                        Arrays.asList(
                            addFunction, subtractFunction, divideFunction, multiplyFunction))
                    .build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        "I have 57 cats, each owns 44 mittens, how many mittens is that in total?",
        config);

if (response.functionCalls() == null || response.functionCalls().isEmpty()) {
  System.err.println("No function call received");
  return null;
}

var functionCall = response.functionCalls().getFirst();
String functionName = functionCall.name().get();
var arguments = functionCall.args();

Map<String, BiFunction<Double, Double, Double>> functionMapping = new HashMap<>();
functionMapping.put("addNumbers", (a, b) -> a + b);
functionMapping.put("subtractNumbers", (a, b) -> a - b);
functionMapping.put("multiplyNumbers", (a, b) -> a * b);
functionMapping.put("divideNumbers", (a, b) -> b != 0 ? a / b : Double.NaN);

BiFunction<Double, Double, Double> function = functionMapping.get(functionName);

Number firstParam = (Number) arguments.get().get("firstParam");
Number secondParam = (Number) arguments.get().get("secondParam");
Double result = function.apply(firstParam.doubleValue(), secondParam.doubleValue());

System.out.println(result);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
modelName := "gemini-3.8-flash"

// Create the function declarations for arithmetic operations.
addDeclaration := createArithmeticToolDeclaration("addNumbers", "Return the result of adding two numbers.")
subtractDeclaration := createArithmeticToolDeclaration("subtractNumbers", "Return the result of subtracting the second number from the first.")
multiplyDeclaration := createArithmeticToolDeclaration("multiplyNumbers", "Return the product of two numbers.")
divideDeclaration := createArithmeticToolDeclaration("divideNumbers", "Return the quotient of dividing the first number by the second.")

// Group the function declarations as a tool.
tools := []*genai.Tool{
    {
        FunctionDeclarations: []*genai.FunctionDeclaration{
            addDeclaration,
            subtractDeclaration,
            multiplyDeclaration,
            divideDeclaration,
        },
    },
}

// Create the content prompt.
contents := []*genai.Content{
    genai.NewContentFromText(
        "I have 57 cats, each owns 44 mittens, how many mittens is that in total?", genai.RoleUser,
    ),
}

// Set up the generate content configuration with function calling enabled.
config := &genai.GenerateContentConfig{
    Tools: tools,
    ToolConfig: &genai.ToolConfig{
        FunctionCallingConfig: &genai.FunctionCallingConfig{
            // The mode equivalent to FunctionCallingConfigMode.ANY in JS.
            Mode: genai.FunctionCallingConfigModeAny,
        },
    },
}

genContentResp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
if err != nil {
    log.Fatal(err)
}

// Assume the response includes a list of function calls.
if len(genContentResp.FunctionCalls()) == 0 {
    log.Println("No function call returned from the AI.")
    return nil
}
functionCall := genContentResp.FunctionCalls()[0]
log.Printf("Function call: %+v\n", functionCall)

// Marshal the Args map into JSON bytes.
argsMap, err := json.Marshal(functionCall.Args)
if err != nil {
    log.Fatal(err)
}

// Unmarshal the JSON bytes into the ArithmeticArgs struct.
var args ArithmeticArgs
if err := json.Unmarshal(argsMap, &args); err != nil {
    log.Fatal(err)
}

// Map the function name to the actual arithmetic function.
var result float64
switch functionCall.Name {
case "addNumbers":
    result = add(args.FirstParam, args.SecondParam)
case "subtractNumbers":
    result = subtract(args.FirstParam, args.SecondParam)
case "multiplyNumbers":
    result = multiply(args.FirstParam, args.SecondParam)
case "divideNumbers":
    result = divide(args.FirstParam, args.SecondParam)
default:
    return fmt.Errorf("unimplemented function: %s", functionCall.Name)
}
log.Printf("Function result: %v\n", result)

// Prepare the final result message as content.
resultContents := []*genai.Content{
    genai.NewContentFromText("The final result is "+fmt.Sprintf("%v", result), genai.RoleUser),
}

// Use GenerateContent to send the final result.
finalResponse, err := client.Models.GenerateContent(ctx, modelName, resultContents, &genai.GenerateContentConfig{})
if err != nil {
    log.Fatal(err)
}

printResponse(finalResponse)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Generation Config" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "contents": [{
            "parts":[
                {"text": "Explain how AI works"}
            ]
        }],
        "generationConfig": {
            "stopSequences": [
                "Title"
            ],
            "temperature": 1.0,
            "maxOutputTokens": 800,
            "topP": 0.8,
            "topK": 10
        }
    }'  2> /dev/null | grep "text"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Tell me a story about a magic backpack.",
    config=types.GenerateContentConfig(
        candidate_count=1,
        stop_sequences=["x"],
        max_output_tokens=20,
        temperature=1.0,
    ),
)
print(response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: 'Tell me a story about a magic backpack.',
  config: {
    candidateCount: 1,
    stopSequences: ['x'],
    maxOutputTokens: 20,
    temperature: 1.0,
  },
});

console.log(response.text);
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .candidateCount(1)
        .stopSequences(List.of("x"))
        .maxOutputTokens(20)
        .temperature(1.0F)
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "Tell me a story about a magic backpack.", config);

System.out.println(response.text());
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

// Create local variables for parameters.
candidateCount := int32(1)
maxOutputTokens := int32(20)
temperature := float32(1.0)

response, err := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    genai.Text("Tell me a story about a magic backpack."),
    &genai.GenerateContentConfig{
        CandidateCount:  candidateCount,
        StopSequences:   []string{"x"},
        MaxOutputTokens: maxOutputTokens,
        Temperature:     &temperature,
    },
)
if err != nil {
    log.Fatal(err)
}

printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Safety Settings" %}

{% tabs %}

{% tab label="REST" %}

```sh
echo '{
    "safetySettings": [
        {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH"},
        {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}
    ],
    "contents": [{
        "parts":[{
            "text": "'I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them.'"}]}]}' > request.json

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d @request.json 2> /dev/null
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
unsafe_prompt = (
    "I support Martians Soccer Club and I think Jupiterians Football Club"
    " sucks! Write a ironic phrase about them including expletives."
)
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=unsafe_prompt,
    config=types.GenerateContentConfig(
        safety_settings=[
            types.SafetySetting(
                category="HARM_CATEGORY_HATE_SPEECH",
                threshold="BLOCK_MEDIUM_AND_ABOVE",
            ),
            types.SafetySetting(
                category="HARM_CATEGORY_HARASSMENT",
                threshold="BLOCK_ONLY_HIGH",
            ),
        ]
    ),
)
try:
  print(response.text)
except Exception:
  print("No information generated by the model.")

print(response.candidates[0].safety_ratings)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const unsafePrompt =
    'I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them including expletives.';

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: unsafePrompt,
  config: {
    safetySettings: [
      {
        category: 'HARM_CATEGORY_HATE_SPEECH',
        threshold: 'BLOCK_MEDIUM_AND_ABOVE',
      },
      {
        category: 'HARM_CATEGORY_HARASSMENT',
        threshold: 'BLOCK_ONLY_HIGH',
      },
    ],
  },
});

try {
  console.log('Generated text:', response.text);
} catch (error) {
  console.log('No information generated by the model.');
}
console.log('Safety ratings:', response.candidates[0].safetyRatings);
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

String unsafePrompt =
    """
     I support Martians Soccer Club and I think Jupiterians Football Club sucks!
     Write a ironic phrase about them including expletives.
    """;

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .safetySettings(
            Arrays.asList(
                SafetySetting.builder()
                    .category("HARM_CATEGORY_HATE_SPEECH")
                    .threshold("BLOCK_MEDIUM_AND_ABOVE")
                    .build(),
                SafetySetting.builder()
                    .category("HARM_CATEGORY_HARASSMENT")
                    .threshold("BLOCK_ONLY_HIGH")
                    .build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", unsafePrompt, config);

try {
  System.out.println(response.text());
} catch (Exception e) {
  System.out.println("No information generated by the model");
}

System.out.println(response.candidates().get().getFirst().safetyRatings());
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

unsafePrompt := "I support Martians Soccer Club and I think Jupiterians Football Club sucks! " +
    "Write a ironic phrase about them including expletives."

config := &genai.GenerateContentConfig{
    SafetySettings: []*genai.SafetySetting{
        {
            Category:  "HARM_CATEGORY_HATE_SPEECH",
            Threshold: "BLOCK_MEDIUM_AND_ABOVE",
        },
        {
            Category:  "HARM_CATEGORY_HARASSMENT",
            Threshold: "BLOCK_ONLY_HIGH",
        },
    },
}
contents := []*genai.Content{
    genai.NewContentFromText(unsafePrompt, genai.RoleUser),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, config)
if err != nil {
    log.Fatal(err)
}

// Print the generated text.
text := response.Text()
fmt.Println("Generated text:", text)

// Print the and safety ratings from the first candidate.
if len(response.Candidates) > 0 {
    fmt.Println("Finish reason:", response.Candidates[0].FinishReason)
    safetyRatings, err := json.MarshalIndent(response.Candidates[0].SafetyRatings, "", "  ")
    if err != nil {
        return err
    }
    fmt.Println("Safety ratings:", string(safetyRatings))
} else {
    fmt.Println("No candidate returned.")
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="System Instruction" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "system_instruction": {
    "parts":
      { "text": "You are a cat. Your name is Neko."}},
    "contents": {
      "parts": {
        "text": "Hello there"}}}'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Good morning! How are you?",
    config=types.GenerateContentConfig(
        system_instruction="You are a cat. Your name is Neko."
    ),
)
print(response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: 'Good morning! How are you?',
  config: {
    systemInstruction: 'You are a cat. Your name is Neko.',
  },
});
console.log(response.text);
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

Part textPart = Part.builder().text("You are a cat. Your name is Neko.").build();

Content content = Content.builder().role("system").parts(ImmutableList.of(textPart)).build();

GenerateContentConfig config =
    GenerateContentConfig.builder().systemInstruction(content).build();

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "Good morning! How are you?", config);

System.out.println(response.text());
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

// Construct the user message contents.
contents := []*genai.Content{
    genai.NewContentFromText("Good morning! How are you?", genai.RoleUser),
}

// Set the system instruction as a *genai.Content.
config := &genai.GenerateContentConfig{
    SystemInstruction: genai.NewContentFromText("You are a cat. Your name is Neko.", genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, config)
if err != nil {
    log.Fatal(err)
}
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Cache" %}

{% tabs %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-3.8-flash"

cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
        contents=[document],
        system_instruction="You are an expert analyzing transcripts.",
    ),
)
print(cache)

response = client.models.generate_content(
    model=model_name,
    contents="Please summarize this transcript",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const filePath = path.join(media, 'a11.txt');
const document = await ai.files.upload({
  file: filePath,
  config: {mimeType: 'text/plain'},
});
console.log('Uploaded file name:', document.name);
const modelName = 'gemini-3.8-flash';

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: 'You are an expert analyzing transcripts.',
  },
});
console.log('Cache created:', cache);

const response = await ai.models.generateContent({
  model: modelName,
  contents: 'Please summarize this transcript',
  config: {cachedContent: cache.name},
});
console.log('Response text:', response.text);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

modelName := "gemini-3.8-flash"
document, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "a11.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
parts := []*genai.Part{
    genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
    Contents: contents,
    SystemInstruction: genai.NewContentFromText(
        "You are an expert analyzing transcripts.", genai.RoleUser,
    ),
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("Cache created:")
fmt.Println(cache)

// Use the cache for generating content.
response, err := client.Models.GenerateContent(
    ctx,
    modelName,
    genai.Text("Please summarize this transcript"),
    &genai.GenerateContentConfig{
        CachedContent: cache.Name,
    },
)
if err != nil {
    log.Fatal(err)
}
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Code Execution" %}

{% tabs %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=(
        "Write and execute code that calculates the sum of the first 50"
        " prime numbers. Ensure that only the executable code and its"
        " resulting output are generated."
    ),
)
# Each part may contain text, executable code, or an execution result.
for part in response.candidates[0].content.parts:
  print(part, "\n")

print("-" * 80)
# The .text accessor concatenates the parts into a markdown-formatted text.
print("\n", response.text)
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

String prompt =
    """
    Write and execute code that calculates the sum of the first 50 prime numbers.
    Ensure that only the executable code and its resulting output are generated.
    """;

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", prompt, null);

for (Part part : response.candidates().get().getFirst().content().get().parts().get()) {
  System.out.println(part + "\n");
}

System.out.println("-".repeat(80));
System.out.println(response.text());
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

response, err := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    genai.Text(
        `Write and execute code that calculates the sum of the first 50 prime numbers.
         Ensure that only the executable code and its resulting output are generated.`,
    ),
    &genai.GenerateContentConfig{},
)
if err != nil {
    log.Fatal(err)
}

// Print the response.
printResponse(response)

fmt.Println("--------------------------------------------------------------------------------")
fmt.Println(response.Text())
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**candidates**: `array (`[`Candidate`](/api-reference/generate-content/generate-content#Resource:Candidate)`)`

Candidate responses from the model.

{% hr /%}

{% details %}

{% summary %}

**promptFeedback**: `PromptFeedback`

Returns the prompt's feedback related to the content filters.

{% /summary %}

{% details %}

{% summary %}

**blockReason**: `enum (string)`

Optional. If set, the prompt was blocked and no candidates are returned. Rephrase the prompt.

{% /summary %}

Possible values:

- `BLOCK_REASON_UNSPECIFIED`: Default value. This value is unused.
- `SAFETY`: Prompt was blocked due to safety reasons. Inspect `safety_ratings` to understand which safety category blocked it.
- `OTHER`: Prompt was blocked due to unknown reasons.
- `BLOCKLIST`: Prompt was blocked due to the terms which are included from the terminology blocklist.
- `PROHIBITED_CONTENT`: Prompt was blocked due to prohibited content.
- `IMAGE_SAFETY`: Candidates blocked due to unsafe image generation content.

{% /details %}

**safetyRatings**: `array (`[`SafetyRating`](/api-reference/generate-content/generate-content#Resource:SafetyRating)`)`

Ratings for safety of the prompt. There is at most one rating per category.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**usageMetadata**: `UsageMetadata`

Output only. Metadata on the generation requests' token usage.

{% /summary %}

**promptTokenCount**: `integer`

Number of tokens in the prompt. When `cached_content` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content.

**cachedContentTokenCount**: `integer`

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

**candidatesTokenCount**: `integer`

Total number of tokens across all the generated response candidates.

**toolUsePromptTokenCount**: `integer`

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

**thoughtsTokenCount**: `integer`

Output only. Number of tokens of thoughts for thinking models.

**totalTokenCount**: `integer`

Total token count for the generation request (prompt + tool-use prompt + thoughts + response candidates).

**promptTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content/generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities that were processed in the request input.

**cacheTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content/generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities of the cached content in the request input.

**candidatesTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content/generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities that were returned in the response.

**toolUsePromptTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content/generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities that were processed for tool-use request inputs.

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/generate-content/generate-content#Resource:ServiceTier)

Output only. Service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

{% /details %}

{% hr /%}

**modelVersion**: `string`

Output only. The model version used to generate the response.

{% hr /%}

**responseId**: `string`

Output only. response_id is used to identify each response.

{% hr /%}

{% details %}

{% summary %}

**modelStatus**: `ModelStatus`

Output only. The current model status of this model.

{% /summary %}

{% details %}

{% summary %}

**modelStage**: `ModelStage`

The stage of the underlying model.

{% /summary %}

Possible values:

- `MODEL_STAGE_UNSPECIFIED`: Unspecified model stage.
- `EXPERIMENTAL`: Models in this stage are for experimental purposes only.
- `PREVIEW`: Models in this stage are more mature than experimental models.
- `STABLE`: Models in this stage are considered stable and ready for production use.
- `LEGACY`: If the model is on this stage, it means that this model is on the path to deprecation in near future. Only existing customers can use this model.
- `RETIRED`: Models in this stage are retired. These models cannot be used.

{% /details %}

**retirementTime**: `string`

The time at which the model will be retired.

**message**: `string`

A message explaining the model status.

{% /details %}

{% /section %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### Candidate {% class="hide-from-toc" id="Resource:Candidate" %}

A response candidate generated from the model.

**Properties:**

**index**: `integer`

Output only. Index of the candidate in the list of response candidates.

{% hr /%}

**content**: [`Content`](/api-reference/generate-content/generate-content#Resource:Content)

Output only. Generated content returned from the model.

{% hr /%}

{% details %}

{% summary %}

**finishReason**: `enum (string)`

Optional. Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating tokens.

{% /summary %}

Possible values:

- `FINISH_REASON_UNSPECIFIED`: Default value. This value is unused.
- `STOP`: Natural stop point of the model or provided stop sequence.
- `MAX_TOKENS`: The maximum number of tokens as specified in the request was reached.
- `SAFETY`: The response candidate content was flagged for safety reasons.
- `RECITATION`: The response candidate content was flagged for recitation reasons.
- `LANGUAGE`: The response candidate content was flagged for using an unsupported language.
- `OTHER`: Unknown reason.
- `BLOCKLIST`: Token generation stopped because the content contains forbidden terms.
- `PROHIBITED_CONTENT`: Token generation stopped for potentially containing prohibited content.
- `SPII`: Token generation stopped because the content potentially contains Sensitive Personally Identifiable Information (SPII).
- `MALFORMED_FUNCTION_CALL`: The function call generated by the model is invalid.
- `IMAGE_SAFETY`: Token generation stopped because generated images contain safety violations.
- `IMAGE_PROHIBITED_CONTENT`: Image generation stopped because generated images has other prohibited content.
- `IMAGE_OTHER`: Image generation stopped because of other miscellaneous issue.
- `NO_IMAGE`: The model was expected to generate an image, but none was generated.
- `IMAGE_RECITATION`: Image generation stopped due to recitation.
- `UNEXPECTED_TOOL_CALL`: Model generated a tool call but no tools were enabled in the request.
- `TOO_MANY_TOOL_CALLS`: Model called too many tools consecutively, thus the system exited execution.
- `MISSING_THOUGHT_SIGNATURE`: Request has at least one thought signature missing.
- `MALFORMED_RESPONSE`: Finished due to malformed response.
- `ESCALATION`: Request was filtered by an escalation rule.
- `PUP_LIMITED_DISABLED`: Indicates that token generation stopped because the user account is limited or disabled due to Prohibited Use Policy (PUP) violations.
- `CONTINUATION`: Token generation was stopped because the response reached the per-request token limit, but generation is not yet complete. The model response can be continued via a subsequent request using the returned `continuation_token`. Note, the `max_output_tokens` is cumulative across continuation hops and must be monotonically increased or omitted.

{% /details %}

{% hr /%}

**finishMessage**: `string`

Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when `finish_reason` is set.

{% hr /%}

**safetyRatings**: `array (`[`SafetyRating`](/api-reference/generate-content/generate-content#Resource:SafetyRating)`)`

List of ratings for the safety of a response candidate. There is at most one rating per category.

{% hr /%}

**citationMetadata**: [`CitationMetadata`](/api-reference/generate-content/generate-content#Resource:CitationMetadata)

Output only. Citation information for model-generated candidate. This field may be populated with recitation information for any text included in the `content`. These are passages that are "recited" from copyrighted material in the foundational LLM's training data.

{% hr /%}

**tokenCount**: `integer`

Output only. Token count for this candidate.

{% hr /%}

{% details %}

{% summary %}

**groundingAttributions**: `array (GroundingAttribution)`

Output only. Attribution information for sources that contributed to a grounded answer. This field is populated for `GenerateAnswer` calls.

{% /summary %}

{% details %}

{% summary %}

**sourceId**: `AttributionSourceId`

Output only. Identifier for the source contributing to this attribution.

{% /summary %}

{% details %}

{% summary %}

**groundingPassage**: `GroundingPassageId`

Identifier for an inline passage.

{% /summary %}

**passageId**: `string`

Output only. ID of the passage matching the `GenerateAnswerRequest`'s `GroundingPassage.id`.

**partIndex**: `integer`

Output only. Index of the part within the `GenerateAnswerRequest`'s `GroundingPassage.content`.

{% /details %}

{% details %}

{% summary %}

**semanticRetrieverChunk**: `SemanticRetrieverChunk`

Identifier for a `Chunk` fetched via Semantic Retriever.

{% /summary %}

**source**: `string`

Output only. Name of the source matching the request's `SemanticRetrieverConfig.source`. Example: `corpora/123` or `corpora/123/documents/abc`

**chunk**: `string`

Output only. Name of the `Chunk` containing the attributed text. Example: `corpora/123/documents/abc/chunks/xyz`

{% /details %}

{% /details %}

**content**: [`Content`](/api-reference/generate-content/generate-content#Resource:Content)

Grounding source content that makes up this attribution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**groundingMetadata**: `GroundingMetadata`

Output only. Grounding metadata for the candidate. This field is populated for `GenerateContent` calls.

{% /summary %}

{% details %}

{% summary %}

**searchEntryPoint**: `SearchEntryPoint`

Optional. Google search entry for the following-up web searches.

{% /summary %}

**renderedContent**: `string`

Optional. Web content snippet that can be embedded in a web page or an app webview.

**sdkBlob**: `string`

Optional. Base64 encoded JSON representing array of tuple.

{% /details %}

{% details %}

{% summary %}

**groundingChunks**: `array (GroundingChunk)`

List of supporting references retrieved from specified grounding source. When streaming, this only contains the grounding chunks that have not been included in the grounding metadata of previous responses.

{% /summary %}

{% details %}

{% summary %}

**web**: `Web`

Grounding chunk from the web.

{% /summary %}

**uri**: `string`

Output only. URI reference of the chunk.

**title**: `string`

Output only. Title of the chunk.

{% /details %}

{% details %}

{% summary %}

**image**: `Image`

Optional. Grounding chunk from image search.

{% /summary %}

**sourceUri**: `string`

The web page URI for attribution.

**imageUri**: `string`

The image asset URL.

**title**: `string`

The title of the web page that the image is from.

**domain**: `string`

The root domain of the web page that the image is from, e.g. "example.com".

{% /details %}

{% details %}

{% summary %}

**retrievedContext**: `RetrievedContext`

Optional. Grounding chunk from context retrieved by the file search tool.

{% /summary %}

**uri**: `string`

Optional. URI reference of the semantic retrieval document.

**title**: `string`

Optional. Title of the document.

**text**: `string`

Optional. Text of the chunk.

**fileSearchStore**: `string`

Optional. Name of the `FileSearchStore` containing the document. Example: `fileSearchStores/123`

{% details %}

{% summary %}

**customMetadata**: `array (GroundingChunkCustomMetadata)`

Optional. User-provided metadata about the retrieved context.

{% /summary %}

**stringValue**: `string`

Optional. The string value of the metadata.

{% details %}

{% summary %}

**stringListValue**: `GroundingChunkStringList`

Optional. A list of string values for the metadata.

{% /summary %}

**values**: `array (string)`

The string values of the list.

{% /details %}

**numericValue**: `number`

Optional. The numeric value of the metadata. The expected range for this value depends on the specific `key` used.

**key**: `string`

The key of the metadata.

{% /details %}

**pageNumber**: `integer`

Optional. Page number of the retrieved context, if applicable.

**mediaId**: `string`

Optional. The media blob resource name for multimodal file search results. Format: fileSearchStores/{file_search_store_id}/media/{blob_id}

{% /details %}

{% details %}

{% summary %}

**maps**: `Maps`

Optional. Grounding chunk from Google Maps.

{% /summary %}

**uri**: `string`

URI reference of the place.

**title**: `string`

Title of the place.

**text**: `string`

Text description of the place answer.

**placeId**: `string`

The ID of the place, in `places/{place_id}` format. A user can use this ID to look up that place.

{% details %}

{% summary %}

**placeAnswerSources**: `PlaceAnswerSources`

Sources that provide answers about the features of a given place in Google Maps.

{% /summary %}

{% details %}

{% summary %}

**reviewSnippets**: `array (ReviewSnippet)`

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

{% /summary %}

**reviewId**: `string`

The ID of the review snippet.

**googleMapsUri**: `string`

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

**title**: `string`

Title of the review.

{% /details %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingSupports**: `array (GoogleAiGenerativelanguageV1betaGroundingSupport)`

List of grounding support.

{% /summary %}

{% details %}

{% summary %}

**segment**: `GoogleAiGenerativelanguageV1betaSegment`

Segment of the content this support belongs to.

{% /summary %}

**partIndex**: `integer`

The index of a Part object within its parent Content object.

**startIndex**: `integer`

Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero.

**endIndex**: `integer`

End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero.

**text**: `string`

The text corresponding to the segment from the response.

{% /details %}

**groundingChunkIndices**: `array (integer)`

Optional. A list of indices (into 'grounding_chunk' in `response.candidate.grounding_metadata`) specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. If the response is streaming, the grounding_chunk_indices refer to the indices across all responses. It is the client's responsibility to accumulate the grounding chunks from all responses (while maintaining the same order).

**confidenceScores**: `array (number)`

Optional. Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices.

**renderedParts**: `array (integer)`

Output only. Indices into the `parts` field of the candidate's content. These indices specify which rendered parts are associated with this support source.

{% /details %}

{% details %}

{% summary %}

**retrievalMetadata**: `RetrievalMetadata`

Metadata related to retrieval in the grounding flow.

{% /summary %}

**googleSearchDynamicRetrievalScore**: `number`

Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger google search.

{% /details %}

**webSearchQueries**: `array (string)`

Web search queries for the following-up web search.

**imageSearchQueries**: `array (string)`

Image search queries used for grounding.

**googleMapsWidgetContextToken**: `string`

Optional. Resource name of the Google Maps widget context token that can be used with the PlacesContextElement widget in order to render contextual data. Only populated in the case that grounding with Google Maps is enabled.

{% /details %}

{% hr /%}

**avgLogprobs**: `number`

Output only. Average log probability score of the candidate.

{% hr /%}

{% details %}

{% summary %}

**logprobsResult**: `LogprobsResult`

Output only. Log-likelihood scores for the response tokens and top tokens

{% /summary %}

**logProbabilitySum**: `number`

Sum of log probabilities for all tokens.

{% details %}

{% summary %}

**topCandidates**: `array (TopCandidates)`

Length = total number of decoding steps.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (LogprobsResultCandidate)`

Sorted by log probability in descending order.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**chosenCandidates**: `array (LogprobsResultCandidate)`

Length = total number of decoding steps. The chosen candidates may or may not be in top_candidates.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**urlContextMetadata**: `UrlContextMetadata`

Output only. Metadata related to url context retrieval tool.

{% /summary %}

{% details %}

{% summary %}

**urlMetadata**: `array (UrlMetadata)`

List of url context.

{% /summary %}

**retrievedUrl**: `string`

Retrieved url by the tool.

{% details %}

{% summary %}

**urlRetrievalStatus**: `enum (string)`

Status of the url retrieval.

{% /summary %}

Possible values:

- `URL_RETRIEVAL_STATUS_UNSPECIFIED`: Default value. This value is unused.
- `URL_RETRIEVAL_STATUS_SUCCESS`: Url retrieval is successful.
- `URL_RETRIEVAL_STATUS_ERROR`: Url retrieval is failed due to error.
- `URL_RETRIEVAL_STATUS_PAYWALL`: Url retrieval is failed because the content is behind paywall.
- `URL_RETRIEVAL_STATUS_UNSAFE`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**continuationToken**: `string`

An optional opaque continuation token returned when `finish_reason` is `CONTINUATION`. Clients can pass this token in a subsequent [`GenerateContentRequest`](/api-reference/generate-content/generate-content#request-body) to continue generation.

### CitationMetadata {% class="hide-from-toc" id="Resource:CitationMetadata" %}

A collection of source attributions for a piece of content.

**Properties:**

{% details %}

{% summary %}

**citationSources**: `array (CitationSource)`

Citations to sources for a specific response.

{% /summary %}

**startIndex**: `integer`

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

**endIndex**: `integer`

Optional. End of the attributed segment, exclusive.

**uri**: `string`

Optional. URI that is attributed as a source for a portion of the text.

**license**: `string`

Optional. License for the GitHub project that is attributed as a source for segment. License info is required for code citations.

{% /details %}

### HarmCategory {% class="hide-from-toc" id="Resource:HarmCategory" %}

**Possible values:**

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

### ModalityTokenCount {% class="hide-from-toc" id="Resource:ModalityTokenCount" %}

Represents token counting info for a single modality.

**Properties:**

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

{% hr /%}

**tokenCount**: `integer`

Number of tokens.

### SafetyRating {% class="hide-from-toc" id="Resource:SafetyRating" %}

Safety rating for a piece of content.

The safety rating contains the category of harm and the
harm probability level in that category for a piece of content.
Content is classified for safety across a number of
harm categories and the probability of the harm classification is included
here.

**Properties:**

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} [`HarmCategory`](/api-reference/generate-content/generate-content#Resource:HarmCategory)

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

{% hr /%}

**blocked**: `boolean`

Was this content blocked because of this rating?

### SafetySetting {% class="hide-from-toc" id="Resource:SafetySetting" %}

Safety setting, affecting the safety-blocking behavior.

Passing a safety setting for a category changes the allowed probability that
content is blocked.

**Properties:**

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} [`HarmCategory`](/api-reference/generate-content/generate-content#Resource:HarmCategory)

The category for this setting.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

Controls the probability threshold at which harm is blocked.

{% /summary %}

Possible values:

- `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: Threshold is unspecified.
- `BLOCK_LOW_AND_ABOVE`: Content with NEGLIGIBLE will be allowed.
- `BLOCK_MEDIUM_AND_ABOVE`: Content with NEGLIGIBLE and LOW will be allowed.
- `BLOCK_ONLY_HIGH`: Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
- `BLOCK_NONE`: All content will be allowed.
- `OFF`: Turn off the safety filter.

{% /details %}

### ServiceTier {% class="hide-from-toc" id="Resource:ServiceTier" %}

**Possible values:**

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

### Content {% class="hide-from-toc" id="Resource:Content" %}

The base structured datatype containing multi-part content of a message.

A [`Content`](/api-reference/generate-content/generate-content#Resource:Content) includes a `role` field designating the producer of the [`Content`](/api-reference/generate-content/generate-content#Resource:Content)
and a `parts` field containing multi-part data that contains the content of
the message turn.

**Properties:**

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

{% hr /%}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

### Schema {% class="hide-from-toc" id="Resource:Schema" %}

The [`Schema`](/api-reference/generate-content/generate-content#Resource:Schema) object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
Represents a select subset of an [OpenAPI 3.0 schema
object](https://spec.openapis.org/oas/v3.0.3#schema).

**Properties:**

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

{% hr /%}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

{% hr /%}

**title**: `string`

Optional. The title of the schema.

{% hr /%}

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

{% hr /%}

**nullable**: `boolean`

Optional. Indicates if the value may be null.

{% hr /%}

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

{% hr /%}

**items**: [`Schema`](/api-reference/generate-content/generate-content#Resource:Schema)

Optional. Schema of the elements of Type.ARRAY.

{% hr /%}

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

{% hr /%}

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

{% hr /%}

**properties**: `object`

Optional. Properties of Type.OBJECT.

{% hr /%}

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

{% hr /%}

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

{% hr /%}

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

{% hr /%}

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

{% hr /%}

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

{% hr /%}

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

{% hr /%}

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

{% hr /%}

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

{% hr /%}

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

{% hr /%}

**anyOf**: `array (`[`Schema`](/api-reference/generate-content/generate-content#Resource:Schema)`)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

{% hr /%}

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

{% hr /%}

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

### Tool {% class="hide-from-toc" id="Resource:Tool" %}

Tool details that the model may use to generate response.

A [`Tool`](/api-reference/generate-content/generate-content#Resource:Tool) is a piece of code that enables the system to interact with
external systems to perform an action, or set of actions, outside of
knowledge and scope of the model.

**Properties:**

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

**parameters**: [`Schema`](/api-reference/generate-content/generate-content#Resource:Schema)

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

**response**: [`Schema`](/api-reference/generate-content/generate-content#Resource:Schema)

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

# Streaming generated content
Source: https://aistudio.google.com/api-reference/generate-content/stream-generate-content
Description: Generates a [streamed response](/docs/text-generation#streaming-responses) from the model given an input `GenerateContentRequest`.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/models/{model}:streamGenerateContent`

Generates a [streamed
response](/docs/text-generation#streaming-responses)
from the model given an input [`GenerateContentRequest`](/api-reference/generate-content/stream-generate-content#request-body).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The model ID, for example `gemini-2.5-flash`. Forms the resource name `models/{model}`.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% hr /%}

**contents**: {% mark %}required{% /mark %} `array (`[`Content`](/api-reference/generate-content/stream-generate-content#Resource:Content)`)`

The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like [chat](/docs/text-generation#multi-turn-conversations), this is a repeated field that contains the conversation history and the latest request.

{% hr /%}

**systemInstruction**: [`Content`](/api-reference/generate-content/stream-generate-content#Resource:Content)

Optional. Developer set [system instruction(s)](/docs/text-generation#system-instructions). Currently, text only.

{% hr /%}

**tools**: `array (`[`Tool`](/api-reference/generate-content/stream-generate-content#Resource:Tool)`)`

Optional. A list of `Tools` the `Model` may use to generate the next response. A [`Tool`](/api-reference/generate-content/stream-generate-content#Resource:Tool) is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the `Model`. Supported [`Tool`](/api-reference/generate-content/stream-generate-content#Resource:Tool)s are `Function` and `code_execution`. Refer to the [Function calling](/docs/function-calling) and the [Code execution](/docs/code-execution) guides to learn more.

{% hr /%}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Tool configuration for any [`Tool`](/api-reference/generate-content/stream-generate-content#Resource:Tool) specified in the request. Refer to the [Function calling guide](/docs/function-calling#function_calling_modes) for a usage example.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the [`Content`](/api-reference/generate-content/stream-generate-content#Resource:Content) message. This allows clients to observe the server's tool interactions.

{% /details %}

{% hr /%}

**safetySettings**: `array (`[`SafetySetting`](/api-reference/generate-content/stream-generate-content#Resource:SafetySetting)`)`

Optional. A list of unique [`SafetySetting`](/api-reference/generate-content/stream-generate-content#Resource:SafetySetting) instances for blocking unsafe content. This will be enforced on the `GenerateContentRequest.contents` and `GenerateContentResponse.candidates`. There should not be more than one setting for each `SafetyCategory` type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each `SafetyCategory` specified in the safety_settings. If there is no [`SafetySetting`](/api-reference/generate-content/stream-generate-content#Resource:SafetySetting) for a given `SafetyCategory` provided in the list, the API will use the default safety setting for that category. Harm categories HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_CIVIC_INTEGRITY, HARM_CATEGORY_JAILBREAK are supported. Refer to the [guide](/docs/safety-settings) for detailed information on available safety settings. Also refer to the [Safety guidance](/docs/safety-guidance) to learn how to incorporate safety considerations in your AI applications.

{% hr /%}

{% details %}

{% summary %}

**generationConfig**: `GenerationConfig`

Optional. Configuration options for model generation and outputs.

{% /summary %}

**candidateCount**: `integer`

Optional. Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)

**stopSequences**: `array (string)`

Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a `stop_sequence`. The stop sequence will not be included as part of the response.

**maxOutputTokens**: `integer`

Optional. The maximum number of tokens to include in a response candidate. Note: The default value varies by model, see the `Model.output_token_limit` attribute of the `Model` returned from the `getModel` function.

**temperature**: `number`

Optional. Controls the randomness of the output. Note: The default value varies by model, see the `Model.temperature` attribute of the `Model` returned from the `getModel` function. Values can range from [0.0, 2.0]. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topP**: `number`

Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topK**: `integer`

Optional. The maximum number of tokens to consider when sampling. Gemini models use Top-p (nucleus) sampling or a combination of Top-k and nucleus sampling. Top-k sampling considers the set of `top_k` most probable tokens. Models running with nucleus sampling don't allow top_k setting. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**seed**: `integer`

Optional. Seed used in decoding. If not set, the request uses a randomly generated seed.

**responseMimeType**: `string`

Optional. MIME type of the generated candidate text. Supported MIME types are: `text/plain`: (default) Text output. `application/json`: JSON response in the response candidates. `text/x.enum`: ENUM as a string response in the response candidates. Refer to the [docs](/docs/file-input-methods#text-file-types) for a list of all supported text MIME types.

**responseJsonSchema**: `object`

Optional. An internal detail. Use `responseJsonSchema` rather than this field.

**presencePenalty**: `number`

Optional. Presence penalty applied to the next token's logprobs if the token has already been seen in the response. This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequency_penalty for a penalty that increases with each use. A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary. A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.

**frequencyPenalty**: `number`

Optional. Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far. A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses. Caution: A _negative_ penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the max_output_tokens limit.

**responseLogprobs**: `boolean`

Optional. If true, export the logprobs results in response.

**logprobs**: `integer`

Optional. Only valid if response_logprobs=True. This sets the number of top logprobs, including the chosen candidate, to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].

**enableEnhancedCivicAnswers**: `boolean`

Optional. Enables enhanced civic answers. It may not be available for all models.

{% details %}

{% summary %}

**responseModalities**: `array (enum (string))`

Optional. The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response. A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned. An empty list is equivalent to requesting only text.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Default value.
- `TEXT`: Indicates the model should return text.
- `IMAGE`: Indicates the model should return images.
- `AUDIO`: Indicates the model should return audio.

{% /details %}

{% details %}

{% summary %}

**speechConfig**: `SpeechConfig`

Optional. The speech generation config.

{% /summary %}

{% details %}

{% summary %}

**voiceConfig**: `VoiceConfig`

The configuration in case of single-voice output.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% details %}

{% summary %}

**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig`

Optional. The configuration for the multi-speaker setup. It is mutually exclusive with the voice_config field.

{% /summary %}

{% details %}

{% summary %}

**speakerVoiceConfigs**: {% mark %}required{% /mark %} `array (SpeakerVoiceConfig)`

All the enabled speaker voices.

{% /summary %}

**speaker**: {% mark %}required{% /mark %} `string`

The name of the speaker to use. Should be the same as in the prompt.

{% details %}

{% summary %}

**voiceConfig**: {% mark %}required{% /mark %} `VoiceConfig`

The configuration for the voice to use.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% /details %}

{% /details %}

**languageCode**: `string`

Optional. The IETF [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code that the user configured the app to use. Used for speech recognition and synthesis. Valid values are: `de-DE`, `en-AU`, `en-GB`, `en-IN`, `en-US`, `es-US`, `fr-FR`, `hi-IN`, `pt-BR`, `ar-XA`, `es-ES`, `fr-CA`, `id-ID`, `it-IT`, `ja-JP`, `tr-TR`, `vi-VN`, `bn-IN`, `gu-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `ta-IN`, `te-IN`, `nl-NL`, `ko-KR`, `cmn-CN`, `pl-PL`, `ru-RU`, and `th-TH`.

{% /details %}

{% details %}

{% summary %}

**thinkingConfig**: `ThinkingConfig`

Optional. Config for thinking features. An error will be returned if this field is set for models that don't support thinking.

{% /summary %}

**includeThoughts**: `boolean`

Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.

**thinkingBudget**: `integer`

The number of thoughts tokens that the model should generate.

{% details %}

{% summary %}

**thinkingLevel**: `enum (string)`

Optional. Controls the maximum depth of the model's internal reasoning process before it produces a response. The default value is model-dependent. Refer to the [Thinking levels guide](/docs/thinking#thinking-levels) for more details. Recommended for Gemini 3 or later models. Use with earlier models results in an error.

{% /summary %}

Possible values:

- `THINKING_LEVEL_UNSPECIFIED`: Default value.
- `MINIMAL`: Little to no thinking.
- `LOW`: Low thinking level.
- `MEDIUM`: Medium thinking level.
- `HIGH`: High thinking level.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**imageConfig**: `ImageConfig`

Optional. Config for image generation. An error will be returned if this field is set for models that don't support these config options.

{% /summary %}

**aspectRatio**: `string`

Optional. The aspect ratio of the image to generate. Supported aspect ratios: `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, or `21:9`. If not specified, the model will choose a default aspect ratio based on any reference images provided.

**imageSize**: `string`

Optional. Specifies the size of generated images. Supported values are `512`, `1K`, `2K`, `4K`. If not specified, the model will use default value `1K`.

{% /details %}

{% details %}

{% summary %}

**mediaResolution**: `enum (string)`

Optional. If specified, the media resolution specified will be used.

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low (64 tokens).
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium (256 tokens).
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high (zoomed reframing with 256 tokens).

{% /details %}

**enableAffectiveDialog**: `boolean`

Optional. If enabled, the model will detect emotions and adapt its responses accordingly.

{% details %}

{% summary %}

**responseFormat**: `ResponseFormatConfig`

Optional. Configuration for the response output format. Allows specifying output configuration per modality (text, audio, image) in a flat structure.

{% /summary %}

{% details %}

{% summary %}

**text**: `TextResponseFormat`

Optional. Text output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the text output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `APPLICATION_JSON`: JSON output format.
- `TEXT_PLAIN`: Plain text output format.

{% /details %}

**schema**: `object`

Optional. The JSON schema that the output should conform to. Only applicable when mime_type is APPLICATION_JSON.

{% /details %}

{% details %}

{% summary %}

**audio**: `AudioResponseFormat`

Optional. Audio output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the audio output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `AUDIO_MP3`: MP3 audio format.
- `AUDIO_OGG_OPUS`: OGG Opus audio format.
- `AUDIO_L16`: Raw PCM (L16) audio format.
- `AUDIO_WAV`: WAV audio format.
- `AUDIO_ALAW`: A-law audio format.
- `AUDIO_MULAW`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the audio output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Audio data is returned inline in the response.
- `URI`: Audio data is returned as a URI.

{% /details %}

**sampleRate**: `integer`

Optional. Sample rate in Hz.

**bitRate**: `integer`

Optional. Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}

**image**: `ImageResponseFormat`

Optional. Image output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the image output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_JPEG`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the image output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Image data is returned inline in the response.
- `URI`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspectRatio**: `enum (string)`

Optional. The aspect ratio for the image output.

{% /summary %}

Possible values:

- `ASPECT_RATIO_UNSPECIFIED`: Default value. This value is unused.
- `ASPECT_RATIO_ONE_BY_ONE`: 1:1 aspect ratio.
- `ASPECT_RATIO_TWO_BY_THREE`: 2:3 aspect ratio.
- `ASPECT_RATIO_THREE_BY_TWO`: 3:2 aspect ratio.
- `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 aspect ratio.
- `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 aspect ratio.
- `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 aspect ratio.
- `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 aspect ratio.
- `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 aspect ratio.
- `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 aspect ratio.
- `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 aspect ratio.
- `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**imageSize**: `enum (string)`

Optional. The size of the image output.

{% /summary %}

Possible values:

- `IMAGE_SIZE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_SIZE_FIVE_TWELVE`: 512px image size.
- `IMAGE_SIZE_ONE_K`: 1K image size.
- `IMAGE_SIZE_TWO_K`: 2K image size.
- `IMAGE_SIZE_FOUR_K`: 4K image size.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**translationConfig**: `TranslationConfig`

Optional. Config for translation.

{% /summary %}

**targetLanguageCode**: {% mark %}required{% /mark %} `string`

The target language for translation. Supported values are BCP-47 language codes (e.g. "en", "es", "fr").

**echoTargetLanguage**: `boolean`

Optional. If true, the model will generate audio when the target language is spoken, essentially it will parrot the input. If false, we will not produce audio for the target language.

{% /details %}

{% details %}

{% summary %}

**audioTranscriptionConfig**: `AudioTranscriptionConfig`

Optional. Config for audio transcription (speech recognition).

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**cachedContent**: `string`

Optional. The name of the content [cached](/docs/caching) to use as context to serve the prediction. Format: `cachedContents/{cachedContent}`

{% hr /%}

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/generate-content/stream-generate-content#Resource:ServiceTier)

Optional. The service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

{% hr /%}

**store**: `boolean`

Optional. Configures the logging behavior for a given request. If set, it takes precedence over the project-level logging config.

{% hr /%}

**continuationToken**: `string`

Optional. An opaque continuation token used to resume generation from a previous `GenerateContent` or `StreamGenerateContent` response that stopped with `finish_reason` set to `CONTINUATION`. Note that `contents` is mandatory and must identically replicate the prompt and conversation history from the initial request when continuation token is provided in a request.

{% hr /%}

**labels**: `object`

Optional. Labels with user-defined metadata for the request. Optional. Labels must follow standard unified Cloud label requirements:

- Label keys must start with a letter.
- Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes.
- International characters are allowed.

Usage:

- Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="Text" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=${GEMINI_API_KEY}" \
        -H 'Content-Type: application/json' \
        --no-buffer \
        -d '{ "contents":[{"parts":[{"text": "Write a story about a magic backpack."}]}]}'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents="Write a story about a magic backpack.",
)
for chunk in response:
  print(chunk.text)
  print("_" * 80)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const response = await ai.models.generateContentStream({
  model: 'gemini-3.8-flash',
  contents: 'Write a story about a magic backpack.',
});
let text = '';
for await (const chunk of response) {
  console.log(chunk.text);
  text += chunk.text;
}
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

ResponseStream<GenerateContentResponse> responseStream =
    client.models.generateContentStream(
        "gemini-3.8-flash", "Write a story about a magic backpack.", null);

StringBuilder response = new StringBuilder();
for (GenerateContentResponse res : responseStream) {
  System.out.print(res.text());
  response.append(res.text());
}

responseStream.close();
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
contents := []*genai.Content{
    genai.NewContentFromText("Write a story about a magic backpack.", genai.RoleUser),
}
for response, err := range client.Models.GenerateContentStream(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(response.Candidates[0].Content.Parts[0].Text)
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Image" %}

{% tabs %}

{% tab label="REST" %}

```sh
cat > "$TEMP_JSON" << EOF
{
  "contents": [{
    "parts":[
      {"text": "Tell me about this instrument"},
      {
        "inline_data": {
          "mime_type":"image/jpeg",
          "data": "$(cat "$TEMP_B64")"
        }
      }
    ]
  }]
}
EOF

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d "@$TEMP_JSON" 2> /dev/null
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
import PIL.Image

client = genai.Client()
organ = PIL.Image.open(media / "organ.jpg")
response = client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents=["Tell me about this instrument", organ],
)
for chunk in response:
  print(chunk.text)
  print("_" * 80)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const organ = await ai.files.upload({
  file: path.join(media, 'organ.jpg'),
});

const response = await ai.models.generateContentStream({
  model: 'gemini-3.8-flash',
  contents: [
    createUserContent([
      'Tell me about this instrument',
      createPartFromUri(organ.uri, organ.mimeType)
    ]),
  ],
});
let text = '';
for await (const chunk of response) {
  console.log(chunk.text);
  text += chunk.text;
}
```

{% /tab %}

{% tab label="Java" %}

```java
Client client = new Client();

String path = media_path + "organ.jpg";
byte[] imageData = Files.readAllBytes(Paths.get(path));

Content content =
    Content.fromParts(
        Part.fromText("Tell me about this instrument."),
        Part.fromBytes(imageData, "image/jpeg"));

ResponseStream<GenerateContentResponse> responseStream =
    client.models.generateContentStream("gemini-3.8-flash", content, null);

StringBuilder response = new StringBuilder();
for (GenerateContentResponse res : responseStream) {
  System.out.print(res.text());
  response.append(res.text());
}

responseStream.close();
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
file, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "organ.jpg"),
    &genai.UploadFileConfig{
        MIMEType: "image/jpeg",
    },
)
if err != nil {
    log.Fatal(err)
}
parts := []*genai.Part{
    genai.NewPartFromText("Tell me about this instrument"),
    genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
for response, err := range client.Models.GenerateContentStream(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(response.Candidates[0].Content.Parts[0].Text)
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Audio" %}

{% tabs %}

{% tab label="REST" %}

```sh
# Use File API to upload audio data to API request.
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Please describe this file."},
          {"file_data":{"mime_type": "audio/mpeg", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
sample_audio = client.files.upload(file=media / "sample.mp3")
response = client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this audio file.", sample_audio],
)
for chunk in response:
  print(chunk.text)
  print("_" * 80)
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "sample.mp3"),
    &genai.UploadFileConfig{
        MIMEType: "audio/mpeg",
    },
)
if err != nil {
    log.Fatal(err)
}

parts := []*genai.Part{
    genai.NewPartFromText("Give me a summary of this audio file."),
    genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

for result, err := range client.Models.GenerateContentStream(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Video" %}

{% tabs %}

{% tab label="REST" %}

```sh
# Use File API to upload audio data to API request.
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO_PATH

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

state=$(jq ".file.state" file_info.json)
echo state=$state

while [[ "($state)" = *"PROCESSING"* ]];
do
  echo "Processing video..."
  sleep 5
  # Get the file of interest to check state
  curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
  state=$(jq ".file.state" file_info.json)
done

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Please describe this file."},
          {"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
import time

client = genai.Client()
# Video clip (CC BY 3.0) from https://peach.blender.org/download/
myfile = client.files.upload(file=media / "Big_Buck_Bunny.mp4")
print(f"{myfile=}")

# Poll until the video file is completely processed (state becomes ACTIVE).
while not myfile.state or myfile.state.name != "ACTIVE":
  print("Processing video...")
  print("File state:", myfile.state)
  time.sleep(5)
  myfile = client.files.get(name=myfile.name)

response = client.models.generate_content_stream(
    model="gemini-3.8-flash", contents=[myfile, "Describe this video clip"]
)
for chunk in response:
  print(chunk.text)
  print("_" * 80)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

let video = await ai.files.upload({
  file: path.join(media, 'Big_Buck_Bunny.mp4'),
});

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!video.state || video.state.toString() !== 'ACTIVE') {
  console.log('Processing video...');
  console.log('File state: ', video.state);
  await sleep(5000);
  video = await ai.files.get({name: video.name});
}

const response = await ai.models.generateContentStream({
  model: 'gemini-3.8-flash',
  contents: [
    createUserContent([
      'Describe this video clip',
      createPartFromUri(video.uri, video.mimeType),
    ]),
  ],
});
let text = '';
for await (const chunk of response) {
  console.log(chunk.text);
  text += chunk.text;
}
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "Big_Buck_Bunny.mp4"),
    &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    },
)
if err != nil {
    log.Fatal(err)
}

// Poll until the video file is completely processed (state becomes ACTIVE).
for file.State == genai.FileStateUnspecified || file.State != genai.FileStateActive {
    fmt.Println("Processing video...")
    fmt.Println("File state:", file.State)
    time.Sleep(5 * time.Second)

    file, err = client.Files.Get(ctx, file.Name, nil)
    if err != nil {
        log.Fatal(err)
    }
}

parts := []*genai.Part{
    genai.NewPartFromText("Describe this video clip"),
    genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

for result, err := range client.Models.GenerateContentStream(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Pdf" %}

{% tabs %}

{% tab label="REST" %}

```sh
MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
NUM_BYTES=$(wc -c < "${PDF_PATH}")
DISPLAY_NAME=TEXT


echo $MIME_TYPE
tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${PDF_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Can you add a few more lines to this poem?"},
          {"file_data":{"mime_type": "application/pdf", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
sample_pdf = client.files.upload(file=media / "test.pdf")
response = client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this document:", sample_pdf],
)

for chunk in response:
  print(chunk.text)
  print("_" * 80)
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "test.pdf"),
    &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    },
)
if err != nil {
    log.Fatal(err)
}

parts := []*genai.Part{
    genai.NewPartFromText("Give me a summary of this document:"),
    genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

for result, err := range client.Models.GenerateContentStream(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Chat" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {"role":"user",
         "parts":[{
           "text": "Hello"}]},
        {"role": "model",
         "parts":[{
           "text": "Great to meet you. What would you like to know?"}]},
        {"role":"user",
         "parts":[{
           "text": "I have two dogs in my house. How many paws are in my house?"}]},
      ]
    }' 2> /dev/null | grep "text"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
chat = client.chats.create(
    model="gemini-3.8-flash",
    history=[
        types.Content(role="user", parts=[types.Part(text="Hello")]),
        types.Content(
            role="model",
            parts=[
                types.Part(
                    text="Great to meet you. What would you like to know?"
                )
            ],
        ),
    ],
)
response = chat.send_message_stream(message="I have 2 dogs in my house.")
for chunk in response:
  print(chunk.text)
  print("_" * 80)
response = chat.send_message_stream(
    message="How many paws are in my house?"
)
for chunk in response:
  print(chunk.text)
  print("_" * 80)

print(chat.get_history())
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const chat = ai.chats.create({
  model: 'gemini-3.8-flash',
  history: [
    {
      role: 'user',
      parts: [{text: 'Hello'}],
    },
    {
      role: 'model',
      parts: [{text: 'Great to meet you. What would you like to know?'}],
    },
  ],
});

console.log('Streaming response for first message:');
const stream1 = await chat.sendMessageStream({
  message: 'I have 2 dogs in my house.',
});
for await (const chunk of stream1) {
  console.log(chunk.text);
  console.log('_'.repeat(80));
}

console.log('Streaming response for second message:');
const stream2 = await chat.sendMessageStream({
  message: 'How many paws are in my house?',
});
for await (const chunk of stream2) {
  console.log(chunk.text);
  console.log('_'.repeat(80));
}

console.log(chat.getHistory());
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

history := []*genai.Content{
    genai.NewContentFromText("Hello", genai.RoleUser),
    genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel),
}
chat, err := client.Chats.Create(ctx, "gemini-3.8-flash", nil, history)
if err != nil {
    log.Fatal(err)
}

for chunk, err := range chat.SendMessageStream(ctx, genai.Part{Text: "I have 2 dogs in my house."}) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(chunk.Text())
    fmt.Println(strings.Repeat("_", 64))
}

for chunk, err := range chat.SendMessageStream(ctx, genai.Part{Text: "How many paws are in my house?"}) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(chunk.Text())
    fmt.Println(strings.Repeat("_", 64))
}

fmt.Println(chat.History(false))
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**candidates**: `array (`[`Candidate`](/api-reference/generate-content/stream-generate-content#Resource:Candidate)`)`

Candidate responses from the model.

{% hr /%}

{% details %}

{% summary %}

**promptFeedback**: `PromptFeedback`

Returns the prompt's feedback related to the content filters.

{% /summary %}

{% details %}

{% summary %}

**blockReason**: `enum (string)`

Optional. If set, the prompt was blocked and no candidates are returned. Rephrase the prompt.

{% /summary %}

Possible values:

- `BLOCK_REASON_UNSPECIFIED`: Default value. This value is unused.
- `SAFETY`: Prompt was blocked due to safety reasons. Inspect `safety_ratings` to understand which safety category blocked it.
- `OTHER`: Prompt was blocked due to unknown reasons.
- `BLOCKLIST`: Prompt was blocked due to the terms which are included from the terminology blocklist.
- `PROHIBITED_CONTENT`: Prompt was blocked due to prohibited content.
- `IMAGE_SAFETY`: Candidates blocked due to unsafe image generation content.

{% /details %}

**safetyRatings**: `array (`[`SafetyRating`](/api-reference/generate-content/stream-generate-content#Resource:SafetyRating)`)`

Ratings for safety of the prompt. There is at most one rating per category.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**usageMetadata**: `UsageMetadata`

Output only. Metadata on the generation requests' token usage.

{% /summary %}

**promptTokenCount**: `integer`

Number of tokens in the prompt. When `cached_content` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content.

**cachedContentTokenCount**: `integer`

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

**candidatesTokenCount**: `integer`

Total number of tokens across all the generated response candidates.

**toolUsePromptTokenCount**: `integer`

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

**thoughtsTokenCount**: `integer`

Output only. Number of tokens of thoughts for thinking models.

**totalTokenCount**: `integer`

Total token count for the generation request (prompt + tool-use prompt + thoughts + response candidates).

**promptTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content/stream-generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities that were processed in the request input.

**cacheTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content/stream-generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities of the cached content in the request input.

**candidatesTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content/stream-generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities that were returned in the response.

**toolUsePromptTokensDetails**: `array (`[`ModalityTokenCount`](/api-reference/generate-content/stream-generate-content#Resource:ModalityTokenCount)`)`

Output only. List of modalities that were processed for tool-use request inputs.

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/generate-content/stream-generate-content#Resource:ServiceTier)

Output only. Service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

{% /details %}

{% hr /%}

**modelVersion**: `string`

Output only. The model version used to generate the response.

{% hr /%}

**responseId**: `string`

Output only. response_id is used to identify each response.

{% hr /%}

{% details %}

{% summary %}

**modelStatus**: `ModelStatus`

Output only. The current model status of this model.

{% /summary %}

{% details %}

{% summary %}

**modelStage**: `ModelStage`

The stage of the underlying model.

{% /summary %}

Possible values:

- `MODEL_STAGE_UNSPECIFIED`: Unspecified model stage.
- `EXPERIMENTAL`: Models in this stage are for experimental purposes only.
- `PREVIEW`: Models in this stage are more mature than experimental models.
- `STABLE`: Models in this stage are considered stable and ready for production use.
- `LEGACY`: If the model is on this stage, it means that this model is on the path to deprecation in near future. Only existing customers can use this model.
- `RETIRED`: Models in this stage are retired. These models cannot be used.

{% /details %}

**retirementTime**: `string`

The time at which the model will be retired.

**message**: `string`

A message explaining the model status.

{% /details %}

{% /section %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### Candidate {% class="hide-from-toc" id="Resource:Candidate" %}

A response candidate generated from the model.

**Properties:**

**index**: `integer`

Output only. Index of the candidate in the list of response candidates.

{% hr /%}

**content**: [`Content`](/api-reference/generate-content/stream-generate-content#Resource:Content)

Output only. Generated content returned from the model.

{% hr /%}

{% details %}

{% summary %}

**finishReason**: `enum (string)`

Optional. Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating tokens.

{% /summary %}

Possible values:

- `FINISH_REASON_UNSPECIFIED`: Default value. This value is unused.
- `STOP`: Natural stop point of the model or provided stop sequence.
- `MAX_TOKENS`: The maximum number of tokens as specified in the request was reached.
- `SAFETY`: The response candidate content was flagged for safety reasons.
- `RECITATION`: The response candidate content was flagged for recitation reasons.
- `LANGUAGE`: The response candidate content was flagged for using an unsupported language.
- `OTHER`: Unknown reason.
- `BLOCKLIST`: Token generation stopped because the content contains forbidden terms.
- `PROHIBITED_CONTENT`: Token generation stopped for potentially containing prohibited content.
- `SPII`: Token generation stopped because the content potentially contains Sensitive Personally Identifiable Information (SPII).
- `MALFORMED_FUNCTION_CALL`: The function call generated by the model is invalid.
- `IMAGE_SAFETY`: Token generation stopped because generated images contain safety violations.
- `IMAGE_PROHIBITED_CONTENT`: Image generation stopped because generated images has other prohibited content.
- `IMAGE_OTHER`: Image generation stopped because of other miscellaneous issue.
- `NO_IMAGE`: The model was expected to generate an image, but none was generated.
- `IMAGE_RECITATION`: Image generation stopped due to recitation.
- `UNEXPECTED_TOOL_CALL`: Model generated a tool call but no tools were enabled in the request.
- `TOO_MANY_TOOL_CALLS`: Model called too many tools consecutively, thus the system exited execution.
- `MISSING_THOUGHT_SIGNATURE`: Request has at least one thought signature missing.
- `MALFORMED_RESPONSE`: Finished due to malformed response.
- `ESCALATION`: Request was filtered by an escalation rule.
- `PUP_LIMITED_DISABLED`: Indicates that token generation stopped because the user account is limited or disabled due to Prohibited Use Policy (PUP) violations.
- `CONTINUATION`: Token generation was stopped because the response reached the per-request token limit, but generation is not yet complete. The model response can be continued via a subsequent request using the returned `continuation_token`. Note, the `max_output_tokens` is cumulative across continuation hops and must be monotonically increased or omitted.

{% /details %}

{% hr /%}

**finishMessage**: `string`

Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when `finish_reason` is set.

{% hr /%}

**safetyRatings**: `array (`[`SafetyRating`](/api-reference/generate-content/stream-generate-content#Resource:SafetyRating)`)`

List of ratings for the safety of a response candidate. There is at most one rating per category.

{% hr /%}

**citationMetadata**: [`CitationMetadata`](/api-reference/generate-content/stream-generate-content#Resource:CitationMetadata)

Output only. Citation information for model-generated candidate. This field may be populated with recitation information for any text included in the `content`. These are passages that are "recited" from copyrighted material in the foundational LLM's training data.

{% hr /%}

**tokenCount**: `integer`

Output only. Token count for this candidate.

{% hr /%}

{% details %}

{% summary %}

**groundingAttributions**: `array (GroundingAttribution)`

Output only. Attribution information for sources that contributed to a grounded answer. This field is populated for `GenerateAnswer` calls.

{% /summary %}

{% details %}

{% summary %}

**sourceId**: `AttributionSourceId`

Output only. Identifier for the source contributing to this attribution.

{% /summary %}

{% details %}

{% summary %}

**groundingPassage**: `GroundingPassageId`

Identifier for an inline passage.

{% /summary %}

**passageId**: `string`

Output only. ID of the passage matching the `GenerateAnswerRequest`'s `GroundingPassage.id`.

**partIndex**: `integer`

Output only. Index of the part within the `GenerateAnswerRequest`'s `GroundingPassage.content`.

{% /details %}

{% details %}

{% summary %}

**semanticRetrieverChunk**: `SemanticRetrieverChunk`

Identifier for a `Chunk` fetched via Semantic Retriever.

{% /summary %}

**source**: `string`

Output only. Name of the source matching the request's `SemanticRetrieverConfig.source`. Example: `corpora/123` or `corpora/123/documents/abc`

**chunk**: `string`

Output only. Name of the `Chunk` containing the attributed text. Example: `corpora/123/documents/abc/chunks/xyz`

{% /details %}

{% /details %}

**content**: [`Content`](/api-reference/generate-content/stream-generate-content#Resource:Content)

Grounding source content that makes up this attribution.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**groundingMetadata**: `GroundingMetadata`

Output only. Grounding metadata for the candidate. This field is populated for `GenerateContent` calls.

{% /summary %}

{% details %}

{% summary %}

**searchEntryPoint**: `SearchEntryPoint`

Optional. Google search entry for the following-up web searches.

{% /summary %}

**renderedContent**: `string`

Optional. Web content snippet that can be embedded in a web page or an app webview.

**sdkBlob**: `string`

Optional. Base64 encoded JSON representing array of tuple.

{% /details %}

{% details %}

{% summary %}

**groundingChunks**: `array (GroundingChunk)`

List of supporting references retrieved from specified grounding source. When streaming, this only contains the grounding chunks that have not been included in the grounding metadata of previous responses.

{% /summary %}

{% details %}

{% summary %}

**web**: `Web`

Grounding chunk from the web.

{% /summary %}

**uri**: `string`

Output only. URI reference of the chunk.

**title**: `string`

Output only. Title of the chunk.

{% /details %}

{% details %}

{% summary %}

**image**: `Image`

Optional. Grounding chunk from image search.

{% /summary %}

**sourceUri**: `string`

The web page URI for attribution.

**imageUri**: `string`

The image asset URL.

**title**: `string`

The title of the web page that the image is from.

**domain**: `string`

The root domain of the web page that the image is from, e.g. "example.com".

{% /details %}

{% details %}

{% summary %}

**retrievedContext**: `RetrievedContext`

Optional. Grounding chunk from context retrieved by the file search tool.

{% /summary %}

**uri**: `string`

Optional. URI reference of the semantic retrieval document.

**title**: `string`

Optional. Title of the document.

**text**: `string`

Optional. Text of the chunk.

**fileSearchStore**: `string`

Optional. Name of the `FileSearchStore` containing the document. Example: `fileSearchStores/123`

{% details %}

{% summary %}

**customMetadata**: `array (GroundingChunkCustomMetadata)`

Optional. User-provided metadata about the retrieved context.

{% /summary %}

**stringValue**: `string`

Optional. The string value of the metadata.

{% details %}

{% summary %}

**stringListValue**: `GroundingChunkStringList`

Optional. A list of string values for the metadata.

{% /summary %}

**values**: `array (string)`

The string values of the list.

{% /details %}

**numericValue**: `number`

Optional. The numeric value of the metadata. The expected range for this value depends on the specific `key` used.

**key**: `string`

The key of the metadata.

{% /details %}

**pageNumber**: `integer`

Optional. Page number of the retrieved context, if applicable.

**mediaId**: `string`

Optional. The media blob resource name for multimodal file search results. Format: fileSearchStores/{file_search_store_id}/media/{blob_id}

{% /details %}

{% details %}

{% summary %}

**maps**: `Maps`

Optional. Grounding chunk from Google Maps.

{% /summary %}

**uri**: `string`

URI reference of the place.

**title**: `string`

Title of the place.

**text**: `string`

Text description of the place answer.

**placeId**: `string`

The ID of the place, in `places/{place_id}` format. A user can use this ID to look up that place.

{% details %}

{% summary %}

**placeAnswerSources**: `PlaceAnswerSources`

Sources that provide answers about the features of a given place in Google Maps.

{% /summary %}

{% details %}

{% summary %}

**reviewSnippets**: `array (ReviewSnippet)`

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

{% /summary %}

**reviewId**: `string`

The ID of the review snippet.

**googleMapsUri**: `string`

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

**title**: `string`

Title of the review.

{% /details %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingSupports**: `array (GoogleAiGenerativelanguageV1betaGroundingSupport)`

List of grounding support.

{% /summary %}

{% details %}

{% summary %}

**segment**: `GoogleAiGenerativelanguageV1betaSegment`

Segment of the content this support belongs to.

{% /summary %}

**partIndex**: `integer`

The index of a Part object within its parent Content object.

**startIndex**: `integer`

Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero.

**endIndex**: `integer`

End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero.

**text**: `string`

The text corresponding to the segment from the response.

{% /details %}

**groundingChunkIndices**: `array (integer)`

Optional. A list of indices (into 'grounding_chunk' in `response.candidate.grounding_metadata`) specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. If the response is streaming, the grounding_chunk_indices refer to the indices across all responses. It is the client's responsibility to accumulate the grounding chunks from all responses (while maintaining the same order).

**confidenceScores**: `array (number)`

Optional. Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices.

**renderedParts**: `array (integer)`

Output only. Indices into the `parts` field of the candidate's content. These indices specify which rendered parts are associated with this support source.

{% /details %}

{% details %}

{% summary %}

**retrievalMetadata**: `RetrievalMetadata`

Metadata related to retrieval in the grounding flow.

{% /summary %}

**googleSearchDynamicRetrievalScore**: `number`

Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger google search.

{% /details %}

**webSearchQueries**: `array (string)`

Web search queries for the following-up web search.

**imageSearchQueries**: `array (string)`

Image search queries used for grounding.

**googleMapsWidgetContextToken**: `string`

Optional. Resource name of the Google Maps widget context token that can be used with the PlacesContextElement widget in order to render contextual data. Only populated in the case that grounding with Google Maps is enabled.

{% /details %}

{% hr /%}

**avgLogprobs**: `number`

Output only. Average log probability score of the candidate.

{% hr /%}

{% details %}

{% summary %}

**logprobsResult**: `LogprobsResult`

Output only. Log-likelihood scores for the response tokens and top tokens

{% /summary %}

**logProbabilitySum**: `number`

Sum of log probabilities for all tokens.

{% details %}

{% summary %}

**topCandidates**: `array (TopCandidates)`

Length = total number of decoding steps.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (LogprobsResultCandidate)`

Sorted by log probability in descending order.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**chosenCandidates**: `array (LogprobsResultCandidate)`

Length = total number of decoding steps. The chosen candidates may or may not be in top_candidates.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**urlContextMetadata**: `UrlContextMetadata`

Output only. Metadata related to url context retrieval tool.

{% /summary %}

{% details %}

{% summary %}

**urlMetadata**: `array (UrlMetadata)`

List of url context.

{% /summary %}

**retrievedUrl**: `string`

Retrieved url by the tool.

{% details %}

{% summary %}

**urlRetrievalStatus**: `enum (string)`

Status of the url retrieval.

{% /summary %}

Possible values:

- `URL_RETRIEVAL_STATUS_UNSPECIFIED`: Default value. This value is unused.
- `URL_RETRIEVAL_STATUS_SUCCESS`: Url retrieval is successful.
- `URL_RETRIEVAL_STATUS_ERROR`: Url retrieval is failed due to error.
- `URL_RETRIEVAL_STATUS_PAYWALL`: Url retrieval is failed because the content is behind paywall.
- `URL_RETRIEVAL_STATUS_UNSAFE`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**continuationToken**: `string`

An optional opaque continuation token returned when `finish_reason` is `CONTINUATION`. Clients can pass this token in a subsequent [`GenerateContentRequest`](/api-reference/generate-content/stream-generate-content#request-body) to continue generation.

### CitationMetadata {% class="hide-from-toc" id="Resource:CitationMetadata" %}

A collection of source attributions for a piece of content.

**Properties:**

{% details %}

{% summary %}

**citationSources**: `array (CitationSource)`

Citations to sources for a specific response.

{% /summary %}

**startIndex**: `integer`

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

**endIndex**: `integer`

Optional. End of the attributed segment, exclusive.

**uri**: `string`

Optional. URI that is attributed as a source for a portion of the text.

**license**: `string`

Optional. License for the GitHub project that is attributed as a source for segment. License info is required for code citations.

{% /details %}

### HarmCategory {% class="hide-from-toc" id="Resource:HarmCategory" %}

**Possible values:**

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

### ModalityTokenCount {% class="hide-from-toc" id="Resource:ModalityTokenCount" %}

Represents token counting info for a single modality.

**Properties:**

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

{% hr /%}

**tokenCount**: `integer`

Number of tokens.

### SafetyRating {% class="hide-from-toc" id="Resource:SafetyRating" %}

Safety rating for a piece of content.

The safety rating contains the category of harm and the
harm probability level in that category for a piece of content.
Content is classified for safety across a number of
harm categories and the probability of the harm classification is included
here.

**Properties:**

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} [`HarmCategory`](/api-reference/generate-content/stream-generate-content#Resource:HarmCategory)

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

{% hr /%}

**blocked**: `boolean`

Was this content blocked because of this rating?

### SafetySetting {% class="hide-from-toc" id="Resource:SafetySetting" %}

Safety setting, affecting the safety-blocking behavior.

Passing a safety setting for a category changes the allowed probability that
content is blocked.

**Properties:**

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} [`HarmCategory`](/api-reference/generate-content/stream-generate-content#Resource:HarmCategory)

The category for this setting.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

Controls the probability threshold at which harm is blocked.

{% /summary %}

Possible values:

- `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: Threshold is unspecified.
- `BLOCK_LOW_AND_ABOVE`: Content with NEGLIGIBLE will be allowed.
- `BLOCK_MEDIUM_AND_ABOVE`: Content with NEGLIGIBLE and LOW will be allowed.
- `BLOCK_ONLY_HIGH`: Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
- `BLOCK_NONE`: All content will be allowed.
- `OFF`: Turn off the safety filter.

{% /details %}

### ServiceTier {% class="hide-from-toc" id="Resource:ServiceTier" %}

**Possible values:**

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

### Content {% class="hide-from-toc" id="Resource:Content" %}

The base structured datatype containing multi-part content of a message.

A [`Content`](/api-reference/generate-content/stream-generate-content#Resource:Content) includes a `role` field designating the producer of the [`Content`](/api-reference/generate-content/stream-generate-content#Resource:Content)
and a `parts` field containing multi-part data that contains the content of
the message turn.

**Properties:**

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

{% hr /%}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

### Schema {% class="hide-from-toc" id="Resource:Schema" %}

The [`Schema`](/api-reference/generate-content/stream-generate-content#Resource:Schema) object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
Represents a select subset of an [OpenAPI 3.0 schema
object](https://spec.openapis.org/oas/v3.0.3#schema).

**Properties:**

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

{% hr /%}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

{% hr /%}

**title**: `string`

Optional. The title of the schema.

{% hr /%}

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

{% hr /%}

**nullable**: `boolean`

Optional. Indicates if the value may be null.

{% hr /%}

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

{% hr /%}

**items**: [`Schema`](/api-reference/generate-content/stream-generate-content#Resource:Schema)

Optional. Schema of the elements of Type.ARRAY.

{% hr /%}

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

{% hr /%}

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

{% hr /%}

**properties**: `object`

Optional. Properties of Type.OBJECT.

{% hr /%}

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

{% hr /%}

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

{% hr /%}

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

{% hr /%}

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

{% hr /%}

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

{% hr /%}

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

{% hr /%}

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

{% hr /%}

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

{% hr /%}

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

{% hr /%}

**anyOf**: `array (`[`Schema`](/api-reference/generate-content/stream-generate-content#Resource:Schema)`)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

{% hr /%}

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

{% hr /%}

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

### Tool {% class="hide-from-toc" id="Resource:Tool" %}

Tool details that the model may use to generate response.

A [`Tool`](/api-reference/generate-content/stream-generate-content#Resource:Tool) is a piece of code that enables the system to interact with
external systems to perform an action, or set of actions, outside of
knowledge and scope of the model.

**Properties:**

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

**parameters**: [`Schema`](/api-reference/generate-content/stream-generate-content#Resource:Schema)

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

**response**: [`Schema`](/api-reference/generate-content/stream-generate-content#Resource:Schema)

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

# Creating an ephemeral auth token
Source: https://aistudio.google.com/api-reference/generate-content/create-token
Description: Creates a token that can be used to constrain the behavior of a BidiGenerateContent session.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/auth_tokens`

Creates a token that can be used to constrain the behavior of a
BidiGenerateContent session.

{% two-column-layout %}

{% left-column %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**bidiGenerateContentSetup**: `BidiGenerateContentSetup`

Optional. Input only. Immutable. Configuration specific to `BidiGenerateContent`.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The model's resource name. This serves as an ID for the Model to use. Format: `models/{model}`

{% details %}

{% summary %}

**generationConfig**: `GenerationConfig`

Optional. Generation config. The following fields are not supported:

- `response_logprobs`
- `response_mime_type`
- `logprobs`
- `response_schema`
- `response_json_schema`
- `stop_sequence`
- `skip_response_cache`
- `routing_config`
- `audio_timestamp`

{% /summary %}

**candidateCount**: `integer`

Optional. Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)

**stopSequences**: `array (string)`

Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a `stop_sequence`. The stop sequence will not be included as part of the response.

**maxOutputTokens**: `integer`

Optional. The maximum number of tokens to include in a response candidate. Note: The default value varies by model, see the `Model.output_token_limit` attribute of the `Model` returned from the `getModel` function.

**temperature**: `number`

Optional. Controls the randomness of the output. Note: The default value varies by model, see the `Model.temperature` attribute of the `Model` returned from the `getModel` function. Values can range from [0.0, 2.0]. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topP**: `number`

Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topK**: `integer`

Optional. The maximum number of tokens to consider when sampling. Gemini models use Top-p (nucleus) sampling or a combination of Top-k and nucleus sampling. Top-k sampling considers the set of `top_k` most probable tokens. Models running with nucleus sampling don't allow top_k setting. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**seed**: `integer`

Optional. Seed used in decoding. If not set, the request uses a randomly generated seed.

**responseMimeType**: `string`

Optional. MIME type of the generated candidate text. Supported MIME types are: `text/plain`: (default) Text output. `application/json`: JSON response in the response candidates. `text/x.enum`: ENUM as a string response in the response candidates. Refer to the [docs](/docs/file-input-methods#text-file-types) for a list of all supported text MIME types.

**responseJsonSchema**: `object`

Optional. An internal detail. Use `responseJsonSchema` rather than this field.

**presencePenalty**: `number`

Optional. Presence penalty applied to the next token's logprobs if the token has already been seen in the response. This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequency_penalty for a penalty that increases with each use. A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary. A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.

**frequencyPenalty**: `number`

Optional. Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far. A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses. Caution: A _negative_ penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the max_output_tokens limit.

**responseLogprobs**: `boolean`

Optional. If true, export the logprobs results in response.

**logprobs**: `integer`

Optional. Only valid if response_logprobs=True. This sets the number of top logprobs, including the chosen candidate, to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].

**enableEnhancedCivicAnswers**: `boolean`

Optional. Enables enhanced civic answers. It may not be available for all models.

{% details %}

{% summary %}

**responseModalities**: `array (enum (string))`

Optional. The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response. A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned. An empty list is equivalent to requesting only text.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Default value.
- `TEXT`: Indicates the model should return text.
- `IMAGE`: Indicates the model should return images.
- `AUDIO`: Indicates the model should return audio.

{% /details %}

{% details %}

{% summary %}

**speechConfig**: `SpeechConfig`

Optional. The speech generation config.

{% /summary %}

{% details %}

{% summary %}

**voiceConfig**: `VoiceConfig`

The configuration in case of single-voice output.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% details %}

{% summary %}

**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig`

Optional. The configuration for the multi-speaker setup. It is mutually exclusive with the voice_config field.

{% /summary %}

{% details %}

{% summary %}

**speakerVoiceConfigs**: {% mark %}required{% /mark %} `array (SpeakerVoiceConfig)`

All the enabled speaker voices.

{% /summary %}

**speaker**: {% mark %}required{% /mark %} `string`

The name of the speaker to use. Should be the same as in the prompt.

{% details %}

{% summary %}

**voiceConfig**: {% mark %}required{% /mark %} `VoiceConfig`

The configuration for the voice to use.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% /details %}

{% /details %}

**languageCode**: `string`

Optional. The IETF [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code that the user configured the app to use. Used for speech recognition and synthesis. Valid values are: `de-DE`, `en-AU`, `en-GB`, `en-IN`, `en-US`, `es-US`, `fr-FR`, `hi-IN`, `pt-BR`, `ar-XA`, `es-ES`, `fr-CA`, `id-ID`, `it-IT`, `ja-JP`, `tr-TR`, `vi-VN`, `bn-IN`, `gu-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `ta-IN`, `te-IN`, `nl-NL`, `ko-KR`, `cmn-CN`, `pl-PL`, `ru-RU`, and `th-TH`.

{% /details %}

{% details %}

{% summary %}

**thinkingConfig**: `ThinkingConfig`

Optional. Config for thinking features. An error will be returned if this field is set for models that don't support thinking.

{% /summary %}

**includeThoughts**: `boolean`

Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.

**thinkingBudget**: `integer`

The number of thoughts tokens that the model should generate.

{% details %}

{% summary %}

**thinkingLevel**: `enum (string)`

Optional. Controls the maximum depth of the model's internal reasoning process before it produces a response. The default value is model-dependent. Refer to the [Thinking levels guide](/docs/thinking#thinking-levels) for more details. Recommended for Gemini 3 or later models. Use with earlier models results in an error.

{% /summary %}

Possible values:

- `THINKING_LEVEL_UNSPECIFIED`: Default value.
- `MINIMAL`: Little to no thinking.
- `LOW`: Low thinking level.
- `MEDIUM`: Medium thinking level.
- `HIGH`: High thinking level.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**imageConfig**: `ImageConfig`

Optional. Config for image generation. An error will be returned if this field is set for models that don't support these config options.

{% /summary %}

**aspectRatio**: `string`

Optional. The aspect ratio of the image to generate. Supported aspect ratios: `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, or `21:9`. If not specified, the model will choose a default aspect ratio based on any reference images provided.

**imageSize**: `string`

Optional. Specifies the size of generated images. Supported values are `512`, `1K`, `2K`, `4K`. If not specified, the model will use default value `1K`.

{% /details %}

{% details %}

{% summary %}

**mediaResolution**: `enum (string)`

Optional. If specified, the media resolution specified will be used.

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low (64 tokens).
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium (256 tokens).
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high (zoomed reframing with 256 tokens).

{% /details %}

**enableAffectiveDialog**: `boolean`

Optional. If enabled, the model will detect emotions and adapt its responses accordingly.

{% details %}

{% summary %}

**responseFormat**: `ResponseFormatConfig`

Optional. Configuration for the response output format. Allows specifying output configuration per modality (text, audio, image) in a flat structure.

{% /summary %}

{% details %}

{% summary %}

**text**: `TextResponseFormat`

Optional. Text output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the text output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `APPLICATION_JSON`: JSON output format.
- `TEXT_PLAIN`: Plain text output format.

{% /details %}

**schema**: `object`

Optional. The JSON schema that the output should conform to. Only applicable when mime_type is APPLICATION_JSON.

{% /details %}

{% details %}

{% summary %}

**audio**: `AudioResponseFormat`

Optional. Audio output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the audio output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `AUDIO_MP3`: MP3 audio format.
- `AUDIO_OGG_OPUS`: OGG Opus audio format.
- `AUDIO_L16`: Raw PCM (L16) audio format.
- `AUDIO_WAV`: WAV audio format.
- `AUDIO_ALAW`: A-law audio format.
- `AUDIO_MULAW`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the audio output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Audio data is returned inline in the response.
- `URI`: Audio data is returned as a URI.

{% /details %}

**sampleRate**: `integer`

Optional. Sample rate in Hz.

**bitRate**: `integer`

Optional. Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}

**image**: `ImageResponseFormat`

Optional. Image output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the image output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_JPEG`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the image output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Image data is returned inline in the response.
- `URI`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspectRatio**: `enum (string)`

Optional. The aspect ratio for the image output.

{% /summary %}

Possible values:

- `ASPECT_RATIO_UNSPECIFIED`: Default value. This value is unused.
- `ASPECT_RATIO_ONE_BY_ONE`: 1:1 aspect ratio.
- `ASPECT_RATIO_TWO_BY_THREE`: 2:3 aspect ratio.
- `ASPECT_RATIO_THREE_BY_TWO`: 3:2 aspect ratio.
- `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 aspect ratio.
- `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 aspect ratio.
- `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 aspect ratio.
- `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 aspect ratio.
- `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 aspect ratio.
- `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 aspect ratio.
- `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 aspect ratio.
- `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**imageSize**: `enum (string)`

Optional. The size of the image output.

{% /summary %}

Possible values:

- `IMAGE_SIZE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_SIZE_FIVE_TWELVE`: 512px image size.
- `IMAGE_SIZE_ONE_K`: 1K image size.
- `IMAGE_SIZE_TWO_K`: 2K image size.
- `IMAGE_SIZE_FOUR_K`: 4K image size.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**translationConfig**: `TranslationConfig`

Optional. Config for translation.

{% /summary %}

**targetLanguageCode**: {% mark %}required{% /mark %} `string`

The target language for translation. Supported values are BCP-47 language codes (e.g. "en", "es", "fr").

**echoTargetLanguage**: `boolean`

Optional. If true, the model will generate audio when the target language is spoken, essentially it will parrot the input. If false, we will not produce audio for the target language.

{% /details %}

{% details %}

{% summary %}

**audioTranscriptionConfig**: `AudioTranscriptionConfig`

Optional. Config for audio transcription (speech recognition).

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

**systemInstruction**: [`Content`](/api-reference/generate-content/create-token#Resource:Content)

Optional. The user provided system instructions for the model. Note: Only text should be used in parts and content in each part will be in a separate paragraph.

**tools**: `array (`[`Tool`](/api-reference/generate-content/create-token#Resource:Tool)`)`

Optional. A list of `Tools` the model may use to generate the next response. A [`Tool`](/api-reference/generate-content/create-token#Resource:Tool) is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.

{% details %}

{% summary %}

**realtimeInputConfig**: `RealtimeInputConfig`

Optional. Configures the handling of realtime input.

{% /summary %}

{% details %}

{% summary %}

**automaticActivityDetection**: `AutomaticActivityDetection`

Optional. If not set, automatic activity detection is enabled by default. If automatic voice detection is disabled, the client must send activity signals.

{% /summary %}

**disabled**: `boolean`

Optional. If enabled (the default), detected voice and text input count as activity. If disabled, the client must send activity signals.

{% details %}

{% summary %}

**startOfSpeechSensitivity**: `enum (string)`

Optional. Determines how likely speech is to be detected.

{% /summary %}

Possible values:

- `START_SENSITIVITY_UNSPECIFIED`: The default is START_SENSITIVITY_HIGH.
- `START_SENSITIVITY_HIGH`: Automatic detection will detect the start of speech more often.
- `START_SENSITIVITY_LOW`: Automatic detection will detect the start of speech less often.

{% /details %}

**prefixPaddingMs**: `integer`

Optional. The required duration of detected speech before start-of-speech is committed. The lower this value, the more sensitive the start-of-speech detection is and shorter speech can be recognized. However, this also increases the probability of false positives.

{% details %}

{% summary %}

**endOfSpeechSensitivity**: `enum (string)`

Optional. Determines how likely detected speech is ended.

{% /summary %}

Possible values:

- `END_SENSITIVITY_UNSPECIFIED`: The default is END_SENSITIVITY_HIGH.
- `END_SENSITIVITY_HIGH`: Automatic detection ends speech more often.
- `END_SENSITIVITY_LOW`: Automatic detection ends speech less often.

{% /details %}

**silenceDurationMs**: `integer`

Optional. The required duration of detected non-speech (e.g. silence) before end-of-speech is committed. The larger this value, the longer speech gaps can be without interrupting the user's activity but this will increase the model's latency.

{% /details %}

{% details %}

{% summary %}

**activityHandling**: `ActivityHandling`

Optional. Defines what effect activity has.

{% /summary %}

Possible values:

- `ACTIVITY_HANDLING_UNSPECIFIED`: If unspecified, the default behavior is `START_OF_ACTIVITY_INTERRUPTS`.
- `START_OF_ACTIVITY_INTERRUPTS`: If true, start of activity will interrupt the model's response (also called "barge in"). The model's current response will be cut-off in the moment of the interruption. This is the default behavior.
- `NO_INTERRUPTION`: The model's response will not be interrupted.

{% /details %}

{% details %}

{% summary %}

**turnCoverage**: `enum (string)`

Optional. Defines which input is included in the user's turn.

{% /summary %}

Possible values:

- `TURN_COVERAGE_UNSPECIFIED`: If unspecified, a default behavior is selected based on the model. E.g., for Gemini 2.5, the default is `TURN_INCLUDES_ONLY_ACTIVITY`, while for Gemini 3.1 and onwards, it's `TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`.
- `TURN_INCLUDES_ONLY_ACTIVITY`: Includes activity since the last turn, excluding inactivity (e.g. silence on the audio stream).
- `TURN_INCLUDES_ALL_INPUT`: Includes all realtime input since the last turn, including inactivity (e.g. silence on the audio stream).
- `TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`: Includes audio activity and all video since the last turn. With automatic activity detection, audio activity means speech and excludes silence.

{% /details %}

**interimTranscriptTimestampEnabled**: `boolean`

Optional. Configures interim transcript timestamps.

{% /details %}

{% details %}

{% summary %}

**sessionResumption**: `SessionResumptionConfig`

Optional. Configures session resumption mechanism. If included, the server will send `SessionResumptionUpdate` messages.

{% /summary %}

**handle**: `string`

The handle of a previous session. If not present then a new session is created. Session handles come from `SessionResumptionUpdate.token` values in previous connections.

{% /details %}

{% details %}

{% summary %}

**contextWindowCompression**: `ContextWindowCompressionConfig`

Optional. Configures a context window compression mechanism. If included, the server will automatically reduce the size of the context when it exceeds the configured length.

{% /summary %}

{% details %}

{% summary %}

**slidingWindow**: `SlidingWindow`

A sliding-window mechanism.

{% /summary %}

**targetTokens**: `string`

The target number of tokens to keep. The default value is trigger_tokens/2. Discarding parts of the context window causes a temporary latency increase so this value should be calibrated to avoid frequent compression operations.

{% /details %}

**triggerTokens**: `string`

The number of tokens (before running a turn) required to trigger a context window compression. This can be used to balance quality against latency as shorter context windows may result in faster model responses. However, any compression operation will cause a temporary latency increase, so they should not be triggered frequently. If not set, the default is 80% of the model's context window limit. This leaves 20% for the next user request/model response.

{% /details %}

{% details %}

{% summary %}

**inputAudioTranscription**: `AudioTranscriptionConfig`

Optional. If set, enables transcription of voice input. The transcription aligns with the input audio language, if configured.

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**outputAudioTranscription**: `AudioTranscriptionConfig`

Optional. If set, enables transcription of the model's audio output. The transcription aligns with the language code specified for the output audio, if configured.

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**proactivity**: `ProactivityConfig`

Optional. Configures the proactivity of the model. This allows the model to respond proactively to the input and to ignore irrelevant input.

{% /summary %}

**proactiveAudio**: `boolean`

Optional. If enabled, the model can reject responding to the last prompt. For example, this allows the model to ignore out of context speech or to stay silent if the user did not make a request, yet.

{% /details %}

{% details %}

{% summary %}

**historyConfig**: `HistoryConfig`

Optional. Configures the exchange of history between the client and the server.

{% /summary %}

**initialHistoryInClientContent**: `boolean`

Optional. If true, after sending `setup_complete`, the server will wait and at first process `client_content` messages until `turn_complete` is `true`. This initial history will not trigger a model call and may end with role `MODEL`. After `turn_complete` is `true`, the client can start the realtime conversation via `realtime_input`.

{% /details %}

**labels**: `object`

Optional. Labels with user-defined metadata for the request. Optional. Labels must follow standard unified Cloud label requirements:

- Label keys must start with a letter.
- Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes.
- International characters are allowed.

Usage:

- Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)

{% /details %}

{% hr /%}

**expireTime**: `string`

Optional. Input only. Immutable. An optional time after which, when using the resulting token, messages in BidiGenerateContent sessions will be rejected. (Gemini may preemptively close the session after this time.) If not set then this defaults to 30 minutes in the future. If set, this value must be less than 20 hours in the future.

{% hr /%}

**newSessionExpireTime**: `string`

Optional. Input only. Immutable. The time after which new Live API sessions using the token resulting from this request will be rejected. If not set this defaults to 60 seconds in the future. If set, this value must be less than 20 hours in the future.

{% hr /%}

**uses**: `integer`

Optional. Input only. Immutable. The number of times the token can be used. If this value is zero then no limit is applied. Resuming a Live API session does not count as a use. If unspecified, the default is 1.

{% hr /%}

**fieldMask**: `string`

Optional. Input only. Immutable. If field_mask is empty, and `bidi_generate_content_setup` is not present, then the effective `BidiGenerateContentSetup` message is taken from the Live API connection. If field_mask is empty, and `bidi_generate_content_setup` _is_ present, then the effective `BidiGenerateContentSetup` message is taken entirely from `bidi_generate_content_setup` in this request. The setup message from the Live API connection is ignored. If field_mask is not empty, then the corresponding fields from `bidi_generate_content_setup` will overwrite the fields from the setup message in the Live API connection.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**name**: `string`

Output only. Identifier. The token itself.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "bidiGenerateContentSetup": {
    "model": "string",
    "generationConfig": {
      "candidateCount": 0,
      "stopSequences": [
        "string"
      ],
      "maxOutputTokens": 0,
      "temperature": 0.0,
      "topP": 0.0,
      "topK": 0,
      "seed": 0,
      "responseMimeType": "string",
      "responseJsonSchema": {},
      "presencePenalty": 0.0,
      "frequencyPenalty": 0.0,
      "responseLogprobs": true,
      "logprobs": 0,
      "enableEnhancedCivicAnswers": true,
      "responseModalities": [
        "MODALITY_UNSPECIFIED"
      ],
      "speechConfig": {
        "voiceConfig": {
          "prebuiltVoiceConfig": "...",
          "voice": "string"
        },
        "multiSpeakerVoiceConfig": {
          "speakerVoiceConfigs": [
            "..."
          ]
        },
        "languageCode": "string"
      },
      "thinkingConfig": {
        "includeThoughts": true,
        "thinkingBudget": 0,
        "thinkingLevel": "THINKING_LEVEL_UNSPECIFIED"
      },
      "imageConfig": {
        "aspectRatio": "string",
        "imageSize": "string"
      },
      "mediaResolution": "MEDIA_RESOLUTION_UNSPECIFIED",
      "enableAffectiveDialog": true,
      "responseFormat": {
        "text": {
          "mimeType": "MIME_TYPE_UNSPECIFIED",
          "schema": {}
        },
        "audio": {
          "mimeType": "MIME_TYPE_UNSPECIFIED",
          "delivery": "DELIVERY_UNSPECIFIED",
          "sampleRate": 0,
          "bitRate": 0
        },
        "image": {
          "mimeType": "MIME_TYPE_UNSPECIFIED",
          "delivery": "DELIVERY_UNSPECIFIED",
          "aspectRatio": "ASPECT_RATIO_UNSPECIFIED",
          "imageSize": "IMAGE_SIZE_UNSPECIFIED"
        }
      },
      "translationConfig": {
        "targetLanguageCode": "string",
        "echoTargetLanguage": true
      },
      "audioTranscriptionConfig": {
        "languageCodes": [
          "string"
        ],
        "customVocabulary": [
          "string"
        ],
        "wordTimestamp": true,
        "diarization": true,
        "mode": "MODE_UNSPECIFIED"
      }
    },
    "systemInstruction": {
      "parts": [
        {
          "text": "string",
          "inlineData": {
            "mimeType": "...",
            "data": "...",
            "displayName": "..."
          },
          "functionCall": {
            "name": "...",
            "id": "...",
            "args": "..."
          },
          "functionResponse": {
            "name": "...",
            "response": "...",
            "id": "...",
            "parts": "...",
            "willContinue": "...",
            "scheduling": "..."
          },
          "fileData": {
            "fileUri": "...",
            "mimeType": "...",
            "displayName": "..."
          },
          "executableCode": {
            "language": "...",
            "code": "...",
            "id": "..."
          },
          "codeExecutionResult": {
            "outcome": "...",
            "id": "...",
            "output": "..."
          },
          "toolCall": {
            "toolType": "...",
            "id": "...",
            "toolName": "...",
            "args": "..."
          },
          "toolResponse": {
            "toolType": "...",
            "id": "...",
            "response": "..."
          },
          "videoMetadata": {
            "startOffset": "...",
            "endOffset": "...",
            "fps": "..."
          },
          "thought": true,
          "thoughtSignature": "string",
          "partMetadata": {},
          "mediaResolution": {
            "level": "..."
          },
          "mediaProcessing": "MEDIA_PROCESSING_UNSPECIFIED",
          "audioTranscription": {
            "text": "...",
            "speakerLabel": "...",
            "words": "..."
          },
          "speechMetadata": {
            "speaker": "...",
            "style": "..."
          }
        }
      ],
      "role": "string"
    },
    "tools": [
      {
        "functionDeclarations": [
          {
            "name": "string",
            "description": "string",
            "parameters": "...",
            "parametersJsonSchema": {},
            "response": "...",
            "responseJsonSchema": {},
            "behavior": "UNSPECIFIED"
          }
        ],
        "googleSearchRetrieval": {
          "dynamicRetrievalConfig": {
            "mode": "...",
            "dynamicThreshold": "..."
          }
        },
        "codeExecution": {},
        "googleSearch": {
          "timeRangeFilter": {
            "startTime": "...",
            "endTime": "..."
          },
          "searchTypes": {
            "webSearch": "...",
            "imageSearch": "..."
          }
        },
        "computerUse": {
          "environment": "ENVIRONMENT_UNSPECIFIED",
          "excludedPredefinedFunctions": [
            "string"
          ],
          "enablePromptInjectionDetection": true,
          "disabledSafetyPolicies": [
            "SAFETY_POLICY_UNSPECIFIED"
          ]
        },
        "urlContext": {},
        "fileSearch": {
          "fileSearchStoreNames": [
            "string"
          ],
          "topK": 0,
          "metadataFilter": "string"
        },
        "mcpServers": [
          {
            "streamableHttpTransport": "...",
            "name": "string"
          }
        ],
        "googleMaps": {
          "enableWidget": true
        }
      }
    ],
    "realtimeInputConfig": {
      "automaticActivityDetection": {
        "disabled": true,
        "startOfSpeechSensitivity": "START_SENSITIVITY_UNSPECIFIED",
        "prefixPaddingMs": 0,
        "endOfSpeechSensitivity": "END_SENSITIVITY_UNSPECIFIED",
        "silenceDurationMs": 0
      },
      "activityHandling": "ACTIVITY_HANDLING_UNSPECIFIED",
      "turnCoverage": "TURN_COVERAGE_UNSPECIFIED",
      "interimTranscriptTimestampEnabled": true
    },
    "sessionResumption": {
      "handle": "string"
    },
    "contextWindowCompression": {
      "slidingWindow": {
        "targetTokens": "string"
      },
      "triggerTokens": "string"
    },
    "inputAudioTranscription": {
      "languageCodes": [
        "string"
      ],
      "customVocabulary": [
        "string"
      ],
      "wordTimestamp": true,
      "diarization": true,
      "mode": "MODE_UNSPECIFIED"
    },
    "outputAudioTranscription": {
      "languageCodes": [
        "string"
      ],
      "customVocabulary": [
        "string"
      ],
      "wordTimestamp": true,
      "diarization": true,
      "mode": "MODE_UNSPECIFIED"
    },
    "proactivity": {
      "proactiveAudio": true
    },
    "historyConfig": {
      "initialHistoryInClientContent": true
    },
    "labels": {}
  },
  "name": "string",
  "expireTime": "string",
  "newSessionExpireTime": "string",
  "uses": 0,
  "fieldMask": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### Content {% class="hide-from-toc" id="Resource:Content" %}

The base structured datatype containing multi-part content of a message.

A [`Content`](/api-reference/generate-content/create-token#Resource:Content) includes a `role` field designating the producer of the [`Content`](/api-reference/generate-content/create-token#Resource:Content)
and a `parts` field containing multi-part data that contains the content of
the message turn.

**Properties:**

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

{% hr /%}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

### Schema {% class="hide-from-toc" id="Resource:Schema" %}

The [`Schema`](/api-reference/generate-content/create-token#Resource:Schema) object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
Represents a select subset of an [OpenAPI 3.0 schema
object](https://spec.openapis.org/oas/v3.0.3#schema).

**Properties:**

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

{% hr /%}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

{% hr /%}

**title**: `string`

Optional. The title of the schema.

{% hr /%}

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

{% hr /%}

**nullable**: `boolean`

Optional. Indicates if the value may be null.

{% hr /%}

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

{% hr /%}

**items**: [`Schema`](/api-reference/generate-content/create-token#Resource:Schema)

Optional. Schema of the elements of Type.ARRAY.

{% hr /%}

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

{% hr /%}

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

{% hr /%}

**properties**: `object`

Optional. Properties of Type.OBJECT.

{% hr /%}

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

{% hr /%}

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

{% hr /%}

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

{% hr /%}

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

{% hr /%}

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

{% hr /%}

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

{% hr /%}

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

{% hr /%}

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

{% hr /%}

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

{% hr /%}

**anyOf**: `array (`[`Schema`](/api-reference/generate-content/create-token#Resource:Schema)`)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

{% hr /%}

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

{% hr /%}

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

### Tool {% class="hide-from-toc" id="Resource:Tool" %}

Tool details that the model may use to generate response.

A [`Tool`](/api-reference/generate-content/create-token#Resource:Tool) is a piece of code that enables the system to interact with
external systems to perform an action, or set of actions, outside of
knowledge and scope of the model.

**Properties:**

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

**parameters**: [`Schema`](/api-reference/generate-content/create-token#Resource:Schema)

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

**response**: [`Schema`](/api-reference/generate-content/create-token#Resource:Schema)

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

# Live API - WebSockets API reference
Source: https://aistudio.google.com/api-reference/live
Description: Reference for the stateful, WebSockets-based Live API, including session configuration and the client and server messages it exchanges.

{% callout type="note" %}
**Preview:** The Live API is in preview.
{% /callout %}

The Live API is a stateful API
that uses [WebSockets](https://en.wikipedia.org/wiki/WebSocket).
In this section, you'll find additional details regarding the WebSockets API.

## Methods {% id="methods" %}

{% table %}
* Method
* Endpoint
---
* [Starting a Live session](/api-reference/live/bidi-generate-content)
* {% mark class="http-wss" %}{% icon name="sync_alt" /%}`WSS`{% /mark %} `/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent`

  Opens a stateful WebSocket session for exchanging text, audio, and video
  with the model.
---
* [Creating an ephemeral auth token](/api-reference/generate-content/create-token)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/auth_tokens`

  Creates a token that can be used to constrain the behavior of a
  BidiGenerateContent session.
{% /table %}

## Data Models {% id="data-models" %}

### ActivityEnd {% id="BidiGenerateContentRealtimeInput.ActivityEnd" %}

Marks the end of user activity.

This type has no fields.

### ActivityHandling {% id="ActivityHandling" %}

The different ways of handling user activity.

{% table %}
* Value
* Description
---
* `ACTIVITY_HANDLING_UNSPECIFIED`
* If unspecified, the default behavior is `START_OF_ACTIVITY_INTERRUPTS`.
---
* `START_OF_ACTIVITY_INTERRUPTS`
* If true, start of activity will interrupt the model's response (also called "barge in"). The model's current response will be cut-off in the moment of the interruption. This is the default behavior.
---
* `NO_INTERRUPTION`
* The model's response will not be interrupted.
{% /table %}

### ActivityStart {% id="BidiGenerateContentRealtimeInput.ActivityStart" %}

Marks the start of user activity.

This type has no fields.

### AudioTranscriptionConfig {% id="AudioTranscriptionConfig" %}

The audio transcription configuration.

{% table %}
* Field
* Type
* Description
---
* `languageCodes[]`
* `string`
* Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.
---
* `customVocabulary[]`
* `string`
* Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).
---
* `wordTimestamp`
* `bool`
* Optional. Configures word-level timestamp generation.
---
* `diarization`
* `bool`
* Optional. Configures speaker diarization.
---
* `mode`
* [`Mode`](/api-reference/live#AudioTranscriptionConfig.Mode)
* Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.
{% /table %}

### Mode {% id="AudioTranscriptionConfig.Mode" %}

Transcription mode.

{% table %}
* Value
* Description
---
* `MODE_UNSPECIFIED`
* Unspecified transcription mode.
---
* `VERBATIM`
* Verbatim transcription mode.
---
* `SMART`
* Smart transcription mode.
{% /table %}

### AutomaticActivityDetection {% id="RealtimeInputConfig.AutomaticActivityDetection" %}

Configures automatic detection of activity.

{% table %}
* Field
* Type
* Description
---
* `disabled`
* `bool`
* Optional. If enabled (the default), detected voice and text input count as activity. If disabled, the client must send activity signals.
---
* `startOfSpeechSensitivity`
* [`StartSensitivity`](/api-reference/live#RealtimeInputConfig.AutomaticActivityDetection.StartSensitivity)
* Optional. Determines how likely speech is to be detected.
---
* `prefixPaddingMs`
* `int32`
* Optional. The required duration of detected speech before start-of-speech is committed. The lower this value, the more sensitive the start-of-speech detection is and shorter speech can be recognized. However, this also increases the probability of false positives.
---
* `endOfSpeechSensitivity`
* [`EndSensitivity`](/api-reference/live#RealtimeInputConfig.AutomaticActivityDetection.EndSensitivity)
* Optional. Determines how likely detected speech is ended.
---
* `silenceDurationMs`
* `int32`
* Optional. The required duration of detected non-speech (e.g. silence) before end-of-speech is committed. The larger this value, the longer speech gaps can be without interrupting the user's activity but this will increase the model's latency.
{% /table %}

### BidiGenerateContentClientContent {% id="BidiGenerateContentClientContent" %}

Incremental update of the current conversation delivered from the client. All of the content here is unconditionally appended to the conversation history and used as part of the prompt to the model to generate content.

A message here will interrupt any current model generation.

{% table %}
* Field
* Type
* Description
---
* `turns[]`
* [`Content`](/api-reference/generate-content#Resource:Content)
* Optional. The content appended to the current conversation with the model.

  For single-turn queries, this is a single instance. For multi-turn queries, this is a repeated field that contains conversation history and the latest request.
---
* `turnComplete`
* `bool`
* Optional. If true, indicates that the server content generation should start with the currently accumulated prompt. Otherwise, the server awaits additional messages before starting generation.
{% /table %}

### BidiGenerateContentRealtimeInput {% id="BidiGenerateContentRealtimeInput" %}

User input that is sent in real time.

The different modalities (audio, video and text) are handled as concurrent streams. The ordering across these streams is not guaranteed.

This is different from [`BidiGenerateContentClientContent`](/api-reference/live#BidiGenerateContentClientContent) in a few ways:

- Can be sent continuously without interruption to model generation.
- If there is a need to mix data interleaved across the [`BidiGenerateContentClientContent`](/api-reference/live#BidiGenerateContentClientContent) and the [`BidiGenerateContentRealtimeInput`](/api-reference/live#BidiGenerateContentRealtimeInput), the server attempts to optimize for best response, but there are no guarantees.
- End of turn is not explicitly specified, but is rather derived from user activity (for example, end of speech).
- Even before the end of turn, the data is processed incrementally to optimize for a fast start of the response from the model.

{% table %}
* Field
* Type
* Description
---
* `mediaChunks[]`
* [`Blob`](/api-reference/generate-content)
* Optional. Inlined bytes data for media input. Multiple `mediaChunks` are not supported, all but the first will be ignored.

  DEPRECATED: Use one of `audio`, `video`, or `text` instead.
---
* `audio`
* [`Blob`](/api-reference/generate-content)
* Optional. These form the realtime audio input stream.
---
* `video`
* [`Blob`](/api-reference/generate-content)
* Optional. These form the realtime video input stream.
---
* `activityStart`
* [`ActivityStart`](/api-reference/live#BidiGenerateContentRealtimeInput.ActivityStart)
* Optional. Marks the start of user activity. This can only be sent if automatic (i.e. server-side) activity detection is disabled.
---
* `activityEnd`
* [`ActivityEnd`](/api-reference/live#BidiGenerateContentRealtimeInput.ActivityEnd)
* Optional. Marks the end of user activity. This can only be sent if automatic (i.e. server-side) activity detection is disabled.
---
* `mediaResolution`
* [`MediaResolution`](/api-reference/generate-content)
* Optional. The media resolution to use. If not specified, `setup.generationConfig.mediaResolution` is used or a default if the setup is not provided.
---
* `audioStreamEnd`
* `bool`
* Optional. Indicates that the audio stream has ended, e.g. because the microphone was turned off.

  This should only be sent when automatic activity detection is enabled (which is the default).

  The client can reopen the stream by sending an audio message.
---
* `text`
* `string`
* Optional. These form the realtime text input stream.
{% /table %}

### BidiGenerateContentServerContent {% id="BidiGenerateContentServerContent" %}

Incremental server update generated by the model in response to client messages.

Content is generated as quickly as possible, and not in real time. Clients may choose to buffer and play it out in real time.

{% table %}
* Field
* Type
* Description
---
* `generationComplete`
* `bool`
* Output only. If true, indicates that the model is done generating.

  When model is interrupted while generating there will be no 'generation_complete' message in interrupted turn, it will go through 'interrupted > turn_complete'.

  When model assumes realtime playback there will be delay between generation_complete and turn_complete that is caused by model waiting for playback to finish.
---
* `turnComplete`
* `bool`
* Output only. If true, indicates that the model has completed its turn. Generation will only start in response to additional client messages. Note when playback status reporting is enabled, this is emitted only when the playback status indicates that the playback is done. Future playback status of the same generation will be ignored.
---
* `interrupted`
* `bool`
* Output only. If true, indicates that a client message has interrupted current model generation. If the client is playing out the content in real time, this is a good signal to stop and empty the current playback queue.
---
* `groundingMetadata`
* [`GroundingMetadata`](/api-reference/generate-content)
* Output only. Grounding metadata for the generated content.
---
* `inputTranscription`
* [`BidiGenerateContentTranscription`](/api-reference/live#BidiGenerateContentTranscription)
* Output only. Input audio transcription. The transcription is sent independently of the other server messages and there is no guaranteed ordering.
---
* `interimInputTranscription`
* [`BidiGenerateContentTranscription`](/api-reference/live#BidiGenerateContentTranscription)
* Output only. Low latency transcription updated while the user is speaking. This field is subject to frequent updates.
---
* `outputTranscription`
* [`BidiGenerateContentTranscription`](/api-reference/live#BidiGenerateContentTranscription)
* Output only. Output audio transcription. These transcriptions are part of the Generation output of the server. The last output transcription of this turn is sent before either `generationComplete` or `interrupted`, which in turn are followed by `turnComplete`. There is no guaranteed exact ordering between transcriptions and other `modelTurn` output but the server tries to send the transcripts close to the corresponding audio output.
---
* `urlContextMetadata`
* [`UrlContextMetadata`](/api-reference/live#UrlContextMetadata)
*
---
* `waitingForInput`
* `bool`
* Output only. If true, indicates that the model is not generating content because it is waiting for more input from the user, e.g. because it expects the user to continue talking.
---
* `interactionStatus`
* [`InteractionStatus`](/api-reference/live#BidiGenerateContentServerContent.InteractionStatus)
* Output only. The current activity status of the live session. Always sent alongside `turnComplete`.
---
* `modelTurn`
* [`Content`](/api-reference/generate-content#Resource:Content)
* Output only. The content that the model has generated as part of the current conversation with the user.
{% /table %}

### BidiGenerateContentServerMessage {% id="BidiGenerateContentServerMessage" %}

Response message for the BidiGenerateContent call.

{% table %}
* Field
* Type
* Description
---
* `usageMetadata`
* [`UsageMetadata`](/api-reference/live#UsageMetadata)
* Output only. Usage metadata about the response(s).
---
* `voiceActivity`
* [`VoiceActivity`](/api-reference/live#VoiceActivity)
* Output only. Voice activity detected in audio stream.
{% /table %}

Union field `messageType`. The type of the message. `messageType` can be only one of the following:

{% table %}
* Field
* Type
* Description
---
* `setupComplete`
* [`BidiGenerateContentSetupComplete`](/api-reference/live#BidiGenerateContentSetupComplete)
* Output only. Sent in response to a `BidiGenerateContentSetup` message from the client when setup is complete.
---
* `serverContent`
* [`BidiGenerateContentServerContent`](/api-reference/live#BidiGenerateContentServerContent)
* Output only. Content generated by the model in response to client messages.
---
* `toolCall`
* [`BidiGenerateContentToolCall`](/api-reference/live#BidiGenerateContentToolCall)
* Output only. Request for the client to execute the `functionCalls` and return the responses with the matching `id`s.
---
* `toolCallCancellation`
* [`BidiGenerateContentToolCallCancellation`](/api-reference/live#BidiGenerateContentToolCallCancellation)
* Output only. Notification for the client that a previously issued `ToolCallMessage` with the specified `id`s should be cancelled.
---
* `goAway`
* [`GoAway`](/api-reference/live#GoAway)
* Output only. A notice that the server will soon disconnect.
---
* `sessionResumptionUpdate`
* [`SessionResumptionUpdate`](/api-reference/live#SessionResumptionUpdate)
* Output only. Update of the session resumption state.
{% /table %}

### BidiGenerateContentSetup {% id="BidiGenerateContentSetup" %}

Message to be sent in the first (and only in the first) `BidiGenerateContentClientMessage`. Contains configuration that will apply for the duration of the streaming RPC.

Clients should wait for a `BidiGenerateContentSetupComplete` message before sending any additional messages.

{% table %}
* Field
* Type
* Description
---
* `model`
* `string`
* Required. The model's resource name. This serves as an ID for the Model to use.

  Format: `models/{model}`
---
* `generationConfig`
* [`GenerationConfig`](/api-reference/generate-content)
* Optional. Generation config.

  The following fields are not supported:

  - `responseLogprobs`
  - `responseMimeType`
  - `logprobs`
  - `responseSchema`
  - `responseJsonSchema`
  - `stopSequence`
  - `skipResponseCache`
  - `routingConfig`
  - `audioTimestamp`
---
* `systemInstruction`
* [`Content`](/api-reference/generate-content#Resource:Content)
* Optional. The user provided system instructions for the model.

  Note: Only text should be used in parts and content in each part will be in a separate paragraph.
---
* `tools[]`
* [`Tool`](/api-reference/generate-content#Resource:Tool)
* Optional. A list of `Tools` the model may use to generate the next response.

  A `Tool` is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.
---
* `realtimeInputConfig`
* [`RealtimeInputConfig`](/api-reference/live#RealtimeInputConfig)
* Optional. Configures the handling of realtime input.
---
* `sessionResumption`
* [`SessionResumptionConfig`](/api-reference/live#SessionResumptionConfig)
* Optional. Configures session resumption mechanism.

  If included, the server will send `SessionResumptionUpdate` messages.
---
* `contextWindowCompression`
* [`ContextWindowCompressionConfig`](/api-reference/live#ContextWindowCompressionConfig)
* Optional. Configures a context window compression mechanism.

  If included, the server will automatically reduce the size of the context when it exceeds the configured length.
---
* `inputAudioTranscription`
* [`AudioTranscriptionConfig`](/api-reference/live#AudioTranscriptionConfig)
* Optional. If set, enables transcription of voice input. The transcription aligns with the input audio language, if configured.
---
* `outputAudioTranscription`
* [`AudioTranscriptionConfig`](/api-reference/live#AudioTranscriptionConfig)
* Optional. If set, enables transcription of the model's audio output. The transcription aligns with the language code specified for the output audio, if configured.
---
* `proactivity`
* [`ProactivityConfig`](/api-reference/live#ProactivityConfig)
* Optional. Configures the proactivity of the model.

  This allows the model to respond proactively to the input and to ignore irrelevant input.
---
* `historyConfig`
* [`HistoryConfig`](/api-reference/live#HistoryConfig)
* Optional. Configures the exchange of history between the client and the server.
---
* `labels`
* `map<string, string>`
* Optional. Labels with user-defined metadata for the request.

  Optional. Labels must follow standard unified Cloud label requirements: - Label keys must start with a letter. - Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. - International characters are allowed.

  Usage: - Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)
{% /table %}

### BidiGenerateContentSetupComplete {% id="BidiGenerateContentSetupComplete" %}

Sent in response to a `BidiGenerateContentSetup` message from the client.

This type has no fields.

### BidiGenerateContentToolCall {% id="BidiGenerateContentToolCall" %}

Request for the client to execute the `functionCalls` and return the responses with the matching `id`s.

{% table %}
* Field
* Type
* Description
---
* `functionCalls[]`
* [`FunctionCall`](/api-reference/generate-content)
* Output only. The function call to be executed.
{% /table %}

### BidiGenerateContentToolCallCancellation {% id="BidiGenerateContentToolCallCancellation" %}

Notification for the client that a previously issued `ToolCallMessage` with the specified `id`s should not have been executed and should be cancelled. If there were side-effects to those tool calls, clients may attempt to undo the tool calls. This message occurs only in cases where the clients interrupt server turns.

{% table %}
* Field
* Type
* Description
---
* `ids[]`
* `string`
* Output only. The ids of the tool calls to be cancelled.
{% /table %}

### BidiGenerateContentToolResponse {% id="BidiGenerateContentToolResponse" %}

Client generated response to a `ToolCall` received from the server. Individual `FunctionResponse` objects are matched to the respective `FunctionCall` objects by the `id` field.

Note that in the unary and server-streaming GenerateContent APIs function calling happens by exchanging the `Content` parts, while in the bidi GenerateContent APIs function calling happens over these dedicated set of messages.

{% table %}
* Field
* Type
* Description
---
* `functionResponses[]`
* [`FunctionResponse`](/api-reference/generate-content)
* Optional. The response to the function calls.
{% /table %}

### BidiGenerateContentTranscription {% id="BidiGenerateContentTranscription" %}

Transcription of audio (input or output).

{% table %}
* Field
* Type
* Description
---
* `text`
* `string`
* Transcription text.
---
* `languageCode`
* `string`
* The BCP-47 language code of the transcription.
---
* `startOffset`
* [`Duration`](https://protobuf.dev/reference/protobuf/google.protobuf/#duration)
* Optional. Start offset in time of the transcription relative to the start of the audio.
---
* `endOffset`
* [`Duration`](https://protobuf.dev/reference/protobuf/google.protobuf/#duration)
* Optional. End offset in time of the transcription relative to the start of the audio.
{% /table %}

### ContextWindowCompressionConfig {% id="ContextWindowCompressionConfig" %}

Enables context window compression — a mechanism for managing the model's context window so that it does not exceed a given length.

Union field `compressionMechanism`. The context window compression mechanism used. `compressionMechanism` can be only one of the following:

{% table %}
* Field
* Type
* Description
---
* `slidingWindow`
* [`SlidingWindow`](/api-reference/live#ContextWindowCompressionConfig.SlidingWindow)
* A sliding-window mechanism.
---
* `triggerTokens`
* `int64`
* The number of tokens (before running a turn) required to trigger a context window compression.

  This can be used to balance quality against latency as shorter context windows may result in faster model responses. However, any compression operation will cause a temporary latency increase, so they should not be triggered frequently.

  If not set, the default is 80% of the model's context window limit. This leaves 20% for the next user request/model response.
{% /table %}

### EndSensitivity {% id="RealtimeInputConfig.AutomaticActivityDetection.EndSensitivity" %}

Determines how end of speech is detected.

{% table %}
* Value
* Description
---
* `END_SENSITIVITY_UNSPECIFIED`
* The default is END_SENSITIVITY_HIGH.
---
* `END_SENSITIVITY_HIGH`
* Automatic detection ends speech more often.
---
* `END_SENSITIVITY_LOW`
* Automatic detection ends speech less often.
{% /table %}

### GoAway {% id="GoAway" %}

A notice that the server will soon disconnect.

{% table %}
* Field
* Type
* Description
---
* `timeLeft`
* [`Duration`](https://protobuf.dev/reference/protobuf/google.protobuf/#duration)
* The remaining time before the connection will be terminated as ABORTED.

  This duration will never be less than a model-specific minimum, which will be specified together with the rate limits for the model.
{% /table %}

### HistoryConfig {% id="HistoryConfig" %}

History configuration.

This message is included in the session configuration as `BidiGenerateContentSetup.historyConfig`. Configures the exchange of history messages.

{% table %}
* Field
* Type
* Description
---
* `initialHistoryInClientContent`
* `bool`
* Optional. If true, after sending `setupComplete`, the server will wait and at first process `clientContent` messages until `turnComplete` is `true`. This initial history will not trigger a model call and may end with role `MODEL`. After `turnComplete` is `true`, the client can start the realtime conversation via `realtimeInput`.
{% /table %}

### InteractionStatus {% id="BidiGenerateContentServerContent.InteractionStatus" %}

The different activity states of the live session. This field is always sent together with `turnComplete` to indicate whether the server has finished all processing.

{% table %}
* Value
* Description
---
* `INTERACTION_STATUS_UNSPECIFIED`
* Unspecified interaction status.
---
* `IN_PROGRESS`
* The server is still actively processing user input or running background reasoning. More model output may follow.
---
* `REQUIRES_ACTION`
* Deprecated: Use IDLE instead.
---
* `IDLE`
* The server has completed all processing and background reasoning.
{% /table %}

### ProactivityConfig {% id="ProactivityConfig" %}

Config for proactivity features.

{% table %}
* Field
* Type
* Description
---
* `proactiveAudio`
* `bool`
* Optional. If enabled, the model can reject responding to the last prompt. For example, this allows the model to ignore out of context speech or to stay silent if the user did not make a request, yet.
{% /table %}

### RealtimeInputConfig {% id="RealtimeInputConfig" %}

Configures the realtime input behavior in `BidiGenerateContent`.

{% table %}
* Field
* Type
* Description
---
* `automaticActivityDetection`
* [`AutomaticActivityDetection`](/api-reference/live#RealtimeInputConfig.AutomaticActivityDetection)
* Optional. If not set, automatic activity detection is enabled by default. If automatic voice detection is disabled, the client must send activity signals.
---
* `activityHandling`
* [`ActivityHandling`](/api-reference/live#ActivityHandling)
* Optional. Defines what effect activity has.
---
* `turnCoverage`
* [`TurnCoverage`](/api-reference/live#RealtimeInputConfig.TurnCoverage)
* Optional. Defines which input is included in the user's turn.
---
* `interimTranscriptTimestampEnabled`
* `bool`
* Optional. Configures interim transcript timestamps.
{% /table %}

### SessionResumptionConfig {% id="SessionResumptionConfig" %}

Session resumption configuration.

This message is included in the session configuration as `BidiGenerateContentSetup.sessionResumption`. If configured, the server will send `SessionResumptionUpdate` messages.

{% table %}
* Field
* Type
* Description
---
* `handle`
* `string`
* The handle of a previous session. If not present then a new session is created.

  Session handles come from `SessionResumptionUpdate.token` values in previous connections.
{% /table %}

### SessionResumptionUpdate {% id="SessionResumptionUpdate" %}

Update of the session resumption state.

Only sent if `BidiGenerateContentSetup.sessionResumption` was set.

{% table %}
* Field
* Type
* Description
---
* `newHandle`
* `string`
* New handle that represents a state that can be resumed. Empty if `resumable`=false.
---
* `resumable`
* `bool`
* True if the current session can be resumed at this point.

  Resumption is not possible at some points in the session. For example, when the model is executing function calls or generating. Resuming the session (using a previous session token) in such a state will result in some data loss. In these cases, `newHandle` will be empty and `resumable` will be false.
{% /table %}

### SlidingWindow {% id="ContextWindowCompressionConfig.SlidingWindow" %}

The SlidingWindow method operates by discarding content at the beginning of the context window. The resulting context will always begin at the start of a USER role turn. System instructions and any `BidiGenerateContentSetup.prefixTurns` will always remain at the beginning of the result.

{% table %}
* Field
* Type
* Description
---
* `targetTokens`
* `int64`
* The target number of tokens to keep. The default value is trigger_tokens/2.

  Discarding parts of the context window causes a temporary latency increase so this value should be calibrated to avoid frequent compression operations.
{% /table %}

### StartSensitivity {% id="RealtimeInputConfig.AutomaticActivityDetection.StartSensitivity" %}

Determines how start of speech is detected.

{% table %}
* Value
* Description
---
* `START_SENSITIVITY_UNSPECIFIED`
* The default is START_SENSITIVITY_HIGH.
---
* `START_SENSITIVITY_HIGH`
* Automatic detection will detect the start of speech more often.
---
* `START_SENSITIVITY_LOW`
* Automatic detection will detect the start of speech less often.
{% /table %}

### TurnCoverage {% id="RealtimeInputConfig.TurnCoverage" %}

Options about which input is included in the user's turn.

{% table %}
* Value
* Description
---
* `TURN_COVERAGE_UNSPECIFIED`
* If unspecified, a default behavior is selected based on the model. E.g., for Gemini 2.5, the default is `TURN_INCLUDES_ONLY_ACTIVITY`, while for Gemini 3.1 and onwards, it's `TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`.
---
* `TURN_INCLUDES_ONLY_ACTIVITY`
* Includes activity since the last turn, excluding inactivity (e.g. silence on the audio stream).
---
* `TURN_INCLUDES_ALL_INPUT`
* Includes all realtime input since the last turn, including inactivity (e.g. silence on the audio stream).
---
* `TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO`
* Includes audio activity and all video since the last turn. With automatic activity detection, audio activity means speech and excludes silence.
{% /table %}

### TranslationConfig {% id="TranslationConfig" %}

Config for translation features.

{% table %}
* Field
* Type
* Description
---
* `targetLanguageCode`
* `string`
* Required. The target language for translation. Supported values are BCP-47 language codes (e.g. "en", "es", "fr").
---
* `echoTargetLanguage`
* `bool`
* Optional. If true, the model will generate audio when the target language is spoken, essentially it will parrot the input. If false, we will not produce audio for the target language.
{% /table %}

### UrlContextMetadata {% id="UrlContextMetadata" %}

Metadata related to url context retrieval tool.

{% table %}
* Field
* Type
* Description
---
* `urlMetadata[]`
* [`UrlMetadata`](/api-reference/generate-content)
* List of url context.
{% /table %}

### UsageMetadata {% id="UsageMetadata" %}

Usage metadata about response(s).

{% table %}
* Field
* Type
* Description
---
* `promptTokenCount`
* `int32`
* Output only. Number of tokens in the prompt. When `cachedContent` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content.
---
* `cachedContentTokenCount`
* `int32`
* Number of tokens in the cached part of the prompt (the cached content)
---
* `responseTokenCount`
* `int32`
* Output only. Total number of tokens across all the generated response candidates.
---
* `toolUsePromptTokenCount`
* `int32`
* Output only. Number of tokens present in tool-use prompt(s).
---
* `thoughtsTokenCount`
* `int32`
* Output only. Number of tokens of thoughts for thinking models.
---
* `totalTokenCount`
* `int32`
* Output only. Total token count for the generation request (prompt + response candidates).
---
* `promptTokensDetails[]`
* [`ModalityTokenCount`](/api-reference/generate-content#Resource:ModalityTokenCount)
* Output only. List of modalities that were processed in the request input.
---
* `cacheTokensDetails[]`
* [`ModalityTokenCount`](/api-reference/generate-content#Resource:ModalityTokenCount)
* Output only. List of modalities of the cached content in the request input.
---
* `responseTokensDetails[]`
* [`ModalityTokenCount`](/api-reference/generate-content#Resource:ModalityTokenCount)
* Output only. List of modalities that were returned in the response.
---
* `toolUsePromptTokensDetails[]`
* [`ModalityTokenCount`](/api-reference/generate-content#Resource:ModalityTokenCount)
* Output only. List of modalities that were processed for tool-use request inputs.
{% /table %}

### VoiceActivity {% id="VoiceActivity" %}

Voice activity detected in audio stream.

{% table %}
* Field
* Type
* Description
---
* `type`
* [`Type`](/api-reference/live#VoiceActivity.Type)
* Output only. The type of the VAD(voice activity detection) signal.
---
* `audioOffset`
* [`Duration`](https://protobuf.dev/reference/protobuf/google.protobuf/#duration)
* Output only. The time voice activity detected in audio time, relative to the start of the audio stream.
{% /table %}

### Type {% id="VoiceActivity.Type" %}

The type of the VAD signal.

{% table %}
* Value
* Description
---
* `TYPE_UNSPECIFIED`
* The default is UNSPECIFIED.
---
* `ACTIVITY_START`
* Start of sentence signal.
---
* `ACTIVITY_END`
* End of sentence signal.
{% /table %}

## Ephemeral authentication tokens {% id="ephemeral-auth-tokens" %}

Ephemeral authentication tokens can be obtained by calling
`AuthTokenService.CreateToken` and then used with
`GenerativeService.BidiGenerateContentConstrained`, either by passing the token
in an `access_token` query parameter, or in an HTTP `Authorization` header with
"`Token `" prefixed to it.

### CreateAuthTokenRequest {% id="CreateAuthTokenRequest" %}

Create an ephemeral authentication token.

{% table %}
* Field
* Type
* Description
---
* `authToken`
* [`AuthToken`](/api-reference/live#AuthToken)
* Required. The token to create.
{% /table %}

### AuthToken {% id="AuthToken" %}

A request to create an ephemeral authentication token.

{% table %}
* Field
* Type
* Description
---
* `name`
* `string`
* Output only. Identifier. The token itself.
---
* `expireTime`
* [`Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp)
* Optional. Input only. Immutable. An optional time after which, when using the resulting token, messages in BidiGenerateContent sessions will be rejected. (Gemini may preemptively close the session after this time.)

  If not set then this defaults to 30 minutes in the future. If set, this value must be less than 20 hours in the future.
---
* `newSessionExpireTime`
* [`Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp)
* Optional. Input only. Immutable. The time after which new Live API sessions using the token resulting from this request will be rejected.

  If not set this defaults to 60 seconds in the future. If set, this value must be less than 20 hours in the future.
---
* `fieldMask`
* [`FieldMask`](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask)
* Optional. Input only. Immutable. If field_mask is empty, and `bidiGenerateContentSetup` is not present, then the effective `BidiGenerateContentSetup` message is taken from the Live API connection.

  If field_mask is empty, and `bidiGenerateContentSetup` *is* present, then the effective `BidiGenerateContentSetup` message is taken entirely from `bidiGenerateContentSetup` in this request. The setup message from the Live API connection is ignored.

  If field_mask is not empty, then the corresponding fields from `bidiGenerateContentSetup` will overwrite the fields from the setup message in the Live API connection.
{% /table %}

Union field `config`. The method-specific configuration for the resulting token. `config` can be only one of the following:

{% table %}
* Field
* Type
* Description
---
* `bidiGenerateContentSetup`
* [`BidiGenerateContentSetup`](/api-reference/live#BidiGenerateContentSetup)
* Optional. Input only. Immutable. Configuration specific to `BidiGenerateContent`.
---
* `uses`
* `int32`
* Optional. Input only. Immutable. The number of times the token can be used. If this value is zero then no limit is applied. Resuming a Live API session does not count as a use. If unspecified, the default is 1.
{% /table %}

## More information on common types {% id="more-info" %}

For more information on the commonly-used API resource types `Blob`,
`Content`, `FunctionCall`, `FunctionResponse`, `GenerationConfig`,
`GroundingMetadata`, `ModalityTokenCount`, and `Tool`, see
[Generating content](/api-reference/generate-content).

# Starting a Live session
Source: https://aistudio.google.com/api-reference/live/bidi-generate-content
Description: Opens a stateful WebSocket session for exchanging text, audio, and video with the model.

{% callout type="note" %}
**Preview:** The Live API is in preview.
{% /callout %}

{% mark class="http-wss" %}{% icon name="sync_alt" /%}`WSS`{% /mark %} `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent`

A WebSocket connection establishes a session between the client and the Gemini
server. After a client initiates a new connection the session can exchange
messages with the server to:

* Send text, audio, or video to the Gemini server.
* Receive audio, text, or function call requests from the Gemini server.

{% callout type="note" %}
The URL is for version `v1beta`.
{% /callout %}

## Session configuration {% id="session-configuration" %}

The initial message sent after establishing the WebSocket connection sets the
session configuration, which includes the model, generation parameters, system
instructions, and tools.

You cannot update the configuration while the connection is open. However, you
can change the configuration parameters, except the model, when pausing and
resuming via the [session resumption mechanism](/api-reference/live#SessionResumptionConfig).

See the following example configuration. Note that the name casing in SDKs may
vary. You can look up the [Python SDK configuration options here](https://github.com/googleapis/python-genai/blob/main/google/genai/types.py).

```json
{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object,
    "mediaResolution": object,
    "translationConfig": object
  },
  "systemInstruction": string,
  "tools": [object]
}
```

For more information on the API field, see [generationConfig](/api-reference/generate-content).

## Send messages {% id="send-messages" %}

To exchange messages over the WebSocket connection, the client must send a JSON
object over an open WebSocket connection. The JSON object must have
**exactly one** of the fields from the following object set:

```json
{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}
```

### Supported client messages {% id="client-messages" %}

See the supported client messages in the following table:

| Message                                                                                    | Description                                                                      |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| [`BidiGenerateContentSetup`](/api-reference/live#BidiGenerateContentSetup)                 | Session configuration to be sent in the first message                            |
| [`BidiGenerateContentClientContent`](/api-reference/live#BidiGenerateContentClientContent) | Incremental content update of the current conversation delivered from the client |
| [`BidiGenerateContentRealtimeInput`](/api-reference/live#BidiGenerateContentRealtimeInput) | Real time audio, video, or text input                                            |
| [`BidiGenerateContentToolResponse`](/api-reference/live#BidiGenerateContentToolResponse)   | Response to a `ToolCallMessage` received from the server                         |

## Receive messages {% id="receive-messages" %}

To receive messages from Gemini, listen for the WebSocket 'message' event,
and then parse the result according to the definition of the
supported server messages.

See the following:

```python
async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)
```

Server messages may have a [`usageMetadata`](/api-reference/live#UsageMetadata) field but will
otherwise include **exactly one** of the other fields from the
[`BidiGenerateContentServerMessage`](/api-reference/live#BidiGenerateContentServerMessage)
message. (The `messageType` union is not expressed in JSON so the field will
appear at the top-level of the message.)

# Live Music API - WebSockets API reference
Source: https://aistudio.google.com/api-reference/live-music
Description: Reference for the WebSockets-based Live Music API used for real-time music generation with Lyria RealTime.

{% callout type="note" %}
**Preview:** The Live Music API is in preview.
{% /callout %}

Lyria RealTime music generation uses a persistent, bidirectional,
low-latency streaming connection using
[WebSockets](https://en.wikipedia.org/wiki/WebSocket). In this section, you'll
find additional details regarding the WebSockets API.

## Methods {% id="methods" %}

{% table %}
* Method
* Endpoint
---
* [Starting a Live Music session](/api-reference/live-music/bidi-generate-music)
* {% mark class="http-wss" %}{% icon name="sync_alt" /%}`WSS`{% /mark %} `/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateMusic`

  Opens a WebSocket session that streams music generated in real time from
  your prompts and playback controls.
{% /table %}

## Data Models {% id="data-models" %}

### AudioChunk {% id="AudioChunk" %}

Representation of an audio chunk.

Union field `content`. `content` can be only one of the following:

{% table %}
* Field
* Type
* Description
---
* `data`
* `bytes`
* Raw bytes of the audio chunk.
---
* `mimeType`
* `string`
* The MIME type of the content of the audio chunk, such as "audio/wav".
---
* `sourceMetadata`
* [`SourceMetadata`](/api-reference/live-music#AudioChunk.SourceMetadata)
* Output only. Prompts and config used for generating this audio chunk.
{% /table %}

### SourceMetadata {% id="AudioChunk.SourceMetadata" %}

Metadata about the input source used for generating this audio chunk.

{% table %}
* Field
* Type
* Description
---
* `clientContent`
* [`BidiGenerateMusicClientContent`](/api-reference/live-music#BidiGenerateMusicClientContent)
* Weighted prompts for generating this audio chunk.
---
* `musicGenerationConfig`
* [`BidiGenerateMusicGenerationConfig`](/api-reference/live-music#BidiGenerateMusicGenerationConfig)
* Music generation config for generating this audio chunk.
{% /table %}

### BidiGenerateMusicClientContent {% id="BidiGenerateMusicClientContent" %}

User input to start or steer the music.

{% table %}
* Field
* Type
* Description
---
* `weightedPrompts[]`
* [`WeightedPrompt`](/api-reference/live-music#WeightedPrompt)
* Required. Weighted prompts as the model input.
{% /table %}

### BidiGenerateMusicClientMessage {% id="BidiGenerateMusicClientMessage" %}

Messages sent by the client in the BidiGenerateMusic call.

Union field `messageType`. `messageType` can be only one of the following:

{% table %}
* Field
* Type
* Description
---
* `setup`
* [`BidiGenerateMusicSetup`](/api-reference/live-music#BidiGenerateMusicSetup)
* Optional. Session configuration sent in the first and only first client message.
---
* `clientContent`
* [`BidiGenerateMusicClientContent`](/api-reference/live-music#BidiGenerateMusicClientContent)
* Optional. Weighted prompts and music generation configs as the input of music generation.
---
* `musicGenerationConfig`
* [`BidiGenerateMusicGenerationConfig`](/api-reference/live-music#BidiGenerateMusicGenerationConfig)
* Optional. Configuration for music generation.
---
* `playbackControl`
* [`BidiGenerateMusicPlaybackControl`](/api-reference/live-music#BidiGenerateMusicPlaybackControl)
* Optional. Playback control signal for the music generation.
{% /table %}

### BidiGenerateMusicFilteredPrompt {% id="BidiGenerateMusicFilteredPrompt" %}

Filtered prompt with reason.

{% table %}
* Field
* Type
* Description
---
* `filteredReason`
* `string`
* Output only. The reason why the prompt was filtered.
{% /table %}

Union field `prompt`. The prompt that was filtered. `prompt` can be only one of the following:

{% table %}
* Field
* Type
* Description
---
* `text`
* `string`
* Optional. Text prompt.
{% /table %}

### BidiGenerateMusicGenerationConfig {% id="BidiGenerateMusicGenerationConfig" %}

Configuration for music generation.

{% table %}
* Field
* Type
* Description
---
* `temperature`
* `float`
* Optional. Controls the variance in audio generation.

  Higher values produce higher variance. Range is [0.0, 3.0]. Default is 1.1.
---
* `topK`
* `int32`
* Optional. Controls how the model selects tokens for output.

  Samples the topK tokens with the highest probabilities. Range is [1, 1000]. Default is 40.
---
* `seed`
* `int32`
* Optional. Seeds audio generation. If not set, the request uses a randomly generated seed.
---
* `guidance`
* `float`
* Optional. Controls how closely the model follows prompts. Higher guidance follows more closely, but will make transitions more abrupt. Range is [0.0, 6.0]. Default is 4.0.
---
* `bpm`
* `int32`
* Optional. Beats per minute. Range is [60, 200].
---
* `density`
* `float`
* Optional. Density of sounds. Range is [0.0, 1.0].
---
* `brightness`
* `float`
* Optional. Higher value produces brighter audio. Range is [0.0, 1.0].
---
* `scale`
* [`Scale`](/api-reference/live-music#BidiGenerateMusicGenerationConfig.Scale)
* Optional. Scale of the generated music.
---
* `muteBass`
* `bool`
* Optional. The audio output should not contain bass.
---
* `muteDrums`
* `bool`
* Optional. The audio output should not contain drums.
---
* `onlyBassAndDrums`
* `bool`
* Optional. The audio output should only contain bass and drums.
---
* `musicGenerationMode`
* [`MusicGenerationMode`](/api-reference/live-music#BidiGenerateMusicGenerationConfig.MusicGenerationMode)
* Optional. The mode of music generation. Default is QUALITY.
{% /table %}

### MusicGenerationMode {% id="BidiGenerateMusicGenerationConfig.MusicGenerationMode" %}

{% table %}
* Value
* Description
---
* `MUSIC_GENERATION_MODE_UNSPECIFIED`
* This value is unused.
---
* `QUALITY`
* This mode steers text prompts to regions of latent space with higher quality music.
---
* `DIVERSITY`
* This mode steers text prompts to regions of latent space with a larger diversity of music.
---
* `VOCALIZATION`
* This mode steers text prompts to regions of latent space more likely to generate vocal music.
{% /table %}

### Scale {% id="BidiGenerateMusicGenerationConfig.Scale" %}

Scale of the generated music.

{% table %}
* Value
* Description
---
* `SCALE_UNSPECIFIED`
* Default value. This value is unused.
---
* `C_MAJOR_A_MINOR`
* C major or A minor
---
* `D_FLAT_MAJOR_B_FLAT_MINOR`
* D flat major or B flat minor
---
* `D_MAJOR_B_MINOR`
* D major or B minor
---
* `E_FLAT_MAJOR_C_MINOR`
* E flat major or C minor
---
* `E_MAJOR_D_FLAT_MINOR`
* E major or D flat minor
---
* `F_MAJOR_D_MINOR`
* F major or D minor
---
* `G_FLAT_MAJOR_E_FLAT_MINOR`
* G flat major or E flat minor
---
* `G_MAJOR_E_MINOR`
* G major or E minor
---
* `A_FLAT_MAJOR_F_MINOR`
* A flat major or F minor
---
* `A_MAJOR_G_FLAT_MINOR`
* A major or G flat minor
---
* `B_FLAT_MAJOR_G_MINOR`
* B flat major or G minor
---
* `B_MAJOR_A_FLAT_MINOR`
* B major or A flat minor
{% /table %}

### BidiGenerateMusicPlaybackControl {% id="BidiGenerateMusicPlaybackControl" %}

Playback control for the music generation.

{% table %}
* Value
* Description
---
* `PLAYBACK_CONTROL_UNSPECIFIED`
* This value is unused.
---
* `PLAY`
* Start generating the music.
---
* `PAUSE`
* Hold the music generation. Use PLAY to resume from the current position.
---
* `STOP`
* Stop the music generation and reset the context (prompts retained). Use PLAY to restart the music generation.
---
* `RESET_CONTEXT`
* Reset the context (prompts retained) without stopping the music generation.
{% /table %}

### BidiGenerateMusicServerContent {% id="BidiGenerateMusicServerContent" %}

Incremental server update generated by the model in response to client messages.

Content is generated as quickly as possible, and not in real time. Clients may choose to buffer and play it out in real time.

{% table %}
* Field
* Type
* Description
---
* `audioChunks[]`
* [`AudioChunk`](/api-reference/live-music#AudioChunk)
* Output only. Audio chunks that the model has generated.
{% /table %}

### BidiGenerateMusicServerMessage {% id="BidiGenerateMusicServerMessage" %}

Response message for the BidiGenerateMusic call.

Union field `messageType`. The type of the message. `messageType` can be only one of the following:

{% table %}
* Field
* Type
* Description
---
* `setupComplete`
* [`BidiGenerateMusicSetupComplete`](/api-reference/live-music#BidiGenerateMusicSetupComplete)
* Output only. Sent in response to a `BidiGenerateMusicSetup` message from the client when setup is complete.
---
* `serverContent`
* [`BidiGenerateMusicServerContent`](/api-reference/live-music#BidiGenerateMusicServerContent)
* Output only. Content generated by the model in response to client messages.
---
* `filteredPrompt`
* [`BidiGenerateMusicFilteredPrompt`](/api-reference/live-music#BidiGenerateMusicFilteredPrompt)
* Output only. Filtered prompt with reason.
---
* `warning`
* `string`
* Output only. The warning message from the server. Warnings won't terminate the stream.
{% /table %}

### BidiGenerateMusicSetup {% id="BidiGenerateMusicSetup" %}

Message to be sent in the first (and only in the first) `BidiGenerateMusicClientMessage`.

Clients should wait for a `BidiGenerateMusicSetupComplete` message before sending any additional messages.

{% table %}
* Field
* Type
* Description
---
* `model`
* `string`
* Required. The model's resource name. This serves as an ID for the model to use.

  Format: `models/{model}`
{% /table %}

### BidiGenerateMusicSetupComplete {% id="BidiGenerateMusicSetupComplete" %}

Sent in response to a `BidiGenerateMusicSetup` message from the client.

This type has no fields.

### WeightedPrompt {% id="WeightedPrompt" %}

Weighted prompt as the model input.

{% table %}
* Field
* Type
* Description
---
* `weight`
* `float`
* Required. Weight of the prompt.

  The weight is used to control the relative importance of the prompt. Higher weights are more important than lower weights.

  Weights of all weighted_prompts in this BidiGenerateMusicClientContent must not be all 0. Weights of all weighted_prompts in this BidiGenerateMusicClientContent message will be normalized.
{% /table %}

Union field `prompt`. `prompt` can be only one of the following:

{% table %}
* Field
* Type
* Description
---
* `text`
* `string`
* Text prompt.
{% /table %}

## More information on types {% id="more-info" %}

For more information on the types used by the API, see the
[Python SDK](https://github.com/googleapis/python-genai/blob/main/google/genai/types.py).

# Starting a Live Music session
Source: https://aistudio.google.com/api-reference/live-music/bidi-generate-music
Description: Opens a WebSocket session that streams music generated in real time from your prompts and playback controls.

{% callout type="note" %}
**Preview:** The Live Music API is in preview.
{% /callout %}

{% mark class="http-wss" %}{% icon name="sync_alt" /%}`WSS`{% /mark %} `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateMusic`

A WebSocket connection establishes a session to keep a real-time communication
with the model. After a client initiates a new connection the session can
exchange messages with the server to:

*   Send prompts and controls to steer music generation.
*   Send music playback controls.
*   Receive audio chunks.

{% callout type="note" %}
The URL is for version `v1beta`.
{% /callout %}

## Session configuration {% id="session-configuration" %}

The initial message after connection sets the model to use during the session.

See the following example configuration. Note that the name casing in SDKs may
vary. You can look up the
[Python SDK configuration options here](https://github.com/googleapis/python-genai/blob/main/google/genai/live_music.py).

```json
{
  "model": string
}
```

## Send messages {% id="send-messages" %}

To exchange messages over the WebSocket connection, the client must send a JSON
object over an open WebSocket connection. The JSON object must have **exactly
one** of the fields from the following object set:

```json
{
  "setup": BidiGenerateMusicSetup,
  "client_content": BidiGenerateMusicClientContent,
  "music_generation_config": BidiGenerateMusicGenerationConfig,
  "playback_control": BidiGenerateMusicPlaybackControl
}
```

### Supported client messages {% id="client-messages" %}

See the supported client messages in the following table:

| Message                                                                                            | Description                                                |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`BidiGenerateMusicSetup`](/api-reference/live-music#BidiGenerateMusicSetup)                       | Session configuration to be sent only in the first message |
| [`BidiGenerateMusicClientContent`](/api-reference/live-music#BidiGenerateMusicClientContent)       | Weighted prompts as the model input                        |
| [`BidiGenerateMusicGenerationConfig`](/api-reference/live-music#BidiGenerateMusicGenerationConfig) | Configuration for music generation                         |
| [`BidiGenerateMusicPlaybackControl`](/api-reference/live-music#BidiGenerateMusicPlaybackControl)   | Playback control signals for model generation              |

## Receive messages {% id="receive-messages" %}

To receive messages from the server, listen for the WebSocket 'message' event,
and then parse the result according to the definition of the supported server
messages.

See the following:

```python
async def receive_audio(session):
  """Example background task to process incoming audio."""
  while True:
    async for message in session.receive():
      audio_data = message.server_content.audio_chunks[0].data
      # Process audio...
      await asyncio.sleep(10**-12)

async with (
  client.aio.live.music.connect(model='models/lyria-realtime-exp') as session,
  asyncio.TaskGroup() as tg,
):
  # Set up task to receive server messages.
  tg.create_task(receive_audio(session))

  # Send initial prompts and config
  await session.set_weighted_prompts(
    prompts=[
      types.WeightedPrompt(text='minimal techno', weight=1.0),
    ]
  )
  await session.set_music_generation_config(
    config=types.LiveMusicGenerationConfig(bpm=90, temperature=1.0)
  )

  # Start streaming music
  await session.play()
```

Server messages include **exactly one** of the other fields from the
[`BidiGenerateMusicServerMessage`](/api-reference/live-music#BidiGenerateMusicServerMessage) message.
(The `messageType` union is not expressed in JSON so the field will appear at
the top-level of the message.)

# Gemini Agents API
Source: https://aistudio.google.com/api-reference/agents
Description: Agents are systems that leverage Gemini models, a set of tools, and reasoning capabilities to perform complex, multi-step tasks and achieve specific goals.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

Agents are systems that leverage Gemini models, a set of tools, and reasoning capabilities to perform complex, multi-step tasks and achieve specific goals. Unlike a single model call, an agent can plan, execute a series of actions, interact with external systems, and synthesize information to fulfill a user's request.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Creating an agent](/api-reference/agents/create-agent)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/agents`

  Creates a new Agent (Typed version for SDK).
---

* [Listing agents](/api-reference/agents/list-agents)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/agents`

  Lists all Agents.
---

* [Getting an agent](/api-reference/agents/get-agent)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/agents/{agentsId}`

  Gets a specific Agent.
---

* [Deleting an agent](/api-reference/agents/delete-agent)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/agents/{agentsId}`

  Deletes an Agent.
{% /table %}

## Resources {% id="resources" %}

### Agent {% id="Resource:Agent" %}

An agent definition for the CreateAgent API.
This message is the target for annotation-parser-based JSON parsing.
New format:

```json
{
  "id": "customer-sentinel",
  "base_agent": "",
  "system_instruction": "...",
  "base_environment": { "type": "remote", "sources": [...] },
  "tools": [ {"type": "code_execution"} ]
}
```

**Properties:**

**id**: `string`

The unique identifier for the agent.

{% hr /%}

**base_agent**: `string`

The base agent to extend.

{% hr /%}

**system_instruction**: `string`

System instruction for the agent.

{% hr /%}

**description**: `string`

Agent description for developers to quickly read and understand.

{% hr /%}

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig`

Configuration parameters for the agent.

{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**base_environment**: `EnvironmentConfig` or `string`

The environment configuration for the agent.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**tools**: `array (AgentTool)`

The tools available to the agent.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

# Creating an agent
Source: https://aistudio.google.com/api-reference/agents/create-agent
Description: Creates a new Agent (Typed version for SDK).

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/agents`

Creates a new Agent (Typed version for SDK).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**parent**: {% mark %}required{% /mark %} `string`

The parent resource where this agent will be created. Format: `projects/{project}/locations/{location}`

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**id**: `string`

The unique identifier for the agent.

{% hr /%}

**base_agent**: `string`

The base agent to extend.

{% hr /%}

**system_instruction**: `string`

System instruction for the agent.

{% hr /%}

**description**: `string`

Agent description for developers to quickly read and understand.

{% hr /%}

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig`

Configuration parameters for the agent.

{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**base_environment**: `EnvironmentConfig` or `string`

The environment configuration for the agent.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**tools**: `array (AgentTool)`

The tools available to the agent.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="Create Agent" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/agents \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "research-assistant-abc123",
    "base_agent": "antigravity-preview-05-2026",
    "description": "A helpful research assistant.",
    "system_instruction": "You are a helpful research assistant.",
    "base_environment": "remote",
    "tools": [{"type": "google_search"}]
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
import uuid
from google import genai

client = genai.Client()
agent = client.agents.create(
    id=f"research-assistant-{uuid.uuid4().hex[:8]}",
    base_agent="antigravity-preview-05-2026",
    description="A helpful research assistant.",
    system_instruction="You are a helpful research assistant.",
    base_environment="remote",
    tools=[{"type": "google_search"}],
)
print(agent.id)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const agentId = `research-assistant-${crypto.randomUUID().slice(0, 8)}`;
const agent = await ai.agents.create({
  id: agentId,
  base_agent: 'antigravity-preview-05-2026',
  description: 'A helpful research assistant.',
  system_instruction: 'You are a helpful research assistant.',
  base_environment: 'remote',
  tools: [{type: 'google_search'}],
});
if (!agent.id) {
  throw new Error('Agent creation failed: ID is undefined');
}
console.log(agent.id);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.gaos.models.agents.BaseEnvironment;
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateAgentResponse;
import com.google.genai.gaos.models.interactions.GoogleSearch;

Client client = new Client();
String agentId = "research-assistant-" + UUID.randomUUID().toString().substring(0, 8);
Agent agent =
    Agent.builder()
        .id(agentId)
        .baseAgent("antigravity-preview-05-2026")
        .description("A helpful research assistant.")
        .systemInstruction("You are a helpful research assistant.")
        .baseEnvironment(BaseEnvironment.of("remote"))
        .tools(List.of(new GoogleSearch()))
        .build();
CreateAgentResponse response = client.agents.create(agent);
System.out.println(response.agent().flatMap(Agent::id).orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "google.golang.org/genai"
    gaos_agents "google.golang.org/genai/interactions/models/agents"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    agentID := fmt.Sprintf("research-assistant-%d", time.Now().UnixNano())
    req := operations.CreateAgentRequest{
        Body: gaos_agents.Agent{
            ID:                genai.Ptr(agentID),
            BaseAgent:         genai.Ptr("antigravity-preview-05-2026"),
            Description:       genai.Ptr("A helpful research assistant."),
            SystemInstruction: genai.Ptr("You are a helpful research assistant."),
            BaseEnvironment:   genai.Ptr(gaos_agents.NewBaseEnvironment("remote")),
            Tools: []gaos_agents.AgentTool{
                gaos_agents.NewAgentTool(gaos_interactions.GoogleSearch{}),
            },
        },
    }

    res, err := client.Agents.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Agent != nil && res.Agent.ID != nil {
        fmt.Println(*res.Agent.ID)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Agent with Sources" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/agents \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "data-analyst-abc123",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",
    "base_environment": {
      "type": "remote",
      "sources": [
        {
          "type": "inline",
          "target": ".agents/AGENTS.md",
          "content": "Always use matplotlib for charts. Include a summary table in every report."
        },
        {
          "type": "repository",
          "source": "https://github.com/my-org/analysis-templates",
          "target": "/workspace/templates"
        }
      ]
    }
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
import uuid
from google import genai

client = genai.Client()
agent = client.agents.create(
    id=f"data-analyst-{uuid.uuid4().hex[:8]}",
    base_agent="antigravity-preview-05-2026",
    system_instruction=(
        "You are a data analyst. Always include visualizations and export"
        " results as PDF."
    ),
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": (
                    "Always use matplotlib for charts. Include a summary"
                    " table in every report."
                ),
            },
            {
                "type": "repository",
                "source": "https://github.com/my-org/analysis-templates",
                "target": "/workspace/templates",
            },
        ],
    },
)
print(f"Created agent: {agent.id}")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const agentId = `data-analyst-${crypto.randomUUID().slice(0, 8)}`;
const agent = await ai.agents.create({
  id: agentId,
  base_agent: 'antigravity-preview-05-2026',
  system_instruction:
    'You are a data analyst. Always include visualizations and export results as PDF.',
  base_environment: {
    type: 'remote',
    sources: [
      {
        type: 'inline',
        target: '.agents/AGENTS.md',
        content:
          'Always use matplotlib for charts. Include a summary table in every report.',
      },
      {
        type: 'repository',
        source: 'https://github.com/my-org/analysis-templates',
        target: '/workspace/templates',
      },
    ],
  },
});
console.log(`Created agent: ${agent.id}`);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.gaos.models.agents.BaseEnvironment;
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.CreateAgentResponse;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;

Client client = new Client();
String agentId = "data-analyst-" + UUID.randomUUID().toString().substring(0, 8);
com.google.genai.gaos.models.interactions.Environment env =
    com.google.genai.gaos.models.interactions.Environment.builder()
        .sources(
            List.of(
                Source.builder()
                    .type(SourceType.INLINE)
                    .target(".agents/AGENTS.md")
                    .content(
                        "Always use matplotlib for charts. Include a summary table in every"
                            + " report.")
                    .build(),
                Source.builder()
                    .type(SourceType.REPOSITORY)
                    .source("https://github.com/my-org/analysis-templates")
                    .target("/workspace/templates")
                    .build()))
        .build();
Agent agent =
    Agent.builder()
        .id(agentId)
        .baseAgent("antigravity-preview-05-2026")
        .systemInstruction(
            "You are a data analyst. Always include visualizations and export results as PDF.")
        .baseEnvironment(BaseEnvironment.of(env))
        .build();
CreateAgentResponse response = client.agents.create(agent);
System.out.println("Created agent: " + response.agent().flatMap(Agent::id).orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "google.golang.org/genai"
    gaos_agents "google.golang.org/genai/interactions/models/agents"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    agentID := fmt.Sprintf("data-analyst-%d", time.Now().UnixNano())
    env := gaos_interactions.Environment{
        Sources: []gaos_interactions.Source{
            {
                Type:    genai.Ptr(gaos_interactions.SourceTypeInline),
                Target:  genai.Ptr(".agents/AGENTS.md"),
                Content: genai.Ptr("Always use matplotlib for charts. Include a summary table in every report."),
            },
            {
                Type:   genai.Ptr(gaos_interactions.SourceTypeRepository),
                Source: genai.Ptr("https://github.com/my-org/analysis-templates"),
                Target: genai.Ptr("/workspace/templates"),
            },
        },
    }

    req := operations.CreateAgentRequest{
        Body: gaos_agents.Agent{
            ID:                genai.Ptr(agentID),
            BaseAgent:         genai.Ptr("antigravity-preview-05-2026"),
            SystemInstruction: genai.Ptr("You are a data analyst. Always include visualizations and export results as PDF."),
            BaseEnvironment:   genai.Ptr(gaos_agents.NewBaseEnvironment(env)),
        },
    }

    res, err := client.Agents.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Agent != nil && res.Agent.ID != nil {
        fmt.Printf("Created agent: %s\n", *res.Agent.ID)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Agent Forked from Environment" %}

{% tabs %}

{% tab label="REST" %}

```sh
# Step 1: Set up the environment interactively
RESPONSE=$(curl -s -X POST https://generativelanguage.googleapis.com/v1beta/interactions \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "antigravity-preview-05-2026",
    "input": "Write a basic Hello World template to /workspace/template.py.",
    "environment": "remote"
  }')
ENV_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['environment_id'])")

# Step 2: Fork that environment into a named agent
curl -X POST https://generativelanguage.googleapis.com/v1beta/agents \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"my-data-analyst\",
    \"base_agent\": \"antigravity-preview-05-2026\",
    \"system_instruction\": \"You are a data analyst. Use the template at /workspace/template.py for all reports.\",
    \"base_environment\": \"$ENV_ID\"
  }"
```

{% /tab %}

{% tab label="Python" %}

```python
import uuid
from google import genai

client = genai.Client()

# Step 1: Set up the environment interactively.
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a basic Hello World template to /workspace/template.py.",
    environment="remote",
)

# Step 2: Fork that environment into a named agent.
agent_id = f"my-data-analyst-{uuid.uuid4().hex[:8]}"
agent = client.agents.create(
    id=agent_id,
    base_agent="antigravity-preview-05-2026",
    system_instruction=(
        "You are a data analyst. Use the template at /workspace/template.py"
        " for all reports."
    ),
    base_environment=interaction.environment_id,
)
print(f"Forked agent: {agent.id}")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

// Step 1: Set up the environment interactively.
const interaction = await ai.interactions.create({
  agent: 'antigravity-preview-05-2026',
  input: 'Write a basic Hello World template to /workspace/template.py.',
  environment: 'remote',
});

// Step 2: Fork that environment into a named agent.
const agentId = `my-data-analyst-${crypto.randomUUID().slice(0, 8)}`;
const agent = await ai.agents.create({
  id: agentId,
  base_agent: 'antigravity-preview-05-2026',
  system_instruction:
    'You are a data analyst. Use the template at /workspace/template.py for all reports.',
  base_environment: interaction.environment_id,
});
console.log(`Forked agent: ${agent.id}`);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.agents.BaseEnvironment;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.operations.CreateAgentResponse;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.gaos.models.operations.CreateInteractionResponse;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Step;

Client client = new Client();

// Step 1: Set up the environment interactively.
CreateAgentInteraction params =
    CreateAgentInteraction.builder()
        .agent(AgentOption.of("antigravity-preview-05-2026"))
        .input(
            InteractionsInput.of(
                "Write a basic Hello World template to /workspace/template.py."))
        .environment(CreateAgentInteractionEnvironment.of("remote"))
        .build();
CreateInteractionResponse interactionResponse =
    client.interactions.create(CreateInteractionRequestBody.of(params));
Interaction interaction =
    interactionResponse
        .interaction()
        .orElseThrow(() -> new RuntimeException("No interaction returned"));

// Step 2: Fork that environment into a named agent.
String agentId = "my-data-analyst-" + UUID.randomUUID().toString().substring(0, 8);
Agent agent =
    Agent.builder()
        .id(agentId)
        .baseAgent("antigravity-preview-05-2026")
        .systemInstruction(
            "You are a data analyst. Use the template at /workspace/template.py for all"
                + " reports.")
        .baseEnvironment(BaseEnvironment.of(interaction.environmentId().orElse("")))
        .build();
CreateAgentResponse agentResponse = client.agents.create(agent);
System.out.println("Forked agent: " + agentResponse.agent().flatMap(Agent::id).orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "google.golang.org/genai"
    gaos_agents "google.golang.org/genai/interactions/models/agents"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Step 1: Set up the environment interactively.
    interactionReq := operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{
            Agent:       gaos_interactions.AgentOption("antigravity-preview-05-2026"),
            Input:       genai.Ptr(gaos_interactions.NewInteractionsInput("Write a basic Hello World template to /workspace/template.py.")),
            Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment("remote")),
        }),
    }
    interactionRes, err := client.Interactions.Create(ctx, interactionReq)
    if err != nil {
        log.Fatal(err)
    }
    envID := ""
    if interactionRes.Interaction != nil && interactionRes.Interaction.EnvironmentID != nil {
        envID = *interactionRes.Interaction.EnvironmentID
    }

    // Step 2: Fork that environment into a named agent.
    agentID := fmt.Sprintf("my-data-analyst-%d", time.Now().UnixNano())
    req := operations.CreateAgentRequest{
        Body: gaos_agents.Agent{
            ID:                genai.Ptr(agentID),
            BaseAgent:         genai.Ptr("antigravity-preview-05-2026"),
            SystemInstruction: genai.Ptr("You are a data analyst. Use the template at /workspace/template.py for all reports."),
            BaseEnvironment:   genai.Ptr(gaos_agents.NewBaseEnvironment(envID)),
        },
    }
    res, err := client.Agents.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }
    if res.Agent != nil && res.Agent.ID != nil {
        fmt.Printf("Forked agent: %s\n", *res.Agent.ID)
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**id**: `string`

The unique identifier for the agent.

{% hr /%}

**base_agent**: `string`

The base agent to extend.

{% hr /%}

**system_instruction**: `string`

System instruction for the agent.

{% hr /%}

**description**: `string`

Agent description for developers to quickly read and understand.

{% hr /%}

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig`

Configuration parameters for the agent.

{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**base_environment**: `EnvironmentConfig` or `string`

The environment configuration for the agent.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**tools**: `array (AgentTool)`

The tools available to the agent.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

{% tabs %}

{% tab label="Create Agent" %}

```json
{
  "description": "A helpful research assistant.",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": "remote",
  "id": "research-assistant-abc123",
  "system_instruction": "You are a helpful research assistant.",
  "tools": [
    {
      "type": "google_search"
    }
  ]
}
```

{% /tab %}

{% tab label="Agent with Sources" %}

```json
{
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "inline",
        "content": "Always use matplotlib for charts. Include a summary table in every report.",
        "target": ".agents/AGENTS.md"
      },
      {
        "type": "repository",
        "source": "https://github.com/my-org/analysis-templates",
        "target": "/workspace/templates"
      }
    ]
  },
  "id": "data-analyst-abc123",
  "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF."
}
```

{% /tab %}

{% tab label="Agent Forked from Environment" %}

```json
{
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": "env_abc123",
  "id": "my-data-analyst-abc123",
  "system_instruction": "You are a data analyst. Use the template at /workspace/template.py for all reports."
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

# Listing agents
Source: https://aistudio.google.com/api-reference/agents/list-agents
Description: Lists all Agents.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/agents`

Lists all Agents.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**parent**: {% mark %}required{% /mark %} `string`

The parent resource to list agents from. Format: `projects/{project}/locations/{location}`

{% hr /%}

**page_size**: `integer`

{% hr /%}

**page_token**: `string`

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET https://generativelanguage.googleapis.com/v1beta/agents \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.agents.list()
for agent in response.agents or []:
  print(agent.id)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const agents = await ai.agents.list();
for (const agent of agents.agents ?? []) {
  console.log(agent.id);
}
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.gaos.models.agents.AgentListResponse;
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.ListAgentsResponse;

Client client = new Client();
ListAgentsResponse response = client.agents.list().call();
List<Agent> agents =
    response.agentListResponse().flatMap(AgentListResponse::agents).orElse(List.of());
for (Agent agent : agents) {
  agent.id().ifPresent(System.out::println);
}
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Agents.List(ctx, operations.ListAgentsRequest{})
    if err != nil {
        log.Fatal(err)
    }

    if res.AgentListResponse != nil {
        for _, agent := range res.AgentListResponse.Agents {
            if agent.ID != nil {
                fmt.Println(*agent.ID)
            }
        }
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**agents**: `array (`[`Agent`](/api-reference/agents/list-agents#Resource:Agent)`)`

The list of agents.

{% hr /%}

**next_page_token**: `string`

A token to retrieve the next page of results.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "agents": [
    {
      "description": "A helpful research assistant.",
      "base_agent": "antigravity-preview-05-2026",
      "id": "research-assistant-abc123",
      "system_instruction": "You are a helpful research assistant.",
      "tools": [
        {
          "type": "google_search"
        }
      ]
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### Agent {% class="hide-from-toc" id="Resource:Agent" %}

An agent definition for the CreateAgent API.
This message is the target for annotation-parser-based JSON parsing.
New format:

```json
{
  "id": "customer-sentinel",
  "base_agent": "",
  "system_instruction": "...",
  "base_environment": { "type": "remote", "sources": [...] },
  "tools": [ {"type": "code_execution"} ]
}
```

**Properties:**

**id**: `string`

The unique identifier for the agent.

{% hr /%}

**base_agent**: `string`

The base agent to extend.

{% hr /%}

**system_instruction**: `string`

System instruction for the agent.

{% hr /%}

**description**: `string`

Agent description for developers to quickly read and understand.

{% hr /%}

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig`

Configuration parameters for the agent.

{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**base_environment**: `EnvironmentConfig` or `string`

The environment configuration for the agent.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**tools**: `array (AgentTool)`

The tools available to the agent.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

# Getting an agent
Source: https://aistudio.google.com/api-reference/agents/get-agent
Description: Gets a specific Agent.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/agents/{agentsId}`

Gets a specific Agent.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**agentsId**: {% mark %}required{% /mark %} `string`

The name of the agent to retrieve.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET https://generativelanguage.googleapis.com/v1beta/agents/ag_abc123 \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
import uuid
from google import genai

client = genai.Client()


agent = client.agents.get(agent_id)
print(agent.id)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


const agent = await ai.agents.get(agentId);
if (!agent.id) {
  throw new Error('Agent retrieval failed: ID is undefined');
}
console.log(agent.id);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.Client;
import com.google.genai.gaos.models.operations.GetAgentResponse;

Client client = new Client();


GetAgentResponse response = client.agents.get(agentId);
Agent agent = response.agent().orElseThrow(() -> new RuntimeException("No agent returned"));
System.out.println(agent.id().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    res, err := client.Agents.Get(ctx, operations.GetAgentRequest{ID: agentID})
    if err != nil {
        log.Fatal(err)
    }

    if res.Agent != nil && res.Agent.ID != nil {
        fmt.Println(*res.Agent.ID)
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**id**: `string`

The unique identifier for the agent.

{% hr /%}

**base_agent**: `string`

The base agent to extend.

{% hr /%}

**system_instruction**: `string`

System instruction for the agent.

{% hr /%}

**description**: `string`

Agent description for developers to quickly read and understand.

{% hr /%}

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig`

Configuration parameters for the agent.

{% /summary %}

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**base_environment**: `EnvironmentConfig` or `string`

The environment configuration for the agent.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**tools**: `array (AgentTool)`

The tools available to the agent.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "created": "2025-11-26T12:25:15Z",
  "display_name": "My Research Agent",
  "id": "ag_abc123",
  "object": "agent",
  "system_instruction": "You are a helpful research assistant.",
  "tools": [
    {
      "type": "google_search"
    }
  ],
  "updated": "2025-11-26T12:25:15Z"
}
```

{% /right-column %}

{% /two-column-layout %}

# Deleting an agent
Source: https://aistudio.google.com/api-reference/agents/delete-agent
Description: Deletes an Agent.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/agents/{agentsId}`

Deletes an Agent.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**agentsId**: {% mark %}required{% /mark %} `string`

The name of the agent to delete.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE https://generativelanguage.googleapis.com/v1beta/agents/ag_abc123 \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
import uuid
from google import genai

client = genai.Client()


client.agents.delete(agent_id)
print("Agent deleted successfully.")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


await ai.agents.delete(agentId);
console.log('Agent deleted successfully.');
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.agents.Agent;
import com.google.genai.Client;

Client client = new Client();


client.agents.delete(agentId);
System.out.println("Agent deleted successfully.");
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    _, err = client.Agents.Delete(ctx, operations.DeleteAgentRequest{ID: agentID})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Agent deleted successfully.")
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Gemini Environments API
Source: https://aistudio.google.com/api-reference/environments
Description: Environments provide isolated execution contexts for running agent code, tools, and services securely.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

Environments provide isolated execution contexts for running agent code, tools, and services securely.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Creating an environment](/api-reference/environments/create-environment)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/environments`

  Creates an environment.
---

* [Listing environments](/api-reference/environments/list-environments)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/environments`

  Lists environments.
---

* [Getting environment files](/api-reference/environments/get-environment-files)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/environments/{environment}/files/{path}`

  Retrieves file metadata or directory contents from an environment's snapshot.
---

* [Getting an environment](/api-reference/environments/get-environment)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/environments/{id}`

  Gets an environment.
---

* [Uploading an environment file](/api-reference/environments/start-environment-file-upload)
* {% mark class="http-put" %}{% icon name="north_east" /%}`PUT`{% /mark %} `/upload/v1beta/environments/{environment}/files/{path}`

  Starts a resumable upload session for a file in an environment workspace.
---

* [Deleting an environment](/api-reference/environments/delete-environment)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/environments/{id}`

  Deletes an environment.
{% /table %}

## Resources {% id="resources" %}

### Environment {% id="Resource:Environment" %}

An execution environment for an agent.

**Properties:**

**id**: {% mark %}required{% /mark %} `string`

Output only. The ID of the environment.

{% hr /%}

{% details %}

{% summary %}

**sources**: `array (Source)`

Sources to be mounted into the environment.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% hr /%}

**created**: `string`

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

{% hr /%}

**updated**: `string`

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

{% hr /%}

**last_accessed**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The status of the environment container.

{% /summary %}

Possible values:

- `active`: Output only. The status of the environment container.
- `expired`: Output only. The status of the environment container.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% hr /%}

**file_count**: `string`

Output only. The number of files in the environment, output only.

{% hr /%}

**size_bytes**: `string`

Output only. The total size of the environment files in bytes, output only.

# Creating an environment
Source: https://aistudio.google.com/api-reference/environments/create-environment
Description: Creates an environment.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/environments`

Creates an environment.

{% two-column-layout %}

{% left-column %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**sources**: `array (Source)`

Sources to be mounted into the environment.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% hr /%}

**from_environment**: `string`

Optional. The source environment to copy/fork from. Format: `environments/{environment_id}` or `{environment_id}`. When specified, `sources` and `env` must be empty.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="Create" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/environments \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{
      "type": "inline",
      "target": "main.py",
      "content": "print(\"Hello, World!\")"
    }]
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
environment = client.environments.create(
    sources=[{
        "type": "inline",
        "target": "main.py",
        "content": "print('Hello, World!')",
    }]
)
print(environment.id)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const environment = await ai.environments.create({
  sources: [
    {
      type: 'inline',
      target: 'main.py',
      content: "print('Hello, World!')",
    },
  ],
});
if (!environment.id) {
  throw new Error('Environment creation failed: ID is undefined');
}
console.log(environment.id);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.CreateEnvironmentRequest;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;

Client client = new Client();
CreateEnvironmentRequest request =
    CreateEnvironmentRequest.builder()
        .sources(
            List.of(
                Source.builder()
                    .type(SourceType.INLINE)
                    .target("main.py")
                    .content("print('Hello, World!')")
                    .build()))
        .build();
com.google.genai.gaos.models.environments.Environment environment =
    client.environments.createEnvironment(request).environment().orElseThrow();
System.out.println(environment.id().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_environments "google.golang.org/genai/interactions/models/environments"
    gaos_interactions "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    req := operations.CreateEnvironmentRequest{
        Body: gaos_environments.CreateEnvironmentRequest{
            Sources: []gaos_interactions.Source{
                {
                    Type:    genai.Ptr(gaos_interactions.SourceTypeInline),
                    Target:  genai.Ptr("main.py"),
                    Content: genai.Ptr("print('Hello, World!')"),
                },
            },
        },
    }

    res, err := client.Environments.CreateEnvironment(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Environment != nil && res.Environment.ID != "" {
        fmt.Println(res.Environment.ID)

    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Copy" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/environments \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_environment": "environments/env_abc123"
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()


environment = client.environments.create(
    from_environment=source_env.id,
)
print(environment.id)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


const environment = await ai.environments.create({
  from_environment: sourceEnv.id,
});
if (!environment.id) {
  throw new Error('Environment creation failed: ID is undefined');
}
console.log(environment.id);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.CreateEnvironmentRequest;
import com.google.genai.gaos.models.environments.Environment;

Client client = new Client();


CreateEnvironmentRequest request =
    CreateEnvironmentRequest.builder().fromEnvironment(sourceEnvId).build();
com.google.genai.gaos.models.environments.Environment environment =
    client.environments.createEnvironment(request).environment().orElseThrow();
System.out.println(environment.id().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_environments "google.golang.org/genai/interactions/models/environments"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    res, err := client.Environments.CreateEnvironment(ctx, operations.CreateEnvironmentRequest{
        Body: gaos_environments.CreateEnvironmentRequest{
            FromEnvironment: genai.Ptr(sourceEnvID),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Environment != nil && res.Environment.ID != "" {
        fmt.Println(res.Environment.ID)

    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Output only. The ID of the environment.

{% hr /%}

{% details %}

{% summary %}

**sources**: `array (Source)`

Sources to be mounted into the environment.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% hr /%}

**created**: `string`

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

{% hr /%}

**updated**: `string`

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

{% hr /%}

**last_accessed**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The status of the environment container.

{% /summary %}

Possible values:

- `active`: Output only. The status of the environment container.
- `expired`: Output only. The status of the environment container.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% hr /%}

**file_count**: `string`

Output only. The number of files in the environment, output only.

{% hr /%}

**size_bytes**: `string`

Output only. The total size of the environment files in bytes, output only.

{% /section %}

# Listing environments
Source: https://aistudio.google.com/api-reference/environments/list-environments
Description: Lists environments.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/environments`

Lists environments.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**page_size**: `integer`

Optional. Maximum number of environments to return. If unspecified, defaults to 50. Maximum is 1000.

{% hr /%}

**page_token**: `string`

Optional. Pagination token.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET https://generativelanguage.googleapis.com/v1beta/environments \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.environments.list()
for environment in response.environments or []:
  print(environment.id)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const response = await ai.environments.list();
for (const env of response.environments ?? []) {
  console.log(env.id);
}
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.operations.ListEnvironmentsResponse;

Client client = new Client();
ListEnvironmentsResponse response = client.environments.listEnvironmentsDirect();
for (com.google.genai.gaos.models.environments.Environment env :
    response.listEnvironmentsResponse().flatMap(res -> res.environments()).orElse(List.of())) {
  System.out.println(env.id().orElse(""));
}
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Environments.ListEnvironments(ctx, operations.ListEnvironmentsRequest{})
    if err != nil {
        log.Fatal(err)
    }

    if res.ListEnvironmentsResponse != nil {
        for _, env := range res.ListEnvironmentsResponse.Environments {
            if env.ID != "" {
                fmt.Println(env.ID)
            }
        }
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**environments**: `array (`[`Environment`](/api-reference/environments/list-environments#Resource:Environment)`)`

Environments belonging to the provided project.

{% hr /%}

**next_page_token**: `string`

Pagination token.

{% /section %}

## Resources {% class="hide-from-toc" id="resources" %}

### Environment {% class="hide-from-toc" id="Resource:Environment" %}

An execution environment for an agent.

**Properties:**

**id**: {% mark %}required{% /mark %} `string`

Output only. The ID of the environment.

{% hr /%}

{% details %}

{% summary %}

**sources**: `array (Source)`

Sources to be mounted into the environment.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% hr /%}

**created**: `string`

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

{% hr /%}

**updated**: `string`

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

{% hr /%}

**last_accessed**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The status of the environment container.

{% /summary %}

Possible values:

- `active`: Output only. The status of the environment container.
- `expired`: Output only. The status of the environment container.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% hr /%}

**file_count**: `string`

Output only. The number of files in the environment, output only.

{% hr /%}

**size_bytes**: `string`

Output only. The total size of the environment files in bytes, output only.

# Getting environment files
Source: https://aistudio.google.com/api-reference/environments/get-environment-files
Description: Retrieves file metadata or directory contents from an environment's snapshot.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/environments/{environment}/files/{path}`

Retrieves file metadata or directory contents from an environment's snapshot. To download file content, use the download URL returned in the response.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**page_size**: `integer`

Optional. Maximum number of entries to return per page (for directory listing).

{% hr /%}

**page_token**: `string`

Optional. Pagination token for directory listing.

{% hr /%}

**recursive**: `boolean`

Optional. If true and the path is a directory, recursively lists all files.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="List Files" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET 'https://generativelanguage.googleapis.com/v1beta/environments/env_abc123/files/src' \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()


response = client.environments.files.list(
    environment=created.id,
    path="src",
)
for file in response.files or []:
  print(file.name, file.type, file.size_bytes)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


const response = await ai.environments.files.list({
  environment: created.id,
  path: 'src',
});
for (const file of response.files ?? []) {
  console.log(file.name, file.type, file.size_bytes);
}
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.EnvironmentFile;
import com.google.genai.gaos.models.operations.GetEnvironmentFilesRequest;
import com.google.genai.gaos.models.environments.GetEnvironmentFilesResponse;

Client client = new Client();


com.google.genai.gaos.models.operations.GetEnvironmentFilesResponse response =
    client
        .environments
        .files()
        .list(GetEnvironmentFilesRequest.builder().environment(envId).path("src").build());
GetEnvironmentFilesResponse filesResponse =
    response.getEnvironmentFilesResponse().orElseThrow();
for (EnvironmentFile file : filesResponse.files().orElse(List.of())) {
  System.out.println(
      file.name().orElse("")
          + " "
          + file.type().map(Object::toString).orElse("")
          + " "
          + file.sizeBytes().orElse(""));
}
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    res, err := client.Environments.Files.List(ctx, operations.GetEnvironmentFilesRequest{
        Environment: envID,
        Path:        "src",
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.GetEnvironmentFilesResponse != nil {
        for _, file := range res.GetEnvironmentFilesResponse.Files {
            name := ""
            if file.Name != nil {
                name = *file.Name
            }
            fileType := ""
            if file.Type != nil {
                fileType = string(*file.Type)
            }
            var size int64
            if file.SizeBytes != nil {
                size = *file.SizeBytes
            }
            fmt.Println(name, fileType, size)
        }
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Get File" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET 'https://generativelanguage.googleapis.com/v1beta/environments/env_abc123/files/main.py' \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()


response = client.environments.files.get(
    environment=created.id,
    path="main.py",
)
for file in response.files or []:
  print(file.name, file.size_bytes)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


const response = await ai.environments.files.list({
  environment: created.id,
  path: 'main.py',
});
for (const file of response.files ?? []) {
  console.log(file.name, file.size_bytes);
}
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.EnvironmentFile;
import com.google.genai.gaos.models.operations.GetEnvironmentFilesRequest;
import com.google.genai.gaos.models.environments.GetEnvironmentFilesResponse;

Client client = new Client();


com.google.genai.gaos.models.operations.GetEnvironmentFilesResponse response =
    client
        .environments
        .files()
        .list(GetEnvironmentFilesRequest.builder().environment(envId).path("main.py").build());
GetEnvironmentFilesResponse filesResponse =
    response.getEnvironmentFilesResponse().orElseThrow();
for (EnvironmentFile file : filesResponse.files().orElse(List.of())) {
  System.out.println(file.name().orElse("") + " " + file.sizeBytes().orElse(""));
}
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    res, err := client.Environments.Files.List(ctx, operations.GetEnvironmentFilesRequest{
        Environment: envID,
        Path:        "main.py",
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.GetEnvironmentFilesResponse != nil {
        for _, file := range res.GetEnvironmentFilesResponse.Files {
            name := ""
            if file.Name != nil {
                name = *file.Name
            }
            var size int64
            if file.SizeBytes != nil {
                size = *file.SizeBytes
            }
            fmt.Println(name, size)
        }
    }
}
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Download File" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET 'https://generativelanguage.googleapis.com/v1beta/environments/env_abc123/files/src/main.py?alt=media' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --output main.py
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()


content = client.environments.files.download(
    environment=created.id,
    path="src/main.py",
)
print(content.decode("utf-8"))
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**files**: `array (EnvironmentFile)`

If the requested path is a directory, this contains its contents. If the requested path is a file, this contains a single entry with the file's metadata. If alt=media was specified, this is empty (content is served via `blob`).

{% /summary %}

**name**: `string`

Output only. The name of the file or directory (e.g., "main.py" or "src").

**path**: `string`

Output only. The full relative path within the environment (e.g., "workspace/src/main.py").

{% details %}

{% summary %}

**type**: `enum (string)`

Output only. The type of the entry.

{% /summary %}

Possible values:

- `file`: A regular file.
- `directory`: A directory.

{% /details %}

**size_bytes**: `string`

Output only. The size of the file/directory in bytes. NOLINT

**mime_type**: `string`

Output only. The MIME type of the file (e.g., "text/python", "image/png"). Empty for directories. NOLINT

**created**: `string`

Output only. The creation time of the file/directory.

**modified**: `string`

Output only. The modification time of the file/directory.

{% /details %}

{% hr /%}

**next_page_token**: `string`

Pagination token for directory listing. NOLINT

{% /section %}

# Getting an environment
Source: https://aistudio.google.com/api-reference/environments/get-environment
Description: Gets an environment.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/environments/{id}`

Gets an environment.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Resource ID segment making up resource `name`. It identifies the resource within its parent collection as described in https://google.aip.dev/122.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET https://generativelanguage.googleapis.com/v1beta/environments/env_abc123 \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()


environment = client.environments.get(id=created.id)
print(environment.id)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


const environment = await ai.environments.get(created.id);
console.log(environment.id);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.Environment;

Client client = new Client();


com.google.genai.gaos.models.environments.Environment environment =
    client.environments.getEnvironment(envId).environment().orElseThrow();
System.out.println(environment.id().orElse(""));
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    res, err := client.Environments.GetEnvironment(ctx, operations.GetEnvironmentRequest{
        ID: envID,
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Environment != nil && res.Environment.ID != "" {
        fmt.Println(res.Environment.ID)
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Output only. The ID of the environment.

{% hr /%}

{% details %}

{% summary %}

**sources**: `array (Source)`

Sources to be mounted into the environment.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% hr /%}

**created**: `string`

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

{% hr /%}

**updated**: `string`

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

{% hr /%}

**last_accessed**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The status of the environment container.

{% /summary %}

Possible values:

- `active`: Output only. The status of the environment container.
- `expired`: Output only. The status of the environment container.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% hr /%}

**file_count**: `string`

Output only. The number of files in the environment, output only.

{% hr /%}

**size_bytes**: `string`

Output only. The total size of the environment files in bytes, output only.

{% /section %}

# Uploading an environment file
Source: https://aistudio.google.com/api-reference/environments/start-environment-file-upload
Description: Starts a resumable upload session for a file in an environment workspace.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-put" %}{% icon name="north_east" /%}`PUT`{% /mark %} `https://generativelanguage.googleapis.com/upload/v1beta/environments/{environment}/files/{path}`

Starts a resumable upload session for a file in an environment workspace.
Upload the file bytes to the URL returned in the `X-Goog-Upload-URL`
response header, using the resumable upload protocol.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**X-Goog-Upload-Command**: {% mark %}required{% /mark %} `string`

Command that starts the resumable upload session.

Default: `start`

{% hr /%}

**X-Goog-Upload-Header-Content-Length**: {% mark %}required{% /mark %} `integer`

Total number of file bytes that will be uploaded to the session URL.

{% hr /%}

**X-Goog-Upload-Header-Content-Type**: {% mark %}required{% /mark %} `string`

MIME type of the file that will be uploaded to the session URL.

{% hr /%}

**X-Goog-Upload-Protocol**: {% mark %}required{% /mark %} `string`

Resumable upload protocol selector.

Default: `resumable`

{% hr /%}

**extract**: `boolean`

Optional. If true, treats the uploaded file as a tar/tar.gz archive and unpacks it into `path`.

{% hr /%}

**overwrite**: `boolean`

Optional. Whether to overwrite the destination file if it already exists.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -i -X PUT \
  'https://generativelanguage.googleapis.com/upload/v1beta/environments/env_abc123/files/main.py?overwrite=true' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'X-Goog-Upload-Protocol: resumable' \
  -H 'X-Goog-Upload-Command: start' \
  -H "X-Goog-Upload-Header-Content-Length: $(wc -c < main.py)" \
  -H 'X-Goog-Upload-Header-Content-Type: text/x-python'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

Empty response.

# Deleting an environment
Source: https://aistudio.google.com/api-reference/environments/delete-environment
Description: Deletes an environment.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/environments/{id}`

Deletes an environment.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Resource ID segment making up resource `name`. It identifies the resource within its parent collection as described in https://google.aip.dev/122.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE https://generativelanguage.googleapis.com/v1beta/environments/env_abc123 \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()


client.environments.delete(id=created.id)
print("Environment deleted successfully.")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


await ai.environments.delete(created.id);
console.log('Environment deleted successfully.');
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.Environment;

Client client = new Client();


client.environments.deleteEnvironment(envId);
System.out.println(
    "com.google.genai.gaos.models.environments.Environment deleted successfully.");
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }


    _, err = client.Environments.DeleteEnvironment(ctx, operations.DeleteEnvironmentRequest{
        ID: envID,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Environment deleted successfully.")
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Gemini Triggers API
Source: https://aistudio.google.com/api-reference/triggers
Description: Triggers allow you to schedule agent executions on a cron schedule, enabling automated and recurring tasks.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

Triggers allow you to schedule agent executions on a cron schedule, enabling automated and recurring tasks.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Creating a trigger](/api-reference/triggers/create-trigger)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/triggers`

  Creates a new trigger that will invoke the specified agent on the given cron schedule.
---

* [Running a trigger](/api-reference/triggers/run-trigger)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/triggers/{triggerId}/executions`

  Runs a trigger immediately.
---

* [Listing triggers](/api-reference/triggers/list-triggers)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/triggers`

  Lists triggers for a project.
---

* [Getting a trigger](/api-reference/triggers/get-trigger)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/triggers/{id}`

  Gets details of a single trigger.
---

* [Listing trigger executions](/api-reference/triggers/list-trigger-executions)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/triggers/{triggerId}/executions`

  Lists executions for a trigger.
---

* [Updating a trigger](/api-reference/triggers/update-trigger)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/triggers/{id}`

  Updates a trigger.
---

* [Deleting a trigger](/api-reference/triggers/delete-trigger)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/triggers/{id}`

  Deletes a trigger.
{% /table %}

## Resources {% id="resources" %}

### Trigger {% id="Resource:Trigger" %}

A trigger configuration that is scheduled to run an agent.

**Properties:**

**schedule**: {% mark %}required{% /mark %} `string`

The cron schedule on which the trigger should run. Standard cron format.

{% hr /%}

**time_zone**: {% mark %}required{% /mark %} `string`

Time zone in which the schedule should be interpreted.

{% hr /%}

{% details %}

{% summary %}

**interaction**: {% mark %}required{% /mark %} `CreateAgentInteractionParams`

The interaction request template to be executed.

{% /summary %}

{% details %}

{% summary %}

**agent**: {% mark %}required{% /mark %} `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

**input**: {% mark %}required{% /mark %} `Content` or `array (Content)` or `array (Step)` or `string`

The input for the interaction.

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

Configuration parameters for the agent interaction.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

**id**: `string`

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

{% details %}

{% summary %}

**status**: `enum (string)`

Required. Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

**created**: `string`

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

**updated**: `string`

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

**system_instruction**: `string`

System instruction for the interaction.

{% details %}

{% summary %}

**tools**: `array (Tool)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**ComputerUse**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `computer_use`

{% details %}

{% summary %}

**environment**: `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `browser`: Operates in a web browser.
- `mobile`: Operates in a mobile environment.
- `desktop`: Operates in a desktop environment.

{% /details %}

**excluded_predefined_functions**: `array (string)`

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

**enable_prompt_injection_detection**: `boolean`

Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabled_safety_policies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `financial_transactions`: Safety policy for financial transactions.
- `sensitive_data_modification`: Safety policy for sensitive data modification.
- `communication_tool`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `account_creation`: Safety policy for account creation.
- `data_modification`: Safety policy for data modification.
- `user_consent_management`: Safety policy for user consent management.
- `legal_terms_and_agreements`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}**FileSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleMaps**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

{% details %}

{% summary %}

**response_format**: `ResponseFormat` or `array (ResponseFormat)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AudioResponseFormat**{% /summary %}

Configuration for audio output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the audio output.

{% /summary %}

Possible values:

- `audio/mp3`: MP3 audio format.
- `audio/ogg_opus`: OGG Opus audio format.
- `audio/l16`: Raw PCM (L16) audio format.
- `audio/wav`: WAV audio format.
- `audio/alaw`: A-law audio format.
- `audio/mulaw`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the audio output.

{% /summary %}

Possible values:

- `inline`: Audio data is returned inline in the response.
- `uri`: Audio data is returned as a URI.

{% /details %}

**sample_rate**: `integer`

Sample rate in Hz.

**bit_rate**: `integer`

Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}**ImageResponseFormat**{% /summary %}

Configuration for image output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the image output.

{% /summary %}

Possible values:

- `image/jpeg`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the image output.

{% /summary %}

Possible values:

- `inline`: Image data is returned inline in the response.
- `uri`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the image output.

{% /summary %}

Possible values:

- `1:1`: 1:1 aspect ratio.
- `2:3`: 2:3 aspect ratio.
- `3:2`: 3:2 aspect ratio.
- `3:4`: 3:4 aspect ratio.
- `4:3`: 4:3 aspect ratio.
- `4:5`: 4:5 aspect ratio.
- `5:4`: 5:4 aspect ratio.
- `9:16`: 9:16 aspect ratio.
- `16:9`: 16:9 aspect ratio.
- `21:9`: 21:9 aspect ratio.
- `1:8`: 1:8 aspect ratio.
- `8:1`: 8:1 aspect ratio.
- `1:4`: 1:4 aspect ratio.
- `4:1`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**image_size**: `enum (string)`

The size of the image output.

{% /summary %}

Possible values:

- `512`: 512px image size.
- `1K`: 1K image size.
- `2K`: 2K image size.
- `4K`: 4K image size.

{% /details %}

{% /details %}

{% details %}

{% summary %}**TextResponseFormat**{% /summary %}

Configuration for text output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the text output.

{% /summary %}

Possible values:

- `application/json`: JSON output format.
- `text/plain`: Plain text output format.

{% /details %}

**schema**: `object`

The JSON schema that the output should conform to. Only applicable when mime_type is application/json. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced; validate these in your application. `minItems` and `maxItems` are enforced. Schemas that are too complex to enforce (for example, large `maxItems` on nested arrays) return a 400 INVALID_ARGUMENT error.

{% /details %}

{% details %}

{% summary %}**VideoResponseFormat**{% /summary %}

Configuration for video output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the video output.

{% /summary %}

Possible values:

- `inline`: Video data is returned inline in the response.
- `uri`: Video data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the video output.

{% /summary %}

Possible values:

- `16:9`: 16:9 aspect ratio.
- `9:16`: 9:16 aspect ratio.

{% /details %}

**duration**: `string`

The duration for the video output.

{% details %}

{% summary %}

**resolution**: `enum (string)`

The video output resolution. Defaults to 720p.

{% /summary %}

Possible values:

- `360p`: 360p resolution.
- `720p`: 720p resolution.
- `1080p`: 1080p resolution.
- `4k`: 4K resolution.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (ResponseFormat)**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% details %}

{% summary %}

**environment**: `EnvironmentConfig` or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

**environment_id**: `string`

Output only. The environment ID for the interaction. Only populated if environment config is set in the request.

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

**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.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. The ID of the trigger.

{% hr /%}

**display_name**: `string`

Optional. The display name of the trigger.

{% hr /%}

**environment_id**: `string`

Optional. The environment ID for the trigger execution.

{% hr /%}

**max_consecutive_failures**: `integer`

Optional. The maximum number of consecutive failures allowed before the trigger is automatically paused (status becomes ERROR).

{% hr /%}

**execution_timeout_seconds**: `integer`

Optional. The execution timeout for the triggered interaction.

{% hr /%}

**consecutive_failure_count**: `integer`

Output only. The number of consecutive failures that have occurred since the last successful execution.

{% hr /%}

**create_time**: `string`

Output only. The time when the trigger was created.

{% hr /%}

**update_time**: `string`

Output only. The time when the trigger was last updated.

{% hr /%}

**last_run_time**: `string`

Output only. The time when the trigger was last run.

{% hr /%}

**next_run_time**: `string`

Output only. The time when the trigger is scheduled to run next.

{% hr /%}

**last_pause_time**: `string`

Output only. The time when the trigger was last paused.

{% hr /%}

**last_resume_time**: `string`

Output only. The time when the trigger was last resumed.

{% hr /%}

**previous_interaction_id**: `string`

Output only. The ID of the last interaction created by this trigger.

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The current status of the trigger.

{% /summary %}

Possible values:

- `active`: The trigger is active and will fire on schedule.
- `paused`: The trigger is paused and will not fire.
- `error`: The trigger has entered an error state due to consecutive failures.

{% /details %}

# Creating a trigger
Source: https://aistudio.google.com/api-reference/triggers/create-trigger
Description: Creates a new trigger that will invoke the specified agent on the given cron schedule.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/triggers`

Creates a new trigger that will invoke the specified agent on the given
cron schedule.

{% two-column-layout %}

{% left-column %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**schedule**: {% mark %}required{% /mark %} `string`

The cron schedule on which the trigger should run. Standard cron format.

{% hr /%}

**time_zone**: {% mark %}required{% /mark %} `string`

Time zone in which the schedule should be interpreted.

{% hr /%}

{% details %}

{% summary %}

**interaction**: {% mark %}required{% /mark %} `CreateAgentInteractionParams`

The interaction request template to be executed.

{% /summary %}

{% details %}

{% summary %}

**agent**: {% mark %}required{% /mark %} `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

**input**: {% mark %}required{% /mark %} `Content` or `array (Content)` or `array (Step)` or `string`

The input for the interaction.

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

Configuration parameters for the agent interaction.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

**id**: `string`

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

{% details %}

{% summary %}

**status**: `enum (string)`

Required. Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

**created**: `string`

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

**updated**: `string`

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

**system_instruction**: `string`

System instruction for the interaction.

{% details %}

{% summary %}

**tools**: `array (Tool)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**ComputerUse**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `computer_use`

{% details %}

{% summary %}

**environment**: `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `browser`: Operates in a web browser.
- `mobile`: Operates in a mobile environment.
- `desktop`: Operates in a desktop environment.

{% /details %}

**excluded_predefined_functions**: `array (string)`

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

**enable_prompt_injection_detection**: `boolean`

Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabled_safety_policies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `financial_transactions`: Safety policy for financial transactions.
- `sensitive_data_modification`: Safety policy for sensitive data modification.
- `communication_tool`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `account_creation`: Safety policy for account creation.
- `data_modification`: Safety policy for data modification.
- `user_consent_management`: Safety policy for user consent management.
- `legal_terms_and_agreements`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}**FileSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleMaps**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

{% details %}

{% summary %}

**response_format**: `ResponseFormat` or `array (ResponseFormat)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AudioResponseFormat**{% /summary %}

Configuration for audio output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the audio output.

{% /summary %}

Possible values:

- `audio/mp3`: MP3 audio format.
- `audio/ogg_opus`: OGG Opus audio format.
- `audio/l16`: Raw PCM (L16) audio format.
- `audio/wav`: WAV audio format.
- `audio/alaw`: A-law audio format.
- `audio/mulaw`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the audio output.

{% /summary %}

Possible values:

- `inline`: Audio data is returned inline in the response.
- `uri`: Audio data is returned as a URI.

{% /details %}

**sample_rate**: `integer`

Sample rate in Hz.

**bit_rate**: `integer`

Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}**ImageResponseFormat**{% /summary %}

Configuration for image output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the image output.

{% /summary %}

Possible values:

- `image/jpeg`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the image output.

{% /summary %}

Possible values:

- `inline`: Image data is returned inline in the response.
- `uri`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the image output.

{% /summary %}

Possible values:

- `1:1`: 1:1 aspect ratio.
- `2:3`: 2:3 aspect ratio.
- `3:2`: 3:2 aspect ratio.
- `3:4`: 3:4 aspect ratio.
- `4:3`: 4:3 aspect ratio.
- `4:5`: 4:5 aspect ratio.
- `5:4`: 5:4 aspect ratio.
- `9:16`: 9:16 aspect ratio.
- `16:9`: 16:9 aspect ratio.
- `21:9`: 21:9 aspect ratio.
- `1:8`: 1:8 aspect ratio.
- `8:1`: 8:1 aspect ratio.
- `1:4`: 1:4 aspect ratio.
- `4:1`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**image_size**: `enum (string)`

The size of the image output.

{% /summary %}

Possible values:

- `512`: 512px image size.
- `1K`: 1K image size.
- `2K`: 2K image size.
- `4K`: 4K image size.

{% /details %}

{% /details %}

{% details %}

{% summary %}**TextResponseFormat**{% /summary %}

Configuration for text output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the text output.

{% /summary %}

Possible values:

- `application/json`: JSON output format.
- `text/plain`: Plain text output format.

{% /details %}

**schema**: `object`

The JSON schema that the output should conform to. Only applicable when mime_type is application/json. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced; validate these in your application. `minItems` and `maxItems` are enforced. Schemas that are too complex to enforce (for example, large `maxItems` on nested arrays) return a 400 INVALID_ARGUMENT error.

{% /details %}

{% details %}

{% summary %}**VideoResponseFormat**{% /summary %}

Configuration for video output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the video output.

{% /summary %}

Possible values:

- `inline`: Video data is returned inline in the response.
- `uri`: Video data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the video output.

{% /summary %}

Possible values:

- `16:9`: 16:9 aspect ratio.
- `9:16`: 9:16 aspect ratio.

{% /details %}

**duration**: `string`

The duration for the video output.

{% details %}

{% summary %}

**resolution**: `enum (string)`

The video output resolution. Defaults to 720p.

{% /summary %}

Possible values:

- `360p`: 360p resolution.
- `720p`: 720p resolution.
- `1080p`: 1080p resolution.
- `4k`: 4K resolution.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (ResponseFormat)**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% details %}

{% summary %}

**environment**: `EnvironmentConfig` or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

**environment_id**: `string`

Output only. The environment ID for the interaction. Only populated if environment config is set in the request.

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

**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.

{% /details %}

{% hr /%}

**display_name**: `string`

Optional. The display name of the trigger.

{% hr /%}

**environment_id**: `string`

Optional. The environment ID for the trigger execution.

{% hr /%}

**max_consecutive_failures**: `integer`

Optional. The maximum number of consecutive failures allowed before the trigger is automatically paused (status becomes ERROR).

{% hr /%}

**execution_timeout_seconds**: `integer`

Optional. The execution timeout for the triggered interaction.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/triggers \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 9 * * *",
    "time_zone": "America/New_York",
    "interaction": {
      "agent": "antigravity-preview-05-2026",
      "input": "Summarize top news stories.",
      "environment": "remote"
    }
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
trigger = client.triggers.create(
    schedule="0 9 * * *",
    time_zone="America/New_York",
    interaction={
        "agent": "antigravity-preview-05-2026",
        "input": "Summarize top news stories.",
        "environment": "remote",
    },
)
print(trigger.id, trigger.interaction.agent)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const trigger = await ai.triggers.create({
  schedule: '0 9 * * *',
  time_zone: 'America/New_York',
  interaction: {
    agent: 'antigravity-preview-05-2026',
    input: 'Summarize top news stories.',
    environment: 'remote',
  },
});
console.log(trigger.id, trigger.interaction.agent);
```

{% /tab %}

{% tab label="Java" %}

```java
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.operations.CreateTriggerResponse;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.triggers.Trigger;
import com.google.genai.gaos.models.triggers.TriggerCreateParams;

Client client = new Client();
CreateAgentInteraction interaction =
    CreateAgentInteraction.builder()
        .agent(AgentOption.of("antigravity-preview-05-2026"))
        .input(InteractionsInput.of("Summarize top news stories."))
        .environment(CreateAgentInteractionEnvironment.of("remote"))
        .build();
TriggerCreateParams params =
    TriggerCreateParams.builder()
        .schedule("0 9 * * *")
        .timeZone("America/New_York")
        .interaction(interaction)
        .build();
CreateTriggerResponse response = client.triggers.create(params);
Trigger trigger =
    response.trigger().orElseThrow(() -> new RuntimeException("No trigger returned"));
System.out.println(
    trigger.id().orElse("")
        + " "
        + trigger.interaction().flatMap(CreateAgentInteraction::agent).orElse(null));
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**schedule**: {% mark %}required{% /mark %} `string`

The cron schedule on which the trigger should run. Standard cron format.

{% hr /%}

**time_zone**: {% mark %}required{% /mark %} `string`

Time zone in which the schedule should be interpreted.

{% hr /%}

{% details %}

{% summary %}

**interaction**: {% mark %}required{% /mark %} `CreateAgentInteractionParams`

The interaction request template to be executed.

{% /summary %}

{% details %}

{% summary %}

**agent**: {% mark %}required{% /mark %} `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

**input**: {% mark %}required{% /mark %} `Content` or `array (Content)` or `array (Step)` or `string`

The input for the interaction.

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

Configuration parameters for the agent interaction.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

**id**: `string`

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

{% details %}

{% summary %}

**status**: `enum (string)`

Required. Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

**created**: `string`

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

**updated**: `string`

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

**system_instruction**: `string`

System instruction for the interaction.

{% details %}

{% summary %}

**tools**: `array (Tool)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**ComputerUse**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `computer_use`

{% details %}

{% summary %}

**environment**: `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `browser`: Operates in a web browser.
- `mobile`: Operates in a mobile environment.
- `desktop`: Operates in a desktop environment.

{% /details %}

**excluded_predefined_functions**: `array (string)`

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

**enable_prompt_injection_detection**: `boolean`

Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabled_safety_policies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `financial_transactions`: Safety policy for financial transactions.
- `sensitive_data_modification`: Safety policy for sensitive data modification.
- `communication_tool`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `account_creation`: Safety policy for account creation.
- `data_modification`: Safety policy for data modification.
- `user_consent_management`: Safety policy for user consent management.
- `legal_terms_and_agreements`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}**FileSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleMaps**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

{% details %}

{% summary %}

**response_format**: `ResponseFormat` or `array (ResponseFormat)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AudioResponseFormat**{% /summary %}

Configuration for audio output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the audio output.

{% /summary %}

Possible values:

- `audio/mp3`: MP3 audio format.
- `audio/ogg_opus`: OGG Opus audio format.
- `audio/l16`: Raw PCM (L16) audio format.
- `audio/wav`: WAV audio format.
- `audio/alaw`: A-law audio format.
- `audio/mulaw`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the audio output.

{% /summary %}

Possible values:

- `inline`: Audio data is returned inline in the response.
- `uri`: Audio data is returned as a URI.

{% /details %}

**sample_rate**: `integer`

Sample rate in Hz.

**bit_rate**: `integer`

Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}**ImageResponseFormat**{% /summary %}

Configuration for image output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the image output.

{% /summary %}

Possible values:

- `image/jpeg`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the image output.

{% /summary %}

Possible values:

- `inline`: Image data is returned inline in the response.
- `uri`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the image output.

{% /summary %}

Possible values:

- `1:1`: 1:1 aspect ratio.
- `2:3`: 2:3 aspect ratio.
- `3:2`: 3:2 aspect ratio.
- `3:4`: 3:4 aspect ratio.
- `4:3`: 4:3 aspect ratio.
- `4:5`: 4:5 aspect ratio.
- `5:4`: 5:4 aspect ratio.
- `9:16`: 9:16 aspect ratio.
- `16:9`: 16:9 aspect ratio.
- `21:9`: 21:9 aspect ratio.
- `1:8`: 1:8 aspect ratio.
- `8:1`: 8:1 aspect ratio.
- `1:4`: 1:4 aspect ratio.
- `4:1`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**image_size**: `enum (string)`

The size of the image output.

{% /summary %}

Possible values:

- `512`: 512px image size.
- `1K`: 1K image size.
- `2K`: 2K image size.
- `4K`: 4K image size.

{% /details %}

{% /details %}

{% details %}

{% summary %}**TextResponseFormat**{% /summary %}

Configuration for text output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the text output.

{% /summary %}

Possible values:

- `application/json`: JSON output format.
- `text/plain`: Plain text output format.

{% /details %}

**schema**: `object`

The JSON schema that the output should conform to. Only applicable when mime_type is application/json. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced; validate these in your application. `minItems` and `maxItems` are enforced. Schemas that are too complex to enforce (for example, large `maxItems` on nested arrays) return a 400 INVALID_ARGUMENT error.

{% /details %}

{% details %}

{% summary %}**VideoResponseFormat**{% /summary %}

Configuration for video output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the video output.

{% /summary %}

Possible values:

- `inline`: Video data is returned inline in the response.
- `uri`: Video data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the video output.

{% /summary %}

Possible values:

- `16:9`: 16:9 aspect ratio.
- `9:16`: 9:16 aspect ratio.

{% /details %}

**duration**: `string`

The duration for the video output.

{% details %}

{% summary %}

**resolution**: `enum (string)`

The video output resolution. Defaults to 720p.

{% /summary %}

Possible values:

- `360p`: 360p resolution.
- `720p`: 720p resolution.
- `1080p`: 1080p resolution.
- `4k`: 4K resolution.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (ResponseFormat)**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% details %}

{% summary %}

**environment**: `EnvironmentConfig` or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

**environment_id**: `string`

Output only. The environment ID for the interaction. Only populated if environment config is set in the request.

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

**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.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. The ID of the trigger.

{% hr /%}

**display_name**: `string`

Optional. The display name of the trigger.

{% hr /%}

**environment_id**: `string`

Optional. The environment ID for the trigger execution.

{% hr /%}

**max_consecutive_failures**: `integer`

Optional. The maximum number of consecutive failures allowed before the trigger is automatically paused (status becomes ERROR).

{% hr /%}

**execution_timeout_seconds**: `integer`

Optional. The execution timeout for the triggered interaction.

{% hr /%}

**consecutive_failure_count**: `integer`

Output only. The number of consecutive failures that have occurred since the last successful execution.

{% hr /%}

**create_time**: `string`

Output only. The time when the trigger was created.

{% hr /%}

**update_time**: `string`

Output only. The time when the trigger was last updated.

{% hr /%}

**last_run_time**: `string`

Output only. The time when the trigger was last run.

{% hr /%}

**next_run_time**: `string`

Output only. The time when the trigger is scheduled to run next.

{% hr /%}

**last_pause_time**: `string`

Output only. The time when the trigger was last paused.

{% hr /%}

**last_resume_time**: `string`

Output only. The time when the trigger was last resumed.

{% hr /%}

**previous_interaction_id**: `string`

Output only. The ID of the last interaction created by this trigger.

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The current status of the trigger.

{% /summary %}

Possible values:

- `active`: The trigger is active and will fire on schedule.
- `paused`: The trigger is paused and will not fire.
- `error`: The trigger has entered an error state due to consecutive failures.

{% /details %}

{% /section %}

# Running a trigger
Source: https://aistudio.google.com/api-reference/triggers/run-trigger
Description: Runs a trigger immediately.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/triggers/{triggerId}/executions`

Runs a trigger immediately.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**triggerId**: {% mark %}required{% /mark %} `string`

Resource name of the trigger.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/triggers/$TRIGGER_ID/executions" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. The ID of the trigger execution.

{% hr /%}

**trigger_id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. The ID of the trigger that created this execution.

{% hr /%}

**scheduled_time**: `string`

Output only. The time when the execution was scheduled to run.

{% hr /%}

**start_time**: `string`

Output only. The time when the execution started.

{% hr /%}

**end_time**: `string`

Output only. The time when the execution finished.

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The status of the execution.

{% /summary %}

Possible values:

- `in_progress`: The execution is currently in progress.
- `completed`: The execution completed successfully.
- `failed`: The execution failed.
- `skipped`: The execution was skipped (e.g., previous execution still running).
- `timed_out`: The execution timed out.

{% /details %}

{% hr /%}

**interaction_id**: `string`

Output only. The ID of the interaction created by this execution, if any.

{% hr /%}

**environment_id**: `string`

Output only. The environment ID used for the execution.

{% hr /%}

**error**: `string`

Output only. The error message if the execution failed.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "id": "string",
  "trigger_id": "string",
  "scheduled_time": "string",
  "start_time": "string",
  "end_time": "string",
  "status": "in_progress",
  "interaction_id": "string",
  "environment_id": "string",
  "error": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

# Listing triggers
Source: https://aistudio.google.com/api-reference/triggers/list-triggers
Description: Lists triggers for a project.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/triggers`

Lists triggers for a project.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**filter**: `string`

Optional. Filter expression (e.g., by state).

{% hr /%}

**page_size**: `integer`

Optional. The maximum number of triggers to return per page.

{% hr /%}

**page_token**: `string`

Optional. A page token from a previous ListTriggers call.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/triggers" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**triggers**: `array (`[`Trigger`](/api-reference/triggers/list-triggers#Resource:Trigger)`)`

The list of triggers.

{% hr /%}

**next_page_token**: `string`

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

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "triggers": [
    {
      "schedule": "string",
      "time_zone": "string",
      "interaction": {
        "agent": "deep-research-preview-04-2026",
        "input": {
          "type": "...",
          "data": "...",
          "uri": "...",
          "channels": "...",
          "sample_rate": "...",
          "mime_type": "..."
        },
        "agent_config": {
          "type": "antigravity",
          "model": "string",
          "max_total_tokens": "string"
        },
        "id": "string",
        "status": "in_progress",
        "created": "string",
        "updated": "string",
        "system_instruction": "string",
        "tools": [
          {
            "type": "..."
          }
        ],
        "response_format": {
          "type": "audio",
          "mime_type": "audio/mp3",
          "delivery": "inline",
          "sample_rate": 0,
          "bit_rate": 0
        },
        "previous_interaction_id": "string",
        "environment": {
          "type": "remote",
          "sources": [
            "..."
          ],
          "network": {
            "allowlist": "..."
          },
          "environment_id": "string",
          "env": {}
        },
        "environment_id": "string",
        "service_tier": "flex",
        "webhook_config": {
          "uris": [
            "string"
          ],
          "user_metadata": {}
        },
        "safety_settings": [
          {
            "type": "...",
            "threshold": "block_low_and_above",
            "method": "severity"
          }
        ],
        "labels": {},
        "continuation_token": "string",
        "stream": true,
        "store": true,
        "background": true
      },
      "id": "string",
      "display_name": "string",
      "environment_id": "string",
      "max_consecutive_failures": 0,
      "execution_timeout_seconds": 0,
      "consecutive_failure_count": 0,
      "create_time": "string",
      "update_time": "string",
      "last_run_time": "string",
      "next_run_time": "string",
      "last_pause_time": "string",
      "last_resume_time": "string",
      "previous_interaction_id": "string",
      "status": "active"
    }
  ],
  "next_page_token": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### Trigger {% class="hide-from-toc" id="Resource:Trigger" %}

A trigger configuration that is scheduled to run an agent.

**Properties:**

**schedule**: {% mark %}required{% /mark %} `string`

The cron schedule on which the trigger should run. Standard cron format.

{% hr /%}

**time_zone**: {% mark %}required{% /mark %} `string`

Time zone in which the schedule should be interpreted.

{% hr /%}

{% details %}

{% summary %}

**interaction**: {% mark %}required{% /mark %} `CreateAgentInteractionParams`

The interaction request template to be executed.

{% /summary %}

{% details %}

{% summary %}

**agent**: {% mark %}required{% /mark %} `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

**input**: {% mark %}required{% /mark %} `Content` or `array (Content)` or `array (Step)` or `string`

The input for the interaction.

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

Configuration parameters for the agent interaction.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

**id**: `string`

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

{% details %}

{% summary %}

**status**: `enum (string)`

Required. Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

**created**: `string`

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

**updated**: `string`

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

**system_instruction**: `string`

System instruction for the interaction.

{% details %}

{% summary %}

**tools**: `array (Tool)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**ComputerUse**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `computer_use`

{% details %}

{% summary %}

**environment**: `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `browser`: Operates in a web browser.
- `mobile`: Operates in a mobile environment.
- `desktop`: Operates in a desktop environment.

{% /details %}

**excluded_predefined_functions**: `array (string)`

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

**enable_prompt_injection_detection**: `boolean`

Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabled_safety_policies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `financial_transactions`: Safety policy for financial transactions.
- `sensitive_data_modification`: Safety policy for sensitive data modification.
- `communication_tool`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `account_creation`: Safety policy for account creation.
- `data_modification`: Safety policy for data modification.
- `user_consent_management`: Safety policy for user consent management.
- `legal_terms_and_agreements`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}**FileSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleMaps**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

{% details %}

{% summary %}

**response_format**: `ResponseFormat` or `array (ResponseFormat)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AudioResponseFormat**{% /summary %}

Configuration for audio output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the audio output.

{% /summary %}

Possible values:

- `audio/mp3`: MP3 audio format.
- `audio/ogg_opus`: OGG Opus audio format.
- `audio/l16`: Raw PCM (L16) audio format.
- `audio/wav`: WAV audio format.
- `audio/alaw`: A-law audio format.
- `audio/mulaw`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the audio output.

{% /summary %}

Possible values:

- `inline`: Audio data is returned inline in the response.
- `uri`: Audio data is returned as a URI.

{% /details %}

**sample_rate**: `integer`

Sample rate in Hz.

**bit_rate**: `integer`

Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}**ImageResponseFormat**{% /summary %}

Configuration for image output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the image output.

{% /summary %}

Possible values:

- `image/jpeg`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the image output.

{% /summary %}

Possible values:

- `inline`: Image data is returned inline in the response.
- `uri`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the image output.

{% /summary %}

Possible values:

- `1:1`: 1:1 aspect ratio.
- `2:3`: 2:3 aspect ratio.
- `3:2`: 3:2 aspect ratio.
- `3:4`: 3:4 aspect ratio.
- `4:3`: 4:3 aspect ratio.
- `4:5`: 4:5 aspect ratio.
- `5:4`: 5:4 aspect ratio.
- `9:16`: 9:16 aspect ratio.
- `16:9`: 16:9 aspect ratio.
- `21:9`: 21:9 aspect ratio.
- `1:8`: 1:8 aspect ratio.
- `8:1`: 8:1 aspect ratio.
- `1:4`: 1:4 aspect ratio.
- `4:1`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**image_size**: `enum (string)`

The size of the image output.

{% /summary %}

Possible values:

- `512`: 512px image size.
- `1K`: 1K image size.
- `2K`: 2K image size.
- `4K`: 4K image size.

{% /details %}

{% /details %}

{% details %}

{% summary %}**TextResponseFormat**{% /summary %}

Configuration for text output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the text output.

{% /summary %}

Possible values:

- `application/json`: JSON output format.
- `text/plain`: Plain text output format.

{% /details %}

**schema**: `object`

The JSON schema that the output should conform to. Only applicable when mime_type is application/json. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced; validate these in your application. `minItems` and `maxItems` are enforced. Schemas that are too complex to enforce (for example, large `maxItems` on nested arrays) return a 400 INVALID_ARGUMENT error.

{% /details %}

{% details %}

{% summary %}**VideoResponseFormat**{% /summary %}

Configuration for video output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the video output.

{% /summary %}

Possible values:

- `inline`: Video data is returned inline in the response.
- `uri`: Video data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the video output.

{% /summary %}

Possible values:

- `16:9`: 16:9 aspect ratio.
- `9:16`: 9:16 aspect ratio.

{% /details %}

**duration**: `string`

The duration for the video output.

{% details %}

{% summary %}

**resolution**: `enum (string)`

The video output resolution. Defaults to 720p.

{% /summary %}

Possible values:

- `360p`: 360p resolution.
- `720p`: 720p resolution.
- `1080p`: 1080p resolution.
- `4k`: 4K resolution.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (ResponseFormat)**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% details %}

{% summary %}

**environment**: `EnvironmentConfig` or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

**environment_id**: `string`

Output only. The environment ID for the interaction. Only populated if environment config is set in the request.

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

**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.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. The ID of the trigger.

{% hr /%}

**display_name**: `string`

Optional. The display name of the trigger.

{% hr /%}

**environment_id**: `string`

Optional. The environment ID for the trigger execution.

{% hr /%}

**max_consecutive_failures**: `integer`

Optional. The maximum number of consecutive failures allowed before the trigger is automatically paused (status becomes ERROR).

{% hr /%}

**execution_timeout_seconds**: `integer`

Optional. The execution timeout for the triggered interaction.

{% hr /%}

**consecutive_failure_count**: `integer`

Output only. The number of consecutive failures that have occurred since the last successful execution.

{% hr /%}

**create_time**: `string`

Output only. The time when the trigger was created.

{% hr /%}

**update_time**: `string`

Output only. The time when the trigger was last updated.

{% hr /%}

**last_run_time**: `string`

Output only. The time when the trigger was last run.

{% hr /%}

**next_run_time**: `string`

Output only. The time when the trigger is scheduled to run next.

{% hr /%}

**last_pause_time**: `string`

Output only. The time when the trigger was last paused.

{% hr /%}

**last_resume_time**: `string`

Output only. The time when the trigger was last resumed.

{% hr /%}

**previous_interaction_id**: `string`

Output only. The ID of the last interaction created by this trigger.

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The current status of the trigger.

{% /summary %}

Possible values:

- `active`: The trigger is active and will fire on schedule.
- `paused`: The trigger is paused and will not fire.
- `error`: The trigger has entered an error state due to consecutive failures.

{% /details %}

# Getting a trigger
Source: https://aistudio.google.com/api-reference/triggers/get-trigger
Description: Gets details of a single trigger.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/triggers/{id}`

Gets details of a single trigger.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Resource name of the trigger.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/triggers/$TRIGGER_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**schedule**: {% mark %}required{% /mark %} `string`

The cron schedule on which the trigger should run. Standard cron format.

{% hr /%}

**time_zone**: {% mark %}required{% /mark %} `string`

Time zone in which the schedule should be interpreted.

{% hr /%}

{% details %}

{% summary %}

**interaction**: {% mark %}required{% /mark %} `CreateAgentInteractionParams`

The interaction request template to be executed.

{% /summary %}

{% details %}

{% summary %}

**agent**: {% mark %}required{% /mark %} `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

**input**: {% mark %}required{% /mark %} `Content` or `array (Content)` or `array (Step)` or `string`

The input for the interaction.

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

Configuration parameters for the agent interaction.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

**id**: `string`

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

{% details %}

{% summary %}

**status**: `enum (string)`

Required. Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

**created**: `string`

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

**updated**: `string`

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

**system_instruction**: `string`

System instruction for the interaction.

{% details %}

{% summary %}

**tools**: `array (Tool)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**ComputerUse**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `computer_use`

{% details %}

{% summary %}

**environment**: `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `browser`: Operates in a web browser.
- `mobile`: Operates in a mobile environment.
- `desktop`: Operates in a desktop environment.

{% /details %}

**excluded_predefined_functions**: `array (string)`

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

**enable_prompt_injection_detection**: `boolean`

Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabled_safety_policies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `financial_transactions`: Safety policy for financial transactions.
- `sensitive_data_modification`: Safety policy for sensitive data modification.
- `communication_tool`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `account_creation`: Safety policy for account creation.
- `data_modification`: Safety policy for data modification.
- `user_consent_management`: Safety policy for user consent management.
- `legal_terms_and_agreements`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}**FileSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleMaps**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

{% details %}

{% summary %}

**response_format**: `ResponseFormat` or `array (ResponseFormat)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AudioResponseFormat**{% /summary %}

Configuration for audio output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the audio output.

{% /summary %}

Possible values:

- `audio/mp3`: MP3 audio format.
- `audio/ogg_opus`: OGG Opus audio format.
- `audio/l16`: Raw PCM (L16) audio format.
- `audio/wav`: WAV audio format.
- `audio/alaw`: A-law audio format.
- `audio/mulaw`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the audio output.

{% /summary %}

Possible values:

- `inline`: Audio data is returned inline in the response.
- `uri`: Audio data is returned as a URI.

{% /details %}

**sample_rate**: `integer`

Sample rate in Hz.

**bit_rate**: `integer`

Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}**ImageResponseFormat**{% /summary %}

Configuration for image output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the image output.

{% /summary %}

Possible values:

- `image/jpeg`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the image output.

{% /summary %}

Possible values:

- `inline`: Image data is returned inline in the response.
- `uri`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the image output.

{% /summary %}

Possible values:

- `1:1`: 1:1 aspect ratio.
- `2:3`: 2:3 aspect ratio.
- `3:2`: 3:2 aspect ratio.
- `3:4`: 3:4 aspect ratio.
- `4:3`: 4:3 aspect ratio.
- `4:5`: 4:5 aspect ratio.
- `5:4`: 5:4 aspect ratio.
- `9:16`: 9:16 aspect ratio.
- `16:9`: 16:9 aspect ratio.
- `21:9`: 21:9 aspect ratio.
- `1:8`: 1:8 aspect ratio.
- `8:1`: 8:1 aspect ratio.
- `1:4`: 1:4 aspect ratio.
- `4:1`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**image_size**: `enum (string)`

The size of the image output.

{% /summary %}

Possible values:

- `512`: 512px image size.
- `1K`: 1K image size.
- `2K`: 2K image size.
- `4K`: 4K image size.

{% /details %}

{% /details %}

{% details %}

{% summary %}**TextResponseFormat**{% /summary %}

Configuration for text output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the text output.

{% /summary %}

Possible values:

- `application/json`: JSON output format.
- `text/plain`: Plain text output format.

{% /details %}

**schema**: `object`

The JSON schema that the output should conform to. Only applicable when mime_type is application/json. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced; validate these in your application. `minItems` and `maxItems` are enforced. Schemas that are too complex to enforce (for example, large `maxItems` on nested arrays) return a 400 INVALID_ARGUMENT error.

{% /details %}

{% details %}

{% summary %}**VideoResponseFormat**{% /summary %}

Configuration for video output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the video output.

{% /summary %}

Possible values:

- `inline`: Video data is returned inline in the response.
- `uri`: Video data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the video output.

{% /summary %}

Possible values:

- `16:9`: 16:9 aspect ratio.
- `9:16`: 9:16 aspect ratio.

{% /details %}

**duration**: `string`

The duration for the video output.

{% details %}

{% summary %}

**resolution**: `enum (string)`

The video output resolution. Defaults to 720p.

{% /summary %}

Possible values:

- `360p`: 360p resolution.
- `720p`: 720p resolution.
- `1080p`: 1080p resolution.
- `4k`: 4K resolution.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (ResponseFormat)**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% details %}

{% summary %}

**environment**: `EnvironmentConfig` or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

**environment_id**: `string`

Output only. The environment ID for the interaction. Only populated if environment config is set in the request.

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

**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.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. The ID of the trigger.

{% hr /%}

**display_name**: `string`

Optional. The display name of the trigger.

{% hr /%}

**environment_id**: `string`

Optional. The environment ID for the trigger execution.

{% hr /%}

**max_consecutive_failures**: `integer`

Optional. The maximum number of consecutive failures allowed before the trigger is automatically paused (status becomes ERROR).

{% hr /%}

**execution_timeout_seconds**: `integer`

Optional. The execution timeout for the triggered interaction.

{% hr /%}

**consecutive_failure_count**: `integer`

Output only. The number of consecutive failures that have occurred since the last successful execution.

{% hr /%}

**create_time**: `string`

Output only. The time when the trigger was created.

{% hr /%}

**update_time**: `string`

Output only. The time when the trigger was last updated.

{% hr /%}

**last_run_time**: `string`

Output only. The time when the trigger was last run.

{% hr /%}

**next_run_time**: `string`

Output only. The time when the trigger is scheduled to run next.

{% hr /%}

**last_pause_time**: `string`

Output only. The time when the trigger was last paused.

{% hr /%}

**last_resume_time**: `string`

Output only. The time when the trigger was last resumed.

{% hr /%}

**previous_interaction_id**: `string`

Output only. The ID of the last interaction created by this trigger.

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The current status of the trigger.

{% /summary %}

Possible values:

- `active`: The trigger is active and will fire on schedule.
- `paused`: The trigger is paused and will not fire.
- `error`: The trigger has entered an error state due to consecutive failures.

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "schedule": "string",
  "time_zone": "string",
  "interaction": {
    "agent": "deep-research-preview-04-2026",
    "input": {
      "type": "audio",
      "data": "string",
      "uri": "string",
      "channels": 0,
      "sample_rate": 0,
      "mime_type": "audio/wav"
    },
    "agent_config": {
      "type": "antigravity",
      "model": "string",
      "max_total_tokens": "string"
    },
    "id": "string",
    "status": "in_progress",
    "created": "string",
    "updated": "string",
    "system_instruction": "string",
    "tools": [
      {
        "type": "code_execution"
      }
    ],
    "response_format": {
      "type": "audio",
      "mime_type": "audio/mp3",
      "delivery": "inline",
      "sample_rate": 0,
      "bit_rate": 0
    },
    "previous_interaction_id": "string",
    "environment": {
      "type": "remote",
      "sources": [
        {
          "type": "gcs",
          "source": "string",
          "target": "string",
          "content": "string",
          "encoding": "string"
        }
      ],
      "network": {
        "allowlist": [
          {
            "domain": "...",
            "transform": "...",
            "credential": "..."
          }
        ]
      },
      "environment_id": "string",
      "env": {}
    },
    "environment_id": "string",
    "service_tier": "flex",
    "webhook_config": {
      "uris": [
        "string"
      ],
      "user_metadata": {}
    },
    "safety_settings": [
      {
        "type": "hate_speech",
        "threshold": "block_low_and_above",
        "method": "severity"
      }
    ],
    "labels": {},
    "continuation_token": "string",
    "stream": true,
    "store": true,
    "background": true
  },
  "id": "string",
  "display_name": "string",
  "environment_id": "string",
  "max_consecutive_failures": 0,
  "execution_timeout_seconds": 0,
  "consecutive_failure_count": 0,
  "create_time": "string",
  "update_time": "string",
  "last_run_time": "string",
  "next_run_time": "string",
  "last_pause_time": "string",
  "last_resume_time": "string",
  "previous_interaction_id": "string",
  "status": "active"
}
```

{% /right-column %}

{% /two-column-layout %}

# Listing trigger executions
Source: https://aistudio.google.com/api-reference/triggers/list-trigger-executions
Description: Lists executions for a trigger.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/triggers/{triggerId}/executions`

Lists executions for a trigger.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**triggerId**: {% mark %}required{% /mark %} `string`

The trigger ID to list executions from.

{% hr /%}

**filter**: `string`

Optional. Filter expression.

{% hr /%}

**page_size**: `integer`

The maximum number of executions to return per page.

{% hr /%}

**page_token**: `string`

A page token from a previous ListTriggerExecutions call.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/triggers/$TRIGGER_ID/executions" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**trigger_executions**: `array (TriggerExecution)`

The list of trigger executions.

{% /summary %}

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. The ID of the trigger execution.

**trigger_id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. The ID of the trigger that created this execution.

**scheduled_time**: `string`

Output only. The time when the execution was scheduled to run.

**start_time**: `string`

Output only. The time when the execution started.

**end_time**: `string`

Output only. The time when the execution finished.

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The status of the execution.

{% /summary %}

Possible values:

- `in_progress`: The execution is currently in progress.
- `completed`: The execution completed successfully.
- `failed`: The execution failed.
- `skipped`: The execution was skipped (e.g., previous execution still running).
- `timed_out`: The execution timed out.

{% /details %}

**interaction_id**: `string`

Output only. The ID of the interaction created by this execution, if any.

**environment_id**: `string`

Output only. The environment ID used for the execution.

**error**: `string`

Output only. The error message if the execution failed.

{% /details %}

{% hr /%}

**next_page_token**: `string`

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

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "trigger_executions": [
    {
      "id": "string",
      "trigger_id": "string",
      "scheduled_time": "string",
      "start_time": "string",
      "end_time": "string",
      "status": "in_progress",
      "interaction_id": "string",
      "environment_id": "string",
      "error": "string"
    }
  ],
  "next_page_token": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

# Updating a trigger
Source: https://aistudio.google.com/api-reference/triggers/update-trigger
Description: Updates a trigger.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/triggers/{id}`

Updates a trigger.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Resource name of the trigger.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**trigger**: {% mark %}required{% /mark %} `TriggerUpdate`

The trigger to update.

{% /summary %}

{% details %}

{% summary %}

**status**: `enum (string)`

Optional. The status of the trigger.

{% /summary %}

Possible values:

- `active`: The trigger is active and will fire on schedule.
- `paused`: The trigger is paused and will not fire.
- `error`: The trigger has entered an error state due to consecutive failures.

{% /details %}

**display_name**: `string`

Optional. The display name of the trigger.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

The ID of the trigger to update.

{% hr /%}

**update_mask**: `string`

Optional. The update mask applies to the resource.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/triggers/$TRIGGER_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "trigger": {
    "status": "active"
  },
  "id": "string"
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**schedule**: {% mark %}required{% /mark %} `string`

The cron schedule on which the trigger should run. Standard cron format.

{% hr /%}

**time_zone**: {% mark %}required{% /mark %} `string`

Time zone in which the schedule should be interpreted.

{% hr /%}

{% details %}

{% summary %}

**interaction**: {% mark %}required{% /mark %} `CreateAgentInteractionParams`

The interaction request template to be executed.

{% /summary %}

{% details %}

{% summary %}

**agent**: {% mark %}required{% /mark %} `AgentOption`

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

{% /summary %}

Possible values:

- `deep-research-preview-04-2026`: Gemini Deep Research Agent
- `deep-research-max-preview-04-2026`: Gemini Deep Research Max Agent
- `antigravity-preview-05-2026`: Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use.

{% /details %}

**input**: {% mark %}required{% /mark %} `Content` or `array (Content)` or `array (Step)` or `string`

The input for the interaction.

{% details %}

{% summary %}

**agent_config**: `AntigravityAgentConfig` or `DeepResearchAgentConfig` or `DynamicAgentConfig`

Configuration parameters for the agent interaction.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AntigravityAgentConfig**{% /summary %}

Configuration for the Antigravity agent runtime. Provides server-side control over the agent's execution environment and tool configuration.

**type**: {% mark %}required{% /mark %} `object`

Value: `antigravity`

**model**: `string`

The model to use for agent reasoning.

**max_total_tokens**: `string`

Max total tokens for the agent run.

{% /details %}

{% details %}

{% summary %}**DeepResearchAgentConfig**{% /summary %}

Configuration for the Deep Research agent.

**type**: {% mark %}required{% /mark %} `object`

Value: `deep-research`

{% details %}

{% summary %}

**thinking_summaries**: `ThinkingSummaries`

Whether to include thought summaries in the response.

{% /summary %}

Possible values:

- `auto`: Auto thinking summaries.
- `none`: No thinking summaries.

{% /details %}

{% details %}

{% summary %}

**visualization**: `enum (string)`

Whether to include visualizations in the response.

{% /summary %}

Possible values:

- `off`: Do not include visualizations.
- `auto`: Automatically include visualizations.

{% /details %}

**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.

{% /details %}

{% details %}

{% summary %}**DynamicAgentConfig**{% /summary %}

Configuration for dynamic agents.

**type**: {% mark %}required{% /mark %} `object`

Value: `dynamic`

{% /details %}

{% /details %}

**id**: `string`

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

{% details %}

{% summary %}

**status**: `enum (string)`

Required. Output only. The status of the interaction.

{% /summary %}

Possible values:

- `in_progress`: The interaction is in progress.
- `requires_action`: The interaction requires action/input from the user.
- `completed`: The interaction is completed.
- `failed`: The interaction failed.
- `cancelled`: The interaction was cancelled.
- `incomplete`: The interaction is completed, but contains incomplete results (e.g. hitting max_tokens).
- `requires_continuation`: The interaction requires at least one more request for it to be completed. The next request should set the continuation_token to the one returned by this request.

{% /details %}

**created**: `string`

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

**updated**: `string`

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

**system_instruction**: `string`

System instruction for the interaction.

{% details %}

{% summary %}

**tools**: `array (Tool)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**CodeExecution**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `code_execution`

{% /details %}

{% details %}

{% summary %}**ComputerUse**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `computer_use`

{% details %}

{% summary %}

**environment**: `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `browser`: Operates in a web browser.
- `mobile`: Operates in a mobile environment.
- `desktop`: Operates in a desktop environment.

{% /details %}

**excluded_predefined_functions**: `array (string)`

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

**enable_prompt_injection_detection**: `boolean`

Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabled_safety_policies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `financial_transactions`: Safety policy for financial transactions.
- `sensitive_data_modification`: Safety policy for sensitive data modification.
- `communication_tool`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `account_creation`: Safety policy for account creation.
- `data_modification`: Safety policy for data modification.
- `user_consent_management`: Safety policy for user consent management.
- `legal_terms_and_agreements`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}**FileSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**Function**{% /summary %}

A tool that can be used by the model.

**type**: {% mark %}required{% /mark %} `object`

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. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

{% /details %}

{% details %}

{% summary %}**GoogleMaps**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% /details %}

{% details %}

{% summary %}**GoogleSearch**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `google_search`

{% details %}

{% summary %}

**search_types**: `array (enum (string))`

The types of search grounding to enable.

{% /summary %}

Possible values:

- `web_search`: Setting this field enables web search. Only text results are returned.
- `image_search`: Setting this field enables image search. Image bytes are returned.

{% /details %}

{% /details %}

{% details %}

{% summary %}**McpServer**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

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.

{% details %}

{% summary %}

**allowed_tools**: `array (AllowedTools)`

The allowed tools.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the tool choice.

{% /summary %}

Possible values:

- `auto`: Auto tool choice.
- `any`: Any tool choice.
- `none`: No tool choice.
- `validated`: Validated tool choice.

{% /details %}

**tools**: `array (string)`

The names of the allowed tools.

{% /details %}

{% /details %}

{% details %}

{% summary %}**UrlContext**{% /summary %}

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

**type**: {% mark %}required{% /mark %} `object`

Value: `url_context`

{% /details %}

{% /details %}

{% details %}

{% summary %}

**response_format**: `ResponseFormat` or `array (ResponseFormat)`

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

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**AudioResponseFormat**{% /summary %}

Configuration for audio output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `audio`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the audio output.

{% /summary %}

Possible values:

- `audio/mp3`: MP3 audio format.
- `audio/ogg_opus`: OGG Opus audio format.
- `audio/l16`: Raw PCM (L16) audio format.
- `audio/wav`: WAV audio format.
- `audio/alaw`: A-law audio format.
- `audio/mulaw`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the audio output.

{% /summary %}

Possible values:

- `inline`: Audio data is returned inline in the response.
- `uri`: Audio data is returned as a URI.

{% /details %}

**sample_rate**: `integer`

Sample rate in Hz.

**bit_rate**: `integer`

Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}**ImageResponseFormat**{% /summary %}

Configuration for image output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `image`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the image output.

{% /summary %}

Possible values:

- `image/jpeg`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the image output.

{% /summary %}

Possible values:

- `inline`: Image data is returned inline in the response.
- `uri`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the image output.

{% /summary %}

Possible values:

- `1:1`: 1:1 aspect ratio.
- `2:3`: 2:3 aspect ratio.
- `3:2`: 3:2 aspect ratio.
- `3:4`: 3:4 aspect ratio.
- `4:3`: 4:3 aspect ratio.
- `4:5`: 4:5 aspect ratio.
- `5:4`: 5:4 aspect ratio.
- `9:16`: 9:16 aspect ratio.
- `16:9`: 16:9 aspect ratio.
- `21:9`: 21:9 aspect ratio.
- `1:8`: 1:8 aspect ratio.
- `8:1`: 8:1 aspect ratio.
- `1:4`: 1:4 aspect ratio.
- `4:1`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**image_size**: `enum (string)`

The size of the image output.

{% /summary %}

Possible values:

- `512`: 512px image size.
- `1K`: 1K image size.
- `2K`: 2K image size.
- `4K`: 4K image size.

{% /details %}

{% /details %}

{% details %}

{% summary %}**TextResponseFormat**{% /summary %}

Configuration for text output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `text`

{% details %}

{% summary %}

**mime_type**: `enum (string)`

The MIME type of the text output.

{% /summary %}

Possible values:

- `application/json`: JSON output format.
- `text/plain`: Plain text output format.

{% /details %}

**schema**: `object`

The JSON schema that the output should conform to. Only applicable when mime_type is application/json. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced; validate these in your application. `minItems` and `maxItems` are enforced. Schemas that are too complex to enforce (for example, large `maxItems` on nested arrays) return a 400 INVALID_ARGUMENT error.

{% /details %}

{% details %}

{% summary %}**VideoResponseFormat**{% /summary %}

Configuration for video output format.

**type**: {% mark %}required{% /mark %} `object`

Value: `video`

{% details %}

{% summary %}

**delivery**: `enum (string)`

The delivery mode for the video output.

{% /summary %}

Possible values:

- `inline`: Video data is returned inline in the response.
- `uri`: Video data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspect_ratio**: `enum (string)`

The aspect ratio for the video output.

{% /summary %}

Possible values:

- `16:9`: 16:9 aspect ratio.
- `9:16`: 9:16 aspect ratio.

{% /details %}

**duration**: `string`

The duration for the video output.

{% details %}

{% summary %}

**resolution**: `enum (string)`

The video output resolution. Defaults to 720p.

{% /summary %}

Possible values:

- `360p`: 360p resolution.
- `720p`: 720p resolution.
- `1080p`: 1080p resolution.
- `4k`: 4K resolution.

{% /details %}

{% /details %}

{% details %}

{% summary %}**array (ResponseFormat)**{% /summary %}

A list where each item is one of: `AudioResponseFormat`, `ImageResponseFormat`, `TextResponseFormat`, `VideoResponseFormat`.

{% /details %}

{% /details %}

**previous_interaction_id**: `string`

The ID of the previous interaction, if any.

{% details %}

{% summary %}

**environment**: `EnvironmentConfig` or `string`

The environment configuration for the interaction. Can be an object specifying remote environment sources or a string referencing an existing environment ID.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentConfig**{% /summary %}

Configuration for a custom environment.

**type**: {% mark %}required{% /mark %} `object`

Value: `remote`

{% details %}

{% summary %}

**sources**: `array (Source)`

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

{% /summary %}

Possible values:

- `gcs`: A Cloud Storage bucket.
- `inline`: Inline content.
- `repository`: A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

{% /details %}

**source**: `string`

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

**target**: `string`

Where the source should appear in the environment.

**content**: `string`

The inline content if `type` is `INLINE`.

**encoding**: `string`

Optional encoding for inline content (e.g. `base64`).

{% /details %}

{% details %}

{% summary %}

**network**: `EnvironmentNetworkEgressAllowlist` or `enum (string)`

Network configuration for the environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**EnvironmentNetworkEgressAllowlist**{% /summary %}

Network egress configuration for the environment.

{% details %}

{% summary %}

**allowlist**: `array (EgressRule)` or `enum (string)`

List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**array (EgressRule)**{% /summary %}

A single domain allowlist rule with optional header injection.

**domain**: {% mark %}required{% /mark %} `string`

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

**transform**: `object`

Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

**credential**: `string`

Optional. Reference to a server-managed Credential resource by ID.

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**enum (string)**{% /summary %}

Possible values:

- `disabled`: All network egress is blocked.

{% /details %}

{% /details %}

**environment_id**: `string`

Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

{% details %}

{% summary %}

**env**: `object` or `string`

Environment variables to set in the sandbox environment.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**string**{% /summary %}

A direct string value.

{% /details %}

{% /details %}

**environment_id**: `string`

Output only. The environment ID for the interaction. Only populated if environment config is set in the request.

{% details %}

{% summary %}

**service_tier**: `ServiceTier`

The service tier for the interaction.

{% /summary %}

Possible values:

- `flex`: Flex service tier.
- `standard`: Standard service tier.
- `priority`: Priority service tier.

{% /details %}

{% details %}

{% summary %}

**webhook_config**: `WebhookConfig`

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

{% /summary %}

**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.

{% /details %}

{% details %}

{% summary %}

**safety_settings**: `array (SafetySetting)`

Safety settings for the interaction.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `HarmCategory`

The type of harm category to be blocked.

{% /summary %}

Possible values:

- `hate_speech`: Content that promotes violence or incites hatred against individuals or groups based on certain attributes.
- `dangerous_content`: Content that promotes, facilitates, or enables dangerous activities.
- `harassment`: Abusive, threatening, or content intended to bully, torment, or ridicule.
- `sexually_explicit`: Content that contains sexually explicit material.
- `jailbreak`: Prompts designed to bypass safety filters.

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

The threshold for blocking content. If the harm probability exceeds this threshold, the content will be blocked.

{% /summary %}

Possible values:

- `block_low_and_above`: Block content with a low harm probability or higher.
- `block_medium_and_above`: Block content with a medium harm probability or higher.
- `block_only_high`: Block content with a high harm probability.
- `off`: Turn off the safety filter entirely.

{% /details %}

{% details %}

{% summary %}

**method**: `enum (string)`

Optional. The method for blocking content. If not specified, the default behavior is to use the probability score.

{% /summary %}

Possible values:

- `severity`: The harm block method uses both probability and severity scores.
- `probability`: The harm block method uses the probability score.

{% /details %}

{% /details %}

**labels**: `object`

The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.

**continuation_token**: `string`

Opaque token to resume a long decode. Output: set when status is REQUIRES_CONTINUATION and decoding can be resumed. Input: pass the latest token back unchanged in CreateInteraction to continue decoding.

**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.

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. The ID of the trigger.

{% hr /%}

**display_name**: `string`

Optional. The display name of the trigger.

{% hr /%}

**environment_id**: `string`

Optional. The environment ID for the trigger execution.

{% hr /%}

**max_consecutive_failures**: `integer`

Optional. The maximum number of consecutive failures allowed before the trigger is automatically paused (status becomes ERROR).

{% hr /%}

**execution_timeout_seconds**: `integer`

Optional. The execution timeout for the triggered interaction.

{% hr /%}

**consecutive_failure_count**: `integer`

Output only. The number of consecutive failures that have occurred since the last successful execution.

{% hr /%}

**create_time**: `string`

Output only. The time when the trigger was created.

{% hr /%}

**update_time**: `string`

Output only. The time when the trigger was last updated.

{% hr /%}

**last_run_time**: `string`

Output only. The time when the trigger was last run.

{% hr /%}

**next_run_time**: `string`

Output only. The time when the trigger is scheduled to run next.

{% hr /%}

**last_pause_time**: `string`

Output only. The time when the trigger was last paused.

{% hr /%}

**last_resume_time**: `string`

Output only. The time when the trigger was last resumed.

{% hr /%}

**previous_interaction_id**: `string`

Output only. The ID of the last interaction created by this trigger.

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. The current status of the trigger.

{% /summary %}

Possible values:

- `active`: The trigger is active and will fire on schedule.
- `paused`: The trigger is paused and will not fire.
- `error`: The trigger has entered an error state due to consecutive failures.

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "schedule": "string",
  "time_zone": "string",
  "interaction": {
    "agent": "deep-research-preview-04-2026",
    "input": {
      "type": "audio",
      "data": "string",
      "uri": "string",
      "channels": 0,
      "sample_rate": 0,
      "mime_type": "audio/wav"
    },
    "agent_config": {
      "type": "antigravity",
      "model": "string",
      "max_total_tokens": "string"
    },
    "id": "string",
    "status": "in_progress",
    "created": "string",
    "updated": "string",
    "system_instruction": "string",
    "tools": [
      {
        "type": "code_execution"
      }
    ],
    "response_format": {
      "type": "audio",
      "mime_type": "audio/mp3",
      "delivery": "inline",
      "sample_rate": 0,
      "bit_rate": 0
    },
    "previous_interaction_id": "string",
    "environment": {
      "type": "remote",
      "sources": [
        {
          "type": "gcs",
          "source": "string",
          "target": "string",
          "content": "string",
          "encoding": "string"
        }
      ],
      "network": {
        "allowlist": [
          {
            "domain": "...",
            "transform": "...",
            "credential": "..."
          }
        ]
      },
      "environment_id": "string",
      "env": {}
    },
    "environment_id": "string",
    "service_tier": "flex",
    "webhook_config": {
      "uris": [
        "string"
      ],
      "user_metadata": {}
    },
    "safety_settings": [
      {
        "type": "hate_speech",
        "threshold": "block_low_and_above",
        "method": "severity"
      }
    ],
    "labels": {},
    "continuation_token": "string",
    "stream": true,
    "store": true,
    "background": true
  },
  "id": "string",
  "display_name": "string",
  "environment_id": "string",
  "max_consecutive_failures": 0,
  "execution_timeout_seconds": 0,
  "consecutive_failure_count": 0,
  "create_time": "string",
  "update_time": "string",
  "last_run_time": "string",
  "next_run_time": "string",
  "last_pause_time": "string",
  "last_resume_time": "string",
  "previous_interaction_id": "string",
  "status": "active"
}
```

{% /right-column %}

{% /two-column-layout %}

# Deleting a trigger
Source: https://aistudio.google.com/api-reference/triggers/delete-trigger
Description: Deletes a trigger.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/triggers/{id}`

Deletes a trigger.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Resource name of the trigger.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/triggers/$TRIGGER_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Gemini Webhooks API
Source: https://aistudio.google.com/api-reference/webhooks
Description: Webhooks allow the Gemini API to push real-time notifications to your server when asynchronous or Long-Running Operations (LROs) complete.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

Webhooks allow the Gemini API to push real-time notifications to your server when asynchronous or Long-Running Operations (LROs) complete. This replaces the need to poll the API for status updates, reducing latency and overhead.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Creating a webhook](/api-reference/webhooks/create-webhook)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/webhooks`

  Creates a new Webhook.
---

* [Pinging a webhook](/api-reference/webhooks/ping-webhook)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/webhooks/{id}:ping`

  Sends a ping event to a Webhook.
---

* [Rotating a webhook signing secret](/api-reference/webhooks/rotate-signing-secret)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/webhooks/{id}:rotateSigningSecret`

  Generates a new signing secret for a Webhook.
---

* [Listing webhooks](/api-reference/webhooks/list-webhooks)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/webhooks`

  Lists all Webhooks.
---

* [Getting a webhook](/api-reference/webhooks/get-webhook)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/webhooks/{id}`

  Gets a specific Webhook.
---

* [Updating a webhook](/api-reference/webhooks/update-webhook)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/webhooks/{id}`

  Updates an existing Webhook.
---

* [Deleting a webhook](/api-reference/webhooks/delete-webhook)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/webhooks/{id}`

  Deletes a Webhook.
{% /table %}

## Resources {% id="resources" %}

### Webhook {% id="Resource:Webhook" %}

A Webhook resource.

**Properties:**

**uri**: {% mark %}required{% /mark %} `string`

The URI to which webhook events will be sent.

{% hr /%}

**subscribed_events**: {% mark %}required{% /mark %} `array (string)`

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

{% hr /%}

**name**: `string`

Optional. The user-provided name of the webhook.

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the webhook was created.

{% hr /%}

**update_time**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**signing_secrets**: `array (SigningSecret)`

Output only. The signing secrets associated with this webhook.

{% /summary %}

**truncated_secret**: `string`

Output only. The truncated version of the signing secret.

**expire_time**: `string`

Output only. The expiration date of the signing secret.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. The state of the webhook.

{% /summary %}

Possible values:

- `enabled`: The webhook is enabled.
- `disabled`: The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`: The webhook is disabled due to failed deliveries.

{% /details %}

{% hr /%}

**new_signing_secret**: `string`

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

{% hr /%}

**id**: `string`

Output only. The ID of the webhook.

# Creating a webhook
Source: https://aistudio.google.com/api-reference/webhooks/create-webhook
Description: Creates a new Webhook.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/webhooks`

Creates a new Webhook.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**webhook_id**: `string`

The webhook_id to use for the webhook. If not specified, the server will generate a unique ID.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**webhook**: {% mark %}required{% /mark %} [`Webhook`](/api-reference/webhooks/create-webhook#Resource:Webhook)

The webhook to create.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/webhooks" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "webhook": {
    "uri": "string",
    "subscribed_events": [
      "string"
    ]
  }
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**uri**: {% mark %}required{% /mark %} `string`

The URI to which webhook events will be sent.

{% hr /%}

**subscribed_events**: {% mark %}required{% /mark %} `array (string)`

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

{% hr /%}

**name**: `string`

Optional. The user-provided name of the webhook.

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the webhook was created.

{% hr /%}

**update_time**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**signing_secrets**: `array (SigningSecret)`

Output only. The signing secrets associated with this webhook.

{% /summary %}

**truncated_secret**: `string`

Output only. The truncated version of the signing secret.

**expire_time**: `string`

Output only. The expiration date of the signing secret.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. The state of the webhook.

{% /summary %}

Possible values:

- `enabled`: The webhook is enabled.
- `disabled`: The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`: The webhook is disabled due to failed deliveries.

{% /details %}

{% hr /%}

**new_signing_secret**: `string`

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

{% hr /%}

**id**: `string`

Output only. The ID of the webhook.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

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

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### Webhook {% class="hide-from-toc" id="Resource:Webhook" %}

A Webhook resource.

**Properties:**

**uri**: {% mark %}required{% /mark %} `string`

The URI to which webhook events will be sent.

{% hr /%}

**subscribed_events**: {% mark %}required{% /mark %} `array (string)`

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

{% hr /%}

**name**: `string`

Optional. The user-provided name of the webhook.

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the webhook was created.

{% hr /%}

**update_time**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**signing_secrets**: `array (SigningSecret)`

Output only. The signing secrets associated with this webhook.

{% /summary %}

**truncated_secret**: `string`

Output only. The truncated version of the signing secret.

**expire_time**: `string`

Output only. The expiration date of the signing secret.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. The state of the webhook.

{% /summary %}

Possible values:

- `enabled`: The webhook is enabled.
- `disabled`: The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`: The webhook is disabled due to failed deliveries.

{% /details %}

{% hr /%}

**new_signing_secret**: `string`

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

{% hr /%}

**id**: `string`

Output only. The ID of the webhook.

# Pinging a webhook
Source: https://aistudio.google.com/api-reference/webhooks/ping-webhook
Description: Sends a ping event to a Webhook.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:ping`

Sends a ping event to a Webhook.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

The ID of the webhook to ping.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/webhooks/$WEBHOOK_ID:ping" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Rotating a webhook signing secret
Source: https://aistudio.google.com/api-reference/webhooks/rotate-signing-secret
Description: Generates a new signing secret for a Webhook.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:rotateSigningSecret`

Generates a new signing secret for a Webhook.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

The ID of the webhook for which to generate a signing secret.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/webhooks/$WEBHOOK_ID:rotateSigningSecret" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**secret**: `string`

Output only. The newly generated signing secret.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "secret": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

# Listing webhooks
Source: https://aistudio.google.com/api-reference/webhooks/list-webhooks
Description: Lists all Webhooks.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/webhooks`

Lists all Webhooks.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**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.

{% hr /%}

**page_token**: `string`

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

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/webhooks" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**webhooks**: `array (`[`Webhook`](/api-reference/webhooks/list-webhooks#Resource:Webhook)`)`

The webhooks.

{% hr /%}

**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.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "webhooks": [
    {
      "uri": "string",
      "subscribed_events": [
        "string"
      ],
      "name": "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"
}
```

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### Webhook {% class="hide-from-toc" id="Resource:Webhook" %}

A Webhook resource.

**Properties:**

**uri**: {% mark %}required{% /mark %} `string`

The URI to which webhook events will be sent.

{% hr /%}

**subscribed_events**: {% mark %}required{% /mark %} `array (string)`

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

{% hr /%}

**name**: `string`

Optional. The user-provided name of the webhook.

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the webhook was created.

{% hr /%}

**update_time**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**signing_secrets**: `array (SigningSecret)`

Output only. The signing secrets associated with this webhook.

{% /summary %}

**truncated_secret**: `string`

Output only. The truncated version of the signing secret.

**expire_time**: `string`

Output only. The expiration date of the signing secret.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. The state of the webhook.

{% /summary %}

Possible values:

- `enabled`: The webhook is enabled.
- `disabled`: The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`: The webhook is disabled due to failed deliveries.

{% /details %}

{% hr /%}

**new_signing_secret**: `string`

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

{% hr /%}

**id**: `string`

Output only. The ID of the webhook.

# Getting a webhook
Source: https://aistudio.google.com/api-reference/webhooks/get-webhook
Description: Gets a specific Webhook.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/webhooks/{id}`

Gets a specific Webhook.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

The ID of the webhook to retrieve.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/webhooks/$WEBHOOK_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**uri**: {% mark %}required{% /mark %} `string`

The URI to which webhook events will be sent.

{% hr /%}

**subscribed_events**: {% mark %}required{% /mark %} `array (string)`

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

{% hr /%}

**name**: `string`

Optional. The user-provided name of the webhook.

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the webhook was created.

{% hr /%}

**update_time**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**signing_secrets**: `array (SigningSecret)`

Output only. The signing secrets associated with this webhook.

{% /summary %}

**truncated_secret**: `string`

Output only. The truncated version of the signing secret.

**expire_time**: `string`

Output only. The expiration date of the signing secret.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. The state of the webhook.

{% /summary %}

Possible values:

- `enabled`: The webhook is enabled.
- `disabled`: The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`: The webhook is disabled due to failed deliveries.

{% /details %}

{% hr /%}

**new_signing_secret**: `string`

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

{% hr /%}

**id**: `string`

Output only. The ID of the webhook.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

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

{% /right-column %}

{% /two-column-layout %}

# Updating a webhook
Source: https://aistudio.google.com/api-reference/webhooks/update-webhook
Description: Updates an existing Webhook.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/webhooks/{id}`

Updates an existing Webhook.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

The ID of the webhook to update.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**webhook**: {% mark %}required{% /mark %} `WebhookUpdate`

The webhook to update.

{% /summary %}

**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 (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

{% details %}

{% summary %}

**state**: `enum (string)`

Optional. The state of the webhook.

{% /summary %}

Possible values:

- `enabled`: The webhook is enabled.
- `disabled`: The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`: The webhook is disabled due to failed deliveries.

{% /details %}

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

The ID of the webhook to update.

{% hr /%}

**update_mask**: `string`

Optional. The list of fields to update.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/webhooks/$WEBHOOK_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "webhook": {
    "name": "string"
  },
  "id": "string"
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**uri**: {% mark %}required{% /mark %} `string`

The URI to which webhook events will be sent.

{% hr /%}

**subscribed_events**: {% mark %}required{% /mark %} `array (string)`

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

{% hr /%}

**name**: `string`

Optional. The user-provided name of the webhook.

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the webhook was created.

{% hr /%}

**update_time**: `string`

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

{% hr /%}

{% details %}

{% summary %}

**signing_secrets**: `array (SigningSecret)`

Output only. The signing secrets associated with this webhook.

{% /summary %}

**truncated_secret**: `string`

Output only. The truncated version of the signing secret.

**expire_time**: `string`

Output only. The expiration date of the signing secret.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. The state of the webhook.

{% /summary %}

Possible values:

- `enabled`: The webhook is enabled.
- `disabled`: The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`: The webhook is disabled due to failed deliveries.

{% /details %}

{% hr /%}

**new_signing_secret**: `string`

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

{% hr /%}

**id**: `string`

Output only. The ID of the webhook.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

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

{% /right-column %}

{% /two-column-layout %}

# Deleting a webhook
Source: https://aistudio.google.com/api-reference/webhooks/delete-webhook
Description: Deletes a Webhook.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/webhooks/{id}`

Deletes a Webhook.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

The ID of the webhook to delete.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/webhooks/$WEBHOOK_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Gemini Credentials API
Source: https://aistudio.google.com/api-reference/credentials
Description: The Credentials API allows you to create, retrieve, update, list, and delete server-managed credentials (such as API keys, OAuth2 tokens, HTTP Bearer tokens, and environment variables) to authenticate tool calls and MCP servers.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

The Credentials API allows you to create, retrieve, update, list, and delete server-managed credentials (such as API keys, OAuth2 tokens, HTTP Bearer tokens, and environment variables) to authenticate tool calls and MCP servers.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Creating a credential](/api-reference/credentials/create-credential)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/credentials`

  Creates a new credential.
---

* [Listing credentials](/api-reference/credentials/list-credentials)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/credentials`

  Lists credentials.
---

* [Getting a credential](/api-reference/credentials/get-credential)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/credentials/{id}`

  Gets a credential by ID.
---

* [Updating a credential](/api-reference/credentials/update-credential)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/credentials/{id}`

  Updates a credential.
---

* [Deleting a credential](/api-reference/credentials/delete-credential)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/credentials/{id}`

  Deletes a credential.
{% /table %}

## Resources {% id="resources" %}

### Credential {% id="Resource:Credential" %}

Server-managed credential resource stored in Secret Manager.

**Properties:**

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. Unique identifier for the credential.

{% hr /%}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `enum (string)`

Output only. The type of credential.

{% /summary %}

Possible values:

- `bearer_token`: Static token injected as header. No refresh logic.
- `oauth2`: Auto-refresh expired access tokens using stored refresh token.
- `environment_variable`: Environment variable injected into sandbox container.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. Current status of the credential.

{% /summary %}

Possible values:

- `active`: The credential is active and valid for use.
- `revoked`: The credential has been revoked and is no longer valid.

{% /details %}

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the credential was created.

{% hr /%}

**update_time**: `string`

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

# Creating a credential
Source: https://aistudio.google.com/api-reference/credentials/create-credential
Description: Creates a new credential.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/credentials`

Creates a new credential.

{% two-column-layout %}

{% left-column %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

The request body structure depends on the interaction mode:

{% details open=true %}

{% summary %}**EnvironmentVariableConfig**{% /summary %}

Configuration for environment variable credentials.

**value**: {% mark %}required{% /mark %} `string`

Input only. Secret value of the environment variable. Write-only; never returned in responses.

{% hr /%}

{% details %}

{% summary %}

**injection_location**: {% mark %}required{% /mark %} `InjectionLocation` or `array (InjectionLocation)`

Locations where the environment variable can be injected in outgoing HTTP requests. Must contain at least one location. Accepts either a single location (e.g. "header") or an array of locations.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**InjectionLocation**{% /summary %}

Possible values:

- `header`: Injected into HTTP request headers.
- `query`: Injected into HTTP URL query parameters.
- `body`: Injected into HTTP request body.

{% /details %}

{% details %}

{% summary %}**array (InjectionLocation)**{% /summary %}

Possible values:

- `header`: Injected into HTTP request headers.
- `query`: Injected into HTTP URL query parameters.
- `body`: Injected into HTTP request body.

{% /details %}

{% /details %}

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `environment_variable`

{% hr /%}

**trusted_domains**: `array (string)`

Optional. List of domains allowed to receive this environment variable value in HTTP requests.

{% /details %}

{% details %}

{% summary %}**HttpBearerConfig**{% /summary %}

Configuration for HTTP Bearer token credentials.

**token**: {% mark %}required{% /mark %} `string`

Input only. The static bearer token. Write-only; never returned in responses.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `bearer_token`

{% hr /%}

**header_name**: `string`

Optional. Header name to inject the token into. Defaults to 'Authorization'.

{% hr /%}

**prefix**: `string`

Optional. Prefix to prepend to the token. Defaults to 'Bearer'. Set to '' for no prefix.

{% /details %}

{% details %}

{% summary %}**OAuth2Config**{% /summary %}

Configuration for OAuth2 credentials with automatic token refresh.

**client_id**: {% mark %}required{% /mark %} `string`

OAuth2 client ID.

{% hr /%}

**client_secret**: {% mark %}required{% /mark %} `string`

Input only. OAuth2 client secret. Write-only; never returned in responses.

{% hr /%}

**refresh_token**: {% mark %}required{% /mark %} `string`

Input only. OAuth2 refresh token. Write-only; never returned in responses.

{% hr /%}

**token_url**: {% mark %}required{% /mark %} `string`

OAuth2 token endpoint URL for refreshing access tokens.

{% hr /%}

**id**: {% mark %}required{% /mark %} `string`

{% hr /%}

**type**: {% mark %}required{% /mark %} `object`

Value: `oauth2`

{% hr /%}

**scopes**: `array (string)`

Optional. List of OAuth2 scopes.

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "string",
  "injection_location": "header",
  "id": "string",
  "type": "environment_variable"
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. Unique identifier for the credential.

{% hr /%}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `enum (string)`

Output only. The type of credential.

{% /summary %}

Possible values:

- `bearer_token`: Static token injected as header. No refresh logic.
- `oauth2`: Auto-refresh expired access tokens using stored refresh token.
- `environment_variable`: Environment variable injected into sandbox container.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. Current status of the credential.

{% /summary %}

Possible values:

- `active`: The credential is active and valid for use.
- `revoked`: The credential has been revoked and is no longer valid.

{% /details %}

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the credential was created.

{% hr /%}

**update_time**: `string`

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

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "id": "string",
  "type": "bearer_token",
  "status": "active",
  "create_time": "string",
  "update_time": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

# Listing credentials
Source: https://aistudio.google.com/api-reference/credentials/list-credentials
Description: Lists credentials.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/credentials`

Lists credentials.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**page_size**: `integer`

Optional. Maximum number of credentials to return.

{% hr /%}

**page_token**: `string`

Optional. Pagination token.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/credentials" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**credentials**: `array (`[`Credential`](/api-reference/credentials/list-credentials#Resource:Credential)`)`

{% hr /%}

**next_page_token**: `string`

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "credentials": [
    {
      "id": "string",
      "type": "bearer_token",
      "status": "active",
      "create_time": "string",
      "update_time": "string"
    }
  ],
  "next_page_token": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### Credential {% class="hide-from-toc" id="Resource:Credential" %}

Server-managed credential resource stored in Secret Manager.

**Properties:**

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. Unique identifier for the credential.

{% hr /%}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `enum (string)`

Output only. The type of credential.

{% /summary %}

Possible values:

- `bearer_token`: Static token injected as header. No refresh logic.
- `oauth2`: Auto-refresh expired access tokens using stored refresh token.
- `environment_variable`: Environment variable injected into sandbox container.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. Current status of the credential.

{% /summary %}

Possible values:

- `active`: The credential is active and valid for use.
- `revoked`: The credential has been revoked and is no longer valid.

{% /details %}

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the credential was created.

{% hr /%}

**update_time**: `string`

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

# Getting a credential
Source: https://aistudio.google.com/api-reference/credentials/get-credential
Description: Gets a credential by ID.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/credentials/{id}`

Gets a credential by ID.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Resource ID segment making up resource `name`. It identifies the resource within its parent collection as described in https://google.aip.dev/122.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/credentials/$CREDENTIAL_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. Unique identifier for the credential.

{% hr /%}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `enum (string)`

Output only. The type of credential.

{% /summary %}

Possible values:

- `bearer_token`: Static token injected as header. No refresh logic.
- `oauth2`: Auto-refresh expired access tokens using stored refresh token.
- `environment_variable`: Environment variable injected into sandbox container.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. Current status of the credential.

{% /summary %}

Possible values:

- `active`: The credential is active and valid for use.
- `revoked`: The credential has been revoked and is no longer valid.

{% /details %}

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the credential was created.

{% hr /%}

**update_time**: `string`

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

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "id": "string",
  "type": "bearer_token",
  "status": "active",
  "create_time": "string",
  "update_time": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

# Updating a credential
Source: https://aistudio.google.com/api-reference/credentials/update-credential
Description: Updates a credential.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/credentials/{id}`

Updates a credential.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Resource ID segment making up resource `name`. It identifies the resource within its parent collection as described in https://google.aip.dev/122.

{% hr /%}

**update_mask**: `string`

Optional. The list of fields to update.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

The request body structure depends on the interaction mode:

{% details open=true %}

{% summary %}**EnvironmentVariableUpdateConfig**{% /summary %}

Configuration for updating environment variable credentials.

**type**: {% mark %}required{% /mark %} `object`

Value: `environment_variable`

{% hr /%}

**value**: `string`

Optional. Input only. Secret value of the environment variable. Write-only; never returned in responses.

{% hr /%}

**trusted_domains**: `array (string)`

Optional. List of domains allowed to receive this environment variable value in HTTP requests.

{% hr /%}

{% details %}

{% summary %}

**injection_location**: `InjectionLocation` or `array (InjectionLocation)`

Optional. Locations where the environment variable can be injected in outgoing HTTP requests. Accepts either a single location (e.g. "header") or an array of locations.

{% /summary %}

**Possible Types:**

{% details %}

{% summary %}**InjectionLocation**{% /summary %}

Possible values:

- `header`: Injected into HTTP request headers.
- `query`: Injected into HTTP URL query parameters.
- `body`: Injected into HTTP request body.

{% /details %}

{% details %}

{% summary %}**array (InjectionLocation)**{% /summary %}

Possible values:

- `header`: Injected into HTTP request headers.
- `query`: Injected into HTTP URL query parameters.
- `body`: Injected into HTTP request body.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}**HttpBearerUpdateConfig**{% /summary %}

Configuration for updating HTTP Bearer token credentials.

**type**: {% mark %}required{% /mark %} `object`

Value: `bearer_token`

{% hr /%}

**token**: `string`

Optional. Input only. The static bearer token. Write-only; never returned in responses.

{% hr /%}

**header_name**: `string`

Optional. Header name to inject the token into. Defaults to 'Authorization'.

{% hr /%}

**prefix**: `string`

Optional. Prefix to prepend to the token. Defaults to 'Bearer'. Set to '' for no prefix.

{% /details %}

{% details %}

{% summary %}**OAuth2UpdateConfig**{% /summary %}

Configuration for updating OAuth2 credentials.

**type**: {% mark %}required{% /mark %} `object`

Value: `oauth2`

{% hr /%}

**client_id**: `string`

Optional. OAuth2 client ID.

{% hr /%}

**client_secret**: `string`

Optional. Input only. OAuth2 client secret. Write-only; never returned in responses.

{% hr /%}

**refresh_token**: `string`

Optional. Input only. OAuth2 refresh token. Write-only; never returned in responses.

{% hr /%}

**token_url**: `string`

Optional. OAuth2 token endpoint URL for refreshing access tokens.

{% hr /%}

**scopes**: `array (string)`

Optional. List of OAuth2 scopes.

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/credentials/$CREDENTIAL_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "environment_variable"
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Output only. Identifier. Unique identifier for the credential.

{% hr /%}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `enum (string)`

Output only. The type of credential.

{% /summary %}

Possible values:

- `bearer_token`: Static token injected as header. No refresh logic.
- `oauth2`: Auto-refresh expired access tokens using stored refresh token.
- `environment_variable`: Environment variable injected into sandbox container.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**status**: `enum (string)`

Output only. Current status of the credential.

{% /summary %}

Possible values:

- `active`: The credential is active and valid for use.
- `revoked`: The credential has been revoked and is no longer valid.

{% /details %}

{% hr /%}

**create_time**: `string`

Output only. The timestamp when the credential was created.

{% hr /%}

**update_time**: `string`

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

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "id": "string",
  "type": "bearer_token",
  "status": "active",
  "create_time": "string",
  "update_time": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

# Deleting a credential
Source: https://aistudio.google.com/api-reference/credentials/delete-credential
Description: Deletes a credential.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/credentials/{id}`

Deletes a credential.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

Resource ID segment making up resource `name`. It identifies the resource within its parent collection as described in https://google.aip.dev/122.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/credentials/$CREDENTIAL_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Using files
Source: https://aistudio.google.com/api-reference/files
Description: The Gemini API supports uploading media files separately from the prompt input, allowing your media to be reused across multiple requests and multiple prompts.

The Gemini API supports uploading media files separately from the prompt input, allowing your media to be reused across multiple requests and multiple prompts. For more details, check out the [Prompting with media](/docs/file-input-methods) guide.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Getting a file](/api-reference/files/get-file)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/files/{file}`

  Gets the metadata for the given [`File`](/api-reference/files#Resource:File).
---

* [Listing files](/api-reference/files/list-files)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/files`

  Lists the metadata for [`File`](/api-reference/files#Resource:File)s owned by the requesting project.
---

* [Deleting a file](/api-reference/files/delete-file)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/files/{file}`

  Deletes the [`File`](/api-reference/files#Resource:File).
---

* [Registering files](/api-reference/files/register-files)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/files:register`

  Registers a Google Cloud Storage files with FileService.
---

* [Creating a file](/api-reference/files/create-file)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/files`

  Creates a [`File`](/api-reference/files#Resource:File).
{% /table %}

## Resources {% id="resources" %}

### File {% id="Resource:File" %}

A file uploaded to the API.

**Properties:**

{% details %}

{% summary %}

**videoMetadata**: `VideoFileMetadata`

Output only. Metadata for a video.

{% /summary %}

**videoDuration**: `string`

Duration of the video.

{% /details %}

{% hr /%}

**name**: `string`

Immutable. Identifier. The [`File`](/api-reference/files#Resource:File) resource name. The ID (name excluding the "files/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be generated. Example: `files/123-456`

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`File`](/api-reference/files#Resource:File). The display name must be no more than 512 characters in length, including spaces. Example: "Welcome Image"

{% hr /%}

**mimeType**: `string`

Output only. MIME type of the file.

{% hr /%}

**sizeBytes**: `string`

Output only. Size of the file in bytes.

{% hr /%}

**createTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files#Resource:File) was created.

{% hr /%}

**updateTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files#Resource:File) was last updated.

{% hr /%}

**expirationTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files#Resource:File) will be deleted. Only set if the [`File`](/api-reference/files#Resource:File) is scheduled to expire.

{% hr /%}

**sha256Hash**: `string`

Output only. SHA-256 hash of the uploaded bytes.

{% hr /%}

**uri**: `string`

Output only. The uri of the [`File`](/api-reference/files#Resource:File).

{% hr /%}

**downloadUri**: `string`

Output only. The download uri of the [`File`](/api-reference/files#Resource:File).

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. Processing state of the File.

{% /summary %}

Possible values:

- `STATE_UNSPECIFIED`: The default value. This value is used if the state is omitted.
- `PROCESSING`: File is being processed and cannot be used for inference yet.
- `ACTIVE`: File is processed and available for inference.
- `FAILED`: File failed processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**source**: `enum (string)`

Source of the File.

{% /summary %}

Possible values:

- `SOURCE_UNSPECIFIED`: Used if source is not specified.
- `UPLOADED`: Indicates the file is uploaded by the user.
- `GENERATED`: Indicates the file is generated by Google.
- `REGISTERED`: Indicates the file is a registered, i.e. a Google Cloud Storage file.

{% /details %}

{% hr /%}

**error**: [`Status`](/api-reference/files#Resource:Status)

Output only. Error status if File processing failed.

## Data Models {% id="data-models" %}

### Status {% id="Resource:Status" %}

The [`Status`](/api-reference/files#Resource:Status) type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It is
used by [gRPC](https://github.com/grpc). Each [`Status`](/api-reference/files#Resource:Status) message contains
three pieces of data: error code, error message, and error details.

You can find out more about this error model and how to work with it in the
[API Design Guide](https://cloud.google.com/apis/design/errors).

**Properties:**

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

{% hr /%}

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

{% hr /%}

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

# Getting a file
Source: https://aistudio.google.com/api-reference/files/get-file
Description: Gets the metadata for the given `File`.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/files/{file}`

Gets the metadata for the given [`File`](/api-reference/files#Resource:File).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**file**: {% mark %}required{% /mark %} `string`

The file ID. Forms the resource name `files/{file}`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
name=$(jq ".file.name" file_info.json)
# Get the file of interest to check state
curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
# Print some information about the file you got
name=$(jq ".file.name" file_info.json)
echo name=$name
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
myfile = client.files.upload(file=media / "poem.txt")
file_name = myfile.name
print(file_name)  # "files/*"

myfile = client.files.get(name=file_name)
print(myfile)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const myfile = await ai.files.upload({
  file: path.join(media, 'poem.txt'),
});
const fileName = myfile.name;
console.log(fileName);

const fetchedFile = await ai.files.get({name: fileName});
console.log(fetchedFile);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
myfile, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "poem.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
fileName := myfile.Name
fmt.Println(fileName)
file, err := client.Files.Get(ctx, fileName, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(file)
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**videoMetadata**: `VideoFileMetadata`

Output only. Metadata for a video.

{% /summary %}

**videoDuration**: `string`

Duration of the video.

{% /details %}

{% hr /%}

**name**: `string`

Immutable. Identifier. The [`File`](/api-reference/files#Resource:File) resource name. The ID (name excluding the "files/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be generated. Example: `files/123-456`

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`File`](/api-reference/files#Resource:File). The display name must be no more than 512 characters in length, including spaces. Example: "Welcome Image"

{% hr /%}

**mimeType**: `string`

Output only. MIME type of the file.

{% hr /%}

**sizeBytes**: `string`

Output only. Size of the file in bytes.

{% hr /%}

**createTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files#Resource:File) was created.

{% hr /%}

**updateTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files#Resource:File) was last updated.

{% hr /%}

**expirationTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files#Resource:File) will be deleted. Only set if the [`File`](/api-reference/files#Resource:File) is scheduled to expire.

{% hr /%}

**sha256Hash**: `string`

Output only. SHA-256 hash of the uploaded bytes.

{% hr /%}

**uri**: `string`

Output only. The uri of the [`File`](/api-reference/files#Resource:File).

{% hr /%}

**downloadUri**: `string`

Output only. The download uri of the [`File`](/api-reference/files#Resource:File).

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. Processing state of the File.

{% /summary %}

Possible values:

- `STATE_UNSPECIFIED`: The default value. This value is used if the state is omitted.
- `PROCESSING`: File is being processed and cannot be used for inference yet.
- `ACTIVE`: File is processed and available for inference.
- `FAILED`: File failed processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**source**: `enum (string)`

Source of the File.

{% /summary %}

Possible values:

- `SOURCE_UNSPECIFIED`: Used if source is not specified.
- `UPLOADED`: Indicates the file is uploaded by the user.
- `GENERATED`: Indicates the file is generated by Google.
- `REGISTERED`: Indicates the file is a registered, i.e. a Google Cloud Storage file.

{% /details %}

{% hr /%}

**error**: [`Status`](/api-reference/files/get-file#Resource:Status)

Output only. Error status if File processing failed.

{% /section %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### Status {% class="hide-from-toc" id="Resource:Status" %}

The [`Status`](/api-reference/files/get-file#Resource:Status) type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It is
used by [gRPC](https://github.com/grpc). Each [`Status`](/api-reference/files/get-file#Resource:Status) message contains
three pieces of data: error code, error message, and error details.

You can find out more about this error model and how to work with it in the
[API Design Guide](https://cloud.google.com/apis/design/errors).

**Properties:**

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

{% hr /%}

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

{% hr /%}

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

# Listing files
Source: https://aistudio.google.com/api-reference/files/list-files
Description: Lists the metadata for `File`s owned by the requesting project.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/files`

Lists the metadata for [`File`](/api-reference/files/list-files#Resource:File)s owned by the requesting project.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**pageSize**: `integer`

Optional. Maximum number of [`File`](/api-reference/files/list-files#Resource:File)s to return per page. If unspecified, defaults to 10. Maximum `page_size` is 100.

{% hr /%}

**pageToken**: `string`

Optional. A page token from a previous `ListFiles` call.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
echo "My files: "

curl "https://generativelanguage.googleapis.com/v1beta/files?key=$GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
print("My files:")
for f in client.files.list():
  print("  ", f.name)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
console.log('My files:');
// Using the pager style to list files
const pager = await ai.files.list({config: {pageSize: 10}});
let page = pager.page;
const names = [];
while (true) {
  for (const f of page) {
    console.log('  ', f.name);
    names.push(f.name);
  }
  if (!pager.hasNextPage()) break;
  page = await pager.nextPage();
}
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("My files:")
page, err := client.Files.List(ctx, nil)
if err != nil {
    log.Fatal(err)
}
for _, f := range page.Items {
    fmt.Println("  ", f.Name)
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**files**: `array (`[`File`](/api-reference/files/list-files#Resource:File)`)`

The list of [`File`](/api-reference/files/list-files#Resource:File)s.

{% hr /%}

**nextPageToken**: `string`

A token that can be sent as a `page_token` into a subsequent `ListFiles` call.

{% /section %}

## Resources {% class="hide-from-toc" id="resources" %}

### File {% class="hide-from-toc" id="Resource:File" %}

A file uploaded to the API.

**Properties:**

{% details %}

{% summary %}

**videoMetadata**: `VideoFileMetadata`

Output only. Metadata for a video.

{% /summary %}

**videoDuration**: `string`

Duration of the video.

{% /details %}

{% hr /%}

**name**: `string`

Immutable. Identifier. The [`File`](/api-reference/files/list-files#Resource:File) resource name. The ID (name excluding the "files/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be generated. Example: `files/123-456`

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`File`](/api-reference/files/list-files#Resource:File). The display name must be no more than 512 characters in length, including spaces. Example: "Welcome Image"

{% hr /%}

**mimeType**: `string`

Output only. MIME type of the file.

{% hr /%}

**sizeBytes**: `string`

Output only. Size of the file in bytes.

{% hr /%}

**createTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files/list-files#Resource:File) was created.

{% hr /%}

**updateTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files/list-files#Resource:File) was last updated.

{% hr /%}

**expirationTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files/list-files#Resource:File) will be deleted. Only set if the [`File`](/api-reference/files/list-files#Resource:File) is scheduled to expire.

{% hr /%}

**sha256Hash**: `string`

Output only. SHA-256 hash of the uploaded bytes.

{% hr /%}

**uri**: `string`

Output only. The uri of the [`File`](/api-reference/files/list-files#Resource:File).

{% hr /%}

**downloadUri**: `string`

Output only. The download uri of the [`File`](/api-reference/files/list-files#Resource:File).

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. Processing state of the File.

{% /summary %}

Possible values:

- `STATE_UNSPECIFIED`: The default value. This value is used if the state is omitted.
- `PROCESSING`: File is being processed and cannot be used for inference yet.
- `ACTIVE`: File is processed and available for inference.
- `FAILED`: File failed processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**source**: `enum (string)`

Source of the File.

{% /summary %}

Possible values:

- `SOURCE_UNSPECIFIED`: Used if source is not specified.
- `UPLOADED`: Indicates the file is uploaded by the user.
- `GENERATED`: Indicates the file is generated by Google.
- `REGISTERED`: Indicates the file is a registered, i.e. a Google Cloud Storage file.

{% /details %}

{% hr /%}

**error**: [`Status`](/api-reference/files/list-files#Resource:Status)

Output only. Error status if File processing failed.

## Data Models {% class="hide-from-toc" id="data-models" %}

### Status {% class="hide-from-toc" id="Resource:Status" %}

The [`Status`](/api-reference/files/list-files#Resource:Status) type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It is
used by [gRPC](https://github.com/grpc). Each [`Status`](/api-reference/files/list-files#Resource:Status) message contains
three pieces of data: error code, error message, and error details.

You can find out more about this error model and how to work with it in the
[API Design Guide](https://cloud.google.com/apis/design/errors).

**Properties:**

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

{% hr /%}

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

{% hr /%}

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

# Deleting a file
Source: https://aistudio.google.com/api-reference/files/delete-file
Description: Deletes the `File`.

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/files/{file}`

Deletes the [`File`](/api-reference/files#Resource:File).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**file**: {% mark %}required{% /mark %} `string`

The file ID. Forms the resource name `files/{file}`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl --request "DELETE" https://generativelanguage.googleapis.com/v1beta/files/$name?key=$GEMINI_API_KEY
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
myfile = client.files.upload(file=media / "poem.txt")

client.files.delete(name=myfile.name)

try:
  result = client.models.generate_content(
      model="gemini-3.8-flash", contents=[myfile, "Describe this file."]
  )
  print(result)
except genai.errors.ClientError:
  pass
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
myfile, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "poem.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
// Delete the file.
_, err = client.Files.Delete(ctx, myfile.Name, nil)
if err != nil {
    log.Fatal(err)
}
// Attempt to use the deleted file.
parts := []*genai.Part{
    genai.NewPartFromURI(myfile.URI, myfile.MIMEType),
    genai.NewPartFromText("Describe this file."),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

_, err = client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
// Expect an error when using a deleted file.
if err != nil {
    return nil
}
return fmt.Errorf("expected an error when using deleted file")
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Registering files
Source: https://aistudio.google.com/api-reference/files/register-files
Description: Registers a Google Cloud Storage files with FileService.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/files:register`

Registers a Google Cloud Storage files with FileService. The user is
expected to provide Google Cloud Storage URIs and will receive a File
resource for each URI in return. Note that the files are not copied, just
registered with File API. If one file fails to register, the whole request
fails.

{% two-column-layout %}

{% left-column %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**uris**: {% mark %}required{% /mark %} `array (string)`

The Google Cloud Storage URIs to register. Example: `gs://bucket/object`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/files:register" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "uris": [
    "string"
  ]
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**files**: `array (`[`File`](/api-reference/files/register-files#Resource:File)`)`

The registered files to be used when calling GenerateContent.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "files": [
    {
      "videoMetadata": {
        "videoDuration": "string"
      },
      "name": "string",
      "displayName": "string",
      "mimeType": "string",
      "sizeBytes": "string",
      "createTime": "string",
      "updateTime": "string",
      "expirationTime": "string",
      "sha256Hash": "string",
      "uri": "string",
      "downloadUri": "string",
      "state": "STATE_UNSPECIFIED",
      "source": "SOURCE_UNSPECIFIED",
      "error": {
        "code": 0,
        "message": "string",
        "details": [
          {}
        ]
      }
    }
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### File {% class="hide-from-toc" id="Resource:File" %}

A file uploaded to the API.

**Properties:**

{% details %}

{% summary %}

**videoMetadata**: `VideoFileMetadata`

Output only. Metadata for a video.

{% /summary %}

**videoDuration**: `string`

Duration of the video.

{% /details %}

{% hr /%}

**name**: `string`

Immutable. Identifier. The [`File`](/api-reference/files/register-files#Resource:File) resource name. The ID (name excluding the "files/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be generated. Example: `files/123-456`

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`File`](/api-reference/files/register-files#Resource:File). The display name must be no more than 512 characters in length, including spaces. Example: "Welcome Image"

{% hr /%}

**mimeType**: `string`

Output only. MIME type of the file.

{% hr /%}

**sizeBytes**: `string`

Output only. Size of the file in bytes.

{% hr /%}

**createTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files/register-files#Resource:File) was created.

{% hr /%}

**updateTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files/register-files#Resource:File) was last updated.

{% hr /%}

**expirationTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files/register-files#Resource:File) will be deleted. Only set if the [`File`](/api-reference/files/register-files#Resource:File) is scheduled to expire.

{% hr /%}

**sha256Hash**: `string`

Output only. SHA-256 hash of the uploaded bytes.

{% hr /%}

**uri**: `string`

Output only. The uri of the [`File`](/api-reference/files/register-files#Resource:File).

{% hr /%}

**downloadUri**: `string`

Output only. The download uri of the [`File`](/api-reference/files/register-files#Resource:File).

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. Processing state of the File.

{% /summary %}

Possible values:

- `STATE_UNSPECIFIED`: The default value. This value is used if the state is omitted.
- `PROCESSING`: File is being processed and cannot be used for inference yet.
- `ACTIVE`: File is processed and available for inference.
- `FAILED`: File failed processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**source**: `enum (string)`

Source of the File.

{% /summary %}

Possible values:

- `SOURCE_UNSPECIFIED`: Used if source is not specified.
- `UPLOADED`: Indicates the file is uploaded by the user.
- `GENERATED`: Indicates the file is generated by Google.
- `REGISTERED`: Indicates the file is a registered, i.e. a Google Cloud Storage file.

{% /details %}

{% hr /%}

**error**: [`Status`](/api-reference/files/register-files#Resource:Status)

Output only. Error status if File processing failed.

## Data Models {% class="hide-from-toc" id="data-models" %}

### Status {% class="hide-from-toc" id="Resource:Status" %}

The [`Status`](/api-reference/files/register-files#Resource:Status) type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It is
used by [gRPC](https://github.com/grpc). Each [`Status`](/api-reference/files/register-files#Resource:Status) message contains
three pieces of data: error code, error message, and error details.

You can find out more about this error model and how to work with it in the
[API Design Guide](https://cloud.google.com/apis/design/errors).

**Properties:**

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

{% hr /%}

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

{% hr /%}

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

# Creating a file
Source: https://aistudio.google.com/api-reference/files/create-file
Description: Creates a `File`.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/files`

Creates a [`File`](/api-reference/files/create-file#Resource:File).

{% two-column-layout %}

{% left-column %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**file**: [`File`](/api-reference/files/create-file#Resource:File)

Optional. Metadata for the file to create.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="Image" %}

{% tabs %}

{% tab label="REST" %}

```sh
MIME_TYPE=$(file -b --mime-type "${IMG_PATH_2}")
NUM_BYTES=$(wc -c < "${IMG_PATH_2}")
DISPLAY_NAME=TEXT

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${IMG_PATH_2}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Can you tell me about the instruments in this photo?"},
          {"file_data":
            {"mime_type": "image/jpeg",
            "file_uri": '$file_uri'}
        }]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
myfile = client.files.upload(file=media / "Cajun_instruments.jpg")
print(f"{myfile=}")

result = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        myfile,
        "\n\n",
        "Can you tell me about the instruments in this photo?",
    ],
)
print(f"{result.text=}")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const myfile = await ai.files.upload({
  file: path.join(media, 'Cajun_instruments.jpg'),
  config: {mimeType: 'image/jpeg'},
});
console.log('Uploaded file:', myfile);

const result = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
    '\n\n',
    'Can you tell me about the instruments in this photo?',
  ]),
});
console.log('result.text=', result.text);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
myfile, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "Cajun_instruments.jpg"),
    &genai.UploadFileConfig{
        MIMEType: "image/jpeg",
    },
)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("myfile=%+v\n", myfile)

parts := []*genai.Part{
    genai.NewPartFromURI(myfile.URI, myfile.MIMEType),
    genai.NewPartFromText("\n\n"),
    genai.NewPartFromText("Can you tell me about the instruments in this photo?"),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Audio" %}

{% tabs %}

{% tab label="REST" %}

```sh
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Describe this audio clip"},
          {"file_data":{"mime_type": "audio/mp3", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
myfile = client.files.upload(file=media / "sample.mp3")
print(f"{myfile=}")

result = client.models.generate_content(
    model="gemini-3.8-flash", contents=[myfile, "Describe this audio clip"]
)
print(f"{result.text=}")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const myfile = await ai.files.upload({
  file: path.join(media, 'sample.mp3'),
  config: {mimeType: 'audio/mpeg'},
});
console.log('Uploaded file:', myfile);

const result = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
    'Describe this audio clip',
  ]),
});
console.log('result.text=', result.text);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
myfile, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "sample.mp3"),
    &genai.UploadFileConfig{
        MIMEType: "audio/mpeg",
    },
)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("myfile=%+v\n", myfile)

parts := []*genai.Part{
    genai.NewPartFromURI(myfile.URI, myfile.MIMEType),
    genai.NewPartFromText("Describe this audio clip"),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Text" %}

{% tabs %}

{% tab label="REST" %}

```sh
MIME_TYPE=$(file -b --mime-type "${TEXT_PATH}")
NUM_BYTES=$(wc -c < "${TEXT_PATH}")
DISPLAY_NAME=TEXT

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${TEXT_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Can you add a few more lines to this poem?"},
          {"file_data":{"mime_type": "text/plain", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

name=$(jq ".file.name" file_info.json)
# Get the file of interest to check state
curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
# Print some information about the file you got
name=$(jq ".file.name" file_info.json)
echo name=$name
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

curl --request "DELETE" https://generativelanguage.googleapis.com/v1beta/files/$name?key=$GEMINI_API_KEY
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
myfile = client.files.upload(file=media / "poem.txt")
print(f"{myfile=}")

result = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[myfile, "\n\n", "Can you add a few more lines to this poem?"],
)
print(f"{result.text=}")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const myfile = await ai.files.upload({
  file: path.join(media, 'poem.txt'),
});
console.log('Uploaded file:', myfile);

const result = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
    '\n\n',
    'Can you add a few more lines to this poem?',
  ]),
});
console.log('result.text=', result.text);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

myfile, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "poem.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("myfile=%+v\n", myfile)

parts := []*genai.Part{
    genai.NewPartFromURI(myfile.URI, myfile.MIMEType),
    genai.NewPartFromText("\n\n"),
    genai.NewPartFromText("Can you add a few more lines to this poem?"),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Video" %}

{% tabs %}

{% tab label="REST" %}

```sh
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO_PATH

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

state=$(jq ".file.state" file_info.json)
echo state=$state

# Ensure the state of the video is 'ACTIVE'
while [[ "($state)" = *"PROCESSING"* ]];
do
  echo "Processing video..."
  sleep 5
  # Get the file of interest to check state
  curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
  state=$(jq ".file.state" file_info.json)
done

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Describe this video clip"},
          {"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
import time

client = genai.Client()
# Video clip (CC BY 3.0) from https://peach.blender.org/download/
myfile = client.files.upload(file=media / "Big_Buck_Bunny.mp4")
print(f"{myfile=}")

# Poll until the video file is completely processed (state becomes ACTIVE).
while not myfile.state or myfile.state.name != "ACTIVE":
  print("Processing video...")
  print("File state:", myfile.state)
  time.sleep(5)
  myfile = client.files.get(name=myfile.name)

result = client.models.generate_content(
    model="gemini-3.8-flash", contents=[myfile, "Describe this video clip"]
)
print(f"{result.text=}")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
let myfile = await ai.files.upload({
  file: path.join(media, 'Big_Buck_Bunny.mp4'),
  config: {mimeType: 'video/mp4'},
});
console.log('Uploaded video file:', myfile);

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!myfile.state || myfile.state.toString() !== 'ACTIVE') {
  console.log('Processing video...');
  console.log('File state: ', myfile.state);
  await sleep(5000);
  myfile = await ai.files.get({name: myfile.name});
}

const result = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
    'Describe this video clip',
  ]),
});
console.log('result.text=', result.text);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
myfile, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "Big_Buck_Bunny.mp4"),
    &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    },
)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("myfile=%+v\n", myfile)

// Poll until the video file is completely processed (state becomes ACTIVE).
for myfile.State == genai.FileStateUnspecified || myfile.State != genai.FileStateActive {
    fmt.Println("Processing video...")
    fmt.Println("File state:", myfile.State)
    time.Sleep(5 * time.Second)

    myfile, err = client.Files.Get(ctx, myfile.Name, nil)
    if err != nil {
        log.Fatal(err)
    }
}

parts := []*genai.Part{
    genai.NewPartFromURI(myfile.URI, myfile.MIMEType),
    genai.NewPartFromText("Describe this video clip"),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Pdf" %}

{% tabs %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
sample_pdf = client.files.upload(file=media / "test.pdf")
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this pdf file.", sample_pdf],
)
print(response.text)
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
samplePdf, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "test.pdf"),
    &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    },
)
if err != nil {
    log.Fatal(err)
}

parts := []*genai.Part{
    genai.NewPartFromText("Give me a summary of this pdf file."),
    genai.NewPartFromURI(samplePdf.URI, samplePdf.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
text := response.Text()
fmt.Println(text)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**file**: [`File`](/api-reference/files/create-file#Resource:File)

Metadata for the created file.

{% /section %}

## Resources {% class="hide-from-toc" id="resources" %}

### File {% class="hide-from-toc" id="Resource:File" %}

A file uploaded to the API.

**Properties:**

{% details %}

{% summary %}

**videoMetadata**: `VideoFileMetadata`

Output only. Metadata for a video.

{% /summary %}

**videoDuration**: `string`

Duration of the video.

{% /details %}

{% hr /%}

**name**: `string`

Immutable. Identifier. The [`File`](/api-reference/files/create-file#Resource:File) resource name. The ID (name excluding the "files/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be generated. Example: `files/123-456`

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`File`](/api-reference/files/create-file#Resource:File). The display name must be no more than 512 characters in length, including spaces. Example: "Welcome Image"

{% hr /%}

**mimeType**: `string`

Output only. MIME type of the file.

{% hr /%}

**sizeBytes**: `string`

Output only. Size of the file in bytes.

{% hr /%}

**createTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files/create-file#Resource:File) was created.

{% hr /%}

**updateTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files/create-file#Resource:File) was last updated.

{% hr /%}

**expirationTime**: `string`

Output only. The timestamp of when the [`File`](/api-reference/files/create-file#Resource:File) will be deleted. Only set if the [`File`](/api-reference/files/create-file#Resource:File) is scheduled to expire.

{% hr /%}

**sha256Hash**: `string`

Output only. SHA-256 hash of the uploaded bytes.

{% hr /%}

**uri**: `string`

Output only. The uri of the [`File`](/api-reference/files/create-file#Resource:File).

{% hr /%}

**downloadUri**: `string`

Output only. The download uri of the [`File`](/api-reference/files/create-file#Resource:File).

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. Processing state of the File.

{% /summary %}

Possible values:

- `STATE_UNSPECIFIED`: The default value. This value is used if the state is omitted.
- `PROCESSING`: File is being processed and cannot be used for inference yet.
- `ACTIVE`: File is processed and available for inference.
- `FAILED`: File failed processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**source**: `enum (string)`

Source of the File.

{% /summary %}

Possible values:

- `SOURCE_UNSPECIFIED`: Used if source is not specified.
- `UPLOADED`: Indicates the file is uploaded by the user.
- `GENERATED`: Indicates the file is generated by Google.
- `REGISTERED`: Indicates the file is a registered, i.e. a Google Cloud Storage file.

{% /details %}

{% hr /%}

**error**: [`Status`](/api-reference/files/create-file#Resource:Status)

Output only. Error status if File processing failed.

## Data Models {% class="hide-from-toc" id="data-models" %}

### Status {% class="hide-from-toc" id="Resource:Status" %}

The [`Status`](/api-reference/files/create-file#Resource:Status) type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It is
used by [gRPC](https://github.com/grpc). Each [`Status`](/api-reference/files/create-file#Resource:Status) message contains
three pieces of data: error code, error message, and error details.

You can find out more about this error model and how to work with it in the
[API Design Guide](https://cloud.google.com/apis/design/errors).

**Properties:**

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

{% hr /%}

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

{% hr /%}

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

# File Search Stores
Source: https://aistudio.google.com/api-reference/file-search/file-search-stores
Description: The File Search API provides a hosted question answering service for building Retrieval Augmented Generation (RAG) systems using Google's infrastructure.

The File Search API provides a hosted question answering service for building Retrieval Augmented Generation (RAG) systems using Google's infrastructure.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Creating a file search store](/api-reference/file-search/file-search-stores/create-file-search-store)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/fileSearchStores`

  Creates an empty [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).
---

* [Deleting a file search store](/api-reference/file-search/file-search-stores/delete-file-search-store)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}`

  Deletes a [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).
---

* [Getting a file search store](/api-reference/file-search/file-search-stores/get-file-search-store)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}`

  Gets information about a specific [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).
---

* [Listing file search stores](/api-reference/file-search/file-search-stores/list-file-search-stores)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores`

  Lists all `FileSearchStores` owned by the user.
---

* [Importing a file](/api-reference/file-search/file-search-stores/import-file)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}:importFile`

  Imports a `File` from File Service to a [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).
---

* [Getting an operation](/api-reference/file-search/file-search-stores/get-file-search-store-operation)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}/operations/{operation}`

  Gets the latest state of a long-running operation.
---

* [Getting an upload operation](/api-reference/file-search/file-search-stores/get-file-search-store-upload-operation)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStoresId}/upload/operations/{operationsId}`

  Gets the latest state of a long-running operation.
---

* [Uploading to a file search store](/api-reference/file-search/file-search-stores/upload-to-file-search-store)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}:uploadToFileSearchStore`

  Uploads data to a FileSearchStore, preprocesses and chunks before storing it in a FileSearchStore Document.
{% /table %}

## Resources {% id="resources" %}

### FileSearchStore {% id="Resource:FileSearchStore" %}

A [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) is a collection of `Document`s.

**Properties:**

**name**: `string`

Output only. Immutable. Identifier. The [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) resource name. It is an ID (name excluding the "fileSearchStores/" prefix) that can contain up to 40 characters that are lowercase alphanumeric or dashes (-). It is output only. The unique name will be derived from `display_name` along with a 12 character random suffix. Example: `fileSearchStores/my-awesome-file-search-store-123a456b789c` If `display_name` is not provided, the name will be randomly generated.

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). The display name must be no more than 512 characters in length, including spaces. Example: "Docs on Semantic Retriever"

{% hr /%}

**createTime**: `string`

Output only. The Timestamp of when the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) was created.

{% hr /%}

**updateTime**: `string`

Output only. The Timestamp of when the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) was last updated.

{% hr /%}

**activeDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) that are active and ready for retrieval.

{% hr /%}

**pendingDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) that are being processed.

{% hr /%}

**failedDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) that have failed processing.

{% hr /%}

**sizeBytes**: `string`

Output only. The size of raw bytes ingested into the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). This is the total size of all the documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).

{% hr /%}

**embeddingModel**: `string`

Optional. The embedding model to use for the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). The model's resource name. This serves as an ID for the Model to use. Format: `models/{model}`. If not specified, the default embedding model will be used.

# Creating a file search store
Source: https://aistudio.google.com/api-reference/file-search/file-search-stores/create-file-search-store
Description: Creates an empty `FileSearchStore`.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores`

Creates an empty [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).

{% two-column-layout %}

{% left-column %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**displayName**: `string`

Optional. The human-readable display name for the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). The display name must be no more than 512 characters in length, including spaces. Example: "Docs on Semantic Retriever"

{% hr /%}

**embeddingModel**: `string`

Optional. The embedding model to use for the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). The model's resource name. This serves as an ID for the Model to use. Format: `models/{model}`. If not specified, the default embedding model will be used.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/fileSearchStores" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**name**: `string`

Output only. Immutable. Identifier. The [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) resource name. It is an ID (name excluding the "fileSearchStores/" prefix) that can contain up to 40 characters that are lowercase alphanumeric or dashes (-). It is output only. The unique name will be derived from `display_name` along with a 12 character random suffix. Example: `fileSearchStores/my-awesome-file-search-store-123a456b789c` If `display_name` is not provided, the name will be randomly generated.

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). The display name must be no more than 512 characters in length, including spaces. Example: "Docs on Semantic Retriever"

{% hr /%}

**createTime**: `string`

Output only. The Timestamp of when the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) was created.

{% hr /%}

**updateTime**: `string`

Output only. The Timestamp of when the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) was last updated.

{% hr /%}

**activeDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) that are active and ready for retrieval.

{% hr /%}

**pendingDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) that are being processed.

{% hr /%}

**failedDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) that have failed processing.

{% hr /%}

**sizeBytes**: `string`

Output only. The size of raw bytes ingested into the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). This is the total size of all the documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).

{% hr /%}

**embeddingModel**: `string`

Optional. The embedding model to use for the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). The model's resource name. This serves as an ID for the Model to use. Format: `models/{model}`. If not specified, the default embedding model will be used.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "name": "string",
  "displayName": "string",
  "createTime": "string",
  "updateTime": "string",
  "activeDocumentsCount": "string",
  "pendingDocumentsCount": "string",
  "failedDocumentsCount": "string",
  "sizeBytes": "string",
  "embeddingModel": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

# Deleting a file search store
Source: https://aistudio.google.com/api-reference/file-search/file-search-stores/delete-file-search-store
Description: Deletes a `FileSearchStore`.

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores/{fileSearchStore}`

Deletes a [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**fileSearchStore**: {% mark %}required{% /mark %} `string`

The file search store ID. Forms the resource name `fileSearchStores/{fileSearchStore}`.

{% hr /%}

**force**: `boolean`

Optional. If set to true, any `Document`s and objects related to this [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) will also be deleted. If false (the default), a `FAILED_PRECONDITION` error will be returned if [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) contains any `Document`s.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/$FILE_SEARCH_STORE_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Getting a file search store
Source: https://aistudio.google.com/api-reference/file-search/file-search-stores/get-file-search-store
Description: Gets information about a specific `FileSearchStore`.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores/{fileSearchStore}`

Gets information about a specific [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**fileSearchStore**: {% mark %}required{% /mark %} `string`

The file search store ID. Forms the resource name `fileSearchStores/{fileSearchStore}`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/$FILE_SEARCH_STORE_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**name**: `string`

Output only. Immutable. Identifier. The [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) resource name. It is an ID (name excluding the "fileSearchStores/" prefix) that can contain up to 40 characters that are lowercase alphanumeric or dashes (-). It is output only. The unique name will be derived from `display_name` along with a 12 character random suffix. Example: `fileSearchStores/my-awesome-file-search-store-123a456b789c` If `display_name` is not provided, the name will be randomly generated.

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). The display name must be no more than 512 characters in length, including spaces. Example: "Docs on Semantic Retriever"

{% hr /%}

**createTime**: `string`

Output only. The Timestamp of when the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) was created.

{% hr /%}

**updateTime**: `string`

Output only. The Timestamp of when the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) was last updated.

{% hr /%}

**activeDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) that are active and ready for retrieval.

{% hr /%}

**pendingDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) that are being processed.

{% hr /%}

**failedDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) that have failed processing.

{% hr /%}

**sizeBytes**: `string`

Output only. The size of raw bytes ingested into the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). This is the total size of all the documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).

{% hr /%}

**embeddingModel**: `string`

Optional. The embedding model to use for the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore). The model's resource name. This serves as an ID for the Model to use. Format: `models/{model}`. If not specified, the default embedding model will be used.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "name": "string",
  "displayName": "string",
  "createTime": "string",
  "updateTime": "string",
  "activeDocumentsCount": "string",
  "pendingDocumentsCount": "string",
  "failedDocumentsCount": "string",
  "sizeBytes": "string",
  "embeddingModel": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

# Listing file search stores
Source: https://aistudio.google.com/api-reference/file-search/file-search-stores/list-file-search-stores
Description: Lists all `FileSearchStores` owned by the user.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores`

Lists all `FileSearchStores` owned by the user.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**pageSize**: `integer`

Optional. The maximum number of `FileSearchStores` to return (per page). The service may return fewer `FileSearchStores`. If unspecified, at most 10 `FileSearchStores` will be returned. The maximum size limit is 20 `FileSearchStores` per page.

{% hr /%}

**pageToken**: `string`

Optional. A page token, received from a previous `ListFileSearchStores` call. Provide the `next_page_token` returned in the response as an argument to the next request to retrieve the next page. When paginating, all other parameters provided to `ListFileSearchStores` must match the call that provided the page token.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/fileSearchStores" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**fileSearchStores**: `array (`[`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore)`)`

The returned rag_stores.

{% hr /%}

**nextPageToken**: `string`

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

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "fileSearchStores": [
    {
      "name": "string",
      "displayName": "string",
      "createTime": "string",
      "updateTime": "string",
      "activeDocumentsCount": "string",
      "pendingDocumentsCount": "string",
      "failedDocumentsCount": "string",
      "sizeBytes": "string",
      "embeddingModel": "string"
    }
  ],
  "nextPageToken": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### FileSearchStore {% class="hide-from-toc" id="Resource:FileSearchStore" %}

A [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore) is a collection of `Document`s.

**Properties:**

**name**: `string`

Output only. Immutable. Identifier. The [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore) resource name. It is an ID (name excluding the "fileSearchStores/" prefix) that can contain up to 40 characters that are lowercase alphanumeric or dashes (-). It is output only. The unique name will be derived from `display_name` along with a 12 character random suffix. Example: `fileSearchStores/my-awesome-file-search-store-123a456b789c` If `display_name` is not provided, the name will be randomly generated.

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore). The display name must be no more than 512 characters in length, including spaces. Example: "Docs on Semantic Retriever"

{% hr /%}

**createTime**: `string`

Output only. The Timestamp of when the [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore) was created.

{% hr /%}

**updateTime**: `string`

Output only. The Timestamp of when the [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore) was last updated.

{% hr /%}

**activeDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore) that are active and ready for retrieval.

{% hr /%}

**pendingDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore) that are being processed.

{% hr /%}

**failedDocumentsCount**: `string`

Output only. The number of documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore) that have failed processing.

{% hr /%}

**sizeBytes**: `string`

Output only. The size of raw bytes ingested into the [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore). This is the total size of all the documents in the [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore).

{% hr /%}

**embeddingModel**: `string`

Optional. The embedding model to use for the [`FileSearchStore`](/api-reference/file-search/file-search-stores/list-file-search-stores#Resource:FileSearchStore). The model's resource name. This serves as an ID for the Model to use. Format: `models/{model}`. If not specified, the default embedding model will be used.

# Importing a file
Source: https://aistudio.google.com/api-reference/file-search/file-search-stores/import-file
Description: Imports a `File` from File Service to a `FileSearchStore`.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores/{fileSearchStore}:importFile`

Imports a `File` from File Service to a [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**fileSearchStore**: {% mark %}required{% /mark %} `string`

The file search store ID. Forms the resource name `fileSearchStores/{fileSearchStore}`.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**fileName**: {% mark %}required{% /mark %} `string`

The name of the `File` to import. Example: `files/abc-123`

{% hr /%}

{% details %}

{% summary %}

**customMetadata**: `array (CustomMetadata)`

Custom metadata to be associated with the file.

{% /summary %}

**key**: {% mark %}required{% /mark %} `string`

The key of the metadata to store.

**stringValue**: `string`

The string value of the metadata to store.

{% details %}

{% summary %}

**stringListValue**: `StringList`

The StringList value of the metadata to store.

{% /summary %}

**values**: `array (string)`

The string values of the metadata to store.

{% /details %}

**numericValue**: `number`

The numeric value of the metadata to store.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**chunkingConfig**: `ChunkingConfig`

Optional. Config for telling the service how to chunk the file. If not provided, the service will use default parameters.

{% /summary %}

{% details %}

{% summary %}

**whiteSpaceConfig**: `WhiteSpaceConfig`

White space chunking configuration.

{% /summary %}

**maxTokensPerChunk**: `integer`

Maximum number of tokens per chunk. Tokens are defined as words for this chunking algorithm. Note: we are defining tokens as words split by whitespace as opposed to the output of a tokenizer. The context window of the latest gemini embedding model as of 2025-04-17 is currently 8192 tokens. We assume that the average word is 5 characters. Therefore, we set the upper limit to 2**9, which is 512 words, or 2560 tokens, assuming worst case a character per token. This is a conservative estimate meant to prevent context window overflow.

**maxOverlapTokens**: `integer`

Maximum number of overlapping tokens between two adjacent chunks.

{% /details %}

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/$FILE_SEARCH_STORE_ID:importFile" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "string"
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**error**: `Status`

The error result of the operation in case of failure or cancellation.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**response**: `ImportFileResponse`

{% /summary %}

**parent**: `string`

The name of the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) containing `Document`s. Example: `fileSearchStores/my-file-search-store-123`

**documentName**: `string`

Immutable. Identifier. The identifier for the `Document` imported. Example: `fileSearchStores/my-file-search-store-123/documents/my-awesome-doc-123a456b789c`

{% /details %}

{% hr /%}

**name**: `string`

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.

{% hr /%}

{% details %}

{% summary %}

**metadata**: `ImportFileMetadata`

{% /summary %}

{% /details %}

{% hr /%}

**done**: `boolean`

If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "error": {
    "code": 0,
    "message": "string",
    "details": [
      {}
    ]
  },
  "response": {
    "parent": "string",
    "documentName": "string"
  },
  "name": "string",
  "metadata": {},
  "done": true
}
```

{% /right-column %}

{% /two-column-layout %}

# Getting an operation
Source: https://aistudio.google.com/api-reference/file-search/file-search-stores/get-file-search-store-operation
Description: Gets the latest state of a long-running operation.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores/{fileSearchStore}/operations/{operation}`

Gets the latest state of a long-running operation. Clients can use this
method to poll the operation result at intervals as recommended by the API
service.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**fileSearchStore**: {% mark %}required{% /mark %} `string`

The file search store ID. Forms the resource name `fileSearchStores/{fileSearchStore}`.

{% hr /%}

**operation**: {% mark %}required{% /mark %} `string`

The operation ID.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/$FILE_SEARCH_STORE_ID/operations/$OPERATION_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**error**: `Status`

The error result of the operation in case of failure or cancellation.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% hr /%}

**response**: `object`

The normal, successful response of the operation. If the original method returns no data on success, such as `Delete`, the response is `google.protobuf.Empty`. If the original method is standard `Get`/`Create`/`Update`, the response should be the resource. For other methods, the response should have the type `XxxResponse`, where `Xxx` is the original method name. For example, if the original method name is `TakeSnapshot()`, the inferred response type is `TakeSnapshotResponse`.

{% hr /%}

**name**: `string`

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.

{% hr /%}

**metadata**: `object`

Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata. Any method that returns a long-running operation should document the metadata type, if any.

{% hr /%}

**done**: `boolean`

If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "error": {
    "code": 0,
    "message": "string",
    "details": [
      {}
    ]
  },
  "response": {},
  "name": "string",
  "metadata": {},
  "done": true
}
```

{% /right-column %}

{% /two-column-layout %}

# Getting an upload operation
Source: https://aistudio.google.com/api-reference/file-search/file-search-stores/get-file-search-store-upload-operation
Description: Gets the latest state of a long-running operation.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores/{fileSearchStoresId}/upload/operations/{operationsId}`

Gets the latest state of a long-running operation. Clients can use this
method to poll the operation result at intervals as recommended by the API
service.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**fileSearchStoresId**: {% mark %}required{% /mark %} `string`

The file search store ID. Forms the resource name `fileSearchStores/{fileSearchStoresId}`.

{% hr /%}

**operationsId**: {% mark %}required{% /mark %} `string`

The operation ID.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/$FILE_SEARCH_STORE_ID/upload/operations/$OPERATION_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**error**: `Status`

The error result of the operation in case of failure or cancellation.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% hr /%}

**response**: `object`

The normal, successful response of the operation. If the original method returns no data on success, such as `Delete`, the response is `google.protobuf.Empty`. If the original method is standard `Get`/`Create`/`Update`, the response should be the resource. For other methods, the response should have the type `XxxResponse`, where `Xxx` is the original method name. For example, if the original method name is `TakeSnapshot()`, the inferred response type is `TakeSnapshotResponse`.

{% hr /%}

**name**: `string`

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.

{% hr /%}

**metadata**: `object`

Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata. Any method that returns a long-running operation should document the metadata type, if any.

{% hr /%}

**done**: `boolean`

If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "error": {
    "code": 0,
    "message": "string",
    "details": [
      {}
    ]
  },
  "response": {},
  "name": "string",
  "metadata": {},
  "done": true
}
```

{% /right-column %}

{% /two-column-layout %}

# Uploading to a file search store
Source: https://aistudio.google.com/api-reference/file-search/file-search-stores/upload-to-file-search-store
Description: Uploads data to a FileSearchStore, preprocesses and chunks before storing it in a FileSearchStore Document.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores/{fileSearchStore}:uploadToFileSearchStore`

Uploads data to a FileSearchStore, preprocesses and chunks before storing
it in a FileSearchStore Document.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**fileSearchStore**: {% mark %}required{% /mark %} `string`

The file search store ID. Forms the resource name `fileSearchStores/{fileSearchStore}`.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**displayName**: `string`

Optional. Display name of the created document.

{% hr /%}

{% details %}

{% summary %}

**customMetadata**: `array (CustomMetadata)`

Custom metadata to be associated with the data.

{% /summary %}

**key**: {% mark %}required{% /mark %} `string`

The key of the metadata to store.

**stringValue**: `string`

The string value of the metadata to store.

{% details %}

{% summary %}

**stringListValue**: `StringList`

The StringList value of the metadata to store.

{% /summary %}

**values**: `array (string)`

The string values of the metadata to store.

{% /details %}

**numericValue**: `number`

The numeric value of the metadata to store.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**chunkingConfig**: `ChunkingConfig`

Optional. Config for telling the service how to chunk the data. If not provided, the service will use default parameters.

{% /summary %}

{% details %}

{% summary %}

**whiteSpaceConfig**: `WhiteSpaceConfig`

White space chunking configuration.

{% /summary %}

**maxTokensPerChunk**: `integer`

Maximum number of tokens per chunk. Tokens are defined as words for this chunking algorithm. Note: we are defining tokens as words split by whitespace as opposed to the output of a tokenizer. The context window of the latest gemini embedding model as of 2025-04-17 is currently 8192 tokens. We assume that the average word is 5 characters. Therefore, we set the upper limit to 2**9, which is 512 words, or 2560 tokens, assuming worst case a character per token. This is a conservative estimate meant to prevent context window overflow.

**maxOverlapTokens**: `integer`

Maximum number of overlapping tokens between two adjacent chunks.

{% /details %}

{% /details %}

{% hr /%}

**mimeType**: `string`

Optional. MIME type of the data. If not provided, it will be inferred from the uploaded content.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/$FILE_SEARCH_STORE_ID:uploadToFileSearchStore" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**error**: `Status`

The error result of the operation in case of failure or cancellation.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**response**: `UploadToFileSearchStoreResponse`

{% /summary %}

**parent**: `string`

The name of the [`FileSearchStore`](/api-reference/file-search/file-search-stores#Resource:FileSearchStore) containing `Document`s. Example: `fileSearchStores/my-file-search-store-123`

**documentName**: `string`

Immutable. Identifier. The identifier for the `Document` imported. Example: `fileSearchStores/my-file-search-store-123a456b789c`

**mimeType**: `string`

MIME type of the file.

**sizeBytes**: `string`

Size of the file in bytes.

{% /details %}

{% hr /%}

**name**: `string`

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.

{% hr /%}

{% details %}

{% summary %}

**metadata**: `UploadToFileSearchStoreMetadata`

{% /summary %}

{% /details %}

{% hr /%}

**done**: `boolean`

If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "error": {
    "code": 0,
    "message": "string",
    "details": [
      {}
    ]
  },
  "response": {
    "parent": "string",
    "documentName": "string",
    "mimeType": "string",
    "sizeBytes": "string"
  },
  "name": "string",
  "metadata": {},
  "done": true
}
```

{% /right-column %}

{% /two-column-layout %}

# Documents
Source: https://aistudio.google.com/api-reference/file-search/documents
Description: The File Search API references your raw source files, or documents, as temporary File objects.

The File Search API references your raw source files, or documents, as temporary File objects.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Deleting a document](/api-reference/file-search/documents/delete-document)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}/documents/{document}`

  Deletes a [`Document`](/api-reference/file-search/documents#Resource:Document).
---

* [Getting a document](/api-reference/file-search/documents/get-document)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}/documents/{document}`

  Gets information about a specific [`Document`](/api-reference/file-search/documents#Resource:Document).
---

* [Listing documents](/api-reference/file-search/documents/list-documents)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}/documents`

  Lists all [`Document`](/api-reference/file-search/documents#Resource:Document)s in a `Corpus`.
{% /table %}

## Resources {% id="resources" %}

### Document {% id="Resource:Document" %}

A [`Document`](/api-reference/file-search/documents#Resource:Document) is a collection of `Chunk`s.

**Properties:**

**name**: `string`

Immutable. Identifier. The [`Document`](/api-reference/file-search/documents#Resource:Document) resource name. The ID (name excluding the "fileSearchStores/*/documents/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be derived from `display_name` along with a 12 character random suffix. Example: `fileSearchStores/{file_search_store_id}/documents/my-awesome-doc-123a456b789c`

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`Document`](/api-reference/file-search/documents#Resource:Document). The display name must be no more than 512 characters in length, including spaces. Example: "Semantic Retriever Documentation"

{% hr /%}

{% details %}

{% summary %}

**customMetadata**: `array (CustomMetadata)`

Optional. User provided custom metadata stored as key-value pairs used for querying. A [`Document`](/api-reference/file-search/documents#Resource:Document) can have a maximum of 20 `CustomMetadata`.

{% /summary %}

**key**: {% mark %}required{% /mark %} `string`

The key of the metadata to store.

**stringValue**: `string`

The string value of the metadata to store.

{% details %}

{% summary %}

**stringListValue**: `StringList`

The StringList value of the metadata to store.

{% /summary %}

**values**: `array (string)`

The string values of the metadata to store.

{% /details %}

**numericValue**: `number`

The numeric value of the metadata to store.

{% /details %}

{% hr /%}

**updateTime**: `string`

Output only. The Timestamp of when the [`Document`](/api-reference/file-search/documents#Resource:Document) was last updated.

{% hr /%}

**createTime**: `string`

Output only. The Timestamp of when the [`Document`](/api-reference/file-search/documents#Resource:Document) was created.

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. Current state of the [`Document`](/api-reference/file-search/documents#Resource:Document).

{% /summary %}

Possible values:

- `STATE_UNSPECIFIED`: The default value. This value is used if the state is omitted.
- `STATE_PENDING`: Some `Chunks` of the [`Document`](/api-reference/file-search/documents#Resource:Document) are being processed (embedding and vector storage).
- `STATE_ACTIVE`: All `Chunks` of the [`Document`](/api-reference/file-search/documents#Resource:Document) is processed and available for querying.
- `STATE_FAILED`: Some `Chunks` of the [`Document`](/api-reference/file-search/documents#Resource:Document) failed processing.

{% /details %}

{% hr /%}

**sizeBytes**: `string`

Output only. The size of raw bytes ingested into the Document.

{% hr /%}

**mimeType**: `string`

Output only. The mime type of the Document.

# Deleting a document
Source: https://aistudio.google.com/api-reference/file-search/documents/delete-document
Description: Deletes a `Document`.

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores/{fileSearchStore}/documents/{document}`

Deletes a [`Document`](/api-reference/file-search/documents#Resource:Document).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**document**: {% mark %}required{% /mark %} `string`

The document ID. Forms the resource name `fileSearchStores/{fileSearchStore}/documents/{document}`.

{% hr /%}

**fileSearchStore**: {% mark %}required{% /mark %} `string`

The file search store ID. Forms the resource name `fileSearchStores/{fileSearchStore}`.

{% hr /%}

**force**: `boolean`

Optional. If set to true, any `Chunk`s and objects related to this [`Document`](/api-reference/file-search/documents#Resource:Document) will also be deleted. If false (the default), a `FAILED_PRECONDITION` error will be returned if [`Document`](/api-reference/file-search/documents#Resource:Document) contains any `Chunk`s.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/$FILE_SEARCH_STORE_ID/documents/$DOCUMENT_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Getting a document
Source: https://aistudio.google.com/api-reference/file-search/documents/get-document
Description: Gets information about a specific `Document`.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores/{fileSearchStore}/documents/{document}`

Gets information about a specific [`Document`](/api-reference/file-search/documents#Resource:Document).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**document**: {% mark %}required{% /mark %} `string`

The document ID. Forms the resource name `fileSearchStores/{fileSearchStore}/documents/{document}`.

{% hr /%}

**fileSearchStore**: {% mark %}required{% /mark %} `string`

The file search store ID. Forms the resource name `fileSearchStores/{fileSearchStore}`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/$FILE_SEARCH_STORE_ID/documents/$DOCUMENT_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**name**: `string`

Immutable. Identifier. The [`Document`](/api-reference/file-search/documents#Resource:Document) resource name. The ID (name excluding the "fileSearchStores/*/documents/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be derived from `display_name` along with a 12 character random suffix. Example: `fileSearchStores/{file_search_store_id}/documents/my-awesome-doc-123a456b789c`

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`Document`](/api-reference/file-search/documents#Resource:Document). The display name must be no more than 512 characters in length, including spaces. Example: "Semantic Retriever Documentation"

{% hr /%}

{% details %}

{% summary %}

**customMetadata**: `array (CustomMetadata)`

Optional. User provided custom metadata stored as key-value pairs used for querying. A [`Document`](/api-reference/file-search/documents#Resource:Document) can have a maximum of 20 `CustomMetadata`.

{% /summary %}

**key**: {% mark %}required{% /mark %} `string`

The key of the metadata to store.

**stringValue**: `string`

The string value of the metadata to store.

{% details %}

{% summary %}

**stringListValue**: `StringList`

The StringList value of the metadata to store.

{% /summary %}

**values**: `array (string)`

The string values of the metadata to store.

{% /details %}

**numericValue**: `number`

The numeric value of the metadata to store.

{% /details %}

{% hr /%}

**updateTime**: `string`

Output only. The Timestamp of when the [`Document`](/api-reference/file-search/documents#Resource:Document) was last updated.

{% hr /%}

**createTime**: `string`

Output only. The Timestamp of when the [`Document`](/api-reference/file-search/documents#Resource:Document) was created.

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. Current state of the [`Document`](/api-reference/file-search/documents#Resource:Document).

{% /summary %}

Possible values:

- `STATE_UNSPECIFIED`: The default value. This value is used if the state is omitted.
- `STATE_PENDING`: Some `Chunks` of the [`Document`](/api-reference/file-search/documents#Resource:Document) are being processed (embedding and vector storage).
- `STATE_ACTIVE`: All `Chunks` of the [`Document`](/api-reference/file-search/documents#Resource:Document) is processed and available for querying.
- `STATE_FAILED`: Some `Chunks` of the [`Document`](/api-reference/file-search/documents#Resource:Document) failed processing.

{% /details %}

{% hr /%}

**sizeBytes**: `string`

Output only. The size of raw bytes ingested into the Document.

{% hr /%}

**mimeType**: `string`

Output only. The mime type of the Document.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "name": "string",
  "displayName": "string",
  "customMetadata": [
    {
      "key": "string",
      "stringValue": "string",
      "stringListValue": {
        "values": [
          "string"
        ]
      },
      "numericValue": 0.0
    }
  ],
  "updateTime": "string",
  "createTime": "string",
  "state": "STATE_UNSPECIFIED",
  "sizeBytes": "string",
  "mimeType": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

# Listing documents
Source: https://aistudio.google.com/api-reference/file-search/documents/list-documents
Description: Lists all `Document`s in a `Corpus`.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/fileSearchStores/{fileSearchStore}/documents`

Lists all [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document)s in a `Corpus`.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**fileSearchStore**: {% mark %}required{% /mark %} `string`

The file search store ID. Forms the resource name `fileSearchStores/{fileSearchStore}`.

{% hr /%}

**pageSize**: `integer`

Optional. The maximum number of [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document)s to return (per page). The service may return fewer [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document)s. If unspecified, at most 10 [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document)s will be returned. The maximum size limit is 20 [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document)s per page.

{% hr /%}

**pageToken**: `string`

Optional. A page token, received from a previous `ListDocuments` call. Provide the `next_page_token` returned in the response as an argument to the next request to retrieve the next page. When paginating, all other parameters provided to `ListDocuments` must match the call that provided the page token.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/$FILE_SEARCH_STORE_ID/documents" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**documents**: `array (`[`Document`](/api-reference/file-search/documents/list-documents#Resource:Document)`)`

The returned [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document)s.

{% hr /%}

**nextPageToken**: `string`

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

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "documents": [
    {
      "name": "string",
      "displayName": "string",
      "customMetadata": [
        {
          "key": "string",
          "stringValue": "string",
          "stringListValue": {
            "values": [
              "..."
            ]
          },
          "numericValue": 0.0
        }
      ],
      "updateTime": "string",
      "createTime": "string",
      "state": "STATE_UNSPECIFIED",
      "sizeBytes": "string",
      "mimeType": "string"
    }
  ],
  "nextPageToken": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### Document {% class="hide-from-toc" id="Resource:Document" %}

A [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document) is a collection of `Chunk`s.

**Properties:**

**name**: `string`

Immutable. Identifier. The [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document) resource name. The ID (name excluding the "fileSearchStores/*/documents/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be derived from `display_name` along with a 12 character random suffix. Example: `fileSearchStores/{file_search_store_id}/documents/my-awesome-doc-123a456b789c`

{% hr /%}

**displayName**: `string`

Optional. The human-readable display name for the [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document). The display name must be no more than 512 characters in length, including spaces. Example: "Semantic Retriever Documentation"

{% hr /%}

{% details %}

{% summary %}

**customMetadata**: `array (CustomMetadata)`

Optional. User provided custom metadata stored as key-value pairs used for querying. A [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document) can have a maximum of 20 `CustomMetadata`.

{% /summary %}

**key**: {% mark %}required{% /mark %} `string`

The key of the metadata to store.

**stringValue**: `string`

The string value of the metadata to store.

{% details %}

{% summary %}

**stringListValue**: `StringList`

The StringList value of the metadata to store.

{% /summary %}

**values**: `array (string)`

The string values of the metadata to store.

{% /details %}

**numericValue**: `number`

The numeric value of the metadata to store.

{% /details %}

{% hr /%}

**updateTime**: `string`

Output only. The Timestamp of when the [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document) was last updated.

{% hr /%}

**createTime**: `string`

Output only. The Timestamp of when the [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document) was created.

{% hr /%}

{% details %}

{% summary %}

**state**: `enum (string)`

Output only. Current state of the [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document).

{% /summary %}

Possible values:

- `STATE_UNSPECIFIED`: The default value. This value is used if the state is omitted.
- `STATE_PENDING`: Some `Chunks` of the [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document) are being processed (embedding and vector storage).
- `STATE_ACTIVE`: All `Chunks` of the [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document) is processed and available for querying.
- `STATE_FAILED`: Some `Chunks` of the [`Document`](/api-reference/file-search/documents/list-documents#Resource:Document) failed processing.

{% /details %}

{% hr /%}

**sizeBytes**: `string`

Output only. The size of raw bytes ingested into the Document.

{% hr /%}

**mimeType**: `string`

Output only. The mime type of the Document.

# Caching
Source: https://aistudio.google.com/api-reference/caching
Description: Context caching allows you to save and reuse precomputed input tokens that you wish to use repeatedly, for example when asking different questions about the same media file.

Context caching allows you to save and reuse precomputed input tokens that you wish to use repeatedly, for example when asking different questions about the same media file. This can lead to cost and speed savings, depending on the usage. For a detailed introduction, see the [Context caching](/docs/caching) guide.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Creating cached content](/api-reference/caching/create-cached-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/cachedContents`

  Creates CachedContent resource.
---

* [Listing cached content](/api-reference/caching/list-cached-contents)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/cachedContents`

  Lists CachedContents.
---

* [Getting cached content](/api-reference/caching/get-cached-content)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/cachedContents/{id}`

  Reads CachedContent resource.
---

* [Updating cached content](/api-reference/caching/update-cached-content)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/cachedContents/{id}`

  Updates CachedContent resource (only expiration is updatable).
---

* [Deleting cached content](/api-reference/caching/delete-cached-content)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/cachedContents/{id}`

  Deletes CachedContent resource.
{% /table %}

## Resources {% id="resources" %}

### CachedContent {% id="Resource:CachedContent" %}

Content that has been preprocessed and can be used in subsequent request
to GenerativeService.

Cached content can be only used with model it was created for.

**Properties:**

**model**: {% mark %}required{% /mark %} `string`

Immutable. The name of the `Model` to use for cached content Format: `models/{model}`

{% hr /%}

**expireTime**: `string`

Timestamp in UTC of when this resource is considered expired. This is *always* provided on output, regardless of what was sent on input.

{% hr /%}

**ttl**: `string`

Input only. New TTL for this resource, input only.

{% hr /%}

**name**: `string`

Output only. Identifier. The resource name referring to the cached content. Format: `cachedContents/{id}`

{% hr /%}

**displayName**: `string`

Optional. Immutable. The user-generated meaningful display name of the cached content. Maximum 128 Unicode characters.

{% hr /%}

{% details %}

{% summary %}

**systemInstruction**: `Content`

Optional. Input only. Immutable. Developer set system instruction. Currently text only.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**contents**: `array (Content)`

Optional. Input only. Immutable. The content to cache.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**tools**: `array (Tool)`

Optional. Input only. Immutable. A list of `Tools` the model may use to generate the next response

{% /summary %}

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

{% details %}

{% summary %}

**parameters**: `Schema`

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

{% details %}

{% summary %}

**response**: `Schema`

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Input only. Immutable. Tool config. This config is shared for all tools.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions.

{% /details %}

{% hr /%}

**createTime**: `string`

Output only. Creation time of the cache entry.

{% hr /%}

**updateTime**: `string`

Output only. When the cache entry was last updated in UTC time.

{% hr /%}

{% details %}

{% summary %}

**usageMetadata**: `CachedContentUsageMetadata`

Output only. Metadata on the usage of the cached content.

{% /summary %}

**totalTokenCount**: `integer`

Total number of tokens that the cached content consumes.

{% /details %}

# Creating cached content
Source: https://aistudio.google.com/api-reference/caching/create-cached-content
Description: Creates CachedContent resource.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/cachedContents`

Creates CachedContent resource.

{% two-column-layout %}

{% left-column %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

Immutable. The name of the `Model` to use for cached content Format: `models/{model}`

{% hr /%}

**expireTime**: `string`

Timestamp in UTC of when this resource is considered expired. This is *always* provided on output, regardless of what was sent on input.

{% hr /%}

**ttl**: `string`

Input only. New TTL for this resource, input only.

{% hr /%}

**displayName**: `string`

Optional. Immutable. The user-generated meaningful display name of the cached content. Maximum 128 Unicode characters.

{% hr /%}

{% details %}

{% summary %}

**systemInstruction**: `Content`

Optional. Input only. Immutable. Developer set system instruction. Currently text only.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**contents**: `array (Content)`

Optional. Input only. Immutable. The content to cache.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**tools**: `array (Tool)`

Optional. Input only. Immutable. A list of `Tools` the model may use to generate the next response

{% /summary %}

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

{% details %}

{% summary %}

**parameters**: `Schema`

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

{% details %}

{% summary %}

**response**: `Schema`

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Input only. Immutable. Tool config. This config is shared for all tools.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions.

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="Basic" %}

{% tabs %}

{% tab label="REST" %}

```sh
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-3.8-flash",
  "contents":[
    {
      "parts":[
        {
          "inline_data": {
            "mime_type":"text/plain",
            "data": "'$(base64 $B64FLAGS a11.txt)'"
          }
        }
      ],
    "role": "user"
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are an expert at analyzing transcripts."
      }
    ]
  },
  "ttl": "300s"
}' > request.json

curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d @request.json \
 > cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-3.8-flash"

cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
        contents=[document],
        system_instruction="You are an expert analyzing transcripts.",
    ),
)
print(cache)

response = client.models.generate_content(
    model=model_name,
    contents="Please summarize this transcript",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const filePath = path.join(media, 'a11.txt');
const document = await ai.files.upload({
  file: filePath,
  config: {mimeType: 'text/plain'},
});
console.log('Uploaded file name:', document.name);
const modelName = 'gemini-3.8-flash';

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: 'You are an expert analyzing transcripts.',
  },
});
console.log('Cache created:', cache);

const response = await ai.models.generateContent({
  model: modelName,
  contents: 'Please summarize this transcript',
  config: {cachedContent: cache.name},
});
console.log('Response text:', response.text);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

modelName := "gemini-3.8-flash"
document, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "a11.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
parts := []*genai.Part{
    genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
    Contents: contents,
    SystemInstruction: genai.NewContentFromText(
        "You are an expert analyzing transcripts.", genai.RoleUser,
    ),
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("Cache created:")
fmt.Println(cache)

// Use the cache for generating content.
response, err := client.Models.GenerateContent(
    ctx,
    modelName,
    genai.Text("Please summarize this transcript"),
    &genai.GenerateContentConfig{
        CachedContent: cache.Name,
    },
)
if err != nil {
    log.Fatal(err)
}
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="From Name" %}

{% tabs %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-3.8-flash"

cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
        contents=[document],
        system_instruction="You are an expert analyzing transcripts.",
    ),
)
cache_name = cache.name  # Save the name for later

# Later retrieve the cache
cache = client.caches.get(name=cache_name)
response = client.models.generate_content(
    model=model_name,
    contents="Find a lighthearted moment from this transcript",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const filePath = path.join(media, 'a11.txt');
const document = await ai.files.upload({
  file: filePath,
  config: {mimeType: 'text/plain'},
});
console.log('Uploaded file name:', document.name);
const modelName = 'gemini-3.8-flash';

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: 'You are an expert analyzing transcripts.',
  },
});
const cacheName = cache.name;  // Save the name for later

// Later retrieve the cache
const retrievedCache = await ai.caches.get({name: cacheName});
const response = await ai.models.generateContent({
  model: modelName,
  contents: 'Find a lighthearted moment from this transcript',
  config: {cachedContent: retrievedCache.name},
});
console.log('Response text:', response.text);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

modelName := "gemini-3.8-flash"
document, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "a11.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
parts := []*genai.Part{
    genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
    Contents: contents,
    SystemInstruction: genai.NewContentFromText(
        "You are an expert analyzing transcripts.", genai.RoleUser,
    ),
})
if err != nil {
    log.Fatal(err)
}
cacheName := cache.Name

// Later retrieve the cache.
cache, err = client.Caches.Get(ctx, cacheName, &genai.GetCachedContentConfig{})
if err != nil {
    log.Fatal(err)
}

response, err := client.Models.GenerateContent(
    ctx,
    modelName,
    genai.Text("Find a lighthearted moment from this transcript"),
    &genai.GenerateContentConfig{
        CachedContent: cache.Name,
    },
)
if err != nil {
    log.Fatal(err)
}
fmt.Println("Response from cache (create from name):")
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="From Chat" %}

{% tabs %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
model_name = "gemini-3.8-flash"
system_instruction = "You are an expert analyzing transcripts."

# Create a chat session with the given system instruction.
chat = client.chats.create(
    model=model_name,
    config=types.GenerateContentConfig(
        system_instruction=system_instruction
    ),
)
document = client.files.upload(file=media / "a11.txt")

response = chat.send_message(
    message=["Hi, could you summarize this transcript?", document]
)
print("\n\nmodel:  ", response.text)
response = chat.send_message(
    message=["Okay, could you tell me more about the trans-lunar injection"]
)
print("\n\nmodel:  ", response.text)

# To cache the conversation so far, pass the chat history as the list of contents.
cache = client.caches.create(
    model=model_name,
    config={
        "contents": chat.get_history(),
        "system_instruction": system_instruction,
    },
)
# Continue the conversation using the cached content.
chat = client.chats.create(
    model=model_name,
    config=types.GenerateContentConfig(cached_content=cache.name),
)
response = chat.send_message(
    message=(
        "I didn't understand that last part, could you explain it in"
        " simpler language?"
    )
)
print("\n\nmodel:  ", response.text)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const modelName = 'gemini-3.8-flash';
const systemInstruction = 'You are an expert analyzing transcripts.';

// Create a chat session with the system instruction.
const chat = ai.chats.create({
  model: modelName,
  config: {systemInstruction: systemInstruction},
});
const filePath = path.join(media, 'a11.txt');
const document = await ai.files.upload({
  file: filePath,
  config: {mimeType: 'text/plain'},
});
console.log('Uploaded file name:', document.name);

let response = await chat.sendMessage({
  message: createUserContent([
    'Hi, could you summarize this transcript?',
    createPartFromUri(document.uri, document.mimeType),
  ]),
});
console.log('\n\nmodel:', response.text);

response = await chat.sendMessage({
  message: 'Okay, could you tell me more about the trans-lunar injection',
});
console.log('\n\nmodel:', response.text);

// To cache the conversation so far, pass the chat history as the list of
// contents.
const chatHistory = chat.getHistory();
const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: chatHistory,
    systemInstruction: systemInstruction,
  },
});

// Continue the conversation using the cached content.
const chatWithCache = ai.chats.create({
  model: modelName,
  config: {cachedContent: cache.name},
});
response = await chatWithCache.sendMessage({
  message:
      'I didn\'t understand that last part, could you explain it in simpler language?',
});
console.log('\n\nmodel:', response.text);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

modelName := "gemini-3.8-flash"
systemInstruction := "You are an expert analyzing transcripts."

// Create initial chat with a system instruction.
chat, err := client.Chats.Create(ctx, modelName, &genai.GenerateContentConfig{
    SystemInstruction: genai.NewContentFromText(systemInstruction, genai.RoleUser),
}, nil)
if err != nil {
    log.Fatal(err)
}

document, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "a11.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}

// Send first message with the transcript.
parts := make([]genai.Part, 2)
parts[0] = genai.Part{Text: "Hi, could you summarize this transcript?"}
parts[1] = genai.Part{
    FileData: &genai.FileData{
        FileURI:  document.URI,
        MIMEType: document.MIMEType,
    },
}

// Send chat message.
resp, err := chat.SendMessage(ctx, parts...)
if err != nil {
    log.Fatal(err)
}
fmt.Println("\n\nmodel: ", resp.Text())

resp, err = chat.SendMessage(
    ctx,
    genai.Part{
        Text: "Okay, could you tell me more about the trans-lunar injection",
    },
)
if err != nil {
    log.Fatal(err)
}
fmt.Println("\n\nmodel: ", resp.Text())

// To cache the conversation so far, pass the chat history as the list of contents.
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
    Contents:          chat.History(false),
    SystemInstruction: genai.NewContentFromText(systemInstruction, genai.RoleUser),
})
if err != nil {
    log.Fatal(err)
}

// Continue the conversation using the cached history.
chat, err = client.Chats.Create(ctx, modelName, &genai.GenerateContentConfig{
    CachedContent: cache.Name,
}, nil)
if err != nil {
    log.Fatal(err)
}

resp, err = chat.SendMessage(
    ctx,
    genai.Part{
        Text: "I didn't understand that last part, could you explain it in simpler language?",
    },
)
if err != nil {
    log.Fatal(err)
}
fmt.Println("\n\nmodel: ", resp.Text())
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

Immutable. The name of the `Model` to use for cached content Format: `models/{model}`

{% hr /%}

**expireTime**: `string`

Timestamp in UTC of when this resource is considered expired. This is *always* provided on output, regardless of what was sent on input.

{% hr /%}

**name**: `string`

Output only. Identifier. The resource name referring to the cached content. Format: `cachedContents/{id}`

{% hr /%}

**displayName**: `string`

Optional. Immutable. The user-generated meaningful display name of the cached content. Maximum 128 Unicode characters.

{% hr /%}

**createTime**: `string`

Output only. Creation time of the cache entry.

{% hr /%}

**updateTime**: `string`

Output only. When the cache entry was last updated in UTC time.

{% hr /%}

{% details %}

{% summary %}

**usageMetadata**: `CachedContentUsageMetadata`

Output only. Metadata on the usage of the cached content.

{% /summary %}

**totalTokenCount**: `integer`

Total number of tokens that the cached content consumes.

{% /details %}

{% /section %}

# Listing cached content
Source: https://aistudio.google.com/api-reference/caching/list-cached-contents
Description: Lists CachedContents.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/cachedContents`

Lists CachedContents.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**pageSize**: `integer`

Optional. The maximum number of cached contents to return. The service may return fewer than this value. If unspecified, some default (under maximum) number of items will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

{% hr /%}

**pageToken**: `string`

Optional. A page token, received from a previous `ListCachedContents` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListCachedContents` must match the call that provided the page token.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-3.8-flash"

cache = client.caches.create(
    model=model_name,
    config={
        "contents": [document],
        "system_instruction": "You are an expert analyzing transcripts.",
    },
)
print("My caches:")
for c in client.caches.list():
  print("    ", c.name)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const filePath = path.join(media, 'a11.txt');
const document = await ai.files.upload({
  file: filePath,
  config: {mimeType: 'text/plain'},
});
console.log('Uploaded file name:', document.name);
const modelName = 'gemini-3.8-flash';

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

// Create a cache for demonstration.
const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: 'You are an expert analyzing transcripts.',
  },
});

console.log('My caches:');
const pager = await ai.caches.list({config: {pageSize: 10}});
let page = pager.page;
while (true) {
  for (const c of page) {
    console.log('    ', c.name);
  }
  if (!pager.hasNextPage()) break;
  page = await pager.nextPage();
}
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

// For demonstration, create a cache first.
modelName := "gemini-3.8-flash"
document, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "a11.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
parts := []*genai.Part{
    genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
    Contents: contents,
    SystemInstruction: genai.NewContentFromText(
        "You are an expert analyzing transcripts.", genai.RoleUser,
    ),
})
if err != nil {
    log.Fatal(err)
}

// List caches using the List method with a page size of 2.
page, err := client.Caches.List(ctx, &genai.ListCachedContentsConfig{PageSize: 2})
if err != nil {
    log.Fatal(err)
}

pageIndex := 1
for {
    fmt.Printf("Listing caches (page %d):\n", pageIndex)
    for _, item := range page.Items {
        fmt.Println("   ", item.Name)
    }
    if page.NextPageToken == "" {
        break
    }
    page, err = page.Next(ctx)
    if err == genai.ErrPageDone {
        break
    } else if err != nil {
        return err
    }
    pageIndex++
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**cachedContents**: `array (`[`CachedContent`](/api-reference/caching/list-cached-contents#Resource:CachedContent)`)`

List of cached contents.

{% hr /%}

**nextPageToken**: `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.

{% /section %}

## Resources {% class="hide-from-toc" id="resources" %}

### CachedContent {% class="hide-from-toc" id="Resource:CachedContent" %}

Content that has been preprocessed and can be used in subsequent request
to GenerativeService.

Cached content can be only used with model it was created for.

**Properties:**

**model**: {% mark %}required{% /mark %} `string`

Immutable. The name of the `Model` to use for cached content Format: `models/{model}`

{% hr /%}

**expireTime**: `string`

Timestamp in UTC of when this resource is considered expired. This is *always* provided on output, regardless of what was sent on input.

{% hr /%}

**ttl**: `string`

Input only. New TTL for this resource, input only.

{% hr /%}

**name**: `string`

Output only. Identifier. The resource name referring to the cached content. Format: `cachedContents/{id}`

{% hr /%}

**displayName**: `string`

Optional. Immutable. The user-generated meaningful display name of the cached content. Maximum 128 Unicode characters.

{% hr /%}

{% details %}

{% summary %}

**systemInstruction**: `Content`

Optional. Input only. Immutable. Developer set system instruction. Currently text only.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**contents**: `array (Content)`

Optional. Input only. Immutable. The content to cache.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**tools**: `array (Tool)`

Optional. Input only. Immutable. A list of `Tools` the model may use to generate the next response

{% /summary %}

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

{% details %}

{% summary %}

**parameters**: `Schema`

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

{% details %}

{% summary %}

**response**: `Schema`

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Input only. Immutable. Tool config. This config is shared for all tools.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions.

{% /details %}

{% hr /%}

**createTime**: `string`

Output only. Creation time of the cache entry.

{% hr /%}

**updateTime**: `string`

Output only. When the cache entry was last updated in UTC time.

{% hr /%}

{% details %}

{% summary %}

**usageMetadata**: `CachedContentUsageMetadata`

Output only. Metadata on the usage of the cached content.

{% /summary %}

**totalTokenCount**: `integer`

Total number of tokens that the cached content consumes.

{% /details %}

# Getting cached content
Source: https://aistudio.google.com/api-reference/caching/get-cached-content
Description: Reads CachedContent resource.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/cachedContents/{id}`

Reads CachedContent resource.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

The cached content ID. Forms the resource name `cachedContents/{id}`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-3.8-flash"

cache = client.caches.create(
    model=model_name,
    config={
        "contents": [document],
        "system_instruction": "You are an expert analyzing transcripts.",
    },
)
print(client.caches.get(name=cache.name))
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const filePath = path.join(media, 'a11.txt');
const document = await ai.files.upload({
  file: filePath,
  config: {mimeType: 'text/plain'},
});
console.log('Uploaded file name:', document.name);
const modelName = 'gemini-3.8-flash';

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: 'You are an expert analyzing transcripts.',
  },
});
const retrievedCache = await ai.caches.get({name: cache.name});
console.log('Retrieved Cache:', retrievedCache);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

modelName := "gemini-3.8-flash"
document, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "a11.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
parts := []*genai.Part{
    genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
    Contents: contents,
    SystemInstruction: genai.NewContentFromText(
        "You are an expert analyzing transcripts.", genai.RoleUser,
    ),
})
if err != nil {
    log.Fatal(err)
}

cache, err = client.Caches.Get(ctx, cache.Name, &genai.GetCachedContentConfig{})
if err != nil {
    log.Fatal(err)
}
fmt.Println("Retrieved cache:")
fmt.Println(cache)
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

Immutable. The name of the `Model` to use for cached content Format: `models/{model}`

{% hr /%}

**expireTime**: `string`

Timestamp in UTC of when this resource is considered expired. This is *always* provided on output, regardless of what was sent on input.

{% hr /%}

**name**: `string`

Output only. Identifier. The resource name referring to the cached content. Format: `cachedContents/{id}`

{% hr /%}

**displayName**: `string`

Optional. Immutable. The user-generated meaningful display name of the cached content. Maximum 128 Unicode characters.

{% hr /%}

**createTime**: `string`

Output only. Creation time of the cache entry.

{% hr /%}

**updateTime**: `string`

Output only. When the cache entry was last updated in UTC time.

{% hr /%}

{% details %}

{% summary %}

**usageMetadata**: `CachedContentUsageMetadata`

Output only. Metadata on the usage of the cached content.

{% /summary %}

**totalTokenCount**: `integer`

Total number of tokens that the cached content consumes.

{% /details %}

{% /section %}

# Updating cached content
Source: https://aistudio.google.com/api-reference/caching/update-cached-content
Description: Updates CachedContent resource (only expiration is updatable).

{% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/cachedContents/{id}`

Updates CachedContent resource (only expiration is updatable).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

The cached content ID. Forms the resource name `cachedContents/{id}`.

{% hr /%}

**updateMask**: `string`

The list of fields to update.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

Immutable. The name of the `Model` to use for cached content Format: `models/{model}`

{% hr /%}

**expireTime**: `string`

Timestamp in UTC of when this resource is considered expired. This is *always* provided on output, regardless of what was sent on input.

{% hr /%}

**ttl**: `string`

Input only. New TTL for this resource, input only.

{% hr /%}

**displayName**: `string`

Optional. Immutable. The user-generated meaningful display name of the cached content. Maximum 128 Unicode characters.

{% hr /%}

{% details %}

{% summary %}

**systemInstruction**: `Content`

Optional. Input only. Immutable. Developer set system instruction. Currently text only.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**contents**: `array (Content)`

Optional. Input only. Immutable. The content to cache.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**tools**: `array (Tool)`

Optional. Input only. Immutable. A list of `Tools` the model may use to generate the next response

{% /summary %}

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

{% details %}

{% summary %}

**parameters**: `Schema`

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

{% details %}

{% summary %}

**response**: `Schema`

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Input only. Immutable. Tool config. This config is shared for all tools.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions.

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types
import datetime

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-3.8-flash"

cache = client.caches.create(
    model=model_name,
    config={
        "contents": [document],
        "system_instruction": "You are an expert analyzing transcripts.",
    },
)

# Update the cache's time-to-live (ttl)
ttl = f"{int(datetime.timedelta(hours=2).total_seconds())}s"
client.caches.update(
    name=cache.name, config=types.UpdateCachedContentConfig(ttl=ttl)
)
print(f"After update:\n {cache}")

# Alternatively, update the expire_time directly
# Update the expire_time directly in valid RFC 3339 format (UTC with a "Z" suffix)
expire_time = (
    (
        datetime.datetime.now(datetime.timezone.utc)
        + datetime.timedelta(minutes=15)
    )
    .isoformat()
    .replace("+00:00", "Z")
)
client.caches.update(
    name=cache.name,
    config=types.UpdateCachedContentConfig(expire_time=expire_time),
)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const filePath = path.join(media, 'a11.txt');
const document = await ai.files.upload({
  file: filePath,
  config: {mimeType: 'text/plain'},
});
console.log('Uploaded file name:', document.name);
const modelName = 'gemini-3.8-flash';

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

let cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: 'You are an expert analyzing transcripts.',
  },
});

// Update the cache's time-to-live (ttl)
const ttl = `${2 * 3600}s`;  // 2 hours in seconds
cache = await ai.caches.update({
  name: cache.name,
  config: {ttl},
});
console.log('After update (TTL):', cache);

// Alternatively, update the expire_time directly (in RFC 3339 format with a
// "Z" suffix)
const expireTime =
    new Date(Date.now() + 15 * 60000).toISOString().replace(/\.\d{3}Z$/, 'Z');
cache = await ai.caches.update({
  name: cache.name,
  config: {expireTime: expireTime},
});
console.log('After update (expire_time):', cache);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

modelName := "gemini-3.8-flash"
document, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "a11.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
parts := []*genai.Part{
    genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
    Contents: contents,
    SystemInstruction: genai.NewContentFromText(
        "You are an expert analyzing transcripts.", genai.RoleUser,
    ),
})
if err != nil {
    log.Fatal(err)
}

_, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})
if err != nil {
    log.Fatal(err)
}
fmt.Println("Cache deleted:", cache.Name)
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

Immutable. The name of the `Model` to use for cached content Format: `models/{model}`

{% hr /%}

**expireTime**: `string`

Timestamp in UTC of when this resource is considered expired. This is *always* provided on output, regardless of what was sent on input.

{% hr /%}

**name**: `string`

Output only. Identifier. The resource name referring to the cached content. Format: `cachedContents/{id}`

{% hr /%}

**displayName**: `string`

Optional. Immutable. The user-generated meaningful display name of the cached content. Maximum 128 Unicode characters.

{% hr /%}

**createTime**: `string`

Output only. Creation time of the cache entry.

{% hr /%}

**updateTime**: `string`

Output only. When the cache entry was last updated in UTC time.

{% hr /%}

{% details %}

{% summary %}

**usageMetadata**: `CachedContentUsageMetadata`

Output only. Metadata on the usage of the cached content.

{% /summary %}

**totalTokenCount**: `integer`

Total number of tokens that the cached content consumes.

{% /details %}

{% /section %}

# Deleting cached content
Source: https://aistudio.google.com/api-reference/caching/delete-cached-content
Description: Deletes CachedContent resource.

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/cachedContents/{id}`

Deletes CachedContent resource.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**id**: {% mark %}required{% /mark %} `string`

The cached content ID. Forms the resource name `cachedContents/{id}`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-3.8-flash"

cache = client.caches.create(
    model=model_name,
    config={
        "contents": [document],
        "system_instruction": "You are an expert analyzing transcripts.",
    },
)
client.caches.delete(name=cache.name)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const filePath = path.join(media, 'a11.txt');
const document = await ai.files.upload({
  file: filePath,
  config: {mimeType: 'text/plain'},
});
console.log('Uploaded file name:', document.name);
const modelName = 'gemini-3.8-flash';

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: 'You are an expert analyzing transcripts.',
  },
});
await ai.caches.delete({name: cache.name});
console.log('Cache deleted:', cache.name);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

modelName := "gemini-3.8-flash"
document, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "a11.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
parts := []*genai.Part{
    genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
    Contents: contents,
    SystemInstruction: genai.NewContentFromText(
        "You are an expert analyzing transcripts.", genai.RoleUser,
    ),
})
if err != nil {
    log.Fatal(err)
}

_, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})
if err != nil {
    log.Fatal(err)
}
fmt.Println("Cache deleted:", cache.Name)
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Embeddings
Source: https://aistudio.google.com/api-reference/embeddings
Description: Embeddings are a numerical representation of text input that open up a number of unique use cases, such as clustering, similarity measurement and information retrieval.

Embeddings are a numerical representation of text input that open up a number of unique use cases, such as clustering, similarity measurement and information retrieval. For an introduction, check out the [Embeddings guide](/docs/embeddings).

Unlike generative AI models that create new content, the Gemini Embedding model is only intended to transform the format of your input data into a numerical representation. While Google is responsible for providing an embedding model that transforms the format of your input data to the numerical-format requested, users retain full responsibility for the data they input and the resulting embeddings. By using the Gemini Embedding model you confirm that you have the necessary rights to any content that you upload. Do not generate content that infringes on others' intellectual property or privacy rights. Your use of this service is subject to our [Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy) and [Google's Terms of Service](/docs/terms).

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Embedding content](/api-reference/embeddings/embed-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:embedContent`

  Generates a text embedding vector from the input `Content` using the specified [Gemini Embedding model](/docs/models#specialized-task-models).
---

* [Embedding a batch of contents](/api-reference/embeddings/batch-embed-contents)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:batchEmbedContents`

  Generates multiple embedding vectors from the input `Content` which consists of a batch of strings represented as `EmbedContentRequest` objects.
---

* [Creating an embedding batch](/api-reference/embeddings/async-batch-embed-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:asyncBatchEmbedContent`

  Enqueues a batch of `EmbedContent` requests for batch processing.
{% /table %}

## Data Models {% id="data-models" %}

### EmbedContentResponse {% id="Resource:EmbedContentResponse" %}

The response to an `EmbedContentRequest`.

**Properties:**

**embedding**: [`ContentEmbedding`](/api-reference/embeddings#Resource:ContentEmbedding)

Output only. The embedding generated from the input content.

{% hr /%}

**usageMetadata**: [`EmbeddingUsageMetadata`](/api-reference/embeddings#Resource:EmbeddingUsageMetadata)

Output only. The usage metadata for the request.

### ContentEmbedding {% id="Resource:ContentEmbedding" %}

A list of floats representing an embedding.

**Properties:**

**values**: `array (number)`

The embedding values. This is for 3P users only and will not be populated for 1P calls.

{% hr /%}

**shape**: `array (integer)`

This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]).

### TaskType {% id="Resource:TaskType" %}

**Possible values:**

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

### EmbedContentBatch {% id="Resource:EmbedContentBatch" %}

A resource representing a batch of `EmbedContent` requests.

**Properties:**

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% hr /%}

**displayName**: {% mark %}required{% /mark %} `string`

The user-defined name of this batch.

{% hr /%}

{% details %}

{% summary %}

**inputConfig**: {% mark %}required{% /mark %} `InputEmbedContentConfig`

Input configuration of the instances on which batch processing are performed.

{% /summary %}

**fileName**: `string`

The name of the `File` containing the input requests.

{% details %}

{% summary %}

**requests**: `InlinedEmbedContentRequests`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (InlinedEmbedContentRequest)`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**request**: {% mark %}required{% /mark %} `EmbedContentRequest`

The request to be processed in the batch.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

{% details %}

{% summary %}

**content**: {% mark %}required{% /mark %} `Content`

The content to embed. Only the `parts.text` fields will be counted.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

**embedContentConfig**: [`EmbedContentConfig`](/api-reference/embeddings#Resource:EmbedContentConfig)

Optional. Configuration for the EmbedContent request.

{% /details %}

**metadata**: `object`

Optional. The metadata to be associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

Output only. Identifier. Resource name of the batch. Format: `batches/{batch_id}`.

{% hr /%}

{% details %}

{% summary %}

**output**: `EmbedContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be [`EmbedContentResponse`](/api-reference/embeddings#Resource:EmbedContentResponse) messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedEmbedContentResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedEmbedContentResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

**response**: [`EmbedContentResponse`](/api-reference/embeddings#Resource:EmbedContentResponse)

Output only. The response to the request.

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**createTime**: `string`

Output only. The time at which the batch was created.

{% hr /%}

**endTime**: `string`

Output only. The time at which the batch processing completed.

{% hr /%}

**updateTime**: `string`

Output only. The time at which the batch was last updated.

{% hr /%}

{% details %}

{% summary %}

**batchStats**: `EmbedContentBatchStats`

Output only. Stats about the batch.

{% /summary %}

**requestCount**: `string`

Output only. The number of requests in the batch.

**successfulRequestCount**: `string`

Output only. The number of requests that were successfully processed.

**failedRequestCount**: `string`

Output only. The number of requests that failed to be processed.

**pendingRequestCount**: `string`

Output only. The number of requests that are still pending processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: `BatchState`

Output only. The state of the batch.

{% /summary %}

Possible values:

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

{% /details %}

{% hr /%}

**priority**: `string`

Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.

### EmbedContentConfig {% id="Resource:EmbedContentConfig" %}

Configurations for the EmbedContent request.

**Properties:**

**title**: `string`

Optional. The title for the text.

{% hr /%}

{% details %}

{% summary %}

**taskType**: [`TaskType`](/api-reference/embeddings#Resource:TaskType)

Optional. The task type of the embedding.

{% /summary %}

Possible values:

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

{% /details %}

{% hr /%}

**autoTruncate**: `boolean`

Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.

{% hr /%}

**outputDimensionality**: `integer`

Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

{% hr /%}

**documentOcr**: `boolean`

Optional. Whether to enable OCR for document content.

{% hr /%}

**audioTrackExtraction**: `boolean`

Optional. Whether to extract audio from video content.

### EmbeddingUsageMetadata {% id="Resource:EmbeddingUsageMetadata" %}

Metadata on the usage of the embedding request.

**Properties:**

**promptTokenCount**: `integer`

Output only. Number of tokens in the prompt.

{% hr /%}

{% details %}

{% summary %}

**promptTokenDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

# Embedding content
Source: https://aistudio.google.com/api-reference/embeddings/embed-content
Description: Generates a text embedding vector from the input `Content` using the specified [Gemini Embedding model](/docs/models#specialized-task-models).

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/models/{model}:embedContent`

Generates a text embedding vector from the input `Content` using the
specified [Gemini Embedding
model](/docs/models#specialized-task-models).

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The model ID, for example `gemini-2.5-flash`. Forms the resource name `models/{model}`.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

{% hr /%}

{% details %}

{% summary %}

**content**: {% mark %}required{% /mark %} `Content`

The content to embed. Only the `parts.text` fields will be counted.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% hr /%}

**embedContentConfig**: [`EmbedContentConfig`](/api-reference/embeddings/embed-content#Resource:EmbedContentConfig)

Optional. Configuration for the EmbedContent request.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/gemini-embedding-001",
     "content": {
     "parts":[{
     "text": "What is the meaning of life?"}]}
    }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
text = "Hello World!"
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=text,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const text = 'Hello World!';
const result = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  contents: text,
  config: {outputDimensionality: 10},
});
console.log(result.embeddings);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

text := "Hello World!"
outputDim := int32(10)
contents := []*genai.Content{
    genai.NewContentFromText(text, genai.RoleUser),
}
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001",
    contents, &genai.EmbedContentConfig{
        OutputDimensionality: &outputDim,
    })
if err != nil {
    log.Fatal(err)
}

embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(embeddings))
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**embedding**: [`ContentEmbedding`](/api-reference/embeddings/embed-content#Resource:ContentEmbedding)

Output only. The embedding generated from the input content.

{% hr /%}

**usageMetadata**: [`EmbeddingUsageMetadata`](/api-reference/embeddings/embed-content#Resource:EmbeddingUsageMetadata)

Output only. The usage metadata for the request.

{% /section %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### ContentEmbedding {% class="hide-from-toc" id="Resource:ContentEmbedding" %}

A list of floats representing an embedding.

**Properties:**

**values**: `array (number)`

The embedding values. This is for 3P users only and will not be populated for 1P calls.

{% hr /%}

**shape**: `array (integer)`

This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]).

### TaskType {% class="hide-from-toc" id="Resource:TaskType" %}

**Possible values:**

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

### EmbedContentConfig {% class="hide-from-toc" id="Resource:EmbedContentConfig" %}

Configurations for the EmbedContent request.

**Properties:**

**title**: `string`

Optional. The title for the text.

{% hr /%}

{% details %}

{% summary %}

**taskType**: [`TaskType`](/api-reference/embeddings/embed-content#Resource:TaskType)

Optional. The task type of the embedding.

{% /summary %}

Possible values:

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

{% /details %}

{% hr /%}

**autoTruncate**: `boolean`

Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.

{% hr /%}

**outputDimensionality**: `integer`

Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

{% hr /%}

**documentOcr**: `boolean`

Optional. Whether to enable OCR for document content.

{% hr /%}

**audioTrackExtraction**: `boolean`

Optional. Whether to extract audio from video content.

### EmbeddingUsageMetadata {% class="hide-from-toc" id="Resource:EmbeddingUsageMetadata" %}

Metadata on the usage of the embedding request.

**Properties:**

**promptTokenCount**: `integer`

Output only. Number of tokens in the prompt.

{% hr /%}

{% details %}

{% summary %}

**promptTokenDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

# Embedding a batch of contents
Source: https://aistudio.google.com/api-reference/embeddings/batch-embed-contents
Description: Generates multiple embedding vectors from the input `Content` which consists of a batch of strings represented as `EmbedContentRequest` objects.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/models/{model}:batchEmbedContents`

Generates multiple embedding vectors from the input `Content` which
consists of a batch of strings represented as `EmbedContentRequest`
objects.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The model ID, for example `gemini-2.5-flash`. Forms the resource name `models/{model}`.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (EmbedContentRequest)`

Embed requests for the batch. The model in each of these requests must match the model specified `BatchEmbedContentsRequest.model`.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

{% details %}

{% summary %}

**content**: {% mark %}required{% /mark %} `Content`

The content to embed. Only the `parts.text` fields will be counted.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

**embedContentConfig**: [`EmbedContentConfig`](/api-reference/embeddings/batch-embed-contents#Resource:EmbedContentConfig)

Optional. Configuration for the EmbedContent request.

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"requests": [{
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "What is the meaning of life?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How much wood would a woodchuck chuck?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How does the brain work?"}]}, }, ]}' 2> /dev/null | grep -C 5 values
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()
texts = [
    "What is the meaning of life?",
    "How much wood would a woodchuck chuck?",
    "How does the brain work?",
]
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const texts = [
  'What is the meaning of life?',
  'How much wood would a woodchuck chuck?',
  'How does the brain work?',
];
const result = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  contents: texts,
  config: {outputDimensionality: 10},
});
console.log(result.embeddings);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

contents := []*genai.Content{
    genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    genai.NewContentFromText("How much wood would a woodchuck chuck?", genai.RoleUser),
    genai.NewContentFromText("How does the brain work?", genai.RoleUser),
}

outputDim := int32(10)
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", contents, &genai.EmbedContentConfig{
    OutputDimensionality: &outputDim,
})
if err != nil {
    log.Fatal(err)
}

embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(embeddings))
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**embeddings**: `array (`[`ContentEmbedding`](/api-reference/embeddings/batch-embed-contents#Resource:ContentEmbedding)`)`

Output only. The embeddings for each request, in the same order as provided in the batch request.

{% hr /%}

**usageMetadata**: [`EmbeddingUsageMetadata`](/api-reference/embeddings/batch-embed-contents#Resource:EmbeddingUsageMetadata)

Output only. The usage metadata for the request.

{% /section %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### ContentEmbedding {% class="hide-from-toc" id="Resource:ContentEmbedding" %}

A list of floats representing an embedding.

**Properties:**

**values**: `array (number)`

The embedding values. This is for 3P users only and will not be populated for 1P calls.

{% hr /%}

**shape**: `array (integer)`

This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]).

### TaskType {% class="hide-from-toc" id="Resource:TaskType" %}

**Possible values:**

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

### EmbedContentConfig {% class="hide-from-toc" id="Resource:EmbedContentConfig" %}

Configurations for the EmbedContent request.

**Properties:**

**title**: `string`

Optional. The title for the text.

{% hr /%}

{% details %}

{% summary %}

**taskType**: [`TaskType`](/api-reference/embeddings/batch-embed-contents#Resource:TaskType)

Optional. The task type of the embedding.

{% /summary %}

Possible values:

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

{% /details %}

{% hr /%}

**autoTruncate**: `boolean`

Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.

{% hr /%}

**outputDimensionality**: `integer`

Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

{% hr /%}

**documentOcr**: `boolean`

Optional. Whether to enable OCR for document content.

{% hr /%}

**audioTrackExtraction**: `boolean`

Optional. Whether to extract audio from video content.

### EmbeddingUsageMetadata {% class="hide-from-toc" id="Resource:EmbeddingUsageMetadata" %}

Metadata on the usage of the embedding request.

**Properties:**

**promptTokenCount**: `integer`

Output only. Number of tokens in the prompt.

{% hr /%}

{% details %}

{% summary %}

**promptTokenDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

# Creating an embedding batch
Source: https://aistudio.google.com/api-reference/embeddings/async-batch-embed-content
Description: Enqueues a batch of `EmbedContent` requests for batch processing.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/models/{model}:asyncBatchEmbedContent`

Enqueues a batch of `EmbedContent` requests for batch processing.
We have a `BatchEmbedContents` handler in `GenerativeService`, but it was
synchronized. So we name this one to be `Async` to avoid confusion.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The model ID, for example `gemini-2.5-flash`. Forms the resource name `models/{model}`.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**batch**: {% mark %}required{% /mark %} [`EmbedContentBatch`](/api-reference/embeddings/async-batch-embed-content#Resource:EmbedContentBatch)

The batch to create.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/$MODEL_ID:asyncBatchEmbedContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "batch": {
    "model": "string",
    "displayName": "string",
    "inputConfig": {
      "fileName": "string"
    }
  }
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**error**: `Status`

The error result of the operation in case of failure or cancellation.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**response**: `AsyncBatchEmbedContentResponse`

{% /summary %}

{% details %}

{% summary %}

**output**: `EmbedContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be [`EmbedContentResponse`](/api-reference/embeddings/async-batch-embed-content#Resource:EmbedContentResponse) messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedEmbedContentResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedEmbedContentResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

**response**: [`EmbedContentResponse`](/api-reference/embeddings/async-batch-embed-content#Resource:EmbedContentResponse)

Output only. The response to the request.

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.

{% hr /%}

**metadata**: [`EmbedContentBatch`](/api-reference/embeddings/async-batch-embed-content#Resource:EmbedContentBatch)

{% hr /%}

**done**: `boolean`

If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "error": {
    "code": 0,
    "message": "string",
    "details": [
      {}
    ]
  },
  "response": {
    "output": {
      "responsesFile": "string",
      "inlinedResponses": {
        "inlinedResponses": [
          {
            "error": "...",
            "response": "...",
            "metadata": "..."
          }
        ]
      }
    }
  },
  "name": "string",
  "metadata": {
    "model": "string",
    "displayName": "string",
    "inputConfig": {
      "fileName": "string",
      "requests": {
        "requests": [
          {
            "request": "...",
            "metadata": "..."
          }
        ]
      }
    },
    "name": "string",
    "output": {
      "responsesFile": "string",
      "inlinedResponses": {
        "inlinedResponses": [
          {
            "error": "...",
            "response": "...",
            "metadata": "..."
          }
        ]
      }
    },
    "createTime": "string",
    "endTime": "string",
    "updateTime": "string",
    "batchStats": {
      "requestCount": "string",
      "successfulRequestCount": "string",
      "failedRequestCount": "string",
      "pendingRequestCount": "string"
    },
    "state": "BATCH_STATE_UNSPECIFIED",
    "priority": "string"
  },
  "done": true
}
```

{% /right-column %}

{% /two-column-layout %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### EmbedContentResponse {% class="hide-from-toc" id="Resource:EmbedContentResponse" %}

The response to an `EmbedContentRequest`.

**Properties:**

**embedding**: [`ContentEmbedding`](/api-reference/embeddings/async-batch-embed-content#Resource:ContentEmbedding)

Output only. The embedding generated from the input content.

{% hr /%}

**usageMetadata**: [`EmbeddingUsageMetadata`](/api-reference/embeddings/async-batch-embed-content#Resource:EmbeddingUsageMetadata)

Output only. The usage metadata for the request.

### ContentEmbedding {% class="hide-from-toc" id="Resource:ContentEmbedding" %}

A list of floats representing an embedding.

**Properties:**

**values**: `array (number)`

The embedding values. This is for 3P users only and will not be populated for 1P calls.

{% hr /%}

**shape**: `array (integer)`

This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]).

### TaskType {% class="hide-from-toc" id="Resource:TaskType" %}

**Possible values:**

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

### EmbedContentBatch {% class="hide-from-toc" id="Resource:EmbedContentBatch" %}

A resource representing a batch of `EmbedContent` requests.

**Properties:**

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% hr /%}

**displayName**: {% mark %}required{% /mark %} `string`

The user-defined name of this batch.

{% hr /%}

{% details %}

{% summary %}

**inputConfig**: {% mark %}required{% /mark %} `InputEmbedContentConfig`

Input configuration of the instances on which batch processing are performed.

{% /summary %}

**fileName**: `string`

The name of the `File` containing the input requests.

{% details %}

{% summary %}

**requests**: `InlinedEmbedContentRequests`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (InlinedEmbedContentRequest)`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**request**: {% mark %}required{% /mark %} `EmbedContentRequest`

The request to be processed in the batch.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

{% details %}

{% summary %}

**content**: {% mark %}required{% /mark %} `Content`

The content to embed. Only the `parts.text` fields will be counted.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

**embedContentConfig**: [`EmbedContentConfig`](/api-reference/embeddings/async-batch-embed-content#Resource:EmbedContentConfig)

Optional. Configuration for the EmbedContent request.

{% /details %}

**metadata**: `object`

Optional. The metadata to be associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

Output only. Identifier. Resource name of the batch. Format: `batches/{batch_id}`.

{% hr /%}

{% details %}

{% summary %}

**output**: `EmbedContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be [`EmbedContentResponse`](/api-reference/embeddings/async-batch-embed-content#Resource:EmbedContentResponse) messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedEmbedContentResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedEmbedContentResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

**response**: [`EmbedContentResponse`](/api-reference/embeddings/async-batch-embed-content#Resource:EmbedContentResponse)

Output only. The response to the request.

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**createTime**: `string`

Output only. The time at which the batch was created.

{% hr /%}

**endTime**: `string`

Output only. The time at which the batch processing completed.

{% hr /%}

**updateTime**: `string`

Output only. The time at which the batch was last updated.

{% hr /%}

{% details %}

{% summary %}

**batchStats**: `EmbedContentBatchStats`

Output only. Stats about the batch.

{% /summary %}

**requestCount**: `string`

Output only. The number of requests in the batch.

**successfulRequestCount**: `string`

Output only. The number of requests that were successfully processed.

**failedRequestCount**: `string`

Output only. The number of requests that failed to be processed.

**pendingRequestCount**: `string`

Output only. The number of requests that are still pending processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: `BatchState`

Output only. The state of the batch.

{% /summary %}

Possible values:

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

{% /details %}

{% hr /%}

**priority**: `string`

Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.

### EmbedContentConfig {% class="hide-from-toc" id="Resource:EmbedContentConfig" %}

Configurations for the EmbedContent request.

**Properties:**

**title**: `string`

Optional. The title for the text.

{% hr /%}

{% details %}

{% summary %}

**taskType**: [`TaskType`](/api-reference/embeddings/async-batch-embed-content#Resource:TaskType)

Optional. The task type of the embedding.

{% /summary %}

Possible values:

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

{% /details %}

{% hr /%}

**autoTruncate**: `boolean`

Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.

{% hr /%}

**outputDimensionality**: `integer`

Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

{% hr /%}

**documentOcr**: `boolean`

Optional. Whether to enable OCR for document content.

{% hr /%}

**audioTrackExtraction**: `boolean`

Optional. Whether to extract audio from video content.

### EmbeddingUsageMetadata {% class="hide-from-toc" id="Resource:EmbeddingUsageMetadata" %}

Metadata on the usage of the embedding request.

**Properties:**

**promptTokenCount**: `integer`

Output only. Number of tokens in the prompt.

{% hr /%}

{% details %}

{% summary %}

**promptTokenDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

# Batch API
Source: https://aistudio.google.com/api-reference/batch-api
Description: The Gemini API supports batch APIs, which let you process multiple requests in a single call.

The Gemini API supports batch APIs, which let you process multiple requests in a single call. For more details, see the [Batch API guide](/docs/batch-api).

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Creating a content generation batch](/api-reference/batch-api/batch-generate-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:batchGenerateContent`

  Enqueues a batch of `GenerateContent` requests for batch processing.
---

* [Creating an embedding batch](/api-reference/batch-api/async-batch-embed-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:asyncBatchEmbedContent`

  Enqueues a batch of `EmbedContent` requests for batch processing.
---

* [Getting a batch](/api-reference/batch-api/get-batch)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/batches/{generateContentBatch}`

  Gets the latest state of a long-running operation.
---

* [Listing batches](/api-reference/batch-api/list-batches)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/batches`

  Lists operations that match the specified filter in the request.
---

* [Cancelling a batch](/api-reference/batch-api/cancel-batch)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/batches/{generateContentBatch}:cancel`

  Starts asynchronous cancellation on a long-running operation.
---

* [Deleting a batch](/api-reference/batch-api/delete-batch)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/batches/{generateContentBatch}`

  Deletes a long-running operation.
---

* [Updating a content generation batch](/api-reference/batch-api/update-generate-content-batch)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/batches/{generateContentBatch}:updateGenerateContentBatch`

  Updates a batch of GenerateContent requests for batch processing.
---

* [Updating an embedding batch](/api-reference/batch-api/update-embed-content-batch)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/batches/{generateContentBatch}:updateEmbedContentBatch`

  Updates a batch of EmbedContent requests for batch processing.
{% /table %}

## Resources {% id="resources" %}

### GenerateContentBatch {% id="Resource:GenerateContentBatch" %}

A resource representing a batch of `GenerateContent` requests.

**Properties:**

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% hr /%}

**displayName**: {% mark %}required{% /mark %} `string`

The user-defined name of this batch.

{% hr /%}

{% details %}

{% summary %}

**inputConfig**: {% mark %}required{% /mark %} `InputConfig`

Input configuration of the instances on which batch processing are performed.

{% /summary %}

**fileName**: `string`

The name of the `File` containing the input requests.

{% details %}

{% summary %}

**requests**: `InlinedRequests`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (InlinedRequest)`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**request**: {% mark %}required{% /mark %} `GenerateContentRequest`

The request to be processed in the batch.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% details %}

{% summary %}

**contents**: {% mark %}required{% /mark %} `array (Content)`

The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like [chat](/docs/text-generation#multi-turn-conversations), this is a repeated field that contains the conversation history and the latest request.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**systemInstruction**: `Content`

Optional. Developer set [system instruction(s)](/docs/text-generation#system-instructions). Currently, text only.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**tools**: `array (Tool)`

Optional. A list of `Tools` the `Model` may use to generate the next response. A `Tool` is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the `Model`. Supported `Tool`s are `Function` and `code_execution`. Refer to the [Function calling](/docs/function-calling) and the [Code execution](/docs/code-execution) guides to learn more.

{% /summary %}

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

{% details %}

{% summary %}

**parameters**: `Schema`

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

{% details %}

{% summary %}

**response**: `Schema`

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Tool configuration for any `Tool` specified in the request. Refer to the [Function calling guide](/docs/function-calling#function_calling_modes) for a usage example.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions.

{% /details %}

{% details %}

{% summary %}

**safetySettings**: `array (SafetySetting)`

Optional. A list of unique `SafetySetting` instances for blocking unsafe content. This will be enforced on the `GenerateContentRequest.contents` and `GenerateContentResponse.candidates`. There should not be more than one setting for each `SafetyCategory` type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each `SafetyCategory` specified in the safety_settings. If there is no `SafetySetting` for a given `SafetyCategory` provided in the list, the API will use the default safety setting for that category. Harm categories HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_CIVIC_INTEGRITY, HARM_CATEGORY_JAILBREAK are supported. Refer to the [guide](/docs/safety-settings) for detailed information on available safety settings. Also refer to the [Safety guidance](/docs/safety-guidance) to learn how to incorporate safety considerations in your AI applications.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this setting.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

Controls the probability threshold at which harm is blocked.

{% /summary %}

Possible values:

- `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: Threshold is unspecified.
- `BLOCK_LOW_AND_ABOVE`: Content with NEGLIGIBLE will be allowed.
- `BLOCK_MEDIUM_AND_ABOVE`: Content with NEGLIGIBLE and LOW will be allowed.
- `BLOCK_ONLY_HIGH`: Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
- `BLOCK_NONE`: All content will be allowed.
- `OFF`: Turn off the safety filter.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**generationConfig**: `GenerationConfig`

Optional. Configuration options for model generation and outputs.

{% /summary %}

**candidateCount**: `integer`

Optional. Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)

**stopSequences**: `array (string)`

Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a `stop_sequence`. The stop sequence will not be included as part of the response.

**maxOutputTokens**: `integer`

Optional. The maximum number of tokens to include in a response candidate. Note: The default value varies by model, see the `Model.output_token_limit` attribute of the `Model` returned from the `getModel` function.

**temperature**: `number`

Optional. Controls the randomness of the output. Note: The default value varies by model, see the `Model.temperature` attribute of the `Model` returned from the `getModel` function. Values can range from [0.0, 2.0]. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topP**: `number`

Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topK**: `integer`

Optional. The maximum number of tokens to consider when sampling. Gemini models use Top-p (nucleus) sampling or a combination of Top-k and nucleus sampling. Top-k sampling considers the set of `top_k` most probable tokens. Models running with nucleus sampling don't allow top_k setting. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**seed**: `integer`

Optional. Seed used in decoding. If not set, the request uses a randomly generated seed.

**responseMimeType**: `string`

Optional. MIME type of the generated candidate text. Supported MIME types are: `text/plain`: (default) Text output. `application/json`: JSON response in the response candidates. `text/x.enum`: ENUM as a string response in the response candidates. Refer to the [docs](/docs/file-input-methods#text-file-types) for a list of all supported text MIME types.

**responseJsonSchema**: `object`

Optional. An internal detail. Use `responseJsonSchema` rather than this field.

**presencePenalty**: `number`

Optional. Presence penalty applied to the next token's logprobs if the token has already been seen in the response. This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequency_penalty for a penalty that increases with each use. A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary. A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.

**frequencyPenalty**: `number`

Optional. Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far. A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses. Caution: A _negative_ penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the max_output_tokens limit.

**responseLogprobs**: `boolean`

Optional. If true, export the logprobs results in response.

**logprobs**: `integer`

Optional. Only valid if response_logprobs=True. This sets the number of top logprobs, including the chosen candidate, to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].

**enableEnhancedCivicAnswers**: `boolean`

Optional. Enables enhanced civic answers. It may not be available for all models.

{% details %}

{% summary %}

**responseModalities**: `array (enum (string))`

Optional. The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response. A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned. An empty list is equivalent to requesting only text.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Default value.
- `TEXT`: Indicates the model should return text.
- `IMAGE`: Indicates the model should return images.
- `AUDIO`: Indicates the model should return audio.

{% /details %}

{% details %}

{% summary %}

**speechConfig**: `SpeechConfig`

Optional. The speech generation config.

{% /summary %}

{% details %}

{% summary %}

**voiceConfig**: `VoiceConfig`

The configuration in case of single-voice output.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% details %}

{% summary %}

**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig`

Optional. The configuration for the multi-speaker setup. It is mutually exclusive with the voice_config field.

{% /summary %}

{% details %}

{% summary %}

**speakerVoiceConfigs**: {% mark %}required{% /mark %} `array (SpeakerVoiceConfig)`

All the enabled speaker voices.

{% /summary %}

**speaker**: {% mark %}required{% /mark %} `string`

The name of the speaker to use. Should be the same as in the prompt.

{% details %}

{% summary %}

**voiceConfig**: {% mark %}required{% /mark %} `VoiceConfig`

The configuration for the voice to use.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% /details %}

{% /details %}

**languageCode**: `string`

Optional. The IETF [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code that the user configured the app to use. Used for speech recognition and synthesis. Valid values are: `de-DE`, `en-AU`, `en-GB`, `en-IN`, `en-US`, `es-US`, `fr-FR`, `hi-IN`, `pt-BR`, `ar-XA`, `es-ES`, `fr-CA`, `id-ID`, `it-IT`, `ja-JP`, `tr-TR`, `vi-VN`, `bn-IN`, `gu-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `ta-IN`, `te-IN`, `nl-NL`, `ko-KR`, `cmn-CN`, `pl-PL`, `ru-RU`, and `th-TH`.

{% /details %}

{% details %}

{% summary %}

**thinkingConfig**: `ThinkingConfig`

Optional. Config for thinking features. An error will be returned if this field is set for models that don't support thinking.

{% /summary %}

**includeThoughts**: `boolean`

Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.

**thinkingBudget**: `integer`

The number of thoughts tokens that the model should generate.

{% details %}

{% summary %}

**thinkingLevel**: `enum (string)`

Optional. Controls the maximum depth of the model's internal reasoning process before it produces a response. The default value is model-dependent. Refer to the [Thinking levels guide](/docs/thinking#thinking-levels) for more details. Recommended for Gemini 3 or later models. Use with earlier models results in an error.

{% /summary %}

Possible values:

- `THINKING_LEVEL_UNSPECIFIED`: Default value.
- `MINIMAL`: Little to no thinking.
- `LOW`: Low thinking level.
- `MEDIUM`: Medium thinking level.
- `HIGH`: High thinking level.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**imageConfig**: `ImageConfig`

Optional. Config for image generation. An error will be returned if this field is set for models that don't support these config options.

{% /summary %}

**aspectRatio**: `string`

Optional. The aspect ratio of the image to generate. Supported aspect ratios: `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, or `21:9`. If not specified, the model will choose a default aspect ratio based on any reference images provided.

**imageSize**: `string`

Optional. Specifies the size of generated images. Supported values are `512`, `1K`, `2K`, `4K`. If not specified, the model will use default value `1K`.

{% /details %}

{% details %}

{% summary %}

**mediaResolution**: `enum (string)`

Optional. If specified, the media resolution specified will be used.

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low (64 tokens).
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium (256 tokens).
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high (zoomed reframing with 256 tokens).

{% /details %}

**enableAffectiveDialog**: `boolean`

Optional. If enabled, the model will detect emotions and adapt its responses accordingly.

{% details %}

{% summary %}

**responseFormat**: `ResponseFormatConfig`

Optional. Configuration for the response output format. Allows specifying output configuration per modality (text, audio, image) in a flat structure.

{% /summary %}

{% details %}

{% summary %}

**text**: `TextResponseFormat`

Optional. Text output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the text output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `APPLICATION_JSON`: JSON output format.
- `TEXT_PLAIN`: Plain text output format.

{% /details %}

**schema**: `object`

Optional. The JSON schema that the output should conform to. Only applicable when mime_type is APPLICATION_JSON.

{% /details %}

{% details %}

{% summary %}

**audio**: `AudioResponseFormat`

Optional. Audio output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the audio output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `AUDIO_MP3`: MP3 audio format.
- `AUDIO_OGG_OPUS`: OGG Opus audio format.
- `AUDIO_L16`: Raw PCM (L16) audio format.
- `AUDIO_WAV`: WAV audio format.
- `AUDIO_ALAW`: A-law audio format.
- `AUDIO_MULAW`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the audio output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Audio data is returned inline in the response.
- `URI`: Audio data is returned as a URI.

{% /details %}

**sampleRate**: `integer`

Optional. Sample rate in Hz.

**bitRate**: `integer`

Optional. Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}

**image**: `ImageResponseFormat`

Optional. Image output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the image output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_JPEG`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the image output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Image data is returned inline in the response.
- `URI`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspectRatio**: `enum (string)`

Optional. The aspect ratio for the image output.

{% /summary %}

Possible values:

- `ASPECT_RATIO_UNSPECIFIED`: Default value. This value is unused.
- `ASPECT_RATIO_ONE_BY_ONE`: 1:1 aspect ratio.
- `ASPECT_RATIO_TWO_BY_THREE`: 2:3 aspect ratio.
- `ASPECT_RATIO_THREE_BY_TWO`: 3:2 aspect ratio.
- `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 aspect ratio.
- `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 aspect ratio.
- `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 aspect ratio.
- `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 aspect ratio.
- `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 aspect ratio.
- `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 aspect ratio.
- `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 aspect ratio.
- `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**imageSize**: `enum (string)`

Optional. The size of the image output.

{% /summary %}

Possible values:

- `IMAGE_SIZE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_SIZE_FIVE_TWELVE`: 512px image size.
- `IMAGE_SIZE_ONE_K`: 1K image size.
- `IMAGE_SIZE_TWO_K`: 2K image size.
- `IMAGE_SIZE_FOUR_K`: 4K image size.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**translationConfig**: `TranslationConfig`

Optional. Config for translation.

{% /summary %}

**targetLanguageCode**: {% mark %}required{% /mark %} `string`

The target language for translation. Supported values are BCP-47 language codes (e.g. "en", "es", "fr").

**echoTargetLanguage**: `boolean`

Optional. If true, the model will generate audio when the target language is spoken, essentially it will parrot the input. If false, we will not produce audio for the target language.

{% /details %}

{% details %}

{% summary %}

**audioTranscriptionConfig**: `AudioTranscriptionConfig`

Optional. Config for audio transcription (speech recognition).

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

**cachedContent**: `string`

Optional. The name of the content [cached](/docs/caching) to use as context to serve the prediction. Format: `cachedContents/{cachedContent}`

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/batch-api#Resource:ServiceTier)

Optional. The service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

**store**: `boolean`

Optional. Configures the logging behavior for a given request. If set, it takes precedence over the project-level logging config.

**continuationToken**: `string`

Optional. An opaque continuation token used to resume generation from a previous `GenerateContent` or `StreamGenerateContent` response that stopped with `finish_reason` set to `CONTINUATION`. Note that `contents` is mandatory and must identically replicate the prompt and conversation history from the initial request when continuation token is provided in a request.

**labels**: `object`

Optional. Labels with user-defined metadata for the request. Optional. Labels must follow standard unified Cloud label requirements:

- Label keys must start with a letter.
- Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes.
- International characters are allowed.

Usage:

- Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)

{% /details %}

**metadata**: `object`

Optional. The metadata to be associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

Output only. Identifier. Resource name of the batch. Format: `batches/{batch_id}`.

{% hr /%}

{% details %}

{% summary %}

**output**: `GenerateContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be `GenerateContentResponse` messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% details %}

{% summary %}

**response**: `GenerateContentResponse`

Output only. The response to the request.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (Candidate)`

Candidate responses from the model.

{% /summary %}

**index**: `integer`

Output only. Index of the candidate in the list of response candidates.

{% details %}

{% summary %}

**content**: `Content`

Output only. Generated content returned from the model.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**finishReason**: `enum (string)`

Optional. Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating tokens.

{% /summary %}

Possible values:

- `FINISH_REASON_UNSPECIFIED`: Default value. This value is unused.
- `STOP`: Natural stop point of the model or provided stop sequence.
- `MAX_TOKENS`: The maximum number of tokens as specified in the request was reached.
- `SAFETY`: The response candidate content was flagged for safety reasons.
- `RECITATION`: The response candidate content was flagged for recitation reasons.
- `LANGUAGE`: The response candidate content was flagged for using an unsupported language.
- `OTHER`: Unknown reason.
- `BLOCKLIST`: Token generation stopped because the content contains forbidden terms.
- `PROHIBITED_CONTENT`: Token generation stopped for potentially containing prohibited content.
- `SPII`: Token generation stopped because the content potentially contains Sensitive Personally Identifiable Information (SPII).
- `MALFORMED_FUNCTION_CALL`: The function call generated by the model is invalid.
- `IMAGE_SAFETY`: Token generation stopped because generated images contain safety violations.
- `IMAGE_PROHIBITED_CONTENT`: Image generation stopped because generated images has other prohibited content.
- `IMAGE_OTHER`: Image generation stopped because of other miscellaneous issue.
- `NO_IMAGE`: The model was expected to generate an image, but none was generated.
- `IMAGE_RECITATION`: Image generation stopped due to recitation.
- `UNEXPECTED_TOOL_CALL`: Model generated a tool call but no tools were enabled in the request.
- `TOO_MANY_TOOL_CALLS`: Model called too many tools consecutively, thus the system exited execution.
- `MISSING_THOUGHT_SIGNATURE`: Request has at least one thought signature missing.
- `MALFORMED_RESPONSE`: Finished due to malformed response.
- `ESCALATION`: Request was filtered by an escalation rule.
- `PUP_LIMITED_DISABLED`: Indicates that token generation stopped because the user account is limited or disabled due to Prohibited Use Policy (PUP) violations.
- `CONTINUATION`: Token generation was stopped because the response reached the per-request token limit, but generation is not yet complete. The model response can be continued via a subsequent request using the returned `continuation_token`. Note, the `max_output_tokens` is cumulative across continuation hops and must be monotonically increased or omitted.

{% /details %}

**finishMessage**: `string`

Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when `finish_reason` is set.

{% details %}

{% summary %}

**safetyRatings**: `array (SafetyRating)`

List of ratings for the safety of a response candidate. There is at most one rating per category.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

**blocked**: `boolean`

Was this content blocked because of this rating?

{% /details %}

{% details %}

{% summary %}

**citationMetadata**: `CitationMetadata`

Output only. Citation information for model-generated candidate. This field may be populated with recitation information for any text included in the `content`. These are passages that are "recited" from copyrighted material in the foundational LLM's training data.

{% /summary %}

{% details %}

{% summary %}

**citationSources**: `array (CitationSource)`

Citations to sources for a specific response.

{% /summary %}

**startIndex**: `integer`

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

**endIndex**: `integer`

Optional. End of the attributed segment, exclusive.

**uri**: `string`

Optional. URI that is attributed as a source for a portion of the text.

**license**: `string`

Optional. License for the GitHub project that is attributed as a source for segment. License info is required for code citations.

{% /details %}

{% /details %}

**tokenCount**: `integer`

Output only. Token count for this candidate.

{% details %}

{% summary %}

**groundingAttributions**: `array (GroundingAttribution)`

Output only. Attribution information for sources that contributed to a grounded answer. This field is populated for `GenerateAnswer` calls.

{% /summary %}

{% details %}

{% summary %}

**sourceId**: `AttributionSourceId`

Output only. Identifier for the source contributing to this attribution.

{% /summary %}

{% details %}

{% summary %}

**groundingPassage**: `GroundingPassageId`

Identifier for an inline passage.

{% /summary %}

**passageId**: `string`

Output only. ID of the passage matching the `GenerateAnswerRequest`'s `GroundingPassage.id`.

**partIndex**: `integer`

Output only. Index of the part within the `GenerateAnswerRequest`'s `GroundingPassage.content`.

{% /details %}

{% details %}

{% summary %}

**semanticRetrieverChunk**: `SemanticRetrieverChunk`

Identifier for a `Chunk` fetched via Semantic Retriever.

{% /summary %}

**source**: `string`

Output only. Name of the source matching the request's `SemanticRetrieverConfig.source`. Example: `corpora/123` or `corpora/123/documents/abc`

**chunk**: `string`

Output only. Name of the `Chunk` containing the attributed text. Example: `corpora/123/documents/abc/chunks/xyz`

{% /details %}

{% /details %}

{% details %}

{% summary %}

**content**: `Content`

Grounding source content that makes up this attribution.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingMetadata**: `GroundingMetadata`

Output only. Grounding metadata for the candidate. This field is populated for `GenerateContent` calls.

{% /summary %}

{% details %}

{% summary %}

**searchEntryPoint**: `SearchEntryPoint`

Optional. Google search entry for the following-up web searches.

{% /summary %}

**renderedContent**: `string`

Optional. Web content snippet that can be embedded in a web page or an app webview.

**sdkBlob**: `string`

Optional. Base64 encoded JSON representing array of tuple.

{% /details %}

{% details %}

{% summary %}

**groundingChunks**: `array (GroundingChunk)`

List of supporting references retrieved from specified grounding source. When streaming, this only contains the grounding chunks that have not been included in the grounding metadata of previous responses.

{% /summary %}

{% details %}

{% summary %}

**web**: `Web`

Grounding chunk from the web.

{% /summary %}

**uri**: `string`

Output only. URI reference of the chunk.

**title**: `string`

Output only. Title of the chunk.

{% /details %}

{% details %}

{% summary %}

**image**: `Image`

Optional. Grounding chunk from image search.

{% /summary %}

**sourceUri**: `string`

The web page URI for attribution.

**imageUri**: `string`

The image asset URL.

**title**: `string`

The title of the web page that the image is from.

**domain**: `string`

The root domain of the web page that the image is from, e.g. "example.com".

{% /details %}

{% details %}

{% summary %}

**retrievedContext**: `RetrievedContext`

Optional. Grounding chunk from context retrieved by the file search tool.

{% /summary %}

**uri**: `string`

Optional. URI reference of the semantic retrieval document.

**title**: `string`

Optional. Title of the document.

**text**: `string`

Optional. Text of the chunk.

**fileSearchStore**: `string`

Optional. Name of the `FileSearchStore` containing the document. Example: `fileSearchStores/123`

{% details %}

{% summary %}

**customMetadata**: `array (GroundingChunkCustomMetadata)`

Optional. User-provided metadata about the retrieved context.

{% /summary %}

**stringValue**: `string`

Optional. The string value of the metadata.

{% details %}

{% summary %}

**stringListValue**: `GroundingChunkStringList`

Optional. A list of string values for the metadata.

{% /summary %}

**values**: `array (string)`

The string values of the list.

{% /details %}

**numericValue**: `number`

Optional. The numeric value of the metadata. The expected range for this value depends on the specific `key` used.

**key**: `string`

The key of the metadata.

{% /details %}

**pageNumber**: `integer`

Optional. Page number of the retrieved context, if applicable.

**mediaId**: `string`

Optional. The media blob resource name for multimodal file search results. Format: fileSearchStores/{file_search_store_id}/media/{blob_id}

{% /details %}

{% details %}

{% summary %}

**maps**: `Maps`

Optional. Grounding chunk from Google Maps.

{% /summary %}

**uri**: `string`

URI reference of the place.

**title**: `string`

Title of the place.

**text**: `string`

Text description of the place answer.

**placeId**: `string`

The ID of the place, in `places/{place_id}` format. A user can use this ID to look up that place.

{% details %}

{% summary %}

**placeAnswerSources**: `PlaceAnswerSources`

Sources that provide answers about the features of a given place in Google Maps.

{% /summary %}

{% details %}

{% summary %}

**reviewSnippets**: `array (ReviewSnippet)`

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

{% /summary %}

**reviewId**: `string`

The ID of the review snippet.

**googleMapsUri**: `string`

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

**title**: `string`

Title of the review.

{% /details %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingSupports**: `array (GoogleAiGenerativelanguageV1betaGroundingSupport)`

List of grounding support.

{% /summary %}

{% details %}

{% summary %}

**segment**: `GoogleAiGenerativelanguageV1betaSegment`

Segment of the content this support belongs to.

{% /summary %}

**partIndex**: `integer`

The index of a Part object within its parent Content object.

**startIndex**: `integer`

Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero.

**endIndex**: `integer`

End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero.

**text**: `string`

The text corresponding to the segment from the response.

{% /details %}

**groundingChunkIndices**: `array (integer)`

Optional. A list of indices (into 'grounding_chunk' in `response.candidate.grounding_metadata`) specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. If the response is streaming, the grounding_chunk_indices refer to the indices across all responses. It is the client's responsibility to accumulate the grounding chunks from all responses (while maintaining the same order).

**confidenceScores**: `array (number)`

Optional. Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices.

**renderedParts**: `array (integer)`

Output only. Indices into the `parts` field of the candidate's content. These indices specify which rendered parts are associated with this support source.

{% /details %}

{% details %}

{% summary %}

**retrievalMetadata**: `RetrievalMetadata`

Metadata related to retrieval in the grounding flow.

{% /summary %}

**googleSearchDynamicRetrievalScore**: `number`

Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger google search.

{% /details %}

**webSearchQueries**: `array (string)`

Web search queries for the following-up web search.

**imageSearchQueries**: `array (string)`

Image search queries used for grounding.

**googleMapsWidgetContextToken**: `string`

Optional. Resource name of the Google Maps widget context token that can be used with the PlacesContextElement widget in order to render contextual data. Only populated in the case that grounding with Google Maps is enabled.

{% /details %}

**avgLogprobs**: `number`

Output only. Average log probability score of the candidate.

{% details %}

{% summary %}

**logprobsResult**: `LogprobsResult`

Output only. Log-likelihood scores for the response tokens and top tokens

{% /summary %}

**logProbabilitySum**: `number`

Sum of log probabilities for all tokens.

{% details %}

{% summary %}

**topCandidates**: `array (TopCandidates)`

Length = total number of decoding steps.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (LogprobsResultCandidate)`

Sorted by log probability in descending order.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**chosenCandidates**: `array (LogprobsResultCandidate)`

Length = total number of decoding steps. The chosen candidates may or may not be in top_candidates.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContextMetadata**: `UrlContextMetadata`

Output only. Metadata related to url context retrieval tool.

{% /summary %}

{% details %}

{% summary %}

**urlMetadata**: `array (UrlMetadata)`

List of url context.

{% /summary %}

**retrievedUrl**: `string`

Retrieved url by the tool.

{% details %}

{% summary %}

**urlRetrievalStatus**: `enum (string)`

Status of the url retrieval.

{% /summary %}

Possible values:

- `URL_RETRIEVAL_STATUS_UNSPECIFIED`: Default value. This value is unused.
- `URL_RETRIEVAL_STATUS_SUCCESS`: Url retrieval is successful.
- `URL_RETRIEVAL_STATUS_ERROR`: Url retrieval is failed due to error.
- `URL_RETRIEVAL_STATUS_PAYWALL`: Url retrieval is failed because the content is behind paywall.
- `URL_RETRIEVAL_STATUS_UNSAFE`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% /details %}

**continuationToken**: `string`

An optional opaque continuation token returned when `finish_reason` is `CONTINUATION`. Clients can pass this token in a subsequent `GenerateContentRequest` to continue generation.

{% /details %}

{% details %}

{% summary %}

**promptFeedback**: `PromptFeedback`

Returns the prompt's feedback related to the content filters.

{% /summary %}

{% details %}

{% summary %}

**blockReason**: `enum (string)`

Optional. If set, the prompt was blocked and no candidates are returned. Rephrase the prompt.

{% /summary %}

Possible values:

- `BLOCK_REASON_UNSPECIFIED`: Default value. This value is unused.
- `SAFETY`: Prompt was blocked due to safety reasons. Inspect `safety_ratings` to understand which safety category blocked it.
- `OTHER`: Prompt was blocked due to unknown reasons.
- `BLOCKLIST`: Prompt was blocked due to the terms which are included from the terminology blocklist.
- `PROHIBITED_CONTENT`: Prompt was blocked due to prohibited content.
- `IMAGE_SAFETY`: Candidates blocked due to unsafe image generation content.

{% /details %}

{% details %}

{% summary %}

**safetyRatings**: `array (SafetyRating)`

Ratings for safety of the prompt. There is at most one rating per category.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

**blocked**: `boolean`

Was this content blocked because of this rating?

{% /details %}

{% /details %}

{% details %}

{% summary %}

**usageMetadata**: `UsageMetadata`

Output only. Metadata on the generation requests' token usage.

{% /summary %}

**promptTokenCount**: `integer`

Number of tokens in the prompt. When `cached_content` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content.

**cachedContentTokenCount**: `integer`

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

**candidatesTokenCount**: `integer`

Total number of tokens across all the generated response candidates.

**toolUsePromptTokenCount**: `integer`

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

**thoughtsTokenCount**: `integer`

Output only. Number of tokens of thoughts for thinking models.

**totalTokenCount**: `integer`

Total token count for the generation request (prompt + tool-use prompt + thoughts + response candidates).

{% details %}

{% summary %}

**promptTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**cacheTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities of the cached content in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**candidatesTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were returned in the response.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**toolUsePromptTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed for tool-use request inputs.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/batch-api#Resource:ServiceTier)

Output only. Service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

{% /details %}

**modelVersion**: `string`

Output only. The model version used to generate the response.

**responseId**: `string`

Output only. response_id is used to identify each response.

{% details %}

{% summary %}

**modelStatus**: `ModelStatus`

Output only. The current model status of this model.

{% /summary %}

{% details %}

{% summary %}

**modelStage**: `ModelStage`

The stage of the underlying model.

{% /summary %}

Possible values:

- `MODEL_STAGE_UNSPECIFIED`: Unspecified model stage.
- `EXPERIMENTAL`: Models in this stage are for experimental purposes only.
- `PREVIEW`: Models in this stage are more mature than experimental models.
- `STABLE`: Models in this stage are considered stable and ready for production use.
- `LEGACY`: If the model is on this stage, it means that this model is on the path to deprecation in near future. Only existing customers can use this model.
- `RETIRED`: Models in this stage are retired. These models cannot be used.

{% /details %}

**retirementTime**: `string`

The time at which the model will be retired.

**message**: `string`

A message explaining the model status.

{% /details %}

{% /details %}

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**createTime**: `string`

Output only. The time at which the batch was created.

{% hr /%}

**endTime**: `string`

Output only. The time at which the batch processing completed.

{% hr /%}

**updateTime**: `string`

Output only. The time at which the batch was last updated.

{% hr /%}

{% details %}

{% summary %}

**batchStats**: `BatchStats`

Output only. Stats about the batch.

{% /summary %}

**requestCount**: `string`

Output only. The number of requests in the batch.

**successfulRequestCount**: `string`

Output only. The number of requests that were successfully processed.

**failedRequestCount**: `string`

Output only. The number of requests that failed to be processed.

**pendingRequestCount**: `string`

Output only. The number of requests that are still pending processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: [`BatchState`](/api-reference/batch-api#Resource:BatchState)

Output only. The state of the batch.

{% /summary %}

Possible values:

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

{% /details %}

{% hr /%}

**priority**: `string`

Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.

## Data Models {% id="data-models" %}

### BatchState {% id="Resource:BatchState" %}

**Possible values:**

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

### ServiceTier {% id="Resource:ServiceTier" %}

**Possible values:**

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

# Creating a content generation batch
Source: https://aistudio.google.com/api-reference/batch-api/batch-generate-content
Description: Enqueues a batch of `GenerateContent` requests for batch processing.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/models/{model}:batchGenerateContent`

Enqueues a batch of `GenerateContent` requests for batch processing.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The model ID, for example `gemini-2.5-flash`. Forms the resource name `models/{model}`.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**batch**: {% mark %}required{% /mark %} [`GenerateContentBatch`](/api-reference/batch-api/batch-generate-content#Resource:GenerateContentBatch)

The batch to create.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/$MODEL_ID:batchGenerateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "batch": {
    "model": "string",
    "displayName": "string",
    "inputConfig": {
      "fileName": "string"
    }
  }
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**error**: `Status`

The error result of the operation in case of failure or cancellation.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**response**: `BatchGenerateContentResponse`

{% /summary %}

{% details %}

{% summary %}

**output**: `GenerateContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be `GenerateContentResponse` messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% details %}

{% summary %}

**response**: `GenerateContentResponse`

Output only. The response to the request.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (Candidate)`

Candidate responses from the model.

{% /summary %}

**index**: `integer`

Output only. Index of the candidate in the list of response candidates.

{% details %}

{% summary %}

**content**: `Content`

Output only. Generated content returned from the model.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**finishReason**: `enum (string)`

Optional. Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating tokens.

{% /summary %}

Possible values:

- `FINISH_REASON_UNSPECIFIED`: Default value. This value is unused.
- `STOP`: Natural stop point of the model or provided stop sequence.
- `MAX_TOKENS`: The maximum number of tokens as specified in the request was reached.
- `SAFETY`: The response candidate content was flagged for safety reasons.
- `RECITATION`: The response candidate content was flagged for recitation reasons.
- `LANGUAGE`: The response candidate content was flagged for using an unsupported language.
- `OTHER`: Unknown reason.
- `BLOCKLIST`: Token generation stopped because the content contains forbidden terms.
- `PROHIBITED_CONTENT`: Token generation stopped for potentially containing prohibited content.
- `SPII`: Token generation stopped because the content potentially contains Sensitive Personally Identifiable Information (SPII).
- `MALFORMED_FUNCTION_CALL`: The function call generated by the model is invalid.
- `IMAGE_SAFETY`: Token generation stopped because generated images contain safety violations.
- `IMAGE_PROHIBITED_CONTENT`: Image generation stopped because generated images has other prohibited content.
- `IMAGE_OTHER`: Image generation stopped because of other miscellaneous issue.
- `NO_IMAGE`: The model was expected to generate an image, but none was generated.
- `IMAGE_RECITATION`: Image generation stopped due to recitation.
- `UNEXPECTED_TOOL_CALL`: Model generated a tool call but no tools were enabled in the request.
- `TOO_MANY_TOOL_CALLS`: Model called too many tools consecutively, thus the system exited execution.
- `MISSING_THOUGHT_SIGNATURE`: Request has at least one thought signature missing.
- `MALFORMED_RESPONSE`: Finished due to malformed response.
- `ESCALATION`: Request was filtered by an escalation rule.
- `PUP_LIMITED_DISABLED`: Indicates that token generation stopped because the user account is limited or disabled due to Prohibited Use Policy (PUP) violations.
- `CONTINUATION`: Token generation was stopped because the response reached the per-request token limit, but generation is not yet complete. The model response can be continued via a subsequent request using the returned `continuation_token`. Note, the `max_output_tokens` is cumulative across continuation hops and must be monotonically increased or omitted.

{% /details %}

**finishMessage**: `string`

Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when `finish_reason` is set.

{% details %}

{% summary %}

**safetyRatings**: `array (SafetyRating)`

List of ratings for the safety of a response candidate. There is at most one rating per category.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

**blocked**: `boolean`

Was this content blocked because of this rating?

{% /details %}

{% details %}

{% summary %}

**citationMetadata**: `CitationMetadata`

Output only. Citation information for model-generated candidate. This field may be populated with recitation information for any text included in the `content`. These are passages that are "recited" from copyrighted material in the foundational LLM's training data.

{% /summary %}

{% details %}

{% summary %}

**citationSources**: `array (CitationSource)`

Citations to sources for a specific response.

{% /summary %}

**startIndex**: `integer`

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

**endIndex**: `integer`

Optional. End of the attributed segment, exclusive.

**uri**: `string`

Optional. URI that is attributed as a source for a portion of the text.

**license**: `string`

Optional. License for the GitHub project that is attributed as a source for segment. License info is required for code citations.

{% /details %}

{% /details %}

**tokenCount**: `integer`

Output only. Token count for this candidate.

{% details %}

{% summary %}

**groundingAttributions**: `array (GroundingAttribution)`

Output only. Attribution information for sources that contributed to a grounded answer. This field is populated for `GenerateAnswer` calls.

{% /summary %}

{% details %}

{% summary %}

**sourceId**: `AttributionSourceId`

Output only. Identifier for the source contributing to this attribution.

{% /summary %}

{% details %}

{% summary %}

**groundingPassage**: `GroundingPassageId`

Identifier for an inline passage.

{% /summary %}

**passageId**: `string`

Output only. ID of the passage matching the `GenerateAnswerRequest`'s `GroundingPassage.id`.

**partIndex**: `integer`

Output only. Index of the part within the `GenerateAnswerRequest`'s `GroundingPassage.content`.

{% /details %}

{% details %}

{% summary %}

**semanticRetrieverChunk**: `SemanticRetrieverChunk`

Identifier for a `Chunk` fetched via Semantic Retriever.

{% /summary %}

**source**: `string`

Output only. Name of the source matching the request's `SemanticRetrieverConfig.source`. Example: `corpora/123` or `corpora/123/documents/abc`

**chunk**: `string`

Output only. Name of the `Chunk` containing the attributed text. Example: `corpora/123/documents/abc/chunks/xyz`

{% /details %}

{% /details %}

{% details %}

{% summary %}

**content**: `Content`

Grounding source content that makes up this attribution.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingMetadata**: `GroundingMetadata`

Output only. Grounding metadata for the candidate. This field is populated for `GenerateContent` calls.

{% /summary %}

{% details %}

{% summary %}

**searchEntryPoint**: `SearchEntryPoint`

Optional. Google search entry for the following-up web searches.

{% /summary %}

**renderedContent**: `string`

Optional. Web content snippet that can be embedded in a web page or an app webview.

**sdkBlob**: `string`

Optional. Base64 encoded JSON representing array of tuple.

{% /details %}

{% details %}

{% summary %}

**groundingChunks**: `array (GroundingChunk)`

List of supporting references retrieved from specified grounding source. When streaming, this only contains the grounding chunks that have not been included in the grounding metadata of previous responses.

{% /summary %}

{% details %}

{% summary %}

**web**: `Web`

Grounding chunk from the web.

{% /summary %}

**uri**: `string`

Output only. URI reference of the chunk.

**title**: `string`

Output only. Title of the chunk.

{% /details %}

{% details %}

{% summary %}

**image**: `Image`

Optional. Grounding chunk from image search.

{% /summary %}

**sourceUri**: `string`

The web page URI for attribution.

**imageUri**: `string`

The image asset URL.

**title**: `string`

The title of the web page that the image is from.

**domain**: `string`

The root domain of the web page that the image is from, e.g. "example.com".

{% /details %}

{% details %}

{% summary %}

**retrievedContext**: `RetrievedContext`

Optional. Grounding chunk from context retrieved by the file search tool.

{% /summary %}

**uri**: `string`

Optional. URI reference of the semantic retrieval document.

**title**: `string`

Optional. Title of the document.

**text**: `string`

Optional. Text of the chunk.

**fileSearchStore**: `string`

Optional. Name of the `FileSearchStore` containing the document. Example: `fileSearchStores/123`

{% details %}

{% summary %}

**customMetadata**: `array (GroundingChunkCustomMetadata)`

Optional. User-provided metadata about the retrieved context.

{% /summary %}

**stringValue**: `string`

Optional. The string value of the metadata.

{% details %}

{% summary %}

**stringListValue**: `GroundingChunkStringList`

Optional. A list of string values for the metadata.

{% /summary %}

**values**: `array (string)`

The string values of the list.

{% /details %}

**numericValue**: `number`

Optional. The numeric value of the metadata. The expected range for this value depends on the specific `key` used.

**key**: `string`

The key of the metadata.

{% /details %}

**pageNumber**: `integer`

Optional. Page number of the retrieved context, if applicable.

**mediaId**: `string`

Optional. The media blob resource name for multimodal file search results. Format: fileSearchStores/{file_search_store_id}/media/{blob_id}

{% /details %}

{% details %}

{% summary %}

**maps**: `Maps`

Optional. Grounding chunk from Google Maps.

{% /summary %}

**uri**: `string`

URI reference of the place.

**title**: `string`

Title of the place.

**text**: `string`

Text description of the place answer.

**placeId**: `string`

The ID of the place, in `places/{place_id}` format. A user can use this ID to look up that place.

{% details %}

{% summary %}

**placeAnswerSources**: `PlaceAnswerSources`

Sources that provide answers about the features of a given place in Google Maps.

{% /summary %}

{% details %}

{% summary %}

**reviewSnippets**: `array (ReviewSnippet)`

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

{% /summary %}

**reviewId**: `string`

The ID of the review snippet.

**googleMapsUri**: `string`

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

**title**: `string`

Title of the review.

{% /details %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingSupports**: `array (GoogleAiGenerativelanguageV1betaGroundingSupport)`

List of grounding support.

{% /summary %}

{% details %}

{% summary %}

**segment**: `GoogleAiGenerativelanguageV1betaSegment`

Segment of the content this support belongs to.

{% /summary %}

**partIndex**: `integer`

The index of a Part object within its parent Content object.

**startIndex**: `integer`

Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero.

**endIndex**: `integer`

End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero.

**text**: `string`

The text corresponding to the segment from the response.

{% /details %}

**groundingChunkIndices**: `array (integer)`

Optional. A list of indices (into 'grounding_chunk' in `response.candidate.grounding_metadata`) specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. If the response is streaming, the grounding_chunk_indices refer to the indices across all responses. It is the client's responsibility to accumulate the grounding chunks from all responses (while maintaining the same order).

**confidenceScores**: `array (number)`

Optional. Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices.

**renderedParts**: `array (integer)`

Output only. Indices into the `parts` field of the candidate's content. These indices specify which rendered parts are associated with this support source.

{% /details %}

{% details %}

{% summary %}

**retrievalMetadata**: `RetrievalMetadata`

Metadata related to retrieval in the grounding flow.

{% /summary %}

**googleSearchDynamicRetrievalScore**: `number`

Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger google search.

{% /details %}

**webSearchQueries**: `array (string)`

Web search queries for the following-up web search.

**imageSearchQueries**: `array (string)`

Image search queries used for grounding.

**googleMapsWidgetContextToken**: `string`

Optional. Resource name of the Google Maps widget context token that can be used with the PlacesContextElement widget in order to render contextual data. Only populated in the case that grounding with Google Maps is enabled.

{% /details %}

**avgLogprobs**: `number`

Output only. Average log probability score of the candidate.

{% details %}

{% summary %}

**logprobsResult**: `LogprobsResult`

Output only. Log-likelihood scores for the response tokens and top tokens

{% /summary %}

**logProbabilitySum**: `number`

Sum of log probabilities for all tokens.

{% details %}

{% summary %}

**topCandidates**: `array (TopCandidates)`

Length = total number of decoding steps.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (LogprobsResultCandidate)`

Sorted by log probability in descending order.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**chosenCandidates**: `array (LogprobsResultCandidate)`

Length = total number of decoding steps. The chosen candidates may or may not be in top_candidates.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContextMetadata**: `UrlContextMetadata`

Output only. Metadata related to url context retrieval tool.

{% /summary %}

{% details %}

{% summary %}

**urlMetadata**: `array (UrlMetadata)`

List of url context.

{% /summary %}

**retrievedUrl**: `string`

Retrieved url by the tool.

{% details %}

{% summary %}

**urlRetrievalStatus**: `enum (string)`

Status of the url retrieval.

{% /summary %}

Possible values:

- `URL_RETRIEVAL_STATUS_UNSPECIFIED`: Default value. This value is unused.
- `URL_RETRIEVAL_STATUS_SUCCESS`: Url retrieval is successful.
- `URL_RETRIEVAL_STATUS_ERROR`: Url retrieval is failed due to error.
- `URL_RETRIEVAL_STATUS_PAYWALL`: Url retrieval is failed because the content is behind paywall.
- `URL_RETRIEVAL_STATUS_UNSAFE`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% /details %}

**continuationToken**: `string`

An optional opaque continuation token returned when `finish_reason` is `CONTINUATION`. Clients can pass this token in a subsequent `GenerateContentRequest` to continue generation.

{% /details %}

{% details %}

{% summary %}

**promptFeedback**: `PromptFeedback`

Returns the prompt's feedback related to the content filters.

{% /summary %}

{% details %}

{% summary %}

**blockReason**: `enum (string)`

Optional. If set, the prompt was blocked and no candidates are returned. Rephrase the prompt.

{% /summary %}

Possible values:

- `BLOCK_REASON_UNSPECIFIED`: Default value. This value is unused.
- `SAFETY`: Prompt was blocked due to safety reasons. Inspect `safety_ratings` to understand which safety category blocked it.
- `OTHER`: Prompt was blocked due to unknown reasons.
- `BLOCKLIST`: Prompt was blocked due to the terms which are included from the terminology blocklist.
- `PROHIBITED_CONTENT`: Prompt was blocked due to prohibited content.
- `IMAGE_SAFETY`: Candidates blocked due to unsafe image generation content.

{% /details %}

{% details %}

{% summary %}

**safetyRatings**: `array (SafetyRating)`

Ratings for safety of the prompt. There is at most one rating per category.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

**blocked**: `boolean`

Was this content blocked because of this rating?

{% /details %}

{% /details %}

{% details %}

{% summary %}

**usageMetadata**: `UsageMetadata`

Output only. Metadata on the generation requests' token usage.

{% /summary %}

**promptTokenCount**: `integer`

Number of tokens in the prompt. When `cached_content` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content.

**cachedContentTokenCount**: `integer`

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

**candidatesTokenCount**: `integer`

Total number of tokens across all the generated response candidates.

**toolUsePromptTokenCount**: `integer`

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

**thoughtsTokenCount**: `integer`

Output only. Number of tokens of thoughts for thinking models.

**totalTokenCount**: `integer`

Total token count for the generation request (prompt + tool-use prompt + thoughts + response candidates).

{% details %}

{% summary %}

**promptTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**cacheTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities of the cached content in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**candidatesTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were returned in the response.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**toolUsePromptTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed for tool-use request inputs.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/batch-api/batch-generate-content#Resource:ServiceTier)

Output only. Service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

{% /details %}

**modelVersion**: `string`

Output only. The model version used to generate the response.

**responseId**: `string`

Output only. response_id is used to identify each response.

{% details %}

{% summary %}

**modelStatus**: `ModelStatus`

Output only. The current model status of this model.

{% /summary %}

{% details %}

{% summary %}

**modelStage**: `ModelStage`

The stage of the underlying model.

{% /summary %}

Possible values:

- `MODEL_STAGE_UNSPECIFIED`: Unspecified model stage.
- `EXPERIMENTAL`: Models in this stage are for experimental purposes only.
- `PREVIEW`: Models in this stage are more mature than experimental models.
- `STABLE`: Models in this stage are considered stable and ready for production use.
- `LEGACY`: If the model is on this stage, it means that this model is on the path to deprecation in near future. Only existing customers can use this model.
- `RETIRED`: Models in this stage are retired. These models cannot be used.

{% /details %}

**retirementTime**: `string`

The time at which the model will be retired.

**message**: `string`

A message explaining the model status.

{% /details %}

{% /details %}

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.

{% hr /%}

**metadata**: [`GenerateContentBatch`](/api-reference/batch-api/batch-generate-content#Resource:GenerateContentBatch)

{% hr /%}

**done**: `boolean`

If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "error": {
    "code": 0,
    "message": "string",
    "details": [
      {}
    ]
  },
  "response": {
    "output": {
      "responsesFile": "string",
      "inlinedResponses": {
        "inlinedResponses": [
          {
            "error": "...",
            "response": "...",
            "metadata": "..."
          }
        ]
      }
    }
  },
  "name": "string",
  "metadata": {
    "model": "string",
    "displayName": "string",
    "inputConfig": {
      "fileName": "string",
      "requests": {
        "requests": [
          {
            "request": "...",
            "metadata": "..."
          }
        ]
      }
    },
    "name": "string",
    "output": {
      "responsesFile": "string",
      "inlinedResponses": {
        "inlinedResponses": [
          {
            "error": "...",
            "response": "...",
            "metadata": "..."
          }
        ]
      }
    },
    "createTime": "string",
    "endTime": "string",
    "updateTime": "string",
    "batchStats": {
      "requestCount": "string",
      "successfulRequestCount": "string",
      "failedRequestCount": "string",
      "pendingRequestCount": "string"
    },
    "state": "BATCH_STATE_UNSPECIFIED",
    "priority": "string"
  },
  "done": true
}
```

{% /right-column %}

{% /two-column-layout %}

## Resources {% class="hide-from-toc" id="resources" %}

### GenerateContentBatch {% class="hide-from-toc" id="Resource:GenerateContentBatch" %}

A resource representing a batch of `GenerateContent` requests.

**Properties:**

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% hr /%}

**displayName**: {% mark %}required{% /mark %} `string`

The user-defined name of this batch.

{% hr /%}

{% details %}

{% summary %}

**inputConfig**: {% mark %}required{% /mark %} `InputConfig`

Input configuration of the instances on which batch processing are performed.

{% /summary %}

**fileName**: `string`

The name of the `File` containing the input requests.

{% details %}

{% summary %}

**requests**: `InlinedRequests`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (InlinedRequest)`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**request**: {% mark %}required{% /mark %} `GenerateContentRequest`

The request to be processed in the batch.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% details %}

{% summary %}

**contents**: {% mark %}required{% /mark %} `array (Content)`

The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like [chat](/docs/text-generation#multi-turn-conversations), this is a repeated field that contains the conversation history and the latest request.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**systemInstruction**: `Content`

Optional. Developer set [system instruction(s)](/docs/text-generation#system-instructions). Currently, text only.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**tools**: `array (Tool)`

Optional. A list of `Tools` the `Model` may use to generate the next response. A `Tool` is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the `Model`. Supported `Tool`s are `Function` and `code_execution`. Refer to the [Function calling](/docs/function-calling) and the [Code execution](/docs/code-execution) guides to learn more.

{% /summary %}

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

{% details %}

{% summary %}

**parameters**: `Schema`

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

{% details %}

{% summary %}

**response**: `Schema`

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Tool configuration for any `Tool` specified in the request. Refer to the [Function calling guide](/docs/function-calling#function_calling_modes) for a usage example.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions.

{% /details %}

{% details %}

{% summary %}

**safetySettings**: `array (SafetySetting)`

Optional. A list of unique `SafetySetting` instances for blocking unsafe content. This will be enforced on the `GenerateContentRequest.contents` and `GenerateContentResponse.candidates`. There should not be more than one setting for each `SafetyCategory` type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each `SafetyCategory` specified in the safety_settings. If there is no `SafetySetting` for a given `SafetyCategory` provided in the list, the API will use the default safety setting for that category. Harm categories HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_CIVIC_INTEGRITY, HARM_CATEGORY_JAILBREAK are supported. Refer to the [guide](/docs/safety-settings) for detailed information on available safety settings. Also refer to the [Safety guidance](/docs/safety-guidance) to learn how to incorporate safety considerations in your AI applications.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this setting.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

Controls the probability threshold at which harm is blocked.

{% /summary %}

Possible values:

- `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: Threshold is unspecified.
- `BLOCK_LOW_AND_ABOVE`: Content with NEGLIGIBLE will be allowed.
- `BLOCK_MEDIUM_AND_ABOVE`: Content with NEGLIGIBLE and LOW will be allowed.
- `BLOCK_ONLY_HIGH`: Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
- `BLOCK_NONE`: All content will be allowed.
- `OFF`: Turn off the safety filter.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**generationConfig**: `GenerationConfig`

Optional. Configuration options for model generation and outputs.

{% /summary %}

**candidateCount**: `integer`

Optional. Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)

**stopSequences**: `array (string)`

Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a `stop_sequence`. The stop sequence will not be included as part of the response.

**maxOutputTokens**: `integer`

Optional. The maximum number of tokens to include in a response candidate. Note: The default value varies by model, see the `Model.output_token_limit` attribute of the `Model` returned from the `getModel` function.

**temperature**: `number`

Optional. Controls the randomness of the output. Note: The default value varies by model, see the `Model.temperature` attribute of the `Model` returned from the `getModel` function. Values can range from [0.0, 2.0]. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topP**: `number`

Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topK**: `integer`

Optional. The maximum number of tokens to consider when sampling. Gemini models use Top-p (nucleus) sampling or a combination of Top-k and nucleus sampling. Top-k sampling considers the set of `top_k` most probable tokens. Models running with nucleus sampling don't allow top_k setting. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**seed**: `integer`

Optional. Seed used in decoding. If not set, the request uses a randomly generated seed.

**responseMimeType**: `string`

Optional. MIME type of the generated candidate text. Supported MIME types are: `text/plain`: (default) Text output. `application/json`: JSON response in the response candidates. `text/x.enum`: ENUM as a string response in the response candidates. Refer to the [docs](/docs/file-input-methods#text-file-types) for a list of all supported text MIME types.

**responseJsonSchema**: `object`

Optional. An internal detail. Use `responseJsonSchema` rather than this field.

**presencePenalty**: `number`

Optional. Presence penalty applied to the next token's logprobs if the token has already been seen in the response. This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequency_penalty for a penalty that increases with each use. A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary. A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.

**frequencyPenalty**: `number`

Optional. Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far. A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses. Caution: A _negative_ penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the max_output_tokens limit.

**responseLogprobs**: `boolean`

Optional. If true, export the logprobs results in response.

**logprobs**: `integer`

Optional. Only valid if response_logprobs=True. This sets the number of top logprobs, including the chosen candidate, to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].

**enableEnhancedCivicAnswers**: `boolean`

Optional. Enables enhanced civic answers. It may not be available for all models.

{% details %}

{% summary %}

**responseModalities**: `array (enum (string))`

Optional. The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response. A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned. An empty list is equivalent to requesting only text.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Default value.
- `TEXT`: Indicates the model should return text.
- `IMAGE`: Indicates the model should return images.
- `AUDIO`: Indicates the model should return audio.

{% /details %}

{% details %}

{% summary %}

**speechConfig**: `SpeechConfig`

Optional. The speech generation config.

{% /summary %}

{% details %}

{% summary %}

**voiceConfig**: `VoiceConfig`

The configuration in case of single-voice output.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% details %}

{% summary %}

**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig`

Optional. The configuration for the multi-speaker setup. It is mutually exclusive with the voice_config field.

{% /summary %}

{% details %}

{% summary %}

**speakerVoiceConfigs**: {% mark %}required{% /mark %} `array (SpeakerVoiceConfig)`

All the enabled speaker voices.

{% /summary %}

**speaker**: {% mark %}required{% /mark %} `string`

The name of the speaker to use. Should be the same as in the prompt.

{% details %}

{% summary %}

**voiceConfig**: {% mark %}required{% /mark %} `VoiceConfig`

The configuration for the voice to use.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% /details %}

{% /details %}

**languageCode**: `string`

Optional. The IETF [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code that the user configured the app to use. Used for speech recognition and synthesis. Valid values are: `de-DE`, `en-AU`, `en-GB`, `en-IN`, `en-US`, `es-US`, `fr-FR`, `hi-IN`, `pt-BR`, `ar-XA`, `es-ES`, `fr-CA`, `id-ID`, `it-IT`, `ja-JP`, `tr-TR`, `vi-VN`, `bn-IN`, `gu-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `ta-IN`, `te-IN`, `nl-NL`, `ko-KR`, `cmn-CN`, `pl-PL`, `ru-RU`, and `th-TH`.

{% /details %}

{% details %}

{% summary %}

**thinkingConfig**: `ThinkingConfig`

Optional. Config for thinking features. An error will be returned if this field is set for models that don't support thinking.

{% /summary %}

**includeThoughts**: `boolean`

Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.

**thinkingBudget**: `integer`

The number of thoughts tokens that the model should generate.

{% details %}

{% summary %}

**thinkingLevel**: `enum (string)`

Optional. Controls the maximum depth of the model's internal reasoning process before it produces a response. The default value is model-dependent. Refer to the [Thinking levels guide](/docs/thinking#thinking-levels) for more details. Recommended for Gemini 3 or later models. Use with earlier models results in an error.

{% /summary %}

Possible values:

- `THINKING_LEVEL_UNSPECIFIED`: Default value.
- `MINIMAL`: Little to no thinking.
- `LOW`: Low thinking level.
- `MEDIUM`: Medium thinking level.
- `HIGH`: High thinking level.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**imageConfig**: `ImageConfig`

Optional. Config for image generation. An error will be returned if this field is set for models that don't support these config options.

{% /summary %}

**aspectRatio**: `string`

Optional. The aspect ratio of the image to generate. Supported aspect ratios: `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, or `21:9`. If not specified, the model will choose a default aspect ratio based on any reference images provided.

**imageSize**: `string`

Optional. Specifies the size of generated images. Supported values are `512`, `1K`, `2K`, `4K`. If not specified, the model will use default value `1K`.

{% /details %}

{% details %}

{% summary %}

**mediaResolution**: `enum (string)`

Optional. If specified, the media resolution specified will be used.

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low (64 tokens).
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium (256 tokens).
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high (zoomed reframing with 256 tokens).

{% /details %}

**enableAffectiveDialog**: `boolean`

Optional. If enabled, the model will detect emotions and adapt its responses accordingly.

{% details %}

{% summary %}

**responseFormat**: `ResponseFormatConfig`

Optional. Configuration for the response output format. Allows specifying output configuration per modality (text, audio, image) in a flat structure.

{% /summary %}

{% details %}

{% summary %}

**text**: `TextResponseFormat`

Optional. Text output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the text output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `APPLICATION_JSON`: JSON output format.
- `TEXT_PLAIN`: Plain text output format.

{% /details %}

**schema**: `object`

Optional. The JSON schema that the output should conform to. Only applicable when mime_type is APPLICATION_JSON.

{% /details %}

{% details %}

{% summary %}

**audio**: `AudioResponseFormat`

Optional. Audio output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the audio output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `AUDIO_MP3`: MP3 audio format.
- `AUDIO_OGG_OPUS`: OGG Opus audio format.
- `AUDIO_L16`: Raw PCM (L16) audio format.
- `AUDIO_WAV`: WAV audio format.
- `AUDIO_ALAW`: A-law audio format.
- `AUDIO_MULAW`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the audio output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Audio data is returned inline in the response.
- `URI`: Audio data is returned as a URI.

{% /details %}

**sampleRate**: `integer`

Optional. Sample rate in Hz.

**bitRate**: `integer`

Optional. Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}

**image**: `ImageResponseFormat`

Optional. Image output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the image output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_JPEG`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the image output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Image data is returned inline in the response.
- `URI`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspectRatio**: `enum (string)`

Optional. The aspect ratio for the image output.

{% /summary %}

Possible values:

- `ASPECT_RATIO_UNSPECIFIED`: Default value. This value is unused.
- `ASPECT_RATIO_ONE_BY_ONE`: 1:1 aspect ratio.
- `ASPECT_RATIO_TWO_BY_THREE`: 2:3 aspect ratio.
- `ASPECT_RATIO_THREE_BY_TWO`: 3:2 aspect ratio.
- `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 aspect ratio.
- `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 aspect ratio.
- `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 aspect ratio.
- `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 aspect ratio.
- `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 aspect ratio.
- `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 aspect ratio.
- `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 aspect ratio.
- `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**imageSize**: `enum (string)`

Optional. The size of the image output.

{% /summary %}

Possible values:

- `IMAGE_SIZE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_SIZE_FIVE_TWELVE`: 512px image size.
- `IMAGE_SIZE_ONE_K`: 1K image size.
- `IMAGE_SIZE_TWO_K`: 2K image size.
- `IMAGE_SIZE_FOUR_K`: 4K image size.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**translationConfig**: `TranslationConfig`

Optional. Config for translation.

{% /summary %}

**targetLanguageCode**: {% mark %}required{% /mark %} `string`

The target language for translation. Supported values are BCP-47 language codes (e.g. "en", "es", "fr").

**echoTargetLanguage**: `boolean`

Optional. If true, the model will generate audio when the target language is spoken, essentially it will parrot the input. If false, we will not produce audio for the target language.

{% /details %}

{% details %}

{% summary %}

**audioTranscriptionConfig**: `AudioTranscriptionConfig`

Optional. Config for audio transcription (speech recognition).

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

**cachedContent**: `string`

Optional. The name of the content [cached](/docs/caching) to use as context to serve the prediction. Format: `cachedContents/{cachedContent}`

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/batch-api/batch-generate-content#Resource:ServiceTier)

Optional. The service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

**store**: `boolean`

Optional. Configures the logging behavior for a given request. If set, it takes precedence over the project-level logging config.

**continuationToken**: `string`

Optional. An opaque continuation token used to resume generation from a previous `GenerateContent` or `StreamGenerateContent` response that stopped with `finish_reason` set to `CONTINUATION`. Note that `contents` is mandatory and must identically replicate the prompt and conversation history from the initial request when continuation token is provided in a request.

**labels**: `object`

Optional. Labels with user-defined metadata for the request. Optional. Labels must follow standard unified Cloud label requirements:

- Label keys must start with a letter.
- Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes.
- International characters are allowed.

Usage:

- Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)

{% /details %}

**metadata**: `object`

Optional. The metadata to be associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

Output only. Identifier. Resource name of the batch. Format: `batches/{batch_id}`.

{% hr /%}

{% details %}

{% summary %}

**output**: `GenerateContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be `GenerateContentResponse` messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% details %}

{% summary %}

**response**: `GenerateContentResponse`

Output only. The response to the request.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (Candidate)`

Candidate responses from the model.

{% /summary %}

**index**: `integer`

Output only. Index of the candidate in the list of response candidates.

{% details %}

{% summary %}

**content**: `Content`

Output only. Generated content returned from the model.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**finishReason**: `enum (string)`

Optional. Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating tokens.

{% /summary %}

Possible values:

- `FINISH_REASON_UNSPECIFIED`: Default value. This value is unused.
- `STOP`: Natural stop point of the model or provided stop sequence.
- `MAX_TOKENS`: The maximum number of tokens as specified in the request was reached.
- `SAFETY`: The response candidate content was flagged for safety reasons.
- `RECITATION`: The response candidate content was flagged for recitation reasons.
- `LANGUAGE`: The response candidate content was flagged for using an unsupported language.
- `OTHER`: Unknown reason.
- `BLOCKLIST`: Token generation stopped because the content contains forbidden terms.
- `PROHIBITED_CONTENT`: Token generation stopped for potentially containing prohibited content.
- `SPII`: Token generation stopped because the content potentially contains Sensitive Personally Identifiable Information (SPII).
- `MALFORMED_FUNCTION_CALL`: The function call generated by the model is invalid.
- `IMAGE_SAFETY`: Token generation stopped because generated images contain safety violations.
- `IMAGE_PROHIBITED_CONTENT`: Image generation stopped because generated images has other prohibited content.
- `IMAGE_OTHER`: Image generation stopped because of other miscellaneous issue.
- `NO_IMAGE`: The model was expected to generate an image, but none was generated.
- `IMAGE_RECITATION`: Image generation stopped due to recitation.
- `UNEXPECTED_TOOL_CALL`: Model generated a tool call but no tools were enabled in the request.
- `TOO_MANY_TOOL_CALLS`: Model called too many tools consecutively, thus the system exited execution.
- `MISSING_THOUGHT_SIGNATURE`: Request has at least one thought signature missing.
- `MALFORMED_RESPONSE`: Finished due to malformed response.
- `ESCALATION`: Request was filtered by an escalation rule.
- `PUP_LIMITED_DISABLED`: Indicates that token generation stopped because the user account is limited or disabled due to Prohibited Use Policy (PUP) violations.
- `CONTINUATION`: Token generation was stopped because the response reached the per-request token limit, but generation is not yet complete. The model response can be continued via a subsequent request using the returned `continuation_token`. Note, the `max_output_tokens` is cumulative across continuation hops and must be monotonically increased or omitted.

{% /details %}

**finishMessage**: `string`

Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when `finish_reason` is set.

{% details %}

{% summary %}

**safetyRatings**: `array (SafetyRating)`

List of ratings for the safety of a response candidate. There is at most one rating per category.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

**blocked**: `boolean`

Was this content blocked because of this rating?

{% /details %}

{% details %}

{% summary %}

**citationMetadata**: `CitationMetadata`

Output only. Citation information for model-generated candidate. This field may be populated with recitation information for any text included in the `content`. These are passages that are "recited" from copyrighted material in the foundational LLM's training data.

{% /summary %}

{% details %}

{% summary %}

**citationSources**: `array (CitationSource)`

Citations to sources for a specific response.

{% /summary %}

**startIndex**: `integer`

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

**endIndex**: `integer`

Optional. End of the attributed segment, exclusive.

**uri**: `string`

Optional. URI that is attributed as a source for a portion of the text.

**license**: `string`

Optional. License for the GitHub project that is attributed as a source for segment. License info is required for code citations.

{% /details %}

{% /details %}

**tokenCount**: `integer`

Output only. Token count for this candidate.

{% details %}

{% summary %}

**groundingAttributions**: `array (GroundingAttribution)`

Output only. Attribution information for sources that contributed to a grounded answer. This field is populated for `GenerateAnswer` calls.

{% /summary %}

{% details %}

{% summary %}

**sourceId**: `AttributionSourceId`

Output only. Identifier for the source contributing to this attribution.

{% /summary %}

{% details %}

{% summary %}

**groundingPassage**: `GroundingPassageId`

Identifier for an inline passage.

{% /summary %}

**passageId**: `string`

Output only. ID of the passage matching the `GenerateAnswerRequest`'s `GroundingPassage.id`.

**partIndex**: `integer`

Output only. Index of the part within the `GenerateAnswerRequest`'s `GroundingPassage.content`.

{% /details %}

{% details %}

{% summary %}

**semanticRetrieverChunk**: `SemanticRetrieverChunk`

Identifier for a `Chunk` fetched via Semantic Retriever.

{% /summary %}

**source**: `string`

Output only. Name of the source matching the request's `SemanticRetrieverConfig.source`. Example: `corpora/123` or `corpora/123/documents/abc`

**chunk**: `string`

Output only. Name of the `Chunk` containing the attributed text. Example: `corpora/123/documents/abc/chunks/xyz`

{% /details %}

{% /details %}

{% details %}

{% summary %}

**content**: `Content`

Grounding source content that makes up this attribution.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingMetadata**: `GroundingMetadata`

Output only. Grounding metadata for the candidate. This field is populated for `GenerateContent` calls.

{% /summary %}

{% details %}

{% summary %}

**searchEntryPoint**: `SearchEntryPoint`

Optional. Google search entry for the following-up web searches.

{% /summary %}

**renderedContent**: `string`

Optional. Web content snippet that can be embedded in a web page or an app webview.

**sdkBlob**: `string`

Optional. Base64 encoded JSON representing array of tuple.

{% /details %}

{% details %}

{% summary %}

**groundingChunks**: `array (GroundingChunk)`

List of supporting references retrieved from specified grounding source. When streaming, this only contains the grounding chunks that have not been included in the grounding metadata of previous responses.

{% /summary %}

{% details %}

{% summary %}

**web**: `Web`

Grounding chunk from the web.

{% /summary %}

**uri**: `string`

Output only. URI reference of the chunk.

**title**: `string`

Output only. Title of the chunk.

{% /details %}

{% details %}

{% summary %}

**image**: `Image`

Optional. Grounding chunk from image search.

{% /summary %}

**sourceUri**: `string`

The web page URI for attribution.

**imageUri**: `string`

The image asset URL.

**title**: `string`

The title of the web page that the image is from.

**domain**: `string`

The root domain of the web page that the image is from, e.g. "example.com".

{% /details %}

{% details %}

{% summary %}

**retrievedContext**: `RetrievedContext`

Optional. Grounding chunk from context retrieved by the file search tool.

{% /summary %}

**uri**: `string`

Optional. URI reference of the semantic retrieval document.

**title**: `string`

Optional. Title of the document.

**text**: `string`

Optional. Text of the chunk.

**fileSearchStore**: `string`

Optional. Name of the `FileSearchStore` containing the document. Example: `fileSearchStores/123`

{% details %}

{% summary %}

**customMetadata**: `array (GroundingChunkCustomMetadata)`

Optional. User-provided metadata about the retrieved context.

{% /summary %}

**stringValue**: `string`

Optional. The string value of the metadata.

{% details %}

{% summary %}

**stringListValue**: `GroundingChunkStringList`

Optional. A list of string values for the metadata.

{% /summary %}

**values**: `array (string)`

The string values of the list.

{% /details %}

**numericValue**: `number`

Optional. The numeric value of the metadata. The expected range for this value depends on the specific `key` used.

**key**: `string`

The key of the metadata.

{% /details %}

**pageNumber**: `integer`

Optional. Page number of the retrieved context, if applicable.

**mediaId**: `string`

Optional. The media blob resource name for multimodal file search results. Format: fileSearchStores/{file_search_store_id}/media/{blob_id}

{% /details %}

{% details %}

{% summary %}

**maps**: `Maps`

Optional. Grounding chunk from Google Maps.

{% /summary %}

**uri**: `string`

URI reference of the place.

**title**: `string`

Title of the place.

**text**: `string`

Text description of the place answer.

**placeId**: `string`

The ID of the place, in `places/{place_id}` format. A user can use this ID to look up that place.

{% details %}

{% summary %}

**placeAnswerSources**: `PlaceAnswerSources`

Sources that provide answers about the features of a given place in Google Maps.

{% /summary %}

{% details %}

{% summary %}

**reviewSnippets**: `array (ReviewSnippet)`

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

{% /summary %}

**reviewId**: `string`

The ID of the review snippet.

**googleMapsUri**: `string`

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

**title**: `string`

Title of the review.

{% /details %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingSupports**: `array (GoogleAiGenerativelanguageV1betaGroundingSupport)`

List of grounding support.

{% /summary %}

{% details %}

{% summary %}

**segment**: `GoogleAiGenerativelanguageV1betaSegment`

Segment of the content this support belongs to.

{% /summary %}

**partIndex**: `integer`

The index of a Part object within its parent Content object.

**startIndex**: `integer`

Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero.

**endIndex**: `integer`

End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero.

**text**: `string`

The text corresponding to the segment from the response.

{% /details %}

**groundingChunkIndices**: `array (integer)`

Optional. A list of indices (into 'grounding_chunk' in `response.candidate.grounding_metadata`) specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. If the response is streaming, the grounding_chunk_indices refer to the indices across all responses. It is the client's responsibility to accumulate the grounding chunks from all responses (while maintaining the same order).

**confidenceScores**: `array (number)`

Optional. Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices.

**renderedParts**: `array (integer)`

Output only. Indices into the `parts` field of the candidate's content. These indices specify which rendered parts are associated with this support source.

{% /details %}

{% details %}

{% summary %}

**retrievalMetadata**: `RetrievalMetadata`

Metadata related to retrieval in the grounding flow.

{% /summary %}

**googleSearchDynamicRetrievalScore**: `number`

Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger google search.

{% /details %}

**webSearchQueries**: `array (string)`

Web search queries for the following-up web search.

**imageSearchQueries**: `array (string)`

Image search queries used for grounding.

**googleMapsWidgetContextToken**: `string`

Optional. Resource name of the Google Maps widget context token that can be used with the PlacesContextElement widget in order to render contextual data. Only populated in the case that grounding with Google Maps is enabled.

{% /details %}

**avgLogprobs**: `number`

Output only. Average log probability score of the candidate.

{% details %}

{% summary %}

**logprobsResult**: `LogprobsResult`

Output only. Log-likelihood scores for the response tokens and top tokens

{% /summary %}

**logProbabilitySum**: `number`

Sum of log probabilities for all tokens.

{% details %}

{% summary %}

**topCandidates**: `array (TopCandidates)`

Length = total number of decoding steps.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (LogprobsResultCandidate)`

Sorted by log probability in descending order.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**chosenCandidates**: `array (LogprobsResultCandidate)`

Length = total number of decoding steps. The chosen candidates may or may not be in top_candidates.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContextMetadata**: `UrlContextMetadata`

Output only. Metadata related to url context retrieval tool.

{% /summary %}

{% details %}

{% summary %}

**urlMetadata**: `array (UrlMetadata)`

List of url context.

{% /summary %}

**retrievedUrl**: `string`

Retrieved url by the tool.

{% details %}

{% summary %}

**urlRetrievalStatus**: `enum (string)`

Status of the url retrieval.

{% /summary %}

Possible values:

- `URL_RETRIEVAL_STATUS_UNSPECIFIED`: Default value. This value is unused.
- `URL_RETRIEVAL_STATUS_SUCCESS`: Url retrieval is successful.
- `URL_RETRIEVAL_STATUS_ERROR`: Url retrieval is failed due to error.
- `URL_RETRIEVAL_STATUS_PAYWALL`: Url retrieval is failed because the content is behind paywall.
- `URL_RETRIEVAL_STATUS_UNSAFE`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% /details %}

**continuationToken**: `string`

An optional opaque continuation token returned when `finish_reason` is `CONTINUATION`. Clients can pass this token in a subsequent `GenerateContentRequest` to continue generation.

{% /details %}

{% details %}

{% summary %}

**promptFeedback**: `PromptFeedback`

Returns the prompt's feedback related to the content filters.

{% /summary %}

{% details %}

{% summary %}

**blockReason**: `enum (string)`

Optional. If set, the prompt was blocked and no candidates are returned. Rephrase the prompt.

{% /summary %}

Possible values:

- `BLOCK_REASON_UNSPECIFIED`: Default value. This value is unused.
- `SAFETY`: Prompt was blocked due to safety reasons. Inspect `safety_ratings` to understand which safety category blocked it.
- `OTHER`: Prompt was blocked due to unknown reasons.
- `BLOCKLIST`: Prompt was blocked due to the terms which are included from the terminology blocklist.
- `PROHIBITED_CONTENT`: Prompt was blocked due to prohibited content.
- `IMAGE_SAFETY`: Candidates blocked due to unsafe image generation content.

{% /details %}

{% details %}

{% summary %}

**safetyRatings**: `array (SafetyRating)`

Ratings for safety of the prompt. There is at most one rating per category.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

**blocked**: `boolean`

Was this content blocked because of this rating?

{% /details %}

{% /details %}

{% details %}

{% summary %}

**usageMetadata**: `UsageMetadata`

Output only. Metadata on the generation requests' token usage.

{% /summary %}

**promptTokenCount**: `integer`

Number of tokens in the prompt. When `cached_content` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content.

**cachedContentTokenCount**: `integer`

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

**candidatesTokenCount**: `integer`

Total number of tokens across all the generated response candidates.

**toolUsePromptTokenCount**: `integer`

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

**thoughtsTokenCount**: `integer`

Output only. Number of tokens of thoughts for thinking models.

**totalTokenCount**: `integer`

Total token count for the generation request (prompt + tool-use prompt + thoughts + response candidates).

{% details %}

{% summary %}

**promptTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**cacheTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities of the cached content in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**candidatesTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were returned in the response.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**toolUsePromptTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed for tool-use request inputs.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/batch-api/batch-generate-content#Resource:ServiceTier)

Output only. Service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

{% /details %}

**modelVersion**: `string`

Output only. The model version used to generate the response.

**responseId**: `string`

Output only. response_id is used to identify each response.

{% details %}

{% summary %}

**modelStatus**: `ModelStatus`

Output only. The current model status of this model.

{% /summary %}

{% details %}

{% summary %}

**modelStage**: `ModelStage`

The stage of the underlying model.

{% /summary %}

Possible values:

- `MODEL_STAGE_UNSPECIFIED`: Unspecified model stage.
- `EXPERIMENTAL`: Models in this stage are for experimental purposes only.
- `PREVIEW`: Models in this stage are more mature than experimental models.
- `STABLE`: Models in this stage are considered stable and ready for production use.
- `LEGACY`: If the model is on this stage, it means that this model is on the path to deprecation in near future. Only existing customers can use this model.
- `RETIRED`: Models in this stage are retired. These models cannot be used.

{% /details %}

**retirementTime**: `string`

The time at which the model will be retired.

**message**: `string`

A message explaining the model status.

{% /details %}

{% /details %}

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**createTime**: `string`

Output only. The time at which the batch was created.

{% hr /%}

**endTime**: `string`

Output only. The time at which the batch processing completed.

{% hr /%}

**updateTime**: `string`

Output only. The time at which the batch was last updated.

{% hr /%}

{% details %}

{% summary %}

**batchStats**: `BatchStats`

Output only. Stats about the batch.

{% /summary %}

**requestCount**: `string`

Output only. The number of requests in the batch.

**successfulRequestCount**: `string`

Output only. The number of requests that were successfully processed.

**failedRequestCount**: `string`

Output only. The number of requests that failed to be processed.

**pendingRequestCount**: `string`

Output only. The number of requests that are still pending processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: [`BatchState`](/api-reference/batch-api/batch-generate-content#Resource:BatchState)

Output only. The state of the batch.

{% /summary %}

Possible values:

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

{% /details %}

{% hr /%}

**priority**: `string`

Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.

## Data Models {% class="hide-from-toc" id="data-models" %}

### BatchState {% class="hide-from-toc" id="Resource:BatchState" %}

**Possible values:**

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

### ServiceTier {% class="hide-from-toc" id="Resource:ServiceTier" %}

**Possible values:**

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

# Creating an embedding batch
Source: https://aistudio.google.com/api-reference/batch-api/async-batch-embed-content
Description: Enqueues a batch of `EmbedContent` requests for batch processing.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/models/{model}:asyncBatchEmbedContent`

Enqueues a batch of `EmbedContent` requests for batch processing.
We have a `BatchEmbedContents` handler in `GenerativeService`, but it was
synchronized. So we name this one to be `Async` to avoid confusion.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The model ID, for example `gemini-2.5-flash`. Forms the resource name `models/{model}`.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**batch**: {% mark %}required{% /mark %} `EmbedContentBatch`

The batch to create.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

**displayName**: {% mark %}required{% /mark %} `string`

The user-defined name of this batch.

{% details %}

{% summary %}

**inputConfig**: {% mark %}required{% /mark %} `InputEmbedContentConfig`

Input configuration of the instances on which batch processing are performed.

{% /summary %}

**fileName**: `string`

The name of the `File` containing the input requests.

{% details %}

{% summary %}

**requests**: `InlinedEmbedContentRequests`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (InlinedEmbedContentRequest)`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**request**: {% mark %}required{% /mark %} `EmbedContentRequest`

The request to be processed in the batch.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

{% details %}

{% summary %}

**content**: {% mark %}required{% /mark %} `Content`

The content to embed. Only the `parts.text` fields will be counted.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**embedContentConfig**: `EmbedContentConfig`

Optional. Configuration for the EmbedContent request.

{% /summary %}

**title**: `string`

Optional. The title for the text.

{% details %}

{% summary %}

**taskType**: `TaskType`

Optional. The task type of the embedding.

{% /summary %}

Possible values:

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

{% /details %}

**autoTruncate**: `boolean`

Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.

**outputDimensionality**: `integer`

Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

**documentOcr**: `boolean`

Optional. Whether to enable OCR for document content.

**audioTrackExtraction**: `boolean`

Optional. Whether to extract audio from video content.

{% /details %}

{% /details %}

**metadata**: `object`

Optional. The metadata to be associated with the request.

{% /details %}

{% /details %}

{% /details %}

**name**: `string`

Output only. Identifier. Resource name of the batch. Format: `batches/{batch_id}`.

{% details %}

{% summary %}

**output**: `EmbedContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be `EmbedContentResponse` messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedEmbedContentResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedEmbedContentResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% details %}

{% summary %}

**response**: `EmbedContentResponse`

Output only. The response to the request.

{% /summary %}

{% details %}

{% summary %}

**embedding**: `ContentEmbedding`

Output only. The embedding generated from the input content.

{% /summary %}

**values**: `array (number)`

The embedding values. This is for 3P users only and will not be populated for 1P calls.

**shape**: `array (integer)`

This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]).

{% /details %}

{% details %}

{% summary %}

**usageMetadata**: `EmbeddingUsageMetadata`

Output only. The usage metadata for the request.

{% /summary %}

**promptTokenCount**: `integer`

Output only. Number of tokens in the prompt.

{% details %}

{% summary %}

**promptTokenDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% /details %}

{% /details %}

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

**createTime**: `string`

Output only. The time at which the batch was created.

**endTime**: `string`

Output only. The time at which the batch processing completed.

**updateTime**: `string`

Output only. The time at which the batch was last updated.

{% details %}

{% summary %}

**batchStats**: `EmbedContentBatchStats`

Output only. Stats about the batch.

{% /summary %}

**requestCount**: `string`

Output only. The number of requests in the batch.

**successfulRequestCount**: `string`

Output only. The number of requests that were successfully processed.

**failedRequestCount**: `string`

Output only. The number of requests that failed to be processed.

**pendingRequestCount**: `string`

Output only. The number of requests that are still pending processing.

{% /details %}

{% details %}

{% summary %}

**state**: [`BatchState`](/api-reference/batch-api/async-batch-embed-content#Resource:BatchState)

Output only. The state of the batch.

{% /summary %}

Possible values:

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

{% /details %}

**priority**: `string`

Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/$MODEL_ID:asyncBatchEmbedContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "batch": {
    "model": "string",
    "displayName": "string",
    "inputConfig": {
      "fileName": "string"
    }
  }
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**error**: `Status`

The error result of the operation in case of failure or cancellation.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**response**: `AsyncBatchEmbedContentResponse`

{% /summary %}

{% details %}

{% summary %}

**output**: `EmbedContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be `EmbedContentResponse` messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedEmbedContentResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedEmbedContentResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% details %}

{% summary %}

**response**: `EmbedContentResponse`

Output only. The response to the request.

{% /summary %}

{% details %}

{% summary %}

**embedding**: `ContentEmbedding`

Output only. The embedding generated from the input content.

{% /summary %}

**values**: `array (number)`

The embedding values. This is for 3P users only and will not be populated for 1P calls.

**shape**: `array (integer)`

This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]).

{% /details %}

{% details %}

{% summary %}

**usageMetadata**: `EmbeddingUsageMetadata`

Output only. The usage metadata for the request.

{% /summary %}

**promptTokenCount**: `integer`

Output only. Number of tokens in the prompt.

{% details %}

{% summary %}

**promptTokenDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% /details %}

{% /details %}

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.

{% hr /%}

{% details %}

{% summary %}

**metadata**: `EmbedContentBatch`

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

**displayName**: {% mark %}required{% /mark %} `string`

The user-defined name of this batch.

{% details %}

{% summary %}

**inputConfig**: {% mark %}required{% /mark %} `InputEmbedContentConfig`

Input configuration of the instances on which batch processing are performed.

{% /summary %}

**fileName**: `string`

The name of the `File` containing the input requests.

{% details %}

{% summary %}

**requests**: `InlinedEmbedContentRequests`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (InlinedEmbedContentRequest)`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**request**: {% mark %}required{% /mark %} `EmbedContentRequest`

The request to be processed in the batch.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

{% details %}

{% summary %}

**content**: {% mark %}required{% /mark %} `Content`

The content to embed. Only the `parts.text` fields will be counted.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**embedContentConfig**: `EmbedContentConfig`

Optional. Configuration for the EmbedContent request.

{% /summary %}

**title**: `string`

Optional. The title for the text.

{% details %}

{% summary %}

**taskType**: `TaskType`

Optional. The task type of the embedding.

{% /summary %}

Possible values:

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

{% /details %}

**autoTruncate**: `boolean`

Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.

**outputDimensionality**: `integer`

Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

**documentOcr**: `boolean`

Optional. Whether to enable OCR for document content.

**audioTrackExtraction**: `boolean`

Optional. Whether to extract audio from video content.

{% /details %}

{% /details %}

**metadata**: `object`

Optional. The metadata to be associated with the request.

{% /details %}

{% /details %}

{% /details %}

**name**: `string`

Output only. Identifier. Resource name of the batch. Format: `batches/{batch_id}`.

{% details %}

{% summary %}

**output**: `EmbedContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be `EmbedContentResponse` messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedEmbedContentResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedEmbedContentResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% details %}

{% summary %}

**response**: `EmbedContentResponse`

Output only. The response to the request.

{% /summary %}

{% details %}

{% summary %}

**embedding**: `ContentEmbedding`

Output only. The embedding generated from the input content.

{% /summary %}

**values**: `array (number)`

The embedding values. This is for 3P users only and will not be populated for 1P calls.

**shape**: `array (integer)`

This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]).

{% /details %}

{% details %}

{% summary %}

**usageMetadata**: `EmbeddingUsageMetadata`

Output only. The usage metadata for the request.

{% /summary %}

**promptTokenCount**: `integer`

Output only. Number of tokens in the prompt.

{% details %}

{% summary %}

**promptTokenDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% /details %}

{% /details %}

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

**createTime**: `string`

Output only. The time at which the batch was created.

**endTime**: `string`

Output only. The time at which the batch processing completed.

**updateTime**: `string`

Output only. The time at which the batch was last updated.

{% details %}

{% summary %}

**batchStats**: `EmbedContentBatchStats`

Output only. Stats about the batch.

{% /summary %}

**requestCount**: `string`

Output only. The number of requests in the batch.

**successfulRequestCount**: `string`

Output only. The number of requests that were successfully processed.

**failedRequestCount**: `string`

Output only. The number of requests that failed to be processed.

**pendingRequestCount**: `string`

Output only. The number of requests that are still pending processing.

{% /details %}

{% details %}

{% summary %}

**state**: [`BatchState`](/api-reference/batch-api/async-batch-embed-content#Resource:BatchState)

Output only. The state of the batch.

{% /summary %}

Possible values:

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

{% /details %}

**priority**: `string`

Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.

{% /details %}

{% hr /%}

**done**: `boolean`

If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "error": {
    "code": 0,
    "message": "string",
    "details": [
      {}
    ]
  },
  "response": {
    "output": {
      "responsesFile": "string",
      "inlinedResponses": {
        "inlinedResponses": [
          {
            "error": "...",
            "response": "...",
            "metadata": "..."
          }
        ]
      }
    }
  },
  "name": "string",
  "metadata": {
    "model": "string",
    "displayName": "string",
    "inputConfig": {
      "fileName": "string",
      "requests": {
        "requests": [
          {
            "request": "...",
            "metadata": "..."
          }
        ]
      }
    },
    "name": "string",
    "output": {
      "responsesFile": "string",
      "inlinedResponses": {
        "inlinedResponses": [
          {
            "error": "...",
            "response": "...",
            "metadata": "..."
          }
        ]
      }
    },
    "createTime": "string",
    "endTime": "string",
    "updateTime": "string",
    "batchStats": {
      "requestCount": "string",
      "successfulRequestCount": "string",
      "failedRequestCount": "string",
      "pendingRequestCount": "string"
    },
    "state": "BATCH_STATE_UNSPECIFIED",
    "priority": "string"
  },
  "done": true
}
```

{% /right-column %}

{% /two-column-layout %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### BatchState {% class="hide-from-toc" id="Resource:BatchState" %}

**Possible values:**

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

# Getting a batch
Source: https://aistudio.google.com/api-reference/batch-api/get-batch
Description: Gets the latest state of a long-running operation.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/batches/{generateContentBatch}`

Gets the latest state of a long-running operation. Clients can use this
method to poll the operation result at intervals as recommended by the API
service.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**generateContentBatch**: {% mark %}required{% /mark %} `string`

The batch ID. Forms the resource name `batches/{generateContentBatch}`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/batches/$BATCH_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**error**: `Status`

The error result of the operation in case of failure or cancellation.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% hr /%}

**response**: `object`

The normal, successful response of the operation. If the original method returns no data on success, such as `Delete`, the response is `google.protobuf.Empty`. If the original method is standard `Get`/`Create`/`Update`, the response should be the resource. For other methods, the response should have the type `XxxResponse`, where `Xxx` is the original method name. For example, if the original method name is `TakeSnapshot()`, the inferred response type is `TakeSnapshotResponse`.

{% hr /%}

**name**: `string`

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.

{% hr /%}

**metadata**: `object`

Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata. Any method that returns a long-running operation should document the metadata type, if any.

{% hr /%}

**done**: `boolean`

If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "error": {
    "code": 0,
    "message": "string",
    "details": [
      {}
    ]
  },
  "response": {},
  "name": "string",
  "metadata": {},
  "done": true
}
```

{% /right-column %}

{% /two-column-layout %}

# Listing batches
Source: https://aistudio.google.com/api-reference/batch-api/list-batches
Description: Lists operations that match the specified filter in the request.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/batches`

Lists operations that match the specified filter in the request. If the
server doesn't support this method, it returns `UNIMPLEMENTED`.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**filter**: `string`

The standard list filter.

{% hr /%}

**pageSize**: `integer`

The standard list page size.

{% hr /%}

**pageToken**: `string`

The standard list page token.

{% hr /%}

**returnPartialSuccess**: `boolean`

When set to `true`, operations that are reachable are returned as normal, and those that are unreachable are returned in the ListOperationsResponse.unreachable field. This can only be `true` when reading across collections. For example, when `parent` is set to `"projects/example/locations/-"`. This field is not supported by default and will result in an `UNIMPLEMENTED` error if set unless explicitly documented otherwise in service or product specific documentation.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET "https://generativelanguage.googleapis.com/v1beta/batches" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**operations**: `array (Operation)`

A list of operations that matches the specified filter in the request.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

The error result of the operation in case of failure or cancellation.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

**response**: `object`

The normal, successful response of the operation. If the original method returns no data on success, such as `Delete`, the response is `google.protobuf.Empty`. If the original method is standard `Get`/`Create`/`Update`, the response should be the resource. For other methods, the response should have the type `XxxResponse`, where `Xxx` is the original method name. For example, if the original method name is `TakeSnapshot()`, the inferred response type is `TakeSnapshotResponse`.

**name**: `string`

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.

**metadata**: `object`

Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata. Any method that returns a long-running operation should document the metadata type, if any.

**done**: `boolean`

If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.

{% /details %}

{% hr /%}

**nextPageToken**: `string`

The standard List next-page token.

{% hr /%}

**unreachable**: `array (string)`

Unordered list. Unreachable resources. Populated when the request sets `ListOperationsRequest.return_partial_success` and reads across collections. For example, when attempting to list all resources across all supported locations.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "operations": [
    {
      "error": {
        "code": 0,
        "message": "string",
        "details": [
          {}
        ]
      },
      "response": {},
      "name": "string",
      "metadata": {},
      "done": true
    }
  ],
  "nextPageToken": "string",
  "unreachable": [
    "string"
  ]
}
```

{% /right-column %}

{% /two-column-layout %}

# Cancelling a batch
Source: https://aistudio.google.com/api-reference/batch-api/cancel-batch
Description: Starts asynchronous cancellation on a long-running operation.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/batches/{generateContentBatch}:cancel`

Starts asynchronous cancellation on a long-running operation. The server
makes a best effort to cancel the operation, but success is not
guaranteed. If the server doesn't support this method, it returns
`google.rpc.Code.UNIMPLEMENTED`. Clients can use
Operations.GetOperation or
other methods to check whether the cancellation succeeded or whether the
operation completed despite cancellation. On successful cancellation,
the operation is not deleted; instead, it becomes an operation with
an Operation.error value with a google.rpc.Status.code of `1`,
corresponding to `Code.CANCELLED`.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**generateContentBatch**: {% mark %}required{% /mark %} `string`

The batch ID. Forms the resource name `batches/{generateContentBatch}`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/batches/$BATCH_ID:cancel" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Deleting a batch
Source: https://aistudio.google.com/api-reference/batch-api/delete-batch
Description: Deletes a long-running operation.

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/batches/{generateContentBatch}`

Deletes a long-running operation. This method indicates that the client is
no longer interested in the operation result. It does not cancel the
operation. If the server doesn't support this method, it returns
`google.rpc.Code.UNIMPLEMENTED`.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**generateContentBatch**: {% mark %}required{% /mark %} `string`

The batch ID. Forms the resource name `batches/{generateContentBatch}`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/batches/$BATCH_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Updating a content generation batch
Source: https://aistudio.google.com/api-reference/batch-api/update-generate-content-batch
Description: Updates a batch of GenerateContent requests for batch processing.

{% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/batches/{generateContentBatch}:updateGenerateContentBatch`

Updates a batch of GenerateContent requests for batch processing.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**generateContentBatch**: {% mark %}required{% /mark %} `string`

The batch ID. Forms the resource name `batches/{generateContentBatch}`.

{% hr /%}

**updateMask**: `string`

Optional. The list of fields to update.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% hr /%}

**displayName**: {% mark %}required{% /mark %} `string`

The user-defined name of this batch.

{% hr /%}

{% details %}

{% summary %}

**inputConfig**: {% mark %}required{% /mark %} `InputConfig`

Input configuration of the instances on which batch processing are performed.

{% /summary %}

**fileName**: `string`

The name of the `File` containing the input requests.

{% details %}

{% summary %}

**requests**: `InlinedRequests`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (InlinedRequest)`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**request**: {% mark %}required{% /mark %} `GenerateContentRequest`

The request to be processed in the batch.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% details %}

{% summary %}

**contents**: {% mark %}required{% /mark %} `array (Content)`

The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like [chat](/docs/text-generation#multi-turn-conversations), this is a repeated field that contains the conversation history and the latest request.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**systemInstruction**: `Content`

Optional. Developer set [system instruction(s)](/docs/text-generation#system-instructions). Currently, text only.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**tools**: `array (Tool)`

Optional. A list of `Tools` the `Model` may use to generate the next response. A `Tool` is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the `Model`. Supported `Tool`s are `Function` and `code_execution`. Refer to the [Function calling](/docs/function-calling) and the [Code execution](/docs/code-execution) guides to learn more.

{% /summary %}

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

{% details %}

{% summary %}

**parameters**: `Schema`

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

{% details %}

{% summary %}

**response**: `Schema`

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Tool configuration for any `Tool` specified in the request. Refer to the [Function calling guide](/docs/function-calling#function_calling_modes) for a usage example.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions.

{% /details %}

{% details %}

{% summary %}

**safetySettings**: `array (SafetySetting)`

Optional. A list of unique `SafetySetting` instances for blocking unsafe content. This will be enforced on the `GenerateContentRequest.contents` and `GenerateContentResponse.candidates`. There should not be more than one setting for each `SafetyCategory` type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each `SafetyCategory` specified in the safety_settings. If there is no `SafetySetting` for a given `SafetyCategory` provided in the list, the API will use the default safety setting for that category. Harm categories HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_CIVIC_INTEGRITY, HARM_CATEGORY_JAILBREAK are supported. Refer to the [guide](/docs/safety-settings) for detailed information on available safety settings. Also refer to the [Safety guidance](/docs/safety-guidance) to learn how to incorporate safety considerations in your AI applications.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this setting.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

Controls the probability threshold at which harm is blocked.

{% /summary %}

Possible values:

- `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: Threshold is unspecified.
- `BLOCK_LOW_AND_ABOVE`: Content with NEGLIGIBLE will be allowed.
- `BLOCK_MEDIUM_AND_ABOVE`: Content with NEGLIGIBLE and LOW will be allowed.
- `BLOCK_ONLY_HIGH`: Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
- `BLOCK_NONE`: All content will be allowed.
- `OFF`: Turn off the safety filter.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**generationConfig**: `GenerationConfig`

Optional. Configuration options for model generation and outputs.

{% /summary %}

**candidateCount**: `integer`

Optional. Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)

**stopSequences**: `array (string)`

Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a `stop_sequence`. The stop sequence will not be included as part of the response.

**maxOutputTokens**: `integer`

Optional. The maximum number of tokens to include in a response candidate. Note: The default value varies by model, see the `Model.output_token_limit` attribute of the `Model` returned from the `getModel` function.

**temperature**: `number`

Optional. Controls the randomness of the output. Note: The default value varies by model, see the `Model.temperature` attribute of the `Model` returned from the `getModel` function. Values can range from [0.0, 2.0]. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topP**: `number`

Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topK**: `integer`

Optional. The maximum number of tokens to consider when sampling. Gemini models use Top-p (nucleus) sampling or a combination of Top-k and nucleus sampling. Top-k sampling considers the set of `top_k` most probable tokens. Models running with nucleus sampling don't allow top_k setting. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**seed**: `integer`

Optional. Seed used in decoding. If not set, the request uses a randomly generated seed.

**responseMimeType**: `string`

Optional. MIME type of the generated candidate text. Supported MIME types are: `text/plain`: (default) Text output. `application/json`: JSON response in the response candidates. `text/x.enum`: ENUM as a string response in the response candidates. Refer to the [docs](/docs/file-input-methods#text-file-types) for a list of all supported text MIME types.

**responseJsonSchema**: `object`

Optional. An internal detail. Use `responseJsonSchema` rather than this field.

**presencePenalty**: `number`

Optional. Presence penalty applied to the next token's logprobs if the token has already been seen in the response. This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequency_penalty for a penalty that increases with each use. A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary. A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.

**frequencyPenalty**: `number`

Optional. Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far. A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses. Caution: A _negative_ penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the max_output_tokens limit.

**responseLogprobs**: `boolean`

Optional. If true, export the logprobs results in response.

**logprobs**: `integer`

Optional. Only valid if response_logprobs=True. This sets the number of top logprobs, including the chosen candidate, to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].

**enableEnhancedCivicAnswers**: `boolean`

Optional. Enables enhanced civic answers. It may not be available for all models.

{% details %}

{% summary %}

**responseModalities**: `array (enum (string))`

Optional. The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response. A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned. An empty list is equivalent to requesting only text.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Default value.
- `TEXT`: Indicates the model should return text.
- `IMAGE`: Indicates the model should return images.
- `AUDIO`: Indicates the model should return audio.

{% /details %}

{% details %}

{% summary %}

**speechConfig**: `SpeechConfig`

Optional. The speech generation config.

{% /summary %}

{% details %}

{% summary %}

**voiceConfig**: `VoiceConfig`

The configuration in case of single-voice output.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% details %}

{% summary %}

**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig`

Optional. The configuration for the multi-speaker setup. It is mutually exclusive with the voice_config field.

{% /summary %}

{% details %}

{% summary %}

**speakerVoiceConfigs**: {% mark %}required{% /mark %} `array (SpeakerVoiceConfig)`

All the enabled speaker voices.

{% /summary %}

**speaker**: {% mark %}required{% /mark %} `string`

The name of the speaker to use. Should be the same as in the prompt.

{% details %}

{% summary %}

**voiceConfig**: {% mark %}required{% /mark %} `VoiceConfig`

The configuration for the voice to use.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% /details %}

{% /details %}

**languageCode**: `string`

Optional. The IETF [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code that the user configured the app to use. Used for speech recognition and synthesis. Valid values are: `de-DE`, `en-AU`, `en-GB`, `en-IN`, `en-US`, `es-US`, `fr-FR`, `hi-IN`, `pt-BR`, `ar-XA`, `es-ES`, `fr-CA`, `id-ID`, `it-IT`, `ja-JP`, `tr-TR`, `vi-VN`, `bn-IN`, `gu-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `ta-IN`, `te-IN`, `nl-NL`, `ko-KR`, `cmn-CN`, `pl-PL`, `ru-RU`, and `th-TH`.

{% /details %}

{% details %}

{% summary %}

**thinkingConfig**: `ThinkingConfig`

Optional. Config for thinking features. An error will be returned if this field is set for models that don't support thinking.

{% /summary %}

**includeThoughts**: `boolean`

Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.

**thinkingBudget**: `integer`

The number of thoughts tokens that the model should generate.

{% details %}

{% summary %}

**thinkingLevel**: `enum (string)`

Optional. Controls the maximum depth of the model's internal reasoning process before it produces a response. The default value is model-dependent. Refer to the [Thinking levels guide](/docs/thinking#thinking-levels) for more details. Recommended for Gemini 3 or later models. Use with earlier models results in an error.

{% /summary %}

Possible values:

- `THINKING_LEVEL_UNSPECIFIED`: Default value.
- `MINIMAL`: Little to no thinking.
- `LOW`: Low thinking level.
- `MEDIUM`: Medium thinking level.
- `HIGH`: High thinking level.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**imageConfig**: `ImageConfig`

Optional. Config for image generation. An error will be returned if this field is set for models that don't support these config options.

{% /summary %}

**aspectRatio**: `string`

Optional. The aspect ratio of the image to generate. Supported aspect ratios: `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, or `21:9`. If not specified, the model will choose a default aspect ratio based on any reference images provided.

**imageSize**: `string`

Optional. Specifies the size of generated images. Supported values are `512`, `1K`, `2K`, `4K`. If not specified, the model will use default value `1K`.

{% /details %}

{% details %}

{% summary %}

**mediaResolution**: `enum (string)`

Optional. If specified, the media resolution specified will be used.

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low (64 tokens).
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium (256 tokens).
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high (zoomed reframing with 256 tokens).

{% /details %}

**enableAffectiveDialog**: `boolean`

Optional. If enabled, the model will detect emotions and adapt its responses accordingly.

{% details %}

{% summary %}

**responseFormat**: `ResponseFormatConfig`

Optional. Configuration for the response output format. Allows specifying output configuration per modality (text, audio, image) in a flat structure.

{% /summary %}

{% details %}

{% summary %}

**text**: `TextResponseFormat`

Optional. Text output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the text output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `APPLICATION_JSON`: JSON output format.
- `TEXT_PLAIN`: Plain text output format.

{% /details %}

**schema**: `object`

Optional. The JSON schema that the output should conform to. Only applicable when mime_type is APPLICATION_JSON.

{% /details %}

{% details %}

{% summary %}

**audio**: `AudioResponseFormat`

Optional. Audio output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the audio output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `AUDIO_MP3`: MP3 audio format.
- `AUDIO_OGG_OPUS`: OGG Opus audio format.
- `AUDIO_L16`: Raw PCM (L16) audio format.
- `AUDIO_WAV`: WAV audio format.
- `AUDIO_ALAW`: A-law audio format.
- `AUDIO_MULAW`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the audio output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Audio data is returned inline in the response.
- `URI`: Audio data is returned as a URI.

{% /details %}

**sampleRate**: `integer`

Optional. Sample rate in Hz.

**bitRate**: `integer`

Optional. Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}

**image**: `ImageResponseFormat`

Optional. Image output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the image output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_JPEG`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the image output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Image data is returned inline in the response.
- `URI`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspectRatio**: `enum (string)`

Optional. The aspect ratio for the image output.

{% /summary %}

Possible values:

- `ASPECT_RATIO_UNSPECIFIED`: Default value. This value is unused.
- `ASPECT_RATIO_ONE_BY_ONE`: 1:1 aspect ratio.
- `ASPECT_RATIO_TWO_BY_THREE`: 2:3 aspect ratio.
- `ASPECT_RATIO_THREE_BY_TWO`: 3:2 aspect ratio.
- `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 aspect ratio.
- `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 aspect ratio.
- `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 aspect ratio.
- `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 aspect ratio.
- `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 aspect ratio.
- `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 aspect ratio.
- `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 aspect ratio.
- `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**imageSize**: `enum (string)`

Optional. The size of the image output.

{% /summary %}

Possible values:

- `IMAGE_SIZE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_SIZE_FIVE_TWELVE`: 512px image size.
- `IMAGE_SIZE_ONE_K`: 1K image size.
- `IMAGE_SIZE_TWO_K`: 2K image size.
- `IMAGE_SIZE_FOUR_K`: 4K image size.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**translationConfig**: `TranslationConfig`

Optional. Config for translation.

{% /summary %}

**targetLanguageCode**: {% mark %}required{% /mark %} `string`

The target language for translation. Supported values are BCP-47 language codes (e.g. "en", "es", "fr").

**echoTargetLanguage**: `boolean`

Optional. If true, the model will generate audio when the target language is spoken, essentially it will parrot the input. If false, we will not produce audio for the target language.

{% /details %}

{% details %}

{% summary %}

**audioTranscriptionConfig**: `AudioTranscriptionConfig`

Optional. Config for audio transcription (speech recognition).

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

**cachedContent**: `string`

Optional. The name of the content [cached](/docs/caching) to use as context to serve the prediction. Format: `cachedContents/{cachedContent}`

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/batch-api/update-generate-content-batch#Resource:ServiceTier)

Optional. The service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

**store**: `boolean`

Optional. Configures the logging behavior for a given request. If set, it takes precedence over the project-level logging config.

**continuationToken**: `string`

Optional. An opaque continuation token used to resume generation from a previous `GenerateContent` or `StreamGenerateContent` response that stopped with `finish_reason` set to `CONTINUATION`. Note that `contents` is mandatory and must identically replicate the prompt and conversation history from the initial request when continuation token is provided in a request.

**labels**: `object`

Optional. Labels with user-defined metadata for the request. Optional. Labels must follow standard unified Cloud label requirements:

- Label keys must start with a letter.
- Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes.
- International characters are allowed.

Usage:

- Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)

{% /details %}

**metadata**: `object`

Optional. The metadata to be associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**priority**: `string`

Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/batches/$BATCH_ID:updateGenerateContentBatch" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "string",
  "displayName": "string",
  "inputConfig": {
    "fileName": "string"
  }
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% hr /%}

**displayName**: {% mark %}required{% /mark %} `string`

The user-defined name of this batch.

{% hr /%}

{% details %}

{% summary %}

**inputConfig**: {% mark %}required{% /mark %} `InputConfig`

Input configuration of the instances on which batch processing are performed.

{% /summary %}

**fileName**: `string`

The name of the `File` containing the input requests.

{% details %}

{% summary %}

**requests**: `InlinedRequests`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (InlinedRequest)`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**request**: {% mark %}required{% /mark %} `GenerateContentRequest`

The request to be processed in the batch.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% details %}

{% summary %}

**contents**: {% mark %}required{% /mark %} `array (Content)`

The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like [chat](/docs/text-generation#multi-turn-conversations), this is a repeated field that contains the conversation history and the latest request.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**systemInstruction**: `Content`

Optional. Developer set [system instruction(s)](/docs/text-generation#system-instructions). Currently, text only.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**tools**: `array (Tool)`

Optional. A list of `Tools` the `Model` may use to generate the next response. A `Tool` is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the `Model`. Supported `Tool`s are `Function` and `code_execution`. Refer to the [Function calling](/docs/function-calling) and the [Code execution](/docs/code-execution) guides to learn more.

{% /summary %}

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

{% details %}

{% summary %}

**parameters**: `Schema`

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

{% details %}

{% summary %}

**response**: `Schema`

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Tool configuration for any `Tool` specified in the request. Refer to the [Function calling guide](/docs/function-calling#function_calling_modes) for a usage example.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions.

{% /details %}

{% details %}

{% summary %}

**safetySettings**: `array (SafetySetting)`

Optional. A list of unique `SafetySetting` instances for blocking unsafe content. This will be enforced on the `GenerateContentRequest.contents` and `GenerateContentResponse.candidates`. There should not be more than one setting for each `SafetyCategory` type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each `SafetyCategory` specified in the safety_settings. If there is no `SafetySetting` for a given `SafetyCategory` provided in the list, the API will use the default safety setting for that category. Harm categories HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_CIVIC_INTEGRITY, HARM_CATEGORY_JAILBREAK are supported. Refer to the [guide](/docs/safety-settings) for detailed information on available safety settings. Also refer to the [Safety guidance](/docs/safety-guidance) to learn how to incorporate safety considerations in your AI applications.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this setting.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

Controls the probability threshold at which harm is blocked.

{% /summary %}

Possible values:

- `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: Threshold is unspecified.
- `BLOCK_LOW_AND_ABOVE`: Content with NEGLIGIBLE will be allowed.
- `BLOCK_MEDIUM_AND_ABOVE`: Content with NEGLIGIBLE and LOW will be allowed.
- `BLOCK_ONLY_HIGH`: Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
- `BLOCK_NONE`: All content will be allowed.
- `OFF`: Turn off the safety filter.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**generationConfig**: `GenerationConfig`

Optional. Configuration options for model generation and outputs.

{% /summary %}

**candidateCount**: `integer`

Optional. Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)

**stopSequences**: `array (string)`

Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a `stop_sequence`. The stop sequence will not be included as part of the response.

**maxOutputTokens**: `integer`

Optional. The maximum number of tokens to include in a response candidate. Note: The default value varies by model, see the `Model.output_token_limit` attribute of the `Model` returned from the `getModel` function.

**temperature**: `number`

Optional. Controls the randomness of the output. Note: The default value varies by model, see the `Model.temperature` attribute of the `Model` returned from the `getModel` function. Values can range from [0.0, 2.0]. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topP**: `number`

Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topK**: `integer`

Optional. The maximum number of tokens to consider when sampling. Gemini models use Top-p (nucleus) sampling or a combination of Top-k and nucleus sampling. Top-k sampling considers the set of `top_k` most probable tokens. Models running with nucleus sampling don't allow top_k setting. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**seed**: `integer`

Optional. Seed used in decoding. If not set, the request uses a randomly generated seed.

**responseMimeType**: `string`

Optional. MIME type of the generated candidate text. Supported MIME types are: `text/plain`: (default) Text output. `application/json`: JSON response in the response candidates. `text/x.enum`: ENUM as a string response in the response candidates. Refer to the [docs](/docs/file-input-methods#text-file-types) for a list of all supported text MIME types.

**responseJsonSchema**: `object`

Optional. An internal detail. Use `responseJsonSchema` rather than this field.

**presencePenalty**: `number`

Optional. Presence penalty applied to the next token's logprobs if the token has already been seen in the response. This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequency_penalty for a penalty that increases with each use. A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary. A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.

**frequencyPenalty**: `number`

Optional. Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far. A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses. Caution: A _negative_ penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the max_output_tokens limit.

**responseLogprobs**: `boolean`

Optional. If true, export the logprobs results in response.

**logprobs**: `integer`

Optional. Only valid if response_logprobs=True. This sets the number of top logprobs, including the chosen candidate, to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].

**enableEnhancedCivicAnswers**: `boolean`

Optional. Enables enhanced civic answers. It may not be available for all models.

{% details %}

{% summary %}

**responseModalities**: `array (enum (string))`

Optional. The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response. A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned. An empty list is equivalent to requesting only text.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Default value.
- `TEXT`: Indicates the model should return text.
- `IMAGE`: Indicates the model should return images.
- `AUDIO`: Indicates the model should return audio.

{% /details %}

{% details %}

{% summary %}

**speechConfig**: `SpeechConfig`

Optional. The speech generation config.

{% /summary %}

{% details %}

{% summary %}

**voiceConfig**: `VoiceConfig`

The configuration in case of single-voice output.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% details %}

{% summary %}

**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig`

Optional. The configuration for the multi-speaker setup. It is mutually exclusive with the voice_config field.

{% /summary %}

{% details %}

{% summary %}

**speakerVoiceConfigs**: {% mark %}required{% /mark %} `array (SpeakerVoiceConfig)`

All the enabled speaker voices.

{% /summary %}

**speaker**: {% mark %}required{% /mark %} `string`

The name of the speaker to use. Should be the same as in the prompt.

{% details %}

{% summary %}

**voiceConfig**: {% mark %}required{% /mark %} `VoiceConfig`

The configuration for the voice to use.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% /details %}

{% /details %}

**languageCode**: `string`

Optional. The IETF [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code that the user configured the app to use. Used for speech recognition and synthesis. Valid values are: `de-DE`, `en-AU`, `en-GB`, `en-IN`, `en-US`, `es-US`, `fr-FR`, `hi-IN`, `pt-BR`, `ar-XA`, `es-ES`, `fr-CA`, `id-ID`, `it-IT`, `ja-JP`, `tr-TR`, `vi-VN`, `bn-IN`, `gu-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `ta-IN`, `te-IN`, `nl-NL`, `ko-KR`, `cmn-CN`, `pl-PL`, `ru-RU`, and `th-TH`.

{% /details %}

{% details %}

{% summary %}

**thinkingConfig**: `ThinkingConfig`

Optional. Config for thinking features. An error will be returned if this field is set for models that don't support thinking.

{% /summary %}

**includeThoughts**: `boolean`

Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.

**thinkingBudget**: `integer`

The number of thoughts tokens that the model should generate.

{% details %}

{% summary %}

**thinkingLevel**: `enum (string)`

Optional. Controls the maximum depth of the model's internal reasoning process before it produces a response. The default value is model-dependent. Refer to the [Thinking levels guide](/docs/thinking#thinking-levels) for more details. Recommended for Gemini 3 or later models. Use with earlier models results in an error.

{% /summary %}

Possible values:

- `THINKING_LEVEL_UNSPECIFIED`: Default value.
- `MINIMAL`: Little to no thinking.
- `LOW`: Low thinking level.
- `MEDIUM`: Medium thinking level.
- `HIGH`: High thinking level.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**imageConfig**: `ImageConfig`

Optional. Config for image generation. An error will be returned if this field is set for models that don't support these config options.

{% /summary %}

**aspectRatio**: `string`

Optional. The aspect ratio of the image to generate. Supported aspect ratios: `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, or `21:9`. If not specified, the model will choose a default aspect ratio based on any reference images provided.

**imageSize**: `string`

Optional. Specifies the size of generated images. Supported values are `512`, `1K`, `2K`, `4K`. If not specified, the model will use default value `1K`.

{% /details %}

{% details %}

{% summary %}

**mediaResolution**: `enum (string)`

Optional. If specified, the media resolution specified will be used.

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low (64 tokens).
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium (256 tokens).
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high (zoomed reframing with 256 tokens).

{% /details %}

**enableAffectiveDialog**: `boolean`

Optional. If enabled, the model will detect emotions and adapt its responses accordingly.

{% details %}

{% summary %}

**responseFormat**: `ResponseFormatConfig`

Optional. Configuration for the response output format. Allows specifying output configuration per modality (text, audio, image) in a flat structure.

{% /summary %}

{% details %}

{% summary %}

**text**: `TextResponseFormat`

Optional. Text output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the text output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `APPLICATION_JSON`: JSON output format.
- `TEXT_PLAIN`: Plain text output format.

{% /details %}

**schema**: `object`

Optional. The JSON schema that the output should conform to. Only applicable when mime_type is APPLICATION_JSON.

{% /details %}

{% details %}

{% summary %}

**audio**: `AudioResponseFormat`

Optional. Audio output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the audio output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `AUDIO_MP3`: MP3 audio format.
- `AUDIO_OGG_OPUS`: OGG Opus audio format.
- `AUDIO_L16`: Raw PCM (L16) audio format.
- `AUDIO_WAV`: WAV audio format.
- `AUDIO_ALAW`: A-law audio format.
- `AUDIO_MULAW`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the audio output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Audio data is returned inline in the response.
- `URI`: Audio data is returned as a URI.

{% /details %}

**sampleRate**: `integer`

Optional. Sample rate in Hz.

**bitRate**: `integer`

Optional. Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}

**image**: `ImageResponseFormat`

Optional. Image output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the image output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_JPEG`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the image output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Image data is returned inline in the response.
- `URI`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspectRatio**: `enum (string)`

Optional. The aspect ratio for the image output.

{% /summary %}

Possible values:

- `ASPECT_RATIO_UNSPECIFIED`: Default value. This value is unused.
- `ASPECT_RATIO_ONE_BY_ONE`: 1:1 aspect ratio.
- `ASPECT_RATIO_TWO_BY_THREE`: 2:3 aspect ratio.
- `ASPECT_RATIO_THREE_BY_TWO`: 3:2 aspect ratio.
- `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 aspect ratio.
- `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 aspect ratio.
- `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 aspect ratio.
- `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 aspect ratio.
- `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 aspect ratio.
- `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 aspect ratio.
- `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 aspect ratio.
- `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**imageSize**: `enum (string)`

Optional. The size of the image output.

{% /summary %}

Possible values:

- `IMAGE_SIZE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_SIZE_FIVE_TWELVE`: 512px image size.
- `IMAGE_SIZE_ONE_K`: 1K image size.
- `IMAGE_SIZE_TWO_K`: 2K image size.
- `IMAGE_SIZE_FOUR_K`: 4K image size.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**translationConfig**: `TranslationConfig`

Optional. Config for translation.

{% /summary %}

**targetLanguageCode**: {% mark %}required{% /mark %} `string`

The target language for translation. Supported values are BCP-47 language codes (e.g. "en", "es", "fr").

**echoTargetLanguage**: `boolean`

Optional. If true, the model will generate audio when the target language is spoken, essentially it will parrot the input. If false, we will not produce audio for the target language.

{% /details %}

{% details %}

{% summary %}

**audioTranscriptionConfig**: `AudioTranscriptionConfig`

Optional. Config for audio transcription (speech recognition).

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

**cachedContent**: `string`

Optional. The name of the content [cached](/docs/caching) to use as context to serve the prediction. Format: `cachedContents/{cachedContent}`

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/batch-api/update-generate-content-batch#Resource:ServiceTier)

Optional. The service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

**store**: `boolean`

Optional. Configures the logging behavior for a given request. If set, it takes precedence over the project-level logging config.

**continuationToken**: `string`

Optional. An opaque continuation token used to resume generation from a previous `GenerateContent` or `StreamGenerateContent` response that stopped with `finish_reason` set to `CONTINUATION`. Note that `contents` is mandatory and must identically replicate the prompt and conversation history from the initial request when continuation token is provided in a request.

**labels**: `object`

Optional. Labels with user-defined metadata for the request. Optional. Labels must follow standard unified Cloud label requirements:

- Label keys must start with a letter.
- Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes.
- International characters are allowed.

Usage:

- Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)

{% /details %}

**metadata**: `object`

Optional. The metadata to be associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

Output only. Identifier. Resource name of the batch. Format: `batches/{batch_id}`.

{% hr /%}

{% details %}

{% summary %}

**output**: `GenerateContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be `GenerateContentResponse` messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% details %}

{% summary %}

**response**: `GenerateContentResponse`

Output only. The response to the request.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (Candidate)`

Candidate responses from the model.

{% /summary %}

**index**: `integer`

Output only. Index of the candidate in the list of response candidates.

{% details %}

{% summary %}

**content**: `Content`

Output only. Generated content returned from the model.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**finishReason**: `enum (string)`

Optional. Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating tokens.

{% /summary %}

Possible values:

- `FINISH_REASON_UNSPECIFIED`: Default value. This value is unused.
- `STOP`: Natural stop point of the model or provided stop sequence.
- `MAX_TOKENS`: The maximum number of tokens as specified in the request was reached.
- `SAFETY`: The response candidate content was flagged for safety reasons.
- `RECITATION`: The response candidate content was flagged for recitation reasons.
- `LANGUAGE`: The response candidate content was flagged for using an unsupported language.
- `OTHER`: Unknown reason.
- `BLOCKLIST`: Token generation stopped because the content contains forbidden terms.
- `PROHIBITED_CONTENT`: Token generation stopped for potentially containing prohibited content.
- `SPII`: Token generation stopped because the content potentially contains Sensitive Personally Identifiable Information (SPII).
- `MALFORMED_FUNCTION_CALL`: The function call generated by the model is invalid.
- `IMAGE_SAFETY`: Token generation stopped because generated images contain safety violations.
- `IMAGE_PROHIBITED_CONTENT`: Image generation stopped because generated images has other prohibited content.
- `IMAGE_OTHER`: Image generation stopped because of other miscellaneous issue.
- `NO_IMAGE`: The model was expected to generate an image, but none was generated.
- `IMAGE_RECITATION`: Image generation stopped due to recitation.
- `UNEXPECTED_TOOL_CALL`: Model generated a tool call but no tools were enabled in the request.
- `TOO_MANY_TOOL_CALLS`: Model called too many tools consecutively, thus the system exited execution.
- `MISSING_THOUGHT_SIGNATURE`: Request has at least one thought signature missing.
- `MALFORMED_RESPONSE`: Finished due to malformed response.
- `ESCALATION`: Request was filtered by an escalation rule.
- `PUP_LIMITED_DISABLED`: Indicates that token generation stopped because the user account is limited or disabled due to Prohibited Use Policy (PUP) violations.
- `CONTINUATION`: Token generation was stopped because the response reached the per-request token limit, but generation is not yet complete. The model response can be continued via a subsequent request using the returned `continuation_token`. Note, the `max_output_tokens` is cumulative across continuation hops and must be monotonically increased or omitted.

{% /details %}

**finishMessage**: `string`

Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when `finish_reason` is set.

{% details %}

{% summary %}

**safetyRatings**: `array (SafetyRating)`

List of ratings for the safety of a response candidate. There is at most one rating per category.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

**blocked**: `boolean`

Was this content blocked because of this rating?

{% /details %}

{% details %}

{% summary %}

**citationMetadata**: `CitationMetadata`

Output only. Citation information for model-generated candidate. This field may be populated with recitation information for any text included in the `content`. These are passages that are "recited" from copyrighted material in the foundational LLM's training data.

{% /summary %}

{% details %}

{% summary %}

**citationSources**: `array (CitationSource)`

Citations to sources for a specific response.

{% /summary %}

**startIndex**: `integer`

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

**endIndex**: `integer`

Optional. End of the attributed segment, exclusive.

**uri**: `string`

Optional. URI that is attributed as a source for a portion of the text.

**license**: `string`

Optional. License for the GitHub project that is attributed as a source for segment. License info is required for code citations.

{% /details %}

{% /details %}

**tokenCount**: `integer`

Output only. Token count for this candidate.

{% details %}

{% summary %}

**groundingAttributions**: `array (GroundingAttribution)`

Output only. Attribution information for sources that contributed to a grounded answer. This field is populated for `GenerateAnswer` calls.

{% /summary %}

{% details %}

{% summary %}

**sourceId**: `AttributionSourceId`

Output only. Identifier for the source contributing to this attribution.

{% /summary %}

{% details %}

{% summary %}

**groundingPassage**: `GroundingPassageId`

Identifier for an inline passage.

{% /summary %}

**passageId**: `string`

Output only. ID of the passage matching the `GenerateAnswerRequest`'s `GroundingPassage.id`.

**partIndex**: `integer`

Output only. Index of the part within the `GenerateAnswerRequest`'s `GroundingPassage.content`.

{% /details %}

{% details %}

{% summary %}

**semanticRetrieverChunk**: `SemanticRetrieverChunk`

Identifier for a `Chunk` fetched via Semantic Retriever.

{% /summary %}

**source**: `string`

Output only. Name of the source matching the request's `SemanticRetrieverConfig.source`. Example: `corpora/123` or `corpora/123/documents/abc`

**chunk**: `string`

Output only. Name of the `Chunk` containing the attributed text. Example: `corpora/123/documents/abc/chunks/xyz`

{% /details %}

{% /details %}

{% details %}

{% summary %}

**content**: `Content`

Grounding source content that makes up this attribution.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingMetadata**: `GroundingMetadata`

Output only. Grounding metadata for the candidate. This field is populated for `GenerateContent` calls.

{% /summary %}

{% details %}

{% summary %}

**searchEntryPoint**: `SearchEntryPoint`

Optional. Google search entry for the following-up web searches.

{% /summary %}

**renderedContent**: `string`

Optional. Web content snippet that can be embedded in a web page or an app webview.

**sdkBlob**: `string`

Optional. Base64 encoded JSON representing array of tuple.

{% /details %}

{% details %}

{% summary %}

**groundingChunks**: `array (GroundingChunk)`

List of supporting references retrieved from specified grounding source. When streaming, this only contains the grounding chunks that have not been included in the grounding metadata of previous responses.

{% /summary %}

{% details %}

{% summary %}

**web**: `Web`

Grounding chunk from the web.

{% /summary %}

**uri**: `string`

Output only. URI reference of the chunk.

**title**: `string`

Output only. Title of the chunk.

{% /details %}

{% details %}

{% summary %}

**image**: `Image`

Optional. Grounding chunk from image search.

{% /summary %}

**sourceUri**: `string`

The web page URI for attribution.

**imageUri**: `string`

The image asset URL.

**title**: `string`

The title of the web page that the image is from.

**domain**: `string`

The root domain of the web page that the image is from, e.g. "example.com".

{% /details %}

{% details %}

{% summary %}

**retrievedContext**: `RetrievedContext`

Optional. Grounding chunk from context retrieved by the file search tool.

{% /summary %}

**uri**: `string`

Optional. URI reference of the semantic retrieval document.

**title**: `string`

Optional. Title of the document.

**text**: `string`

Optional. Text of the chunk.

**fileSearchStore**: `string`

Optional. Name of the `FileSearchStore` containing the document. Example: `fileSearchStores/123`

{% details %}

{% summary %}

**customMetadata**: `array (GroundingChunkCustomMetadata)`

Optional. User-provided metadata about the retrieved context.

{% /summary %}

**stringValue**: `string`

Optional. The string value of the metadata.

{% details %}

{% summary %}

**stringListValue**: `GroundingChunkStringList`

Optional. A list of string values for the metadata.

{% /summary %}

**values**: `array (string)`

The string values of the list.

{% /details %}

**numericValue**: `number`

Optional. The numeric value of the metadata. The expected range for this value depends on the specific `key` used.

**key**: `string`

The key of the metadata.

{% /details %}

**pageNumber**: `integer`

Optional. Page number of the retrieved context, if applicable.

**mediaId**: `string`

Optional. The media blob resource name for multimodal file search results. Format: fileSearchStores/{file_search_store_id}/media/{blob_id}

{% /details %}

{% details %}

{% summary %}

**maps**: `Maps`

Optional. Grounding chunk from Google Maps.

{% /summary %}

**uri**: `string`

URI reference of the place.

**title**: `string`

Title of the place.

**text**: `string`

Text description of the place answer.

**placeId**: `string`

The ID of the place, in `places/{place_id}` format. A user can use this ID to look up that place.

{% details %}

{% summary %}

**placeAnswerSources**: `PlaceAnswerSources`

Sources that provide answers about the features of a given place in Google Maps.

{% /summary %}

{% details %}

{% summary %}

**reviewSnippets**: `array (ReviewSnippet)`

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

{% /summary %}

**reviewId**: `string`

The ID of the review snippet.

**googleMapsUri**: `string`

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

**title**: `string`

Title of the review.

{% /details %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**groundingSupports**: `array (GoogleAiGenerativelanguageV1betaGroundingSupport)`

List of grounding support.

{% /summary %}

{% details %}

{% summary %}

**segment**: `GoogleAiGenerativelanguageV1betaSegment`

Segment of the content this support belongs to.

{% /summary %}

**partIndex**: `integer`

The index of a Part object within its parent Content object.

**startIndex**: `integer`

Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero.

**endIndex**: `integer`

End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero.

**text**: `string`

The text corresponding to the segment from the response.

{% /details %}

**groundingChunkIndices**: `array (integer)`

Optional. A list of indices (into 'grounding_chunk' in `response.candidate.grounding_metadata`) specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. If the response is streaming, the grounding_chunk_indices refer to the indices across all responses. It is the client's responsibility to accumulate the grounding chunks from all responses (while maintaining the same order).

**confidenceScores**: `array (number)`

Optional. Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices.

**renderedParts**: `array (integer)`

Output only. Indices into the `parts` field of the candidate's content. These indices specify which rendered parts are associated with this support source.

{% /details %}

{% details %}

{% summary %}

**retrievalMetadata**: `RetrievalMetadata`

Metadata related to retrieval in the grounding flow.

{% /summary %}

**googleSearchDynamicRetrievalScore**: `number`

Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger google search.

{% /details %}

**webSearchQueries**: `array (string)`

Web search queries for the following-up web search.

**imageSearchQueries**: `array (string)`

Image search queries used for grounding.

**googleMapsWidgetContextToken**: `string`

Optional. Resource name of the Google Maps widget context token that can be used with the PlacesContextElement widget in order to render contextual data. Only populated in the case that grounding with Google Maps is enabled.

{% /details %}

**avgLogprobs**: `number`

Output only. Average log probability score of the candidate.

{% details %}

{% summary %}

**logprobsResult**: `LogprobsResult`

Output only. Log-likelihood scores for the response tokens and top tokens

{% /summary %}

**logProbabilitySum**: `number`

Sum of log probabilities for all tokens.

{% details %}

{% summary %}

**topCandidates**: `array (TopCandidates)`

Length = total number of decoding steps.

{% /summary %}

{% details %}

{% summary %}

**candidates**: `array (LogprobsResultCandidate)`

Sorted by log probability in descending order.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**chosenCandidates**: `array (LogprobsResultCandidate)`

Length = total number of decoding steps. The chosen candidates may or may not be in top_candidates.

{% /summary %}

**token**: `string`

The candidate’s token string value.

**tokenId**: `integer`

The candidate’s token id value.

**logProbability**: `number`

The candidate's log probability.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContextMetadata**: `UrlContextMetadata`

Output only. Metadata related to url context retrieval tool.

{% /summary %}

{% details %}

{% summary %}

**urlMetadata**: `array (UrlMetadata)`

List of url context.

{% /summary %}

**retrievedUrl**: `string`

Retrieved url by the tool.

{% details %}

{% summary %}

**urlRetrievalStatus**: `enum (string)`

Status of the url retrieval.

{% /summary %}

Possible values:

- `URL_RETRIEVAL_STATUS_UNSPECIFIED`: Default value. This value is unused.
- `URL_RETRIEVAL_STATUS_SUCCESS`: Url retrieval is successful.
- `URL_RETRIEVAL_STATUS_ERROR`: Url retrieval is failed due to error.
- `URL_RETRIEVAL_STATUS_PAYWALL`: Url retrieval is failed because the content is behind paywall.
- `URL_RETRIEVAL_STATUS_UNSAFE`: Url retrieval is failed because the content is unsafe.

{% /details %}

{% /details %}

{% /details %}

**continuationToken**: `string`

An optional opaque continuation token returned when `finish_reason` is `CONTINUATION`. Clients can pass this token in a subsequent `GenerateContentRequest` to continue generation.

{% /details %}

{% details %}

{% summary %}

**promptFeedback**: `PromptFeedback`

Returns the prompt's feedback related to the content filters.

{% /summary %}

{% details %}

{% summary %}

**blockReason**: `enum (string)`

Optional. If set, the prompt was blocked and no candidates are returned. Rephrase the prompt.

{% /summary %}

Possible values:

- `BLOCK_REASON_UNSPECIFIED`: Default value. This value is unused.
- `SAFETY`: Prompt was blocked due to safety reasons. Inspect `safety_ratings` to understand which safety category blocked it.
- `OTHER`: Prompt was blocked due to unknown reasons.
- `BLOCKLIST`: Prompt was blocked due to the terms which are included from the terminology blocklist.
- `PROHIBITED_CONTENT`: Prompt was blocked due to prohibited content.
- `IMAGE_SAFETY`: Candidates blocked due to unsafe image generation content.

{% /details %}

{% details %}

{% summary %}

**safetyRatings**: `array (SafetyRating)`

Ratings for safety of the prompt. There is at most one rating per category.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this rating.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**probability**: {% mark %}required{% /mark %} `enum (string)`

The probability of harm for this content.

{% /summary %}

Possible values:

- `HARM_PROBABILITY_UNSPECIFIED`: Probability is unspecified.
- `NEGLIGIBLE`: Content has a negligible chance of being unsafe.
- `LOW`: Content has a low chance of being unsafe.
- `MEDIUM`: Content has a medium chance of being unsafe.
- `HIGH`: Content has a high chance of being unsafe.

{% /details %}

**blocked**: `boolean`

Was this content blocked because of this rating?

{% /details %}

{% /details %}

{% details %}

{% summary %}

**usageMetadata**: `UsageMetadata`

Output only. Metadata on the generation requests' token usage.

{% /summary %}

**promptTokenCount**: `integer`

Number of tokens in the prompt. When `cached_content` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content.

**cachedContentTokenCount**: `integer`

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

**candidatesTokenCount**: `integer`

Total number of tokens across all the generated response candidates.

**toolUsePromptTokenCount**: `integer`

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

**thoughtsTokenCount**: `integer`

Output only. Number of tokens of thoughts for thinking models.

**totalTokenCount**: `integer`

Total token count for the generation request (prompt + tool-use prompt + thoughts + response candidates).

{% details %}

{% summary %}

**promptTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**cacheTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities of the cached content in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**candidatesTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were returned in the response.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**toolUsePromptTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed for tool-use request inputs.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% details %}

{% summary %}

**serviceTier**: [`ServiceTier`](/api-reference/batch-api/update-generate-content-batch#Resource:ServiceTier)

Output only. Service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

{% /details %}

**modelVersion**: `string`

Output only. The model version used to generate the response.

**responseId**: `string`

Output only. response_id is used to identify each response.

{% details %}

{% summary %}

**modelStatus**: `ModelStatus`

Output only. The current model status of this model.

{% /summary %}

{% details %}

{% summary %}

**modelStage**: `ModelStage`

The stage of the underlying model.

{% /summary %}

Possible values:

- `MODEL_STAGE_UNSPECIFIED`: Unspecified model stage.
- `EXPERIMENTAL`: Models in this stage are for experimental purposes only.
- `PREVIEW`: Models in this stage are more mature than experimental models.
- `STABLE`: Models in this stage are considered stable and ready for production use.
- `LEGACY`: If the model is on this stage, it means that this model is on the path to deprecation in near future. Only existing customers can use this model.
- `RETIRED`: Models in this stage are retired. These models cannot be used.

{% /details %}

**retirementTime**: `string`

The time at which the model will be retired.

**message**: `string`

A message explaining the model status.

{% /details %}

{% /details %}

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**createTime**: `string`

Output only. The time at which the batch was created.

{% hr /%}

**endTime**: `string`

Output only. The time at which the batch processing completed.

{% hr /%}

**updateTime**: `string`

Output only. The time at which the batch was last updated.

{% hr /%}

{% details %}

{% summary %}

**batchStats**: `BatchStats`

Output only. Stats about the batch.

{% /summary %}

**requestCount**: `string`

Output only. The number of requests in the batch.

**successfulRequestCount**: `string`

Output only. The number of requests that were successfully processed.

**failedRequestCount**: `string`

Output only. The number of requests that failed to be processed.

**pendingRequestCount**: `string`

Output only. The number of requests that are still pending processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: [`BatchState`](/api-reference/batch-api/update-generate-content-batch#Resource:BatchState)

Output only. The state of the batch.

{% /summary %}

Possible values:

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

{% /details %}

{% hr /%}

**priority**: `string`

Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "model": "string",
  "displayName": "string",
  "inputConfig": {
    "fileName": "string",
    "requests": {
      "requests": [
        {
          "request": {
            "model": "...",
            "contents": "...",
            "systemInstruction": "...",
            "tools": "...",
            "toolConfig": "...",
            "safetySettings": "...",
            "generationConfig": "...",
            "cachedContent": "...",
            "serviceTier": "...",
            "store": "...",
            "continuationToken": "...",
            "labels": "..."
          },
          "metadata": {}
        }
      ]
    }
  },
  "name": "string",
  "output": {
    "responsesFile": "string",
    "inlinedResponses": {
      "inlinedResponses": [
        {
          "error": {
            "code": "...",
            "message": "...",
            "details": "..."
          },
          "response": {
            "candidates": "...",
            "promptFeedback": "...",
            "usageMetadata": "...",
            "modelVersion": "...",
            "responseId": "...",
            "modelStatus": "..."
          },
          "metadata": {}
        }
      ]
    }
  },
  "createTime": "string",
  "endTime": "string",
  "updateTime": "string",
  "batchStats": {
    "requestCount": "string",
    "successfulRequestCount": "string",
    "failedRequestCount": "string",
    "pendingRequestCount": "string"
  },
  "state": "BATCH_STATE_UNSPECIFIED",
  "priority": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### BatchState {% class="hide-from-toc" id="Resource:BatchState" %}

**Possible values:**

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

### ServiceTier {% class="hide-from-toc" id="Resource:ServiceTier" %}

**Possible values:**

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

# Updating an embedding batch
Source: https://aistudio.google.com/api-reference/batch-api/update-embed-content-batch
Description: Updates a batch of EmbedContent requests for batch processing.

{% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/batches/{generateContentBatch}:updateEmbedContentBatch`

Updates a batch of EmbedContent requests for batch processing.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**generateContentBatch**: {% mark %}required{% /mark %} `string`

The batch ID. Forms the resource name `batches/{generateContentBatch}`.

{% hr /%}

**updateMask**: `string`

Optional. The list of fields to update.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% hr /%}

**displayName**: {% mark %}required{% /mark %} `string`

The user-defined name of this batch.

{% hr /%}

{% details %}

{% summary %}

**inputConfig**: {% mark %}required{% /mark %} `InputEmbedContentConfig`

Input configuration of the instances on which batch processing are performed.

{% /summary %}

**fileName**: `string`

The name of the `File` containing the input requests.

{% details %}

{% summary %}

**requests**: `InlinedEmbedContentRequests`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (InlinedEmbedContentRequest)`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**request**: {% mark %}required{% /mark %} `EmbedContentRequest`

The request to be processed in the batch.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

{% details %}

{% summary %}

**content**: {% mark %}required{% /mark %} `Content`

The content to embed. Only the `parts.text` fields will be counted.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**embedContentConfig**: `EmbedContentConfig`

Optional. Configuration for the EmbedContent request.

{% /summary %}

**title**: `string`

Optional. The title for the text.

{% details %}

{% summary %}

**taskType**: `TaskType`

Optional. The task type of the embedding.

{% /summary %}

Possible values:

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

{% /details %}

**autoTruncate**: `boolean`

Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.

**outputDimensionality**: `integer`

Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

**documentOcr**: `boolean`

Optional. Whether to enable OCR for document content.

**audioTrackExtraction**: `boolean`

Optional. Whether to extract audio from video content.

{% /details %}

{% /details %}

**metadata**: `object`

Optional. The metadata to be associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**priority**: `string`

Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/batches/$BATCH_ID:updateEmbedContentBatch" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "string",
  "displayName": "string",
  "inputConfig": {
    "fileName": "string"
  }
}'
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}

{% left-column %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% hr /%}

**displayName**: {% mark %}required{% /mark %} `string`

The user-defined name of this batch.

{% hr /%}

{% details %}

{% summary %}

**inputConfig**: {% mark %}required{% /mark %} `InputEmbedContentConfig`

Input configuration of the instances on which batch processing are performed.

{% /summary %}

**fileName**: `string`

The name of the `File` containing the input requests.

{% details %}

{% summary %}

**requests**: `InlinedEmbedContentRequests`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**requests**: {% mark %}required{% /mark %} `array (InlinedEmbedContentRequest)`

The requests to be processed in the batch.

{% /summary %}

{% details %}

{% summary %}

**request**: {% mark %}required{% /mark %} `EmbedContentRequest`

The request to be processed in the batch.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

{% details %}

{% summary %}

**content**: {% mark %}required{% /mark %} `Content`

The content to embed. Only the `parts.text` fields will be counted.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**embedContentConfig**: `EmbedContentConfig`

Optional. Configuration for the EmbedContent request.

{% /summary %}

**title**: `string`

Optional. The title for the text.

{% details %}

{% summary %}

**taskType**: `TaskType`

Optional. The task type of the embedding.

{% /summary %}

Possible values:

- `TASK_TYPE_UNSPECIFIED`: Unset value, which will default to one of the other enum values.
- `RETRIEVAL_QUERY`: Specifies the given text is a query in a search/retrieval setting.
- `RETRIEVAL_DOCUMENT`: Specifies the given text is a document from the corpus being searched.
- `SEMANTIC_SIMILARITY`: Specifies the given text will be used for STS.
- `CLASSIFICATION`: Specifies that the given text will be classified.
- `CLUSTERING`: Specifies that the embeddings will be used for clustering.
- `QUESTION_ANSWERING`: Specifies that the given text will be used for question answering.
- `FACT_VERIFICATION`: Specifies that the given text will be used for fact verification.
- `CODE_RETRIEVAL_QUERY`: Specifies that the given text will be used for code retrieval.

{% /details %}

**autoTruncate**: `boolean`

Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.

**outputDimensionality**: `integer`

Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

**documentOcr**: `boolean`

Optional. Whether to enable OCR for document content.

**audioTrackExtraction**: `boolean`

Optional. Whether to extract audio from video content.

{% /details %}

{% /details %}

**metadata**: `object`

Optional. The metadata to be associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**name**: `string`

Output only. Identifier. Resource name of the batch. Format: `batches/{batch_id}`.

{% hr /%}

{% details %}

{% summary %}

**output**: `EmbedContentBatchOutput`

Output only. The output of the batch request.

{% /summary %}

**responsesFile**: `string`

Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be `EmbedContentResponse` messages formatted as JSON. The responses will be written in the same order as the input requests.

{% details %}

{% summary %}

**inlinedResponses**: `InlinedEmbedContentResponses`

Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.

{% /summary %}

{% details %}

{% summary %}

**inlinedResponses**: `array (InlinedEmbedContentResponse)`

Output only. The responses to the requests in the batch.

{% /summary %}

{% details %}

{% summary %}

**error**: `Status`

Output only. The error encountered while processing the request.

{% /summary %}

**code**: `integer`

The status code, which should be an enum value of google.rpc.Code.

**message**: `string`

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

**details**: `array (object)`

A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /details %}

{% details %}

{% summary %}

**response**: `EmbedContentResponse`

Output only. The response to the request.

{% /summary %}

{% details %}

{% summary %}

**embedding**: `ContentEmbedding`

Output only. The embedding generated from the input content.

{% /summary %}

**values**: `array (number)`

The embedding values. This is for 3P users only and will not be populated for 1P calls.

**shape**: `array (integer)`

This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]).

{% /details %}

{% details %}

{% summary %}

**usageMetadata**: `EmbeddingUsageMetadata`

Output only. The usage metadata for the request.

{% /summary %}

**promptTokenCount**: `integer`

Output only. Number of tokens in the prompt.

{% details %}

{% summary %}

**promptTokenDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% /details %}

{% /details %}

**metadata**: `object`

Output only. The metadata associated with the request.

{% /details %}

{% /details %}

{% /details %}

{% hr /%}

**createTime**: `string`

Output only. The time at which the batch was created.

{% hr /%}

**endTime**: `string`

Output only. The time at which the batch processing completed.

{% hr /%}

**updateTime**: `string`

Output only. The time at which the batch was last updated.

{% hr /%}

{% details %}

{% summary %}

**batchStats**: `EmbedContentBatchStats`

Output only. Stats about the batch.

{% /summary %}

**requestCount**: `string`

Output only. The number of requests in the batch.

**successfulRequestCount**: `string`

Output only. The number of requests that were successfully processed.

**failedRequestCount**: `string`

Output only. The number of requests that failed to be processed.

**pendingRequestCount**: `string`

Output only. The number of requests that are still pending processing.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**state**: [`BatchState`](/api-reference/batch-api/update-embed-content-batch#Resource:BatchState)

Output only. The state of the batch.

{% /summary %}

Possible values:

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

{% /details %}

{% hr /%}

**priority**: `string`

Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example response** {% class="example-heading" %}

```json
{
  "model": "string",
  "displayName": "string",
  "inputConfig": {
    "fileName": "string",
    "requests": {
      "requests": [
        {
          "request": {
            "model": "...",
            "content": "...",
            "embedContentConfig": "..."
          },
          "metadata": {}
        }
      ]
    }
  },
  "name": "string",
  "output": {
    "responsesFile": "string",
    "inlinedResponses": {
      "inlinedResponses": [
        {
          "error": {
            "code": "...",
            "message": "...",
            "details": "..."
          },
          "response": {
            "embedding": "...",
            "usageMetadata": "..."
          },
          "metadata": {}
        }
      ]
    }
  },
  "createTime": "string",
  "endTime": "string",
  "updateTime": "string",
  "batchStats": {
    "requestCount": "string",
    "successfulRequestCount": "string",
    "failedRequestCount": "string",
    "pendingRequestCount": "string"
  },
  "state": "BATCH_STATE_UNSPECIFIED",
  "priority": "string"
}
```

{% /right-column %}

{% /two-column-layout %}

## Data Models {% class="hide-from-toc" id="data-models" %}

### BatchState {% class="hide-from-toc" id="Resource:BatchState" %}

**Possible values:**

- `BATCH_STATE_UNSPECIFIED`: The batch state is unspecified.
- `BATCH_STATE_PENDING`: The service is preparing to run the batch.
- `BATCH_STATE_RUNNING`: The batch is in progress.
- `BATCH_STATE_SUCCEEDED`: The batch completed successfully.
- `BATCH_STATE_FAILED`: The batch failed.
- `BATCH_STATE_CANCELLED`: The batch has been cancelled.
- `BATCH_STATE_EXPIRED`: The batch has expired.

# Counting tokens
Source: https://aistudio.google.com/api-reference/tokens
Description: For a detailed guide on counting tokens using the Gemini API, including how images, audio and video are counted, see the [Token counting guide](/docs/tokens) and accompanying [Cookbook recipe](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Counting_Tokens.ipynb).

For a detailed guide on counting tokens using the Gemini API, including how images, audio and video are counted, see the [Token counting guide](/docs/tokens) and accompanying [Cookbook recipe](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Counting_Tokens.ipynb).

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Counting tokens](/api-reference/tokens/count-tokens)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:countTokens`

  Runs a model's tokenizer on input `Content` and returns the token count.
{% /table %}

# Counting tokens
Source: https://aistudio.google.com/api-reference/tokens/count-tokens
Description: Runs a model's tokenizer on input `Content` and returns the token count.

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/models/{model}:countTokens`

Runs a model's tokenizer on input `Content` and returns the token count.
Refer to the [tokens guide](/docs/tokens)
to learn more about tokens.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The model ID, for example `gemini-2.5-flash`. Forms the resource name `models/{model}`.

{% /section %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**contents**: `array (Content)`

Optional. The input given to the model as a prompt. This field is ignored when `generate_content_request` is set.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**generateContentRequest**: `GenerateContentRequest`

Optional. The overall input given to the `Model`. This includes the prompt as well as other model steering information like [system instructions](/docs/text-generation#system-instructions), and/or function declarations for [function calling](/docs/function-calling). `Model`s/`Content`s and `generate_content_request`s are mutually exclusive. You can either send `Model` + `Content`s or a `generate_content_request`, but never both.

{% /summary %}

**model**: {% mark %}required{% /mark %} `string`

The name of the `Model` to use for generating the completion. Format: `models/{model}`.

{% details %}

{% summary %}

**contents**: {% mark %}required{% /mark %} `array (Content)`

The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like [chat](/docs/text-generation#multi-turn-conversations), this is a repeated field that contains the conversation history and the latest request.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**systemInstruction**: `Content`

Optional. Developer set [system instruction(s)](/docs/text-generation#system-instructions). Currently, text only.

{% /summary %}

{% details %}

{% summary %}

**parts**: `array (Part)`

Ordered `Parts` that constitute a single message. Parts may have different MIME types.

{% /summary %}

**text**: `string`

Inline text.

{% details %}

{% summary %}

**inlineData**: `Blob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples of supported types:

- Images: image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif
- Audio: audio/*, video/audio/s16le, video/audio/wav
- Video: video/*
- Text: text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp
- Applications: application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf For additional context, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Specifies the name used to refer to this blob to the model (e.g. "my_blob.png"). Used as the blob reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**functionCall**: `FunctionCall`

A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**id**: `string`

Optional. Unique identifier of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`.

**args**: `object`

Optional. The function parameters and values in JSON object format.

{% /details %}

{% details %}

{% summary %}

**functionResponse**: `FunctionResponse`

The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

**response**: {% mark %}required{% /mark %} `object`

The function response in JSON object format. Callers can use any keys of their choice that fit the function's syntax to return the function output, e.g. "output", "result", etc. In particular, if the function call failed to execute, the response can have an "error" key to return error details to the model. Multimedia can be included by using a subobject containing a single "$ref" key whose value is the `inline_data.display_name` of a `FunctionResponsePart` holding the multimedia. See /docs/function-calling#multimodal.

**id**: `string`

Optional. The identifier of the function call this response is for. Populated by the client to match the corresponding function call `id`.

{% details %}

{% summary %}

**parts**: `array (FunctionResponsePart)`

Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types.

{% /summary %}

{% details %}

{% summary %}

**inlineData**: `FunctionResponseBlob`

Inline media bytes.

{% /summary %}

**mimeType**: `string`

The IANA standard MIME type of the source data. Examples:

- image/png
- image/jpeg

If an unsupported MIME type is provided, an error will be returned. For a complete list of supported types, see [Supported file formats](/docs/file-input-methods#supported-content-types).

**data**: `string`

Raw bytes for media formats.

**displayName**: `string`

Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs.

{% /details %}

{% details %}

{% summary %}

**fileData**: `FunctionResponseFileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Display name of the file. Used to provide a label or filename to distinguish file data.

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% /details %}

**willContinue**: `boolean`

Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`.

{% details %}

{% summary %}

**scheduling**: `enum (string)`

Optional. Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE.

{% /summary %}

Possible values:

- `SCHEDULING_UNSPECIFIED`: This value is unused.
- `SILENT`: Only add the result to the conversation context, do not interrupt or trigger generation.
- `WHEN_IDLE`: Add the result to the conversation context, and prompt to generate output without interrupting ongoing generation.
- `INTERRUPT`: Add the result to the conversation context, interrupt ongoing generation and prompt to generate output.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**fileData**: `FileData`

URI based data.

{% /summary %}

**fileUri**: {% mark %}required{% /mark %} `string`

URI.

**mimeType**: `string`

Optional. The IANA standard MIME type of the source data.

**displayName**: `string`

Optional. Specifies the name used to refer to this file to the model (e.g. "my_file.pdf"). Used as the file reference identifier when `verbalization_mode` is set to `REFERENCE_ONLY`.

{% /details %}

{% details %}

{% summary %}

**executableCode**: `ExecutableCode`

Code generated by the model that is meant to be executed.

{% /summary %}

{% details %}

{% summary %}

**language**: {% mark %}required{% /mark %} `enum (string)`

Programming language of the `code`.

{% /summary %}

Possible values:

- `LANGUAGE_UNSPECIFIED`: Unspecified language. This value should not be used.
- `PYTHON`: Python >= 3.10, with numpy and simpy available. Python is the default language.

{% /details %}

**code**: {% mark %}required{% /mark %} `string`

The code to be executed.

**id**: `string`

Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`.

{% /details %}

{% details %}

{% summary %}

**codeExecutionResult**: `CodeExecutionResult`

Result of executing the `ExecutableCode`.

{% /summary %}

{% details %}

{% summary %}

**outcome**: {% mark %}required{% /mark %} `enum (string)`

Outcome of the code execution.

{% /summary %}

Possible values:

- `OUTCOME_UNSPECIFIED`: Unspecified status. This value should not be used.
- `OUTCOME_OK`: Code execution completed successfully. `output` contains the stdout, if any.
- `OUTCOME_FAILED`: Code execution failed. `output` contains the stderr and stdout, if any.
- `OUTCOME_DEADLINE_EXCEEDED`: Code execution ran for too long, and was cancelled. There may or may not be a partial `output` present.

{% /details %}

**id**: `string`

Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id.

**output**: `string`

Optional. Contains stdout when code execution is successful, stderr or other description otherwise.

{% /details %}

{% details %}

{% summary %}

**toolCall**: `ToolCall`

Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. Unique identifier of the tool call. The server returns the tool response with the matching `id`.

**toolName**: `string`

Optional. The name of the tool that was called.

**args**: `object`

Optional. The tool call arguments. Example: {"arg1" : "value1", "arg2" : "value2" , ...}

{% /details %}

{% details %}

{% summary %}

**toolResponse**: `ToolResponse`

The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

{% /summary %}

{% details %}

{% summary %}

**toolType**: {% mark %}required{% /mark %} `V1mainToolType`

The type of tool that was called, matching the `tool_type` in the corresponding `ToolCall`.

{% /summary %}

Possible values:

- `TOOL_TYPE_UNSPECIFIED`: Unspecified tool type.
- `GOOGLE_SEARCH_WEB`: Google search tool, maps to Tool.google_search.search_types.web_search.
- `GOOGLE_SEARCH_IMAGE`: Image search tool, maps to Tool.google_search.search_types.image_search.
- `URL_CONTEXT`: URL context tool, maps to Tool.url_context.
- `GOOGLE_MAPS`: Google maps tool, maps to Tool.google_maps.
- `FILE_SEARCH`: File search tool, maps to Tool.file_search.
- `MEDIA_PROCESSING`: Media processing tool types (e.g. video, audio, etc.), maps to invisible tools used for multimodal understanding like GOOGLE_UNDERSTANDING_VIDEO.

{% /details %}

**id**: `string`

Optional. The identifier of the tool call this response is for.

**response**: `object`

Optional. The tool response.

{% /details %}

{% details %}

{% summary %}

**videoMetadata**: `VideoMetadata`

Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

{% /summary %}

**startOffset**: `string`

Optional. The start offset of the video.

**endOffset**: `string`

Optional. The end offset of the video.

**fps**: `number`

Optional. The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0].

{% /details %}

**thought**: `boolean`

Optional. Indicates if the part is thought from the model.

**thoughtSignature**: `string`

Optional. An opaque signature for the thought so it can be reused in subsequent requests.

**partMetadata**: `object`

Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

{% details %}

{% summary %}

**mediaResolution**: `V1mainMediaResolution`

Optional. Media resolution for the input media.

{% /summary %}

{% details %}

{% summary %}

**level**: `enum (string)`

The tokenization quality used for given media. for Gemini API support .

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low.
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium.
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high.
- `MEDIA_RESOLUTION_ULTRA_HIGH`: Media resolution set to ultra high.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**mediaProcessing**: `enum (string)`

Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

{% /summary %}

Possible values:

- `MEDIA_PROCESSING_UNSPECIFIED`: Defaults to model-specific processing.
- `STATIC`: Fixed-rate frame extraction. All frames placed in context.
- `AGENTIC`: Model-driven dynamic navigation. Recommended for most use cases.

{% /details %}

{% details %}

{% summary %}

**audioTranscription**: `AudioTranscription`

Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

{% /summary %}

**text**: {% mark %}required{% /mark %} `string`

The transcription text of this audio segment.

**speakerLabel**: `string`

Optional. A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). Present when diarization is set.

{% details %}

{% summary %}

**words**: `array (WordInfo)`

Optional. Detailed word-level transcriptions and timing details. Present when word_timestamp is set.

{% /summary %}

**word**: {% mark %}required{% /mark %} `string`

Transcript of the word.

**startOffset**: `string`

Optional. Start offset in time of the word relative to the start of the audio.

**endOffset**: `string`

Optional. End offset in time of the word relative to the start of the audio.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**speechMetadata**: `SpeechMetadata`

Optional. Metadata applied to text parts to customize how they should be spoken or synthesized, such as specifying speaker identity or speaking style.

{% /summary %}

**speaker**: `string`

Optional. Optional speaker name for multi-speaker synthesis.

**style**: `string`

Optional. Optional style instruction for the speech synthesis.

{% /details %}

{% /details %}

**role**: `string`

Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

{% /details %}

{% details %}

{% summary %}

**tools**: `array (Tool)`

Optional. A list of `Tools` the `Model` may use to generate the next response. A `Tool` is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the `Model`. Supported `Tool`s are `Function` and `code_execution`. Refer to the [Function calling](/docs/function-calling) and the [Code execution](/docs/code-execution) guides to learn more.

{% /summary %}

{% details %}

{% summary %}

**functionDeclarations**: `array (FunctionDeclaration)`

Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

{% /summary %}

**name**: {% mark %}required{% /mark %} `string`

The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

**description**: {% mark %}required{% /mark %} `string`

A brief description of the function.

{% details %}

{% summary %}

**parameters**: `Schema`

Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**parametersJsonSchema**: `object`

Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: `{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] }` This field is mutually exclusive with `parameters`.

{% details %}

{% summary %}

**response**: `Schema`

Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

{% /summary %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `Type`

Data type.

{% /summary %}

Possible values:

- `TYPE_UNSPECIFIED`: Not specified, should not be used.
- `STRING`: String type.
- `NUMBER`: Number type.
- `INTEGER`: Integer type.
- `BOOLEAN`: Boolean type.
- `ARRAY`: Array type.
- `OBJECT`: Object type.
- `NULL`: Null type.

{% /details %}

**format**: `string`

Optional. The format of the data. Any value is allowed, but most do not trigger any special functionality.

**title**: `string`

Optional. The title of the schema.

**description**: `string`

Optional. A brief description of the parameter. This could contain examples of use. Parameter description may be formatted as Markdown.

**nullable**: `boolean`

Optional. Indicates if the value may be null.

**enum**: `array (string)`

Optional. Possible values of the element of Type.STRING with enum format. For example we can define an Enum Direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

**items**: `Schema`

Optional. Schema of the elements of Type.ARRAY.

**maxItems**: `string`

Optional. Maximum number of the elements for Type.ARRAY.

**minItems**: `string`

Optional. Minimum number of the elements for Type.ARRAY.

**properties**: `object`

Optional. Properties of Type.OBJECT.

**required**: `array (string)`

Optional. Required properties of Type.OBJECT.

**minProperties**: `string`

Optional. Minimum number of the properties for Type.OBJECT.

**maxProperties**: `string`

Optional. Maximum number of the properties for Type.OBJECT.

**minimum**: `number`

Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER

**maximum**: `number`

Optional. Maximum value of the Type.INTEGER and Type.NUMBER

**minLength**: `string`

Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

**maxLength**: `string`

Optional. Maximum length of the Type.STRING

**pattern**: `string`

Optional. Pattern of the Type.STRING to restrict a string to a regular expression.

**example**: `object`

Optional. Example of the object. Will only populated when the object is the root.

**anyOf**: `array (Schema)`

Optional. The value should be validated against any (one or more) of the subschemas in the list.

**propertyOrdering**: `array (string)`

Optional. The order of the properties. Not a standard field in open api spec. Used to determine the order of the properties in the response.

**default**: `object`

Optional. Default value of the field. Per JSON Schema, this field is intended for documentation generators and doesn't affect validation. Thus it's included here and ignored so that developers who send schemas with a `default` field don't get unknown-field errors.

{% /details %}

**responseJsonSchema**: `object`

Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

{% details %}

{% summary %}

**behavior**: `enum (string)`

Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

{% /summary %}

Possible values:

- `UNSPECIFIED`: This value is unused.
- `BLOCKING`: If set, the system will wait to receive the function response before continuing the conversation.
- `NON_BLOCKING`: If set, the system will not wait to receive the function response. Instead, it will attempt to handle function responses as they become available while maintaining the conversation between the user and the model.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**googleSearchRetrieval**: `GoogleSearchRetrieval`

Optional. Retrieval tool that is powered by Google search.

{% /summary %}

{% details %}

{% summary %}

**dynamicRetrievalConfig**: `DynamicRetrievalConfig`

Specifies the dynamic retrieval configuration for the given source.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

The mode of the predictor to be used in dynamic retrieval.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Always trigger retrieval.
- `MODE_DYNAMIC`: Run retrieval only when system decides it is necessary.

{% /details %}

**dynamicThreshold**: `number`

The threshold to be used in dynamic retrieval. If not set, a system default value is used.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**codeExecution**: `CodeExecution`

Optional. Enables the model to execute code as part of generation.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**googleSearch**: `GoogleSearch`

Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

{% /summary %}

{% details %}

{% summary %}

**timeRangeFilter**: `Interval`

Optional. Filter search results to a specific time range. If customers set a start time, they must set an end time (and vice versa).

{% /summary %}

**startTime**: `string`

Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.

**endTime**: `string`

Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.

{% /details %}

{% details %}

{% summary %}

**searchTypes**: `SearchTypes`

Optional. The set of search types to enable. If not set, web search is enabled by default.

{% /summary %}

{% details %}

{% summary %}

**webSearch**: `WebSearch`

Optional. Enables web search. Only text results are returned.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**imageSearch**: `ImageSearch`

Optional. Enables image search. Image bytes are returned.

{% /summary %}

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**computerUse**: `ComputerUse`

Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

{% /summary %}

{% details %}

{% summary %}

**environment**: {% mark %}required{% /mark %} `enum (string)`

The environment being operated.

{% /summary %}

Possible values:

- `ENVIRONMENT_UNSPECIFIED`: Defaults to browser.
- `ENVIRONMENT_BROWSER`: Operates in a web browser.
- `ENVIRONMENT_MOBILE`: Operates in a mobile environment.
- `ENVIRONMENT_DESKTOP`: Operates in a desktop environment.

{% /details %}

**excludedPredefinedFunctions**: `array (string)`

Optional. By default, predefined functions are included in the final model call. Some of them can be explicitly excluded from being automatically included. This can serve two purposes: 1. Using a more restricted / different action space. 2. Improving the definitions / instructions of predefined functions.

**enablePromptInjectionDetection**: `boolean`

Optional. Whether enable the prompt injection detection check on computer-use request.

{% details %}

{% summary %}

**disabledSafetyPolicies**: `array (enum (string))`

Optional. Disabled safety policies for computer use.

{% /summary %}

Possible values:

- `SAFETY_POLICY_UNSPECIFIED`: Unspecified safety policy.
- `FINANCIAL_TRANSACTIONS`: Safety policy for financial transactions.
- `SENSITIVE_DATA_MODIFICATION`: Safety policy for sensitive data modification.
- `COMMUNICATION_TOOL`: Safety policy for communication tools (e.g. Gmail, Chat, Meet).
- `ACCOUNT_CREATION`: Safety policy for account creation.
- `DATA_MODIFICATION`: Safety policy for data modification.
- `USER_CONSENT_MANAGEMENT`: Safety policy for user consent management.
- `LEGAL_TERMS_AND_AGREEMENTS`: Safety policy for legal terms and agreements.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**urlContext**: `UrlContext`

Optional. Tool to support URL context retrieval.

{% /summary %}

{% /details %}

{% details %}

{% summary %}

**fileSearch**: `FileSearch`

Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

{% /summary %}

**fileSearchStoreNames**: {% mark %}required{% /mark %} `array (string)`

The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`

**topK**: `integer`

Optional. The number of semantic retrieval chunks to retrieve.

**metadataFilter**: `string`

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

{% /details %}

{% details %}

{% summary %}

**mcpServers**: `array (McpServer)`

Optional. MCP Servers to connect to.

{% /summary %}

{% details %}

{% summary %}

**streamableHttpTransport**: `StreamableHttpTransport`

A transport that can stream HTTP requests and responses.

{% /summary %}

**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.

**timeout**: `string`

HTTP timeout for regular operations.

**sseReadTimeout**: `string`

Timeout for SSE read operations.

**terminateOnClose**: `boolean`

Whether to close the client session when the transport closes.

{% /details %}

**name**: `string`

The name of the MCPServer.

{% /details %}

{% details %}

{% summary %}

**googleMaps**: `GoogleMaps`

Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

{% /summary %}

**enableWidget**: `boolean`

Optional. Whether to return a widget context token in the GroundingMetadata of the response. Developers can use the widget context token to render a Google Maps widget with geospatial context related to the places that the model references in the response.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**toolConfig**: `ToolConfig`

Optional. Tool configuration for any `Tool` specified in the request. Refer to the [Function calling guide](/docs/function-calling#function_calling_modes) for a usage example.

{% /summary %}

{% details %}

{% summary %}

**functionCallingConfig**: `FunctionCallingConfig`

Optional. Function calling config.

{% /summary %}

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified function calling mode. This value should not be used.
- `AUTO`: Default model behavior, model decides to predict either a function call or a natural language response.
- `ANY`: Model is constrained to always predicting a function call only. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".
- `NONE`: Model will not predict any function call. Model behavior is same as when not passing any function declarations.
- `VALIDATED`: Model decides to predict either a function call or a natural language response, but will validate function calls with constrained decoding. If "allowed_function_names" are set, the predicted function call will be limited to any one of "allowed_function_names", else the predicted function call will be any one of the provided "function_declarations".

{% /details %}

**allowedFunctionNames**: `array (string)`

Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

{% /details %}

{% details %}

{% summary %}

**retrievalConfig**: `RetrievalConfig`

Optional. Retrieval config.

{% /summary %}

{% details %}

{% summary %}

**latLng**: `LatLng`

Optional. The location of the user.

{% /summary %}

**latitude**: `number`

The latitude in degrees. It must be in the range [-90.0, +90.0].

**longitude**: `number`

The longitude in degrees. It must be in the range [-180.0, +180.0].

{% /details %}

**languageCode**: `string`

Optional. The language code of the user. Language code for content. Use language tags defined by [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

{% /details %}

**includeServerSideToolInvocations**: `boolean`

Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions.

{% /details %}

{% details %}

{% summary %}

**safetySettings**: `array (SafetySetting)`

Optional. A list of unique `SafetySetting` instances for blocking unsafe content. This will be enforced on the `GenerateContentRequest.contents` and `GenerateContentResponse.candidates`. There should not be more than one setting for each `SafetyCategory` type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each `SafetyCategory` specified in the safety_settings. If there is no `SafetySetting` for a given `SafetyCategory` provided in the list, the API will use the default safety setting for that category. Harm categories HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_CIVIC_INTEGRITY, HARM_CATEGORY_JAILBREAK are supported. Refer to the [guide](/docs/safety-settings) for detailed information on available safety settings. Also refer to the [Safety guidance](/docs/safety-guidance) to learn how to incorporate safety considerations in your AI applications.

{% /summary %}

{% details %}

{% summary %}

**category**: {% mark %}required{% /mark %} `HarmCategory`

The category for this setting.

{% /summary %}

Possible values:

- `HARM_CATEGORY_UNSPECIFIED`: Category is unspecified.
- `HARM_CATEGORY_HARASSMENT`: **Gemini** - Harassment content.
- `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - Hate speech and content.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - Sexually explicit content.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - Dangerous content.
- `HARM_CATEGORY_JAILBREAK`: **Gemini** - Prompts attempting to bypass or subvert the model's safety guidelines (jailbreak attempts).

{% /details %}

{% details %}

{% summary %}

**threshold**: {% mark %}required{% /mark %} `enum (string)`

Controls the probability threshold at which harm is blocked.

{% /summary %}

Possible values:

- `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: Threshold is unspecified.
- `BLOCK_LOW_AND_ABOVE`: Content with NEGLIGIBLE will be allowed.
- `BLOCK_MEDIUM_AND_ABOVE`: Content with NEGLIGIBLE and LOW will be allowed.
- `BLOCK_ONLY_HIGH`: Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
- `BLOCK_NONE`: All content will be allowed.
- `OFF`: Turn off the safety filter.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**generationConfig**: `GenerationConfig`

Optional. Configuration options for model generation and outputs.

{% /summary %}

**candidateCount**: `integer`

Optional. Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)

**stopSequences**: `array (string)`

Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a `stop_sequence`. The stop sequence will not be included as part of the response.

**maxOutputTokens**: `integer`

Optional. The maximum number of tokens to include in a response candidate. Note: The default value varies by model, see the `Model.output_token_limit` attribute of the `Model` returned from the `getModel` function.

**temperature**: `number`

Optional. Controls the randomness of the output. Note: The default value varies by model, see the `Model.temperature` attribute of the `Model` returned from the `getModel` function. Values can range from [0.0, 2.0]. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topP**: `number`

Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**topK**: `integer`

Optional. The maximum number of tokens to consider when sampling. Gemini models use Top-p (nucleus) sampling or a combination of Top-k and nucleus sampling. Top-k sampling considers the set of `top_k` most probable tokens. Models running with nucleus sampling don't allow top_k setting. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests. This field is no longer supported and is silently ignored on Gemini 3.6 Flash and newer models.

**seed**: `integer`

Optional. Seed used in decoding. If not set, the request uses a randomly generated seed.

**responseMimeType**: `string`

Optional. MIME type of the generated candidate text. Supported MIME types are: `text/plain`: (default) Text output. `application/json`: JSON response in the response candidates. `text/x.enum`: ENUM as a string response in the response candidates. Refer to the [docs](/docs/file-input-methods#text-file-types) for a list of all supported text MIME types.

**responseJsonSchema**: `object`

Optional. An internal detail. Use `responseJsonSchema` rather than this field.

**presencePenalty**: `number`

Optional. Presence penalty applied to the next token's logprobs if the token has already been seen in the response. This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequency_penalty for a penalty that increases with each use. A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary. A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.

**frequencyPenalty**: `number`

Optional. Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far. A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses. Caution: A _negative_ penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the max_output_tokens limit.

**responseLogprobs**: `boolean`

Optional. If true, export the logprobs results in response.

**logprobs**: `integer`

Optional. Only valid if response_logprobs=True. This sets the number of top logprobs, including the chosen candidate, to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].

**enableEnhancedCivicAnswers**: `boolean`

Optional. Enables enhanced civic answers. It may not be available for all models.

{% details %}

{% summary %}

**responseModalities**: `array (enum (string))`

Optional. The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response. A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned. An empty list is equivalent to requesting only text.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Default value.
- `TEXT`: Indicates the model should return text.
- `IMAGE`: Indicates the model should return images.
- `AUDIO`: Indicates the model should return audio.

{% /details %}

{% details %}

{% summary %}

**speechConfig**: `SpeechConfig`

Optional. The speech generation config.

{% /summary %}

{% details %}

{% summary %}

**voiceConfig**: `VoiceConfig`

The configuration in case of single-voice output.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% details %}

{% summary %}

**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig`

Optional. The configuration for the multi-speaker setup. It is mutually exclusive with the voice_config field.

{% /summary %}

{% details %}

{% summary %}

**speakerVoiceConfigs**: {% mark %}required{% /mark %} `array (SpeakerVoiceConfig)`

All the enabled speaker voices.

{% /summary %}

**speaker**: {% mark %}required{% /mark %} `string`

The name of the speaker to use. Should be the same as in the prompt.

{% details %}

{% summary %}

**voiceConfig**: {% mark %}required{% /mark %} `VoiceConfig`

The configuration for the voice to use.

{% /summary %}

{% details %}

{% summary %}

**prebuiltVoiceConfig**: `PrebuiltVoiceConfig`

The configuration for the prebuilt voice to use.

{% /summary %}

**voiceName**: `string`

Optional. The name of the preset voice to use.

{% /details %}

**voice**: `string`

Optional. The speaker identifier for synthesis. Supported formats:

- Speaker name for prebuilt voices (for example, `Orus` or `Kore`).
- Voice ID for stored voices (for example, `voice_xxx`).
- Voice replication key (for example, `voicekey_xxx`).

{% /details %}

{% /details %}

{% /details %}

**languageCode**: `string`

Optional. The IETF [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code that the user configured the app to use. Used for speech recognition and synthesis. Valid values are: `de-DE`, `en-AU`, `en-GB`, `en-IN`, `en-US`, `es-US`, `fr-FR`, `hi-IN`, `pt-BR`, `ar-XA`, `es-ES`, `fr-CA`, `id-ID`, `it-IT`, `ja-JP`, `tr-TR`, `vi-VN`, `bn-IN`, `gu-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `ta-IN`, `te-IN`, `nl-NL`, `ko-KR`, `cmn-CN`, `pl-PL`, `ru-RU`, and `th-TH`.

{% /details %}

{% details %}

{% summary %}

**thinkingConfig**: `ThinkingConfig`

Optional. Config for thinking features. An error will be returned if this field is set for models that don't support thinking.

{% /summary %}

**includeThoughts**: `boolean`

Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.

**thinkingBudget**: `integer`

The number of thoughts tokens that the model should generate.

{% details %}

{% summary %}

**thinkingLevel**: `enum (string)`

Optional. Controls the maximum depth of the model's internal reasoning process before it produces a response. The default value is model-dependent. Refer to the [Thinking levels guide](/docs/thinking#thinking-levels) for more details. Recommended for Gemini 3 or later models. Use with earlier models results in an error.

{% /summary %}

Possible values:

- `THINKING_LEVEL_UNSPECIFIED`: Default value.
- `MINIMAL`: Little to no thinking.
- `LOW`: Low thinking level.
- `MEDIUM`: Medium thinking level.
- `HIGH`: High thinking level.

{% /details %}

{% /details %}

{% details %}

{% summary %}

**imageConfig**: `ImageConfig`

Optional. Config for image generation. An error will be returned if this field is set for models that don't support these config options.

{% /summary %}

**aspectRatio**: `string`

Optional. The aspect ratio of the image to generate. Supported aspect ratios: `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, or `21:9`. If not specified, the model will choose a default aspect ratio based on any reference images provided.

**imageSize**: `string`

Optional. Specifies the size of generated images. Supported values are `512`, `1K`, `2K`, `4K`. If not specified, the model will use default value `1K`.

{% /details %}

{% details %}

{% summary %}

**mediaResolution**: `enum (string)`

Optional. If specified, the media resolution specified will be used.

{% /summary %}

Possible values:

- `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution has not been set.
- `MEDIA_RESOLUTION_LOW`: Media resolution set to low (64 tokens).
- `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium (256 tokens).
- `MEDIA_RESOLUTION_HIGH`: Media resolution set to high (zoomed reframing with 256 tokens).

{% /details %}

**enableAffectiveDialog**: `boolean`

Optional. If enabled, the model will detect emotions and adapt its responses accordingly.

{% details %}

{% summary %}

**responseFormat**: `ResponseFormatConfig`

Optional. Configuration for the response output format. Allows specifying output configuration per modality (text, audio, image) in a flat structure.

{% /summary %}

{% details %}

{% summary %}

**text**: `TextResponseFormat`

Optional. Text output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the text output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `APPLICATION_JSON`: JSON output format.
- `TEXT_PLAIN`: Plain text output format.

{% /details %}

**schema**: `object`

Optional. The JSON schema that the output should conform to. Only applicable when mime_type is APPLICATION_JSON.

{% /details %}

{% details %}

{% summary %}

**audio**: `AudioResponseFormat`

Optional. Audio output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the audio output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `AUDIO_MP3`: MP3 audio format.
- `AUDIO_OGG_OPUS`: OGG Opus audio format.
- `AUDIO_L16`: Raw PCM (L16) audio format.
- `AUDIO_WAV`: WAV audio format.
- `AUDIO_ALAW`: A-law audio format.
- `AUDIO_MULAW`: Mu-law audio format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the audio output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Audio data is returned inline in the response.
- `URI`: Audio data is returned as a URI.

{% /details %}

**sampleRate**: `integer`

Optional. Sample rate in Hz.

**bitRate**: `integer`

Optional. Bit rate in bits per second (bps). Only applicable for compressed formats (MP3, Opus).

{% /details %}

{% details %}

{% summary %}

**image**: `ImageResponseFormat`

Optional. Image output format configuration.

{% /summary %}

{% details %}

{% summary %}

**mimeType**: `enum (string)`

Optional. The MIME type of the image output.

{% /summary %}

Possible values:

- `MIME_TYPE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_JPEG`: JPEG image format.

{% /details %}

{% details %}

{% summary %}

**delivery**: `enum (string)`

Optional. The delivery mode for the image output.

{% /summary %}

Possible values:

- `DELIVERY_UNSPECIFIED`: Default value. This value is unused.
- `INLINE`: Image data is returned inline in the response.
- `URI`: Image data is returned as a URI.

{% /details %}

{% details %}

{% summary %}

**aspectRatio**: `enum (string)`

Optional. The aspect ratio for the image output.

{% /summary %}

Possible values:

- `ASPECT_RATIO_UNSPECIFIED`: Default value. This value is unused.
- `ASPECT_RATIO_ONE_BY_ONE`: 1:1 aspect ratio.
- `ASPECT_RATIO_TWO_BY_THREE`: 2:3 aspect ratio.
- `ASPECT_RATIO_THREE_BY_TWO`: 3:2 aspect ratio.
- `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 aspect ratio.
- `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 aspect ratio.
- `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 aspect ratio.
- `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 aspect ratio.
- `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 aspect ratio.
- `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 aspect ratio.
- `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 aspect ratio.
- `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 aspect ratio.
- `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 aspect ratio.

{% /details %}

{% details %}

{% summary %}

**imageSize**: `enum (string)`

Optional. The size of the image output.

{% /summary %}

Possible values:

- `IMAGE_SIZE_UNSPECIFIED`: Default value. This value is unused.
- `IMAGE_SIZE_FIVE_TWELVE`: 512px image size.
- `IMAGE_SIZE_ONE_K`: 1K image size.
- `IMAGE_SIZE_TWO_K`: 2K image size.
- `IMAGE_SIZE_FOUR_K`: 4K image size.

{% /details %}

{% /details %}

{% /details %}

{% details %}

{% summary %}

**translationConfig**: `TranslationConfig`

Optional. Config for translation.

{% /summary %}

**targetLanguageCode**: {% mark %}required{% /mark %} `string`

The target language for translation. Supported values are BCP-47 language codes (e.g. "en", "es", "fr").

**echoTargetLanguage**: `boolean`

Optional. If true, the model will generate audio when the target language is spoken, essentially it will parrot the input. If false, we will not produce audio for the target language.

{% /details %}

{% details %}

{% summary %}

**audioTranscriptionConfig**: `AudioTranscriptionConfig`

Optional. Config for audio transcription (speech recognition).

{% /summary %}

**languageCodes**: `array (string)`

Optional. BCP-47 language codes providing hints about the languages present in the audio. If omitted or empty, defaults to automatic language detection.

**customVocabulary**: `array (string)`

Optional. A list of custom vocabulary phrases to bias the speech recognition model toward recognizing specific terms (product names, proper nouns, jargon).

**wordTimestamp**: `boolean`

Optional. Configures word-level timestamp generation.

**diarization**: `boolean`

Optional. Configures speaker diarization.

{% details %}

{% summary %}

**mode**: `enum (string)`

Optional. Configures transcription mode. Supported values: `VERBATIM`, `SMART`. If unspecified, defaults to `VERBATIM` transcription. In `SMART` mode, the model performs disfluency removal (eliminating filler words, repetitions, and false starts), light grammatical cleanup, automatic formatting (paragraphs, bullet points, numbered lists), and minor user edits (inline self-corrections). Timestamps and diarization are incompatible with mode `SMART`.

{% /summary %}

Possible values:

- `MODE_UNSPECIFIED`: Unspecified transcription mode.
- `VERBATIM`: Verbatim transcription mode.
- `SMART`: Smart transcription mode.

{% /details %}

{% /details %}

{% /details %}

**cachedContent**: `string`

Optional. The name of the content [cached](/docs/caching) to use as context to serve the prediction. Format: `cachedContents/{cachedContent}`

{% details %}

{% summary %}

**serviceTier**: `ServiceTier`

Optional. The service tier of the request.

{% /summary %}

Possible values:

- `unspecified`: Default service tier, which is standard.
- `standard`: Standard service tier.
- `flex`: Flex service tier.
- `priority`: Priority service tier.

{% /details %}

**store**: `boolean`

Optional. Configures the logging behavior for a given request. If set, it takes precedence over the project-level logging config.

**continuationToken**: `string`

Optional. An opaque continuation token used to resume generation from a previous `GenerateContent` or `StreamGenerateContent` response that stopped with `finish_reason` set to `CONTINUATION`. Note that `contents` is mandatory and must identically replicate the prompt and conversation history from the initial request when continuation token is provided in a request.

**labels**: `object`

Optional. Labels with user-defined metadata for the request. Optional. Labels must follow standard unified Cloud label requirements:

- Label keys must start with a letter.
- Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes.
- International characters are allowed.

Usage:

- Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)

{% /details %}

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="Text" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:countTokens?key=$GEMINI_API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[{
          "text": "The quick brown fox jumps over the lazy dog."
          }],
        }],
      }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
prompt = "The quick brown fox jumps over the lazy dog."

# Count tokens using the new client method.
total_tokens = client.models.count_tokens(
    model="gemini-3.8-flash", contents=prompt
)
print("total_tokens: ", total_tokens)
# ( e.g., total_tokens: 10 )

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=prompt
)

# The usage_metadata provides detailed token counts.
print(response.usage_metadata)
# ( e.g., prompt_token_count: 11, candidates_token_count: 73, total_token_count: 84 )
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const prompt = 'The quick brown fox jumps over the lazy dog.';
const countTokensResponse = await ai.models.countTokens({
  model: 'gemini-3.8-flash',
  contents: prompt,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: prompt,
});
console.log(generateResponse.usageMetadata);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}
prompt := "The quick brown fox jumps over the lazy dog."

// Convert prompt to a slice of *genai.Content using the helper.
contents := []*genai.Content{
    genai.NewContentFromText(prompt, genai.RoleUser),
}
countResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    return err
}
fmt.Println("total_tokens:", countResp.TotalTokens)

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(usageMetadata))
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Chat" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:countTokens?key=$GEMINI_API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {"role": "user",
        "parts": [{"text": "Hi, my name is Bob."}],
        },
        {"role": "model",
         "parts":[{"text": "Hi Bob"}],
        },
      ],
      }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types

client = genai.Client()

chat = client.chats.create(
    model="gemini-3.8-flash",
    history=[
        types.Content(
            role="user", parts=[types.Part(text="Hi my name is Bob")]
        ),
        types.Content(role="model", parts=[types.Part(text="Hi Bob!")]),
    ],
)
# Count tokens for the chat history.
print(
    client.models.count_tokens(
        model="gemini-3.8-flash", contents=chat.get_history()
    )
)
# ( e.g., total_tokens: 10 )

response = chat.send_message(
    message=(
        "In one sentence, explain how a computer works to a young child."
    )
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 25, candidates_token_count: 21, total_token_count: 46 )

# You can count tokens for the combined history and a new message.
extra = types.UserContent(
    parts=[
        types.Part(
            text="What is the meaning of life?",
        )
    ]
)
history = chat.get_history()
history.append(extra)
print(
    client.models.count_tokens(model="gemini-3.8-flash", contents=history)
)
# ( e.g., total_tokens: 56 )
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
// Initial chat history.
const history = [
  {role: 'user', parts: [{text: 'Hi my name is Bob'}]},
  {role: 'model', parts: [{text: 'Hi Bob!'}]},
];
const chat = ai.chats.create({
  model: 'gemini-3.8-flash',
  history: history,
});

// Count tokens for the current chat history.
const countTokensResponse = await ai.models.countTokens({
  model: 'gemini-3.8-flash',
  contents: chat.getHistory(),
});
console.log(countTokensResponse.totalTokens);

const chatResponse = await chat.sendMessage({
  message: 'In one sentence, explain how a computer works to a young child.',
});
console.log(chatResponse.usageMetadata);

// Add an extra user message to the history.
const extraMessage = {
  role: 'user',
  parts: [{text: 'What is the meaning of life?'}],
};
const combinedHistory = chat.getHistory();
combinedHistory.push(extraMessage);
const combinedCountTokensResponse = await ai.models.countTokens({
  model: 'gemini-3.8-flash',
  contents: combinedHistory,
});
console.log(
    'Combined history token count:',
    combinedCountTokensResponse.totalTokens,
);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

// Initialize chat with some history.
history := []*genai.Content{
    {Role: genai.RoleUser, Parts: []*genai.Part{{Text: "Hi my name is Bob"}}},
    {Role: genai.RoleModel, Parts: []*genai.Part{{Text: "Hi Bob!"}}},
}
chat, err := client.Chats.Create(ctx, "gemini-3.8-flash", nil, history)
if err != nil {
    log.Fatal(err)
}

firstTokenResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", chat.History(false), nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(firstTokenResp.TotalTokens)

resp, err := chat.SendMessage(ctx, genai.Part{
    Text: "In one sentence, explain how a computer works to a young child."},
)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%#v\n", resp.UsageMetadata)

// Append an extra user message and recount.
extra := genai.NewContentFromText("What is the meaning of life?", genai.RoleUser)
hist := chat.History(false)
hist = append(hist, extra)

secondTokenResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", hist, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(secondTokenResp.TotalTokens)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Inline Media" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:countTokens?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {"text": "Tell me about this instrument"},
            {
              "inline_data": {
                "mime_type":"image/jpeg",
                "data": "'$(base64 $B64FLAGS $IMG_PATH)'"
              }
            }
        ]
        }]
       }' 2> /dev/null
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
import PIL.Image

client = genai.Client()
prompt = "Tell me about this image"
your_image_file = PIL.Image.open(media / "organ.jpg")

# Count tokens for combined text and inline image.
print(
    client.models.count_tokens(
        model="gemini-3.8-flash", contents=[prompt, your_image_file]
    )
)
# ( e.g., total_tokens: 263 )

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=[prompt, your_image_file]
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 264, candidates_token_count: 80, total_token_count: 345 )
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const prompt = 'Tell me about this image';
const imageBuffer = fs.readFileSync(path.join(media, 'organ.jpg'));

// Convert buffer to base64 string.
const imageBase64 = imageBuffer.toString('base64');

// Build contents using createUserContent and createPartFromBase64.
const contents = createUserContent([
  prompt,
  createPartFromBase64(imageBase64, 'image/jpeg'),
]);

const countTokensResponse = await ai.models.countTokens({
  model: 'gemini-3.8-flash',
  contents: contents,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: contents,
});
console.log(generateResponse.usageMetadata);
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Video" %}

{% tabs %}

{% tab label="REST" %}

```sh
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO_PATH

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)

state=$(jq ".file.state" file_info.json)

name=$(jq ".file.name" file_info.json)

while [[ "($state)" = *"PROCESSING"* ]];
do
  echo "Processing video..."
  sleep 5
  # Get the file of interest to check state
  curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
  state=$(jq ".file.state" file_info.json)
done

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:countTokens?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Describe this video clip"},
          {"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
        }]
       }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai
import time

client = genai.Client()
prompt = "Tell me about this video"
your_file = client.files.upload(file=media / "Big_Buck_Bunny.mp4")

# Poll until the video file is completely processed (state becomes ACTIVE).
while not your_file.state or your_file.state.name != "ACTIVE":
  print("Processing video...")
  print("File state:", your_file.state)
  time.sleep(5)
  your_file = client.files.get(name=your_file.name)

print(
    client.models.count_tokens(
        model="gemini-3.8-flash", contents=[prompt, your_file]
    )
)
# ( e.g., total_tokens: 300 )

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=[prompt, your_file]
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 301, candidates_token_count: 60, total_token_count: 361 )
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const prompt = 'Tell me about this video';
let videoFile = await ai.files.upload({
  file: path.join(media, 'Big_Buck_Bunny.mp4'),
  config: {mimeType: 'video/mp4'},
});

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!videoFile.state || videoFile.state.toString() !== 'ACTIVE') {
  console.log('Processing video...');
  console.log('File state: ', videoFile.state);
  await sleep(5000);
  videoFile = await ai.files.get({name: videoFile.name});
}

const countTokensResponse = await ai.models.countTokens({
  model: 'gemini-3.8-flash',
  contents: createUserContent([
    prompt,
    createPartFromUri(videoFile.uri, videoFile.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: createUserContent([
    prompt,
    createPartFromUri(videoFile.uri, videoFile.mimeType),
  ]),
});
console.log(generateResponse.usageMetadata);
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "Big_Buck_Bunny.mp4"),
    &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    },
)
if err != nil {
    log.Fatal(err)
}

// Poll until the video file is completely processed (state becomes ACTIVE).
for file.State == genai.FileStateUnspecified || file.State != genai.FileStateActive {
    fmt.Println("Processing video...")
    fmt.Println("File state:", file.State)
    time.Sleep(5 * time.Second)

    file, err = client.Files.Get(ctx, file.Name, nil)
    if err != nil {
        log.Fatal(err)
    }
}

parts := []*genai.Part{
    genai.NewPartFromText("Tell me about this video"),
    genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

tokenResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println("Multimodal video/audio token count:", tokenResp.TotalTokens)
response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
    log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(usageMetadata))
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Pdf" %}

{% tabs %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
sample_pdf = client.files.upload(file=media / "test.pdf")
token_count = client.models.count_tokens(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this document.", sample_pdf],
)
print(f"{token_count=}")

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this document.", sample_pdf],
)
print(response.usage_metadata)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="Cache" %}

{% tabs %}

{% tab label="Python" %}

```python
from google import genai
from google.genai import types
import time

client = genai.Client()
your_file = client.files.upload(file=media / "a11.txt")

cache = client.caches.create(
    model="gemini-3.8-flash",
    config={
        "contents": ["Here the Apollo 11 transcript:", your_file],
        "system_instruction": None,
        "tools": None,
    },
)

# Create a prompt.
prompt = "Please give a short summary of this file."

# Count tokens for the prompt (the cached content is not passed here).
print(client.models.count_tokens(model="gemini-3.8-flash", contents=prompt))
# ( e.g., total_tokens: 9 )

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=prompt,
    config=types.GenerateContentConfig(
        cached_content=cache.name,
    ),
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: ..., cached_content_token_count: ..., candidates_token_count: ... )
client.caches.delete(name=cache.name)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const textFile = await ai.files.upload({
  file: path.join(media, 'a11.txt'),
  config: {mimeType: 'text/plain'},
});

const cache = await ai.caches.create({
  model: 'gemini-3.8-flash',
  config: {
    contents: createUserContent([
      'Here the Apollo 11 transcript:',
      createPartFromUri(textFile.uri, textFile.mimeType),
    ]),
    system_instruction: null,
    tools: null,
  },
});

const prompt = 'Please give a short summary of this file.';
const countTokensResponse = await ai.models.countTokens({
  model: 'gemini-3.8-flash',
  contents: prompt,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: prompt,
  config: {cachedContent: cache.name},
});
console.log(generateResponse.usageMetadata);

await ai.caches.delete({name: cache.name});
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
    ctx,
    filepath.Join(getMedia(), "a11.txt"),
    &genai.UploadFileConfig{
        MIMEType: "text/plain",
    },
)
if err != nil {
    log.Fatal(err)
}
parts := []*genai.Part{
    genai.NewPartFromText("Here the Apollo 11 transcript:"),
    genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

// Create cached content using a simple slice with text and a file.
cache, err := client.Caches.Create(ctx, "gemini-3.8-flash", &genai.CreateCachedContentConfig{
    Contents: contents,
})
if err != nil {
    log.Fatal(err)
}

prompt := "Please give a short summary of this file."
countResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", []*genai.Content{
    genai.NewContentFromText(prompt, genai.RoleUser),
}, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%d", countResp.TotalTokens)
response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", []*genai.Content{
    genai.NewContentFromText(prompt, genai.RoleUser),
}, &genai.GenerateContentConfig{
    CachedContent: cache.Name,
})
if err != nil {
    log.Fatal(err)
}

usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
    log.Fatal(err)
}
// Returns `nil` for some reason
fmt.Println(string(usageMetadata))
_, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% tab label="System Instruction" %}

{% tabs %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

// Construct the user message contents.
contents := []*genai.Content{
    genai.NewContentFromText("Good morning! How are you?", genai.RoleUser),
}

// Set the system instruction as a *genai.Content.
config := &genai.GenerateContentConfig{
    SystemInstruction: genai.NewContentFromText("You are a cat. Your name is Neko.", genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, config)
if err != nil {
    log.Fatal(err)
}
printResponse(response)
```

{% /tab %}

{% /tabs %}

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**totalTokens**: `integer`

The number of tokens that the `Model` tokenizes the `prompt` into. Always non-negative.

{% hr /%}

**cachedContentTokenCount**: `integer`

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

{% hr /%}

{% details %}

{% summary %}

**promptTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the request input.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**cacheTokensDetails**: `array (ModalityTokenCount)`

Output only. List of modalities that were processed in the cached content.

{% /summary %}

{% details %}

{% summary %}

**modality**: `GenerativeLanguageModality`

The modality associated with this token count.

{% /summary %}

Possible values:

- `MODALITY_UNSPECIFIED`: Unspecified modality.
- `TEXT`: Plain text.
- `IMAGE`: Image.
- `VIDEO`: Video.
- `AUDIO`: Audio.
- `DOCUMENT`: Document, e.g. PDF.

{% /details %}

**tokenCount**: `integer`

Number of tokens.

{% /details %}

{% /section %}

# Gemini Voices API
Source: https://aistudio.google.com/api-reference/voices
Description: The Voices API allows you to create custom voices from natural language prompts (Voice Design) or from reference audio and speaker consent recordings (Voice Replication), as well as list, retrieve, and manage custom and prebuilt voices for Text-to-Speech (TTS) synthesis.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

The Voices API allows you to create custom voices from natural language prompts (Voice Design) or from reference audio and speaker consent recordings (Voice Replication), as well as list, retrieve, and manage custom and prebuilt voices for Text-to-Speech (TTS) synthesis.

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Creating a voice](/api-reference/voices/create-voice)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/voices`

  Creates a custom voice from a natural-language prompt (`VOICE_TYPE_PROMPTED`) or from reference and consent audio recordings (`VOICE_TYPE_REPLICATED`).
---

* [Listing voices](/api-reference/voices/list-voices)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/voices`

  Lists custom stored voices owned by the caller (ordered newest first) followed by prebuilt system voices from Google's voice catalog.
---

* [Getting a voice](/api-reference/voices/get-voice)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/voices/{voicesId}`

  Gets a custom stored voice (`store = true`) by resource name.
---

* [Deleting a voice](/api-reference/voices/delete-voice)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/voices/{voicesId}`

  Deletes a custom stored voice (`store = true`) by resource name.
{% /table %}

## Resources {% id="resources" %}

### Voice {% id="Resource:Voice" %}

A voice resource representing either a custom voice (created via
`CreateVoice`) or a prebuilt system voice (returned by `ListVoices`).

**Properties:**

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `VoiceType`

The type of the voice. In `CreateVoice`, must be `"replicated"` or `"prompted"`. In `ListVoices` responses, may also be `"prebuilt"`.

{% /summary %}

Possible values:

- `replicated`: A custom voice replicated from a reference audio sample and speaker consent recording.
- `prompted`: A custom voice generated from a natural-language text prompt (optionally editing or remixing a `base_voice`).
- `prebuilt`: A built-in system voice from Google's voice catalog (e.g., `Puck`, `Charon`). Returned in responses; cannot be specified as the type in `CreateVoice`.

{% /details %}

{% hr /%}

**id**: `string`

Output only. The unique identifier of the voice.

- For Google-managed custom voices (`store = true`), this is a generated ID with prefix `voice_` (for example, `voice_abc123def456`). Pass `voices/{id}` as the `name` in `GetVoice` and `DeleteVoice`, and pass `{id}` directly to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.
- For prebuilt catalog voices (`"prebuilt"` returned by `ListVoices`), this is the speaker name (for example, `Puck` or `Charon`).
- Unset when `CreateVoice` is called with `store = false`.

{% hr /%}

**model**: `string`

Optional. The model used to design or replicate the voice. If omitted in `CreateVoice`, defaults to the latest supported voice design model. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for custom voices (`"prompted"` and `"replicated"`); unset for `"prebuilt"` voices. Created voices can be synthesized across any supported TTS synthesis model.

{% hr /%}

**key**: `string`

Output only. The client-managed voice replication key (with prefix `voicekey_`). Returned only by `CreateVoice` when `type` is `"replicated"` and `store` is `false`. Pass this key to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.

{% hr /%}

{% details %}

{% summary %}

**replicated**: `ReplicatedVoice`

Input only. Parameters for replicated voice generation. Required on input when `type` is `"replicated"`. Not returned in responses.

{% /summary %}

{% details %}

{% summary %}

**source_audio**: {% mark %}required{% /mark %} `AudioData`

The reference audio sample of the speaker's voice to replicate. Must be an unmodified recording of an adult human voice.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

{% details %}

{% summary %}

**consent_audio**: {% mark %}required{% /mark %} `AudioData`

Audio recording of the same speaker reading the required consent phrase, confirming authorization to replicate the voice.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

{% /details %}

{% hr /%}

**expire_time**: `string`

Output only. The timestamp at which a custom stored voice (`store = true`) or replicated voice key (`store = false`) expires. For custom stored voices (`store = true`), this expiration time is extended when the voice is used for speech synthesis or as a `base_voice` in `CreateVoice`. Unset for prebuilt catalog voices (`"prebuilt"`), which do not expire.

{% hr /%}

**display_name**: `string`

Optional. User-provided display name for a stored voice (`store = true`), or the catalog name for a prebuilt voice.

{% hr /%}

{% details %}

{% summary %}

**prompted**: `PromptedVoice`

Parameters for prompted voice generation. Required in `CreateVoice` when `type` is `"prompted"`. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for prompted voices.

{% /summary %}

**input**: {% mark %}required{% /mark %} `string`

The natural-language prompt describing the desired voice, e.g. "A deep, booming male voice of a massive evil ogre in his middle years."

**base_voice**: `string`

Optional. The name or ID of an existing base voice to edit or remix. Use the voice name for prebuilt voices (e.g., `Puck`) or the voice ID for previously created voices (e.g., `voice_abc123`). This can be any prompted or replicated voice that the user has access to. When present, `input` describes relative alterations to make to the base voice.

{% /details %}

{% hr /%}

**language_code**: `string`

Optional. Primary BCP-47 language tag (e.g. "en-US", "fr-FR").

{% hr /%}

**region_code**: `string`

Optional. ISO 3166-1 alpha-2 or UN M.49 geographic region code (e.g. "US", "GB", "001").

{% hr /%}

**accent**: `string`

Optional. Regional accent descriptor (e.g. "American", "British").

{% hr /%}

**persona**: `string`

Optional. Intended persona or character archetype (e.g. "Warm, Friendly", "Narrator").

{% hr /%}

**context**: `string`

Optional. Optimal usage context or domain (e.g. "Conversational", "Audiobook", "News").

{% hr /%}

**gender**: `string`

Optional. Perceived voice gender presentation (e.g. "female", "male", "neutral").

{% hr /%}

{% details %}

{% summary %}

**pitch**: `Pitch`

Optional. Voice pitch classification.

{% /summary %}

Possible values:

- `low`: Lower pitch voice.
- `medium`: Medium pitch voice.
- `high`: Higher pitch voice.

{% /details %}

{% hr /%}

**description**: `string`

Optional. Descriptive summary of vocal timbre, personality, and tone.

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

Output only. Token usage statistics for the voice creation request. Populated only in the response of `CreateVoice` when `type` is `"prompted"`; unset for `"replicated"` and in `GetVoice` and `ListVoices` responses.

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**sample_audio**: `AudioData`

Output only. Sample audio (synthesizer prompt audio) generated for a prompted voice. Populated only in `CreateVoice` and `GetVoice` responses when `type` is `"prompted"`; unset in `ListVoices` responses and for `"replicated"` or `"prebuilt"` voices.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

# Creating a voice
Source: https://aistudio.google.com/api-reference/voices/create-voice
Description: Creates a custom voice from a natural-language prompt (`VOICE_TYPE_PROMPTED`) or from reference and consent audio recordings (`VOICE_TYPE_REPLICATED`).

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/voices`

Creates a custom voice from a natural-language prompt
(`VOICE_TYPE_PROMPTED`) or from reference and consent audio recordings
(`VOICE_TYPE_REPLICATED`).

{% two-column-layout %}

{% left-column %}

## Request Body {% class="hide-from-toc" id="request-body" %}

{% section class="api-ref-property-list" %}

**voice**: {% mark %}required{% /mark %} [`Voice`](/api-reference/voices/create-voice#Resource:Voice)

The voice to create. `voice.model` is optional; if omitted, the service selects the default voice creation model. Output-only fields on [`Voice`](/api-reference/voices/create-voice#Resource:Voice) (`id`, `key`, `expire_time`, `usage`) are ignored if set.

{% hr /%}

**store**: `boolean`

Optional. Whether the created voice is persisted and managed by Google.

- When `true`, Google stores the voice and returns `Voice.id` (for example, `voice_abc123def456`), which can be managed via `GetVoice`, `ListVoices`, and `DeleteVoice` and referenced by ID in synthesis requests. Stored voices expire after 1 year of inactivity; using a stored voice in speech synthesis or as a `base_voice` in `CreateVoice` extends its `expire_time`. Projects are subject to a maximum active stored voice quota; exceeding the quota returns `RESOURCE_EXHAUSTED`.
- When `false` (default), the voice is not stored by Google and `Voice.key` (for example, `voicekey_...`) is returned for client-side storage and synthesis. Optional discovery metadata fields on `voice` are not persisted or returned when `store` is `false`.
- Required to be `true` when `voice.type` is `"prompted"` (otherwise fails with `INVALID_ARGUMENT`).

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/voices \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "store": true,
    "voice": {
      "type": "prompted",
      "display_name": "Warm Narrator",
      "language_code": "en-US",
      "prompted": {
        "input": "A warm, friendly narrator voice with a calm pace."
      }
    }
  }'
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
voice = client.voices.create(
    store=True,
    voice={
        "type": "prompted",
        "display_name": "Warm Narrator",
        "language_code": "en-US",
        "prompted": {
            "input": "A warm, friendly narrator voice with a calm pace.",
        },
    },
)
print(voice.id)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const voice = await ai.voices.create({
  store: true,
  voice: {
    type: 'prompted',
    display_name: 'Warm Narrator',
    language_code: 'en-US',
    prompted: {
      input: 'A warm, friendly narrator voice with a calm pace.',
    },
  },
});
console.log(voice.id);
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    gaos_voices "google.golang.org/genai/interactions/models/voices"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    req := operations.CreateVoiceRequest{
        Body: gaos_voices.CreateVoiceRequest{
            Store: genai.Ptr(true),
            Voice: gaos_voices.VoiceInput{
                Type:         gaos_voices.VoiceTypePrompted,
                DisplayName:  genai.Ptr("Warm Narrator"),
                LanguageCode: genai.Ptr("en-US"),
                Prompted: &gaos_voices.PromptedVoice{
                    Input: "A warm, friendly narrator voice with a calm pace.",
                },
            },
        },
    }

    res, err := client.Voices.Create(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.Voice != nil && res.Voice.ID != nil {
        fmt.Println(*res.Voice.ID)
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `VoiceType`

The type of the voice. In `CreateVoice`, must be `"replicated"` or `"prompted"`. In `ListVoices` responses, may also be `"prebuilt"`.

{% /summary %}

Possible values:

- `replicated`: A custom voice replicated from a reference audio sample and speaker consent recording.
- `prompted`: A custom voice generated from a natural-language text prompt (optionally editing or remixing a `base_voice`).
- `prebuilt`: A built-in system voice from Google's voice catalog (e.g., `Puck`, `Charon`). Returned in responses; cannot be specified as the type in `CreateVoice`.

{% /details %}

{% hr /%}

**id**: `string`

Output only. The unique identifier of the voice.

- For Google-managed custom voices (`store = true`), this is a generated ID with prefix `voice_` (for example, `voice_abc123def456`). Pass `voices/{id}` as the `name` in `GetVoice` and `DeleteVoice`, and pass `{id}` directly to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.
- For prebuilt catalog voices (`"prebuilt"` returned by `ListVoices`), this is the speaker name (for example, `Puck` or `Charon`).
- Unset when `CreateVoice` is called with `store = false`.

{% hr /%}

**model**: `string`

Optional. The model used to design or replicate the voice. If omitted in `CreateVoice`, defaults to the latest supported voice design model. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for custom voices (`"prompted"` and `"replicated"`); unset for `"prebuilt"` voices. Created voices can be synthesized across any supported TTS synthesis model.

{% hr /%}

**key**: `string`

Output only. The client-managed voice replication key (with prefix `voicekey_`). Returned only by `CreateVoice` when `type` is `"replicated"` and `store` is `false`. Pass this key to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.

{% hr /%}

**expire_time**: `string`

Output only. The timestamp at which a custom stored voice (`store = true`) or replicated voice key (`store = false`) expires. For custom stored voices (`store = true`), this expiration time is extended when the voice is used for speech synthesis or as a `base_voice` in `CreateVoice`. Unset for prebuilt catalog voices (`"prebuilt"`), which do not expire.

{% hr /%}

**display_name**: `string`

Optional. User-provided display name for a stored voice (`store = true`), or the catalog name for a prebuilt voice.

{% hr /%}

{% details %}

{% summary %}

**prompted**: `PromptedVoice`

Parameters for prompted voice generation. Required in `CreateVoice` when `type` is `"prompted"`. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for prompted voices.

{% /summary %}

**input**: {% mark %}required{% /mark %} `string`

The natural-language prompt describing the desired voice, e.g. "A deep, booming male voice of a massive evil ogre in his middle years."

**base_voice**: `string`

Optional. The name or ID of an existing base voice to edit or remix. Use the voice name for prebuilt voices (e.g., `Puck`) or the voice ID for previously created voices (e.g., `voice_abc123`). This can be any prompted or replicated voice that the user has access to. When present, `input` describes relative alterations to make to the base voice.

{% /details %}

{% hr /%}

**language_code**: `string`

Optional. Primary BCP-47 language tag (e.g. "en-US", "fr-FR").

{% hr /%}

**region_code**: `string`

Optional. ISO 3166-1 alpha-2 or UN M.49 geographic region code (e.g. "US", "GB", "001").

{% hr /%}

**accent**: `string`

Optional. Regional accent descriptor (e.g. "American", "British").

{% hr /%}

**persona**: `string`

Optional. Intended persona or character archetype (e.g. "Warm, Friendly", "Narrator").

{% hr /%}

**context**: `string`

Optional. Optimal usage context or domain (e.g. "Conversational", "Audiobook", "News").

{% hr /%}

**gender**: `string`

Optional. Perceived voice gender presentation (e.g. "female", "male", "neutral").

{% hr /%}

{% details %}

{% summary %}

**pitch**: `Pitch`

Optional. Voice pitch classification.

{% /summary %}

Possible values:

- `low`: Lower pitch voice.
- `medium`: Medium pitch voice.
- `high`: Higher pitch voice.

{% /details %}

{% hr /%}

**description**: `string`

Optional. Descriptive summary of vocal timbre, personality, and tone.

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

Output only. Token usage statistics for the voice creation request. Populated only in the response of `CreateVoice` when `type` is `"prompted"`; unset for `"replicated"` and in `GetVoice` and `ListVoices` responses.

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**sample_audio**: `AudioData`

Output only. Sample audio (synthesizer prompt audio) generated for a prompted voice. Populated only in `CreateVoice` and `GetVoice` responses when `type` is `"prompted"`; unset in `ListVoices` responses and for `"replicated"` or `"prebuilt"` voices.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

{% /section %}

## Resources {% class="hide-from-toc" id="resources" %}

### Voice {% class="hide-from-toc" id="Resource:Voice" %}

A voice resource representing either a custom voice (created via
`CreateVoice`) or a prebuilt system voice (returned by `ListVoices`).

**Properties:**

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `VoiceType`

The type of the voice. In `CreateVoice`, must be `"replicated"` or `"prompted"`. In `ListVoices` responses, may also be `"prebuilt"`.

{% /summary %}

Possible values:

- `replicated`: A custom voice replicated from a reference audio sample and speaker consent recording.
- `prompted`: A custom voice generated from a natural-language text prompt (optionally editing or remixing a `base_voice`).
- `prebuilt`: A built-in system voice from Google's voice catalog (e.g., `Puck`, `Charon`). Returned in responses; cannot be specified as the type in `CreateVoice`.

{% /details %}

{% hr /%}

**id**: `string`

Output only. The unique identifier of the voice.

- For Google-managed custom voices (`store = true`), this is a generated ID with prefix `voice_` (for example, `voice_abc123def456`). Pass `voices/{id}` as the `name` in `GetVoice` and `DeleteVoice`, and pass `{id}` directly to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.
- For prebuilt catalog voices (`"prebuilt"` returned by `ListVoices`), this is the speaker name (for example, `Puck` or `Charon`).
- Unset when `CreateVoice` is called with `store = false`.

{% hr /%}

**model**: `string`

Optional. The model used to design or replicate the voice. If omitted in `CreateVoice`, defaults to the latest supported voice design model. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for custom voices (`"prompted"` and `"replicated"`); unset for `"prebuilt"` voices. Created voices can be synthesized across any supported TTS synthesis model.

{% hr /%}

**key**: `string`

Output only. The client-managed voice replication key (with prefix `voicekey_`). Returned only by `CreateVoice` when `type` is `"replicated"` and `store` is `false`. Pass this key to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.

{% hr /%}

{% details %}

{% summary %}

**replicated**: `ReplicatedVoice`

Input only. Parameters for replicated voice generation. Required on input when `type` is `"replicated"`. Not returned in responses.

{% /summary %}

{% details %}

{% summary %}

**source_audio**: {% mark %}required{% /mark %} `AudioData`

The reference audio sample of the speaker's voice to replicate. Must be an unmodified recording of an adult human voice.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

{% details %}

{% summary %}

**consent_audio**: {% mark %}required{% /mark %} `AudioData`

Audio recording of the same speaker reading the required consent phrase, confirming authorization to replicate the voice.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

{% /details %}

{% hr /%}

**expire_time**: `string`

Output only. The timestamp at which a custom stored voice (`store = true`) or replicated voice key (`store = false`) expires. For custom stored voices (`store = true`), this expiration time is extended when the voice is used for speech synthesis or as a `base_voice` in `CreateVoice`. Unset for prebuilt catalog voices (`"prebuilt"`), which do not expire.

{% hr /%}

**display_name**: `string`

Optional. User-provided display name for a stored voice (`store = true`), or the catalog name for a prebuilt voice.

{% hr /%}

{% details %}

{% summary %}

**prompted**: `PromptedVoice`

Parameters for prompted voice generation. Required in `CreateVoice` when `type` is `"prompted"`. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for prompted voices.

{% /summary %}

**input**: {% mark %}required{% /mark %} `string`

The natural-language prompt describing the desired voice, e.g. "A deep, booming male voice of a massive evil ogre in his middle years."

**base_voice**: `string`

Optional. The name or ID of an existing base voice to edit or remix. Use the voice name for prebuilt voices (e.g., `Puck`) or the voice ID for previously created voices (e.g., `voice_abc123`). This can be any prompted or replicated voice that the user has access to. When present, `input` describes relative alterations to make to the base voice.

{% /details %}

{% hr /%}

**language_code**: `string`

Optional. Primary BCP-47 language tag (e.g. "en-US", "fr-FR").

{% hr /%}

**region_code**: `string`

Optional. ISO 3166-1 alpha-2 or UN M.49 geographic region code (e.g. "US", "GB", "001").

{% hr /%}

**accent**: `string`

Optional. Regional accent descriptor (e.g. "American", "British").

{% hr /%}

**persona**: `string`

Optional. Intended persona or character archetype (e.g. "Warm, Friendly", "Narrator").

{% hr /%}

**context**: `string`

Optional. Optimal usage context or domain (e.g. "Conversational", "Audiobook", "News").

{% hr /%}

**gender**: `string`

Optional. Perceived voice gender presentation (e.g. "female", "male", "neutral").

{% hr /%}

{% details %}

{% summary %}

**pitch**: `Pitch`

Optional. Voice pitch classification.

{% /summary %}

Possible values:

- `low`: Lower pitch voice.
- `medium`: Medium pitch voice.
- `high`: Higher pitch voice.

{% /details %}

{% hr /%}

**description**: `string`

Optional. Descriptive summary of vocal timbre, personality, and tone.

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

Output only. Token usage statistics for the voice creation request. Populated only in the response of `CreateVoice` when `type` is `"prompted"`; unset for `"replicated"` and in `GetVoice` and `ListVoices` responses.

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**sample_audio**: `AudioData`

Output only. Sample audio (synthesizer prompt audio) generated for a prompted voice. Populated only in `CreateVoice` and `GetVoice` responses when `type` is `"prompted"`; unset in `ListVoices` responses and for `"replicated"` or `"prebuilt"` voices.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

# Listing voices
Source: https://aistudio.google.com/api-reference/voices/list-voices
Description: Lists custom stored voices owned by the caller (ordered newest first) followed by prebuilt system voices from Google's voice catalog.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/voices`

Lists custom stored voices owned by the caller (ordered newest first)
followed by prebuilt system voices from Google's voice catalog.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**accent**: `array (string)`

Optional. Filter by accent description (e.g. "American", "British"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified accents (OR).

{% hr /%}

**context**: `array (string)`

Optional. Filter by intended context or domain (e.g. "News, Commercial"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified contexts (OR).

{% hr /%}

**gender**: `array (string)`

Optional. Filter by gender presentation (e.g. "female", "male", "neutral"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified genders (OR).

{% hr /%}

**language_code**: `array (string)`

Optional. Filter by BCP-47 language code (e.g. "en-US"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified language codes (OR).

{% hr /%}

**page_size**: `integer`

Optional. The maximum number of voices to return per page. The service may return fewer than this value. If unspecified, at most 50 voices are returned. The maximum value is 1000; values above 1000 are coerced to 1000.

{% hr /%}

**page_token**: `string`

Optional. A page token received from a previous `ListVoices` call. Provide this to retrieve the subsequent page. When paginating, all filter query parameters (`language_code`, `region_code`, `accent`, `persona`, `context`, `gender`, `pitch`, `type`, and `search`) must match the call that returned this token; otherwise the request fails with `INVALID_ARGUMENT`. `page_size` may change between pages.

{% hr /%}

**persona**: `array (string)`

Optional. Filter by vocal persona (e.g. "Warm, Friendly"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified personas (OR).

{% hr /%}

**pitch**: `array (string)`

Optional. Filter by vocal pitch. Accepts `"low"`, `"medium"`, `"high"` (case-insensitive). If multiple values are specified, matches voices with any of the specified pitches (OR).

{% hr /%}

**region_code**: `array (string)`

Optional. Filter by ISO 3166-1 alpha-2 or UN M.49 region code (e.g. "US", "001"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified region codes (OR).

{% hr /%}

**search**: `string`

Optional. Free-text substring search query matched case-insensitively against both `display_name` and `description`. Maximum 2048 bytes.

{% hr /%}

**type**: `array (string)`

Optional. Filter by voice type. Accepts `"prebuilt"`, `"replicated"`, `"prompted"` (case-insensitive). If multiple values are specified, matches voices with any of the specified types (OR).

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET https://generativelanguage.googleapis.com/v1beta/voices \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
response = client.voices.list()
for voice in response.voices or []:
  print(voice.id, voice.display_name)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const response = await ai.voices.list();
for (const voice of response.voices ?? []) {
  console.log(voice.id, voice.display_name);
}
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Voices.List(ctx, operations.ListVoicesRequest{})
    if err != nil {
        log.Fatal(err)
    }

    if res.ListVoicesResponse != nil {
        for _, voice := range res.ListVoicesResponse.Voices {
            if voice.ID != nil && voice.DisplayName != nil {
                fmt.Println(*voice.ID, *voice.DisplayName)
            }
        }
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**voices**: `array (`[`Voice`](/api-reference/voices/list-voices#Resource:Voice)`)`

The voices from the specified collection.

{% hr /%}

**next_page_token**: `string`

A token that can be sent as `page_token` to retrieve the next page. If empty, there are no subsequent pages.

{% /section %}

## Resources {% class="hide-from-toc" id="resources" %}

### Voice {% class="hide-from-toc" id="Resource:Voice" %}

A voice resource representing either a custom voice (created via
`CreateVoice`) or a prebuilt system voice (returned by `ListVoices`).

**Properties:**

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `VoiceType`

The type of the voice. In `CreateVoice`, must be `"replicated"` or `"prompted"`. In `ListVoices` responses, may also be `"prebuilt"`.

{% /summary %}

Possible values:

- `replicated`: A custom voice replicated from a reference audio sample and speaker consent recording.
- `prompted`: A custom voice generated from a natural-language text prompt (optionally editing or remixing a `base_voice`).
- `prebuilt`: A built-in system voice from Google's voice catalog (e.g., `Puck`, `Charon`). Returned in responses; cannot be specified as the type in `CreateVoice`.

{% /details %}

{% hr /%}

**id**: `string`

Output only. The unique identifier of the voice.

- For Google-managed custom voices (`store = true`), this is a generated ID with prefix `voice_` (for example, `voice_abc123def456`). Pass `voices/{id}` as the `name` in `GetVoice` and `DeleteVoice`, and pass `{id}` directly to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.
- For prebuilt catalog voices (`"prebuilt"` returned by `ListVoices`), this is the speaker name (for example, `Puck` or `Charon`).
- Unset when `CreateVoice` is called with `store = false`.

{% hr /%}

**model**: `string`

Optional. The model used to design or replicate the voice. If omitted in `CreateVoice`, defaults to the latest supported voice design model. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for custom voices (`"prompted"` and `"replicated"`); unset for `"prebuilt"` voices. Created voices can be synthesized across any supported TTS synthesis model.

{% hr /%}

**key**: `string`

Output only. The client-managed voice replication key (with prefix `voicekey_`). Returned only by `CreateVoice` when `type` is `"replicated"` and `store` is `false`. Pass this key to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.

{% hr /%}

{% details %}

{% summary %}

**replicated**: `ReplicatedVoice`

Input only. Parameters for replicated voice generation. Required on input when `type` is `"replicated"`. Not returned in responses.

{% /summary %}

{% details %}

{% summary %}

**source_audio**: {% mark %}required{% /mark %} `AudioData`

The reference audio sample of the speaker's voice to replicate. Must be an unmodified recording of an adult human voice.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

{% details %}

{% summary %}

**consent_audio**: {% mark %}required{% /mark %} `AudioData`

Audio recording of the same speaker reading the required consent phrase, confirming authorization to replicate the voice.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

{% /details %}

{% hr /%}

**expire_time**: `string`

Output only. The timestamp at which a custom stored voice (`store = true`) or replicated voice key (`store = false`) expires. For custom stored voices (`store = true`), this expiration time is extended when the voice is used for speech synthesis or as a `base_voice` in `CreateVoice`. Unset for prebuilt catalog voices (`"prebuilt"`), which do not expire.

{% hr /%}

**display_name**: `string`

Optional. User-provided display name for a stored voice (`store = true`), or the catalog name for a prebuilt voice.

{% hr /%}

{% details %}

{% summary %}

**prompted**: `PromptedVoice`

Parameters for prompted voice generation. Required in `CreateVoice` when `type` is `"prompted"`. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for prompted voices.

{% /summary %}

**input**: {% mark %}required{% /mark %} `string`

The natural-language prompt describing the desired voice, e.g. "A deep, booming male voice of a massive evil ogre in his middle years."

**base_voice**: `string`

Optional. The name or ID of an existing base voice to edit or remix. Use the voice name for prebuilt voices (e.g., `Puck`) or the voice ID for previously created voices (e.g., `voice_abc123`). This can be any prompted or replicated voice that the user has access to. When present, `input` describes relative alterations to make to the base voice.

{% /details %}

{% hr /%}

**language_code**: `string`

Optional. Primary BCP-47 language tag (e.g. "en-US", "fr-FR").

{% hr /%}

**region_code**: `string`

Optional. ISO 3166-1 alpha-2 or UN M.49 geographic region code (e.g. "US", "GB", "001").

{% hr /%}

**accent**: `string`

Optional. Regional accent descriptor (e.g. "American", "British").

{% hr /%}

**persona**: `string`

Optional. Intended persona or character archetype (e.g. "Warm, Friendly", "Narrator").

{% hr /%}

**context**: `string`

Optional. Optimal usage context or domain (e.g. "Conversational", "Audiobook", "News").

{% hr /%}

**gender**: `string`

Optional. Perceived voice gender presentation (e.g. "female", "male", "neutral").

{% hr /%}

{% details %}

{% summary %}

**pitch**: `Pitch`

Optional. Voice pitch classification.

{% /summary %}

Possible values:

- `low`: Lower pitch voice.
- `medium`: Medium pitch voice.
- `high`: Higher pitch voice.

{% /details %}

{% hr /%}

**description**: `string`

Optional. Descriptive summary of vocal timbre, personality, and tone.

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

Output only. Token usage statistics for the voice creation request. Populated only in the response of `CreateVoice` when `type` is `"prompted"`; unset for `"replicated"` and in `GetVoice` and `ListVoices` responses.

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**sample_audio**: `AudioData`

Output only. Sample audio (synthesizer prompt audio) generated for a prompted voice. Populated only in `CreateVoice` and `GetVoice` responses when `type` is `"prompted"`; unset in `ListVoices` responses and for `"replicated"` or `"prebuilt"` voices.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

# Getting a voice
Source: https://aistudio.google.com/api-reference/voices/get-voice
Description: Gets a custom stored voice (`store = true`) by resource name.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/voices/{voicesId}`

Gets a custom stored voice (`store = true`) by resource name.
Prebuilt catalog voices (`VOICE_TYPE_PREBUILT`) cannot be retrieved via
`GetVoice`; use `ListVoices` instead.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**voicesId**: {% mark %}required{% /mark %} `string`

The resource name of the custom stored voice to retrieve (for example, `voices/voice_abc123def456`).

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X GET https://generativelanguage.googleapis.com/v1beta/voices/voice_abc123 \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
voice = client.voices.get(id="voice_abc123")
print(voice.id, voice.display_name)
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const voice = await ai.voices.get('voice_abc123');
console.log(voice.id, voice.display_name);
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Voices.Get(ctx, operations.GetVoiceRequest{
        ID: "voice_abc123",
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Voice != nil && res.Voice.ID != nil && res.Voice.DisplayName != nil {
        fmt.Println(*res.Voice.ID, *res.Voice.DisplayName)
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% details %}

{% summary %}

**type**: {% mark %}required{% /mark %} `VoiceType`

The type of the voice. In `CreateVoice`, must be `"replicated"` or `"prompted"`. In `ListVoices` responses, may also be `"prebuilt"`.

{% /summary %}

Possible values:

- `replicated`: A custom voice replicated from a reference audio sample and speaker consent recording.
- `prompted`: A custom voice generated from a natural-language text prompt (optionally editing or remixing a `base_voice`).
- `prebuilt`: A built-in system voice from Google's voice catalog (e.g., `Puck`, `Charon`). Returned in responses; cannot be specified as the type in `CreateVoice`.

{% /details %}

{% hr /%}

**id**: `string`

Output only. The unique identifier of the voice.

- For Google-managed custom voices (`store = true`), this is a generated ID with prefix `voice_` (for example, `voice_abc123def456`). Pass `voices/{id}` as the `name` in `GetVoice` and `DeleteVoice`, and pass `{id}` directly to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.
- For prebuilt catalog voices (`"prebuilt"` returned by `ListVoices`), this is the speaker name (for example, `Puck` or `Charon`).
- Unset when `CreateVoice` is called with `store = false`.

{% hr /%}

**model**: `string`

Optional. The model used to design or replicate the voice. If omitted in `CreateVoice`, defaults to the latest supported voice design model. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for custom voices (`"prompted"` and `"replicated"`); unset for `"prebuilt"` voices. Created voices can be synthesized across any supported TTS synthesis model.

{% hr /%}

**key**: `string`

Output only. The client-managed voice replication key (with prefix `voicekey_`). Returned only by `CreateVoice` when `type` is `"replicated"` and `store` is `false`. Pass this key to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.

{% hr /%}

**expire_time**: `string`

Output only. The timestamp at which a custom stored voice (`store = true`) or replicated voice key (`store = false`) expires. For custom stored voices (`store = true`), this expiration time is extended when the voice is used for speech synthesis or as a `base_voice` in `CreateVoice`. Unset for prebuilt catalog voices (`"prebuilt"`), which do not expire.

{% hr /%}

**display_name**: `string`

Optional. User-provided display name for a stored voice (`store = true`), or the catalog name for a prebuilt voice.

{% hr /%}

{% details %}

{% summary %}

**prompted**: `PromptedVoice`

Parameters for prompted voice generation. Required in `CreateVoice` when `type` is `"prompted"`. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for prompted voices.

{% /summary %}

**input**: {% mark %}required{% /mark %} `string`

The natural-language prompt describing the desired voice, e.g. "A deep, booming male voice of a massive evil ogre in his middle years."

**base_voice**: `string`

Optional. The name or ID of an existing base voice to edit or remix. Use the voice name for prebuilt voices (e.g., `Puck`) or the voice ID for previously created voices (e.g., `voice_abc123`). This can be any prompted or replicated voice that the user has access to. When present, `input` describes relative alterations to make to the base voice.

{% /details %}

{% hr /%}

**language_code**: `string`

Optional. Primary BCP-47 language tag (e.g. "en-US", "fr-FR").

{% hr /%}

**region_code**: `string`

Optional. ISO 3166-1 alpha-2 or UN M.49 geographic region code (e.g. "US", "GB", "001").

{% hr /%}

**accent**: `string`

Optional. Regional accent descriptor (e.g. "American", "British").

{% hr /%}

**persona**: `string`

Optional. Intended persona or character archetype (e.g. "Warm, Friendly", "Narrator").

{% hr /%}

**context**: `string`

Optional. Optimal usage context or domain (e.g. "Conversational", "Audiobook", "News").

{% hr /%}

**gender**: `string`

Optional. Perceived voice gender presentation (e.g. "female", "male", "neutral").

{% hr /%}

{% details %}

{% summary %}

**pitch**: `Pitch`

Optional. Voice pitch classification.

{% /summary %}

Possible values:

- `low`: Lower pitch voice.
- `medium`: Medium pitch voice.
- `high`: Higher pitch voice.

{% /details %}

{% hr /%}

**description**: `string`

Optional. Descriptive summary of vocal timbre, personality, and tone.

{% hr /%}

{% details %}

{% summary %}

**usage**: `Usage`

Output only. Token usage statistics for the voice creation request. Populated only in the response of `CreateVoice` when `type` is `"prompted"`; unset for `"replicated"` and in `GetVoice` and `ListVoices` responses.

{% /summary %}

**total_input_tokens**: `integer`

Number of tokens in the prompt (context).

**initial_input_tokens**: `integer`

Number of input tokens used in the first turn of this interaction.

{% details %}

{% summary %}

**input_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of input token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_cached_tokens**: `integer`

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

{% details %}

{% summary %}

**cached_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of cached token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_output_tokens**: `integer`

Total number of tokens across all the generated responses.

{% details %}

{% summary %}

**output_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of output token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**total_tool_use_tokens**: `integer`

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

{% details %}

{% summary %}

**tool_use_tokens_by_modality**: `array (ModalityTokens)`

A breakdown of tool-use token usage by modality.

{% /summary %}

{% details %}

{% summary %}

**modality**: `ResponseModality`

The modality associated with the token count.

{% /summary %}

Possible values:

- `text`: Indicates the model should return text.
- `image`: Indicates the model should return images.
- `audio`: Indicates the model should return audio.
- `video`: Indicates the model should return video.
- `document`: Indicates the model should return documents.

{% /details %}

**tokens**: `integer`

Number of tokens for the modality.

{% /details %}

**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).

{% details %}

{% summary %}

**grounding_tool_count**: `array (GroundingToolCount)`

Grounding tool count.

{% /summary %}

{% details %}

{% summary %}

**type**: `enum (string)`

The grounding tool type associated with the count.

{% /summary %}

Possible values:

- `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise.
- `google_maps`: Grounding with Google Maps.

{% /details %}

**count**: `integer`

The number of grounding tool counts.

{% /details %}

{% /details %}

{% hr /%}

{% details %}

{% summary %}

**sample_audio**: `AudioData`

Output only. Sample audio (synthesizer prompt audio) generated for a prompted voice. Populated only in `CreateVoice` and `GetVoice` responses when `type` is `"prompted"`; unset in `ListVoices` responses and for `"replicated"` or `"prebuilt"` voices.

{% /summary %}

**mime_type**: {% mark %}required{% /mark %} `string`

The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`).

**data**: {% mark %}required{% /mark %} `string`

The raw audio bytes.

{% /details %}

{% /section %}

# Deleting a voice
Source: https://aistudio.google.com/api-reference/voices/delete-voice
Description: Deletes a custom stored voice (`store = true`) by resource name.

{% callout type="note" %}

This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

{% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/voices/{voicesId}`

Deletes a custom stored voice (`store = true`) by resource name.
Prebuilt catalog voices (`VOICE_TYPE_PREBUILT`) cannot be deleted.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**voicesId**: {% mark %}required{% /mark %} `string`

The resource name of the custom stored voice to delete (for example, `voices/voice_abc123def456`).

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl -X DELETE https://generativelanguage.googleapis.com/v1beta/voices/voice_abc123 \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
client.voices.delete(id="voice_abc123")
```

{% /tab %}

{% tab label="JavaScript" %}

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
await ai.voices.delete('voice_abc123');
```

{% /tab %}

{% tab label="Go" %}

```go
package main

import (
    "context"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.Voices.Delete(ctx, operations.DeleteVoiceRequest{
        ID: "voice_abc123",
    })
    if err != nil {
        log.Fatal(err)
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

{% /section %}

# Models
Source: https://aistudio.google.com/api-reference/models
Description: The models endpoint provides a way for you to programmatically list the available models, and retrieve extended metadata such as supported functionality and context window sizing.

The models endpoint provides a way for you to programmatically list the available models, and retrieve extended metadata such as supported functionality and context window sizing. Read more in [the Models guide](/docs/models).

## Methods {% id="methods" %}

{% table %}

* Method
* HTTP request
---

* [Getting a model](/api-reference/models/get-model)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/models/{model}`

  Gets information about a specific [`Model`](/api-reference/models#Resource:Model) such as its version number, token limits, [parameters](/docs/prompting-strategies#model-parameters) and other metadata.
---

* [Listing models](/api-reference/models/list-models)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/models`

  Lists the [`Model`s](/docs/models) available through the Gemini API.
{% /table %}

## Resources {% id="resources" %}

### Model {% id="Resource:Model" %}

Information about a Generative Language Model.

**Properties:**

**name**: {% mark %}required{% /mark %} `string`

The resource name of the [`Model`](/api-reference/models#Resource:Model). Refer to [Model variants](/docs/models#model-versions) for all allowed values. Format: `models/{model}` with a `{model}` naming convention of:

- "{base_model_id}-{version}"

Examples:

- `models/gemini-1.5-flash-001`

{% hr /%}

**baseModelId**: {% mark %}required{% /mark %} `string`

The name of the base model, pass this to the generation request. Examples:

- `gemini-1.5-flash`

{% hr /%}

**version**: {% mark %}required{% /mark %} `string`

The version number of the model. This represents the major version (`1.0` or `1.5`)

{% hr /%}

**displayName**: `string`

The human-readable name of the model. E.g. "Gemini 1.5 Flash". The name can be up to 128 characters long and can consist of any UTF-8 characters.

{% hr /%}

**description**: `string`

A short description of the model.

{% hr /%}

**inputTokenLimit**: `integer`

Maximum number of input tokens allowed for this model.

{% hr /%}

**outputTokenLimit**: `integer`

Maximum number of output tokens available for this model.

{% hr /%}

**supportedGenerationMethods**: `array (string)`

The model's supported generation methods. The corresponding API method names are defined as Pascal case strings, such as `generateMessage` and `generateContent`.

{% hr /%}

**temperature**: `number`

Controls the randomness of the output. Values can range over `[0.0,max_temperature]`, inclusive. A higher value will produce responses that are more varied, while a value closer to `0.0` will typically result in less surprising responses from the model. This value specifies default to be used by the backend while making the call to the model.

{% hr /%}

**maxTemperature**: `number`

The maximum temperature this model can use.

{% hr /%}

**topP**: `number`

For [Nucleus sampling](/docs/prompting-strategies#model-parameters). Nucleus sampling considers the smallest set of tokens whose probability sum is at least `top_p`. This value specifies default to be used by the backend while making the call to the model.

{% hr /%}

**topK**: `integer`

For Top-k sampling. Top-k sampling considers the set of `top_k` most probable tokens. This value specifies default to be used by the backend while making the call to the model. If empty, indicates the model doesn't use top-k sampling, and `top_k` isn't allowed as a generation parameter.

{% hr /%}

**thinking**: `boolean`

Whether the model supports thinking.

# Getting a model
Source: https://aistudio.google.com/api-reference/models/get-model
Description: Gets information about a specific `Model` such as its version number, token limits, [parameters](/docs/prompting-strategies#model-parameters) and other metadata.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/models/{model}`

Gets information about a specific [`Model`](/api-reference/models#Resource:Model) such as its version number, token
limits,
[parameters](/docs/prompting-strategies#model-parameters)
and other metadata. Refer to the [Gemini models
guide](/docs/models) for detailed
model information.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**model**: {% mark %}required{% /mark %} `string`

The model ID, for example `gemini-2.5-flash`. Forms the resource name `models/{model}`.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash?key=$GEMINI_API_KEY
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()
model_info = client.models.get(model="gemini-3.8-flash")
print(model_info)
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

modelInfo, err := client.Models.Get(ctx, "gemini-3.8-flash", nil)
if err != nil {
    log.Fatal(err)
}

fmt.Println(modelInfo)
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**name**: {% mark %}required{% /mark %} `string`

The resource name of the [`Model`](/api-reference/models#Resource:Model). Refer to [Model variants](/docs/models#model-versions) for all allowed values. Format: `models/{model}` with a `{model}` naming convention of:

- "{base_model_id}-{version}"

Examples:

- `models/gemini-1.5-flash-001`

{% hr /%}

**baseModelId**: {% mark %}required{% /mark %} `string`

The name of the base model, pass this to the generation request. Examples:

- `gemini-1.5-flash`

{% hr /%}

**version**: {% mark %}required{% /mark %} `string`

The version number of the model. This represents the major version (`1.0` or `1.5`)

{% hr /%}

**displayName**: `string`

The human-readable name of the model. E.g. "Gemini 1.5 Flash". The name can be up to 128 characters long and can consist of any UTF-8 characters.

{% hr /%}

**description**: `string`

A short description of the model.

{% hr /%}

**inputTokenLimit**: `integer`

Maximum number of input tokens allowed for this model.

{% hr /%}

**outputTokenLimit**: `integer`

Maximum number of output tokens available for this model.

{% hr /%}

**supportedGenerationMethods**: `array (string)`

The model's supported generation methods. The corresponding API method names are defined as Pascal case strings, such as `generateMessage` and `generateContent`.

{% hr /%}

**temperature**: `number`

Controls the randomness of the output. Values can range over `[0.0,max_temperature]`, inclusive. A higher value will produce responses that are more varied, while a value closer to `0.0` will typically result in less surprising responses from the model. This value specifies default to be used by the backend while making the call to the model.

{% hr /%}

**maxTemperature**: `number`

The maximum temperature this model can use.

{% hr /%}

**topP**: `number`

For [Nucleus sampling](/docs/prompting-strategies#model-parameters). Nucleus sampling considers the smallest set of tokens whose probability sum is at least `top_p`. This value specifies default to be used by the backend while making the call to the model.

{% hr /%}

**topK**: `integer`

For Top-k sampling. Top-k sampling considers the set of `top_k` most probable tokens. This value specifies default to be used by the backend while making the call to the model. If empty, indicates the model doesn't use top-k sampling, and `top_k` isn't allowed as a generation parameter.

{% hr /%}

**thinking**: `boolean`

Whether the model supports thinking.

{% /section %}

# Listing models
Source: https://aistudio.google.com/api-reference/models/list-models
Description: Lists the [`Model`s](/docs/models) available through the Gemini API.

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/models`

Lists the [`Model`s](/docs/models)
available through the Gemini API.

{% two-column-layout %}

{% left-column %}

## Parameters {% class="hide-from-toc" id="parameters" %}

{% section class="api-ref-property-list" %}

**pageSize**: `integer`

The maximum number of `Models` to return (per page). If unspecified, 50 models will be returned per page. This method returns at most 1000 models per page, even if you pass a larger page_size.

{% hr /%}

**pageToken**: `string`

A page token, received from a previous `ListModels` call. Provide the `page_token` returned by one request as an argument to the next request to retrieve the next page. When paginating, all other parameters provided to `ListModels` must match the call that provided the page token.

{% /section %}

{% /left-column %}

{% right-column class="sticky" %}

**Example request** {% class="example-heading" %}

{% tabs %}

{% tab label="REST" %}

```sh
curl https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY
```

{% /tab %}

{% tab label="Python" %}

```python
from google import genai

client = genai.Client()

print("List of models that support generateContent:\n")
for m in client.models.list():
  for action in m.supported_actions:
    if action == "generateContent":
      print(m.name)

print("List of models that support embedContent:\n")
for m in client.models.list():
  for action in m.supported_actions:
    if action == "embedContent":
      print(m.name)
```

{% /tab %}

{% tab label="Go" %}

```go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  os.Getenv("GEMINI_API_KEY"),
    Backend: genai.BackendGeminiAPI,
})
if err != nil {
    log.Fatal(err)
}

// Retrieve the list of models.
models, err := client.Models.List(ctx, &genai.ListModelsConfig{})
if err != nil {
    log.Fatal(err)
}

fmt.Println("List of models that support generateContent:")
for _, m := range models.Items {
    for _, action := range m.SupportedActions {
        if action == "generateContent" {
            fmt.Println(m.Name)
            break
        }
    }
}

fmt.Println("\nList of models that support embedContent:")
for _, m := range models.Items {
    for _, action := range m.SupportedActions {
        if action == "embedContent" {
            fmt.Println(m.Name)
            break
        }
    }
}
```

{% /tab %}

{% /tabs %}

{% /right-column %}

{% /two-column-layout %}

## Response {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}

**models**: `array (`[`Model`](/api-reference/models/list-models#Resource:Model)`)`

The returned Models.

{% hr /%}

**nextPageToken**: `string`

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

{% /section %}

## Resources {% class="hide-from-toc" id="resources" %}

### Model {% class="hide-from-toc" id="Resource:Model" %}

Information about a Generative Language Model.

**Properties:**

**name**: {% mark %}required{% /mark %} `string`

The resource name of the [`Model`](/api-reference/models/list-models#Resource:Model). Refer to [Model variants](/docs/models#model-versions) for all allowed values. Format: `models/{model}` with a `{model}` naming convention of:

- "{base_model_id}-{version}"

Examples:

- `models/gemini-1.5-flash-001`

{% hr /%}

**baseModelId**: {% mark %}required{% /mark %} `string`

The name of the base model, pass this to the generation request. Examples:

- `gemini-1.5-flash`

{% hr /%}

**version**: {% mark %}required{% /mark %} `string`

The version number of the model. This represents the major version (`1.0` or `1.5`)

{% hr /%}

**displayName**: `string`

The human-readable name of the model. E.g. "Gemini 1.5 Flash". The name can be up to 128 characters long and can consist of any UTF-8 characters.

{% hr /%}

**description**: `string`

A short description of the model.

{% hr /%}

**inputTokenLimit**: `integer`

Maximum number of input tokens allowed for this model.

{% hr /%}

**outputTokenLimit**: `integer`

Maximum number of output tokens available for this model.

{% hr /%}

**supportedGenerationMethods**: `array (string)`

The model's supported generation methods. The corresponding API method names are defined as Pascal case strings, such as `generateMessage` and `generateContent`.

{% hr /%}

**temperature**: `number`

Controls the randomness of the output. Values can range over `[0.0,max_temperature]`, inclusive. A higher value will produce responses that are more varied, while a value closer to `0.0` will typically result in less surprising responses from the model. This value specifies default to be used by the backend while making the call to the model.

{% hr /%}

**maxTemperature**: `number`

The maximum temperature this model can use.

{% hr /%}

**topP**: `number`

For [Nucleus sampling](/docs/prompting-strategies#model-parameters). Nucleus sampling considers the smallest set of tokens whose probability sum is at least `top_p`. This value specifies default to be used by the backend while making the call to the model.

{% hr /%}

**topK**: `integer`

For Top-k sampling. Top-k sampling considers the set of `top_k` most probable tokens. This value specifies default to be used by the backend while making the call to the model. If empty, indicates the model doesn't use top-k sampling, and `top_k` isn't allowed as a generation parameter.

{% hr /%}

**thinking**: `boolean`

Whether the model supports thinking.

# All methods
Source: https://aistudio.google.com/api-reference/all-methods
Description: Every REST method in the Gemini API, grouped by reference page.

Every REST method in the Gemini API, grouped by reference page.
All paths below are relative to `https://generativelanguage.googleapis.com`.

## Gemini Interactions API {% id="interactions-api" %}

See the [Gemini Interactions API reference](/api-reference/interactions-api) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`CreateInteraction`](/api-reference/interactions-api/create-interaction)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/interactions`

  Creates a new interaction.
---

* [`cancelInteractionById`](/api-reference/interactions-api/cancel-interaction-by-id)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/interactions/{id}/cancel`

  Cancels an interaction by id.
---

* [`getInteractionById`](/api-reference/interactions-api/get-interaction-by-id)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/interactions/{id}`

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

* [`deleteInteraction`](/api-reference/interactions-api/delete-interaction)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/interactions/{id}`

  Deletes the interaction by id.
{% /table %}

## Gemini Agents API {% id="agents" %}

See the [Gemini Agents API reference](/api-reference/agents) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`CreateAgent`](/api-reference/agents/create-agent)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/agents`

  Creates a new Agent (Typed version for SDK).
---

* [`ListAgents`](/api-reference/agents/list-agents)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/agents`

  Lists all Agents.
---

* [`GetAgent`](/api-reference/agents/get-agent)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/agents/{agentsId}`

  Gets a specific Agent.
---

* [`DeleteAgent`](/api-reference/agents/delete-agent)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/agents/{agentsId}`

  Deletes an Agent.
{% /table %}

## Gemini Webhooks API {% id="webhooks" %}

See the [Gemini Webhooks API reference](/api-reference/webhooks) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`CreateWebhook`](/api-reference/webhooks/create-webhook)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/webhooks`

  Creates a new Webhook.
---

* [`PingWebhook`](/api-reference/webhooks/ping-webhook)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/webhooks/{id}:ping`

  Sends a ping event to a Webhook.
---

* [`RotateSigningSecret`](/api-reference/webhooks/rotate-signing-secret)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/webhooks/{id}:rotateSigningSecret`

  Generates a new signing secret for a Webhook.
---

* [`ListWebhooks`](/api-reference/webhooks/list-webhooks)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/webhooks`

  Lists all Webhooks.
---

* [`GetWebhook`](/api-reference/webhooks/get-webhook)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/webhooks/{id}`

  Gets a specific Webhook.
---

* [`UpdateWebhook`](/api-reference/webhooks/update-webhook)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/webhooks/{id}`

  Updates an existing Webhook.
---

* [`DeleteWebhook`](/api-reference/webhooks/delete-webhook)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/webhooks/{id}`

  Deletes a Webhook.
{% /table %}

## Gemini Triggers API {% id="triggers" %}

See the [Gemini Triggers API reference](/api-reference/triggers) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`CreateTrigger`](/api-reference/triggers/create-trigger)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/triggers`

  Creates a new trigger that will invoke the specified agent on the given cron schedule.
---

* [`RunTrigger`](/api-reference/triggers/run-trigger)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/triggers/{triggerId}/executions`

  Runs a trigger immediately.
---

* [`ListTriggers`](/api-reference/triggers/list-triggers)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/triggers`

  Lists triggers for a project.
---

* [`GetTrigger`](/api-reference/triggers/get-trigger)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/triggers/{id}`

  Gets details of a single trigger.
---

* [`ListTriggerExecutions`](/api-reference/triggers/list-trigger-executions)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/triggers/{triggerId}/executions`

  Lists executions for a trigger.
---

* [`UpdateTrigger`](/api-reference/triggers/update-trigger)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/triggers/{id}`

  Updates a trigger.
---

* [`DeleteTrigger`](/api-reference/triggers/delete-trigger)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/triggers/{id}`

  Deletes a trigger.
{% /table %}

## Gemini Environments API {% id="environments" %}

See the [Gemini Environments API reference](/api-reference/environments) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`CreateEnvironment`](/api-reference/environments/create-environment)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/environments`

  Creates an environment.
---

* [`ListEnvironments`](/api-reference/environments/list-environments)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/environments`

  Lists environments.
---

* [`GetEnvironmentFiles`](/api-reference/environments/get-environment-files)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/environments/{environment}/files/{path}`

  Retrieves file metadata or directory contents from an environment's snapshot.
---

* [`GetEnvironment`](/api-reference/environments/get-environment)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/environments/{id}`

  Gets an environment.
---

* [`StartEnvironmentFileUpload`](/api-reference/environments/start-environment-file-upload)
* {% mark class="http-put" %}{% icon name="north_east" /%}`PUT`{% /mark %} `/upload/v1beta/environments/{environment}/files/{path}`

  Starts a resumable upload session for a file in an environment workspace.
---

* [`DeleteEnvironment`](/api-reference/environments/delete-environment)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/environments/{id}`

  Deletes an environment.
{% /table %}

## Gemini Voices API {% id="voices" %}

See the [Gemini Voices API reference](/api-reference/voices) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`CreateVoice`](/api-reference/voices/create-voice)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/voices`

  Creates a custom voice from a natural-language prompt (`VOICE_TYPE_PROMPTED`) or from reference and consent audio recordings (`VOICE_TYPE_REPLICATED`).
---

* [`ListVoices`](/api-reference/voices/list-voices)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/voices`

  Lists custom stored voices owned by the caller (ordered newest first) followed by prebuilt system voices from Google's voice catalog.
---

* [`GetVoice`](/api-reference/voices/get-voice)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/voices/{voicesId}`

  Gets a custom stored voice (`store = true`) by resource name.
---

* [`DeleteVoice`](/api-reference/voices/delete-voice)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/voices/{voicesId}`

  Deletes a custom stored voice (`store = true`) by resource name.
{% /table %}

## Gemini Credentials API {% id="credentials" %}

See the [Gemini Credentials API reference](/api-reference/credentials) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`CreateCredential`](/api-reference/credentials/create-credential)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/credentials`

  Creates a new credential.
---

* [`ListCredentials`](/api-reference/credentials/list-credentials)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/credentials`

  Lists credentials.
---

* [`GetCredential`](/api-reference/credentials/get-credential)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/credentials/{id}`

  Gets a credential by ID.
---

* [`UpdateCredential`](/api-reference/credentials/update-credential)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/credentials/{id}`

  Updates a credential.
---

* [`DeleteCredential`](/api-reference/credentials/delete-credential)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/credentials/{id}`

  Deletes a credential.
{% /table %}

## Generating content {% id="generate-content" %}

See the [Generating content reference](/api-reference/generate-content) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`GenerateContent`](/api-reference/generate-content/generate-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:generateContent`

  Generates a model response given an input `GenerateContentRequest`.
---

* [`StreamGenerateContent`](/api-reference/generate-content/stream-generate-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:streamGenerateContent`

  Generates a [streamed response](/docs/text-generation#streaming-responses) from the model given an input `GenerateContentRequest`.
---

* [`CreateToken`](/api-reference/generate-content/create-token)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/auth_tokens`

  Creates a token that can be used to constrain the behavior of a BidiGenerateContent session.
{% /table %}

## Models {% id="models" %}

See the [Models reference](/api-reference/models) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`GetModel`](/api-reference/models/get-model)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/models/{model}`

  Gets information about a specific `Model` such as its version number, token limits, [parameters](/docs/prompting-strategies#model-parameters) and other metadata.
---

* [`ListModels`](/api-reference/models/list-models)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/models`

  Lists the [`Model`s](/docs/models) available through the Gemini API.
{% /table %}

## Batch API {% id="batch-api" %}

See the [Batch API reference](/api-reference/batch-api) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`BatchGenerateContent`](/api-reference/batch-api/batch-generate-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:batchGenerateContent`

  Enqueues a batch of `GenerateContent` requests for batch processing.
---

* [`AsyncBatchEmbedContent`](/api-reference/batch-api/async-batch-embed-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:asyncBatchEmbedContent`

  Enqueues a batch of `EmbedContent` requests for batch processing.
---

* [`GetBatch`](/api-reference/batch-api/get-batch)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/batches/{generateContentBatch}`

  Gets the latest state of a long-running operation.
---

* [`ListBatches`](/api-reference/batch-api/list-batches)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/batches`

  Lists operations that match the specified filter in the request.
---

* [`CancelBatch`](/api-reference/batch-api/cancel-batch)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/batches/{generateContentBatch}:cancel`

  Starts asynchronous cancellation on a long-running operation.
---

* [`DeleteBatch`](/api-reference/batch-api/delete-batch)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/batches/{generateContentBatch}`

  Deletes a long-running operation.
---

* [`UpdateGenerateContentBatch`](/api-reference/batch-api/update-generate-content-batch)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/batches/{generateContentBatch}:updateGenerateContentBatch`

  Updates a batch of GenerateContent requests for batch processing.
---

* [`UpdateEmbedContentBatch`](/api-reference/batch-api/update-embed-content-batch)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/batches/{generateContentBatch}:updateEmbedContentBatch`

  Updates a batch of EmbedContent requests for batch processing.
{% /table %}

## Using files {% id="files" %}

See the [Using files reference](/api-reference/files) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`GetFile`](/api-reference/files/get-file)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/files/{file}`

  Gets the metadata for the given `File`.
---

* [`ListFiles`](/api-reference/files/list-files)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/files`

  Lists the metadata for `File`s owned by the requesting project.
---

* [`DeleteFile`](/api-reference/files/delete-file)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/files/{file}`

  Deletes the `File`.
---

* [`RegisterFiles`](/api-reference/files/register-files)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/files:register`

  Registers a Google Cloud Storage files with FileService.
---

* [`CreateFile`](/api-reference/files/create-file)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/files`

  Creates a `File`.
{% /table %}

## Counting tokens {% id="tokens" %}

See the [Counting tokens reference](/api-reference/tokens) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`CountTokens`](/api-reference/tokens/count-tokens)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:countTokens`

  Runs a model's tokenizer on input `Content` and returns the token count.
{% /table %}

## Caching {% id="caching" %}

See the [Caching reference](/api-reference/caching) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`CreateCachedContent`](/api-reference/caching/create-cached-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/cachedContents`

  Creates CachedContent resource.
---

* [`ListCachedContents`](/api-reference/caching/list-cached-contents)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/cachedContents`

  Lists CachedContents.
---

* [`GetCachedContent`](/api-reference/caching/get-cached-content)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/cachedContents/{id}`

  Reads CachedContent resource.
---

* [`UpdateCachedContent`](/api-reference/caching/update-cached-content)
* {% mark class="http-patch" %}{% icon name="north_east" /%}`PATCH`{% /mark %} `/v1beta/cachedContents/{id}`

  Updates CachedContent resource (only expiration is updatable).
---

* [`DeleteCachedContent`](/api-reference/caching/delete-cached-content)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/cachedContents/{id}`

  Deletes CachedContent resource.
{% /table %}

## Embeddings {% id="embeddings" %}

See the [Embeddings reference](/api-reference/embeddings) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`EmbedContent`](/api-reference/embeddings/embed-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:embedContent`

  Generates a text embedding vector from the input `Content` using the specified [Gemini Embedding model](/docs/models#specialized-task-models).
---

* [`BatchEmbedContents`](/api-reference/embeddings/batch-embed-contents)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:batchEmbedContents`

  Generates multiple embedding vectors from the input `Content` which consists of a batch of strings represented as `EmbedContentRequest` objects.
---

* [`AsyncBatchEmbedContent`](/api-reference/embeddings/async-batch-embed-content)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/models/{model}:asyncBatchEmbedContent`

  Enqueues a batch of `EmbedContent` requests for batch processing.
{% /table %}

## File Search Stores {% id="file-search-file-search-stores" %}

See the [File Search Stores reference](/api-reference/file-search/file-search-stores) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`CreateFileSearchStore`](/api-reference/file-search/file-search-stores/create-file-search-store)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/fileSearchStores`

  Creates an empty `FileSearchStore`.
---

* [`DeleteFileSearchStore`](/api-reference/file-search/file-search-stores/delete-file-search-store)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}`

  Deletes a `FileSearchStore`.
---

* [`GetFileSearchStore`](/api-reference/file-search/file-search-stores/get-file-search-store)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}`

  Gets information about a specific `FileSearchStore`.
---

* [`ListFileSearchStores`](/api-reference/file-search/file-search-stores/list-file-search-stores)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores`

  Lists all `FileSearchStores` owned by the user.
---

* [`ImportFile`](/api-reference/file-search/file-search-stores/import-file)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}:importFile`

  Imports a `File` from File Service to a `FileSearchStore`.
---

* [`GetFileSearchStoreOperation`](/api-reference/file-search/file-search-stores/get-file-search-store-operation)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}/operations/{operation}`

  Gets the latest state of a long-running operation.
---

* [`GetFileSearchStoreUploadOperation`](/api-reference/file-search/file-search-stores/get-file-search-store-upload-operation)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStoresId}/upload/operations/{operationsId}`

  Gets the latest state of a long-running operation.
---

* [`UploadToFileSearchStore`](/api-reference/file-search/file-search-stores/upload-to-file-search-store)
* {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}:uploadToFileSearchStore`

  Uploads data to a FileSearchStore, preprocesses and chunks before storing it in a FileSearchStore Document.
{% /table %}

## Documents {% id="file-search-documents" %}

See the [Documents reference](/api-reference/file-search/documents) for request and response details.

{% table %}

* Method
* HTTP request
---

* [`DeleteDocument`](/api-reference/file-search/documents/delete-document)
* {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}/documents/{document}`

  Deletes a `Document`.
---

* [`GetDocument`](/api-reference/file-search/documents/get-document)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}/documents/{document}`

  Gets information about a specific `Document`.
---

* [`ListDocuments`](/api-reference/file-search/documents/list-documents)
* {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/fileSearchStores/{fileSearchStore}/documents`

  Lists all `Document`s in a `Corpus`.
{% /table %}