spb/doc-api

1<br />23> [!IMPORTANT]4> **Using the Interactions API?** This page covers the new way to use the Gemini API, supporting server-side history, background processing, and agentic workflows. The Interactions API is currently in Beta and subject to [breaking changes](https://ai.google.dev/gemini-api/docs/interactions-breaking-changes-may-2026).5>6> For stable production, we recommend you continue to use the `generateContent` API. If you are transitioning, see the [Migration Guide](https://ai.google.dev/gemini-api/docs/migrate-to-interactions).78The **Interactions API** is the new recommended standard for building with Gemini. It is optimized for agentic workflows, server-side state management, and complex multi-modal, multi-turn conversations. The original [`generateContent`](https://ai.google.dev/gemini-api/docs/interactions/text-generation) API remains fully supported.910## Why use the Interactions API?1112- **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`.13- **Observable execution steps**: Typed steps make it easy to debug complex flows and render UI for intermediate events (like thoughts or search widgets).14- **Built for agentic workflows**: Native support for multi-step tool use, orchestration, and complex reasoning flows through typed execution steps.15- **Long-running and background tasks** : Supports offloading time-intensive operations to background processes using `background=true`. This is supported for both models (such as [Deep Think](https://ai.google.dev/gemini-api/docs/interactions/thinking)) and agents (such as [Deep Research](https://ai.google.dev/gemini-api/docs/interactions/deep-research)).16- **Access to new models and capabilities**: Going forward, new models beyond the core mainline family, along with new agentic capabilities and tools, will launch exclusively on the Interactions API.1718**Use the Interactions API** if you're starting a new project, building agentic applications, or need server-side conversation management. **Use [`generateContent`](https://ai.google.dev/gemini-api/docs/interactions/text-generation)** if you have an existing integration that works for your needs, or if you require a feature that is [not yet available](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview#limitations) in the Interactions API, such as the Batch API or explicit caching.1920## Get started2122- **Set up your coding agent** : Connect to the **Gemini Docs MCP** and install the `gemini-interactions-api` skill to give your assistant direct access to the latest developer docs and best practices. [Set up your coding agent →](https://ai.google.dev/gemini-api/docs/coding-agents)23- **Migrate from `generateContent`** : If you have an existing integration, follow the [Migration Guide](https://ai.google.dev/gemini-api/docs/migrate-to-interactions) to transition to the Interactions API.24- **Try the quickstart** : Get started with a minimal working example in the [Interactions API quickstart](https://ai.google.dev/gemini-api/docs/interactions/quickstart).2526### Feature Guides2728Explore 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:2930- [Text generation](https://ai.google.dev/gemini-api/docs/interactions/text-generation)31- [Image generation](https://ai.google.dev/gemini-api/docs/interactions/image-generation)32- [Image understanding](https://ai.google.dev/gemini-api/docs/interactions/image-understanding)33- [Audio understanding](https://ai.google.dev/gemini-api/docs/interactions/audio)34- [Video understanding](https://ai.google.dev/gemini-api/docs/interactions/video-understanding)35- [Document processing](https://ai.google.dev/gemini-api/docs/interactions/document-processing)36- [Function calling](https://ai.google.dev/gemini-api/docs/interactions/function-calling)37- [Structured output](https://ai.google.dev/gemini-api/docs/interactions/structured-output)38- [Deep Research Agent](https://ai.google.dev/gemini-api/docs/interactions/deep-research)39- [Flex inference](https://ai.google.dev/gemini-api/docs/interactions/flex-inference)40- [Priority inference](https://ai.google.dev/gemini-api/docs/interactions/priority-inference)41- [Streaming](https://ai.google.dev/gemini-api/docs/interactions/streaming)4243## How the Interactions API works4445The 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.4647When you make a call to48[`interactions.create`](https://ai.google.dev/api/interactions-api#CreateInteraction), you are49creating a new `Interaction` resource.5051### Access outputs with SDK convenience properties5253While the Interactions API returns a structured timeline of execution steps54(such as thoughts, search queries, and function calls), you don't need to55manually traverse the steps to get the final model response.5657The Google GenAI SDKs provide convenience properties directly58on the returned `Interaction` object to access the outputs for different59modalities:6061| SDK convenience property | Return Type | Description |62|---|---|---|63| **`interaction.output_text`** | String | Returns the last text blocks in the model's response. If the response is split across multiple consecutive `TextContent` blocks, it automatically joins them. 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. |64| **`interaction.output_image`** | ImageContent or `None` | Returns the last image block generated by the model in the current request. |65| **`interaction.output_audio`** | AudioContent or `None` | Returns the last audio block generated by the model in the current request. |6667For advanced use cases---such as rendering intermediate thinking processes,68inspecting step-by-step tool calls, or debugging---you can still inspect and69traverse the raw `interaction.steps` timeline manually.7071### Server-side state management7273You can use the `id` of a completed interaction in a subsequent call using the74`previous_interaction_id` parameter to continue the conversation. The server75uses this ID to retrieve the conversation history, saving you from having to76resend the entire chat history.7778The `previous_interaction_id` parameter preserves only the conversation history (inputs and outputs)79using `previous_interaction_id`. The other parameters are **interaction-scoped**80and apply only to the specific interaction you are currently generating:8182- `tools`83- `system_instruction`84- `generation_config` (including `thinking_level`, `temperature`, etc.)8586This means you must re-specify these parameters in each new interaction if you87want them to apply. This server-side state management is optional; you can also88operate in stateless mode by sending the full conversation history in each89request.9091### Background execution9293For long-running tasks, you can run interactions in the background by setting94`background=true` in your request. This is supported for both:9596- **Models** : Useful for tasks that take longer to process, such as those using [thinking](https://ai.google.dev/gemini-api/docs/interactions/thinking).97- **Agents** : Required for long-running agent workflows like [Deep Research](https://ai.google.dev/gemini-api/docs/interactions/deep-research).9899When running in the background:100101- You must set `store=true` (the default) because the system needs to store the interaction resource so you can retrieve it later.102- The initial call to `interactions.create` returns immediately with a status of `in_progress`.103- You can retrieve the status and results of the interaction by calling `interactions.get` with the interaction ID, or by configuring [webhooks](https://ai.google.dev/gemini-api/docs/interactions/webhooks) to receive notifications when the interaction completes.104- You can also [stream](https://ai.google.dev/gemini-api/docs/interactions/streaming#streaming-background) the interaction to receive progress updates.105106### Data storage and retention107108By default, the API stores all Interaction objects (`store=true`) in order to109simplify use of server-side state management features (with110`previous_interaction_id`), background execution (using `background=true`) and111observability purposes.112113- **Paid Tier** : The system retains interactions for **55 days**.114- **Free Tier** : The system retains interactions for **1 day**.115116If you don't want this, you can117set `store=false` in your request. This control is separate from state118management; you can opt out of storage for any interaction. However, note that119`store=false` is incompatible with `background=true` and prevents using120`previous_interaction_id` for subsequent turns.121122You can delete stored interactions at any time using the delete method found in123the [API Reference](https://ai.google.dev/api/interactions-api). You can only delete interactions if124you know the interaction ID.125126After the retention period expires, your data will be127deleted automatically.128129The system processes Interaction objects according to the [terms](https://ai.google.dev/gemini-api/terms).130131## Best practices132133- **Cache hit rate** : Using `previous_interaction_id` to continue conversations allows the system to more easily utilize implicit caching for the conversation history, which improves performance and reduces costs.134- **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`.135136## Supported models \& agents137138| Model Name | Type | Model ID |139|---|---|---|140| Gemini 3.5 Flash | Model | `gemini-3.5-flash` |141| Gemini 3.1 Flash-Lite | Model | `gemini-3.1-flash-lite` |142| Gemini 3.1 Pro Preview | Model | `gemini-3.1-pro-preview` |143| Gemini 3 Flash Preview | Model | `gemini-3-flash-preview` |144| Gemini 2.5 Pro | Model | `gemini-2.5-pro` |145| Gemini 2.5 Flash | Model | `gemini-2.5-flash` |146| Gemini 2.5 Flash-lite | Model | `gemini-2.5-flash-lite` |147| Lyria 3 Clip Preview | Model | `lyria-3-clip-preview` |148| Lyria 3 Pro Preview | Model | `lyria-3-pro-preview` |149| Deep Research Preview | Agent | `deep-research-pro-preview-12-2025` |150| Deep Research Preview | Agent | `deep-research-preview-04-2026` |151| Deep Research Preview | Agent | `deep-research-max-preview-04-2026` |152153## SDKs154155You can use latest version of the Google GenAI SDKs in order to access156Interactions API.157158- On Python, this is `google-genai` package from `1.55.0` version onwards.159- On JavaScript, this is `@google/genai` package from `1.33.0` version onwards.160161You can learn more about how to install the SDKs on162[Libraries](https://ai.google.dev/gemini-api/docs/libraries) page.163164## Limitations165166- **Beta status**: The Interactions API is in beta/preview. Features and schemas may change.167- **Remote MCP**: Gemini 3 does not support remote MCP, this is coming soon.168169The following features are supported by the170[`generateContent`](https://ai.google.dev/gemini-api/docs/interactions/text-generation) API but are **not yet171available** in the Interactions API:172173- **[Video metadata](https://ai.google.dev/gemini-api/docs/interactions/video-understanding)** : The `video_metadata` field, used to set clipping intervals and custom frame rates for video understanding.174- **[Batch API](https://ai.google.dev/gemini-api/docs/batch-api)**175- **[Automatic function calling (Python)](https://ai.google.dev/gemini-api/docs/function-calling?example=meeting#automatic_function_calling_python_only)**176- **[Explicit caching](https://ai.google.dev/gemini-api/docs/interactions/caching)** : Note that server-side implicit caching is available in the Interactions API via `previous_interaction_id`.177178## Breaking changes179180The Interactions API is currently in an early beta stage. We are actively181developing and refining the API capabilities, resource schemas, and SDK182interfaces based on real-world usage and developer feedback. As a result, **breaking changes may occur**.183184Existing breaking changes:185186- **Steps schema**: A new steps array replaces the outputs array, providing a structured timeline of each interaction turn.187188To learn about the most recent breaking change and understand how to migrate, see [Breaking changes migration guide (May 2026)](https://ai.google.dev/gemini-api/docs/interactions-breaking-changes-may-2026).189190Other potential updates may include changes to schemas for input and output, SDK method signatures and object structures, specific feature behaviors.191192For production workloads, you should continue to use the standard193[`generateContent`](https://ai.google.dev/gemini-api/docs/interactions/text-generation) API. It remains the194recommended path for stable deployments, and we will continue to actively develop and maintain it.195196## Feedback197198Your feedback is critical to the development of the Interactions API.199Share your thoughts, report bugs, or request features on our200[Google AI Developer Community Forum](https://discuss.ai.google.dev/c/gemini-api/4).201202## What's next203204- Try the [Interactions API quickstart notebook](https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_interactions_api.ipynb).205- Learn about [Streaming interactions](https://ai.google.dev/gemini-api/docs/interactions/streaming) for real-time response handling.206- Learn more about the [Gemini Deep Research Agent](https://ai.google.dev/gemini-api/docs/interactions/deep-research).