Interactions API | Gemini API | Google AI for Developers

Skip to main content

English

Deutsch

Español – América Latina

Français

Indonesia

Italiano

Polski

Português – Brasil

Shqip

Tiếng Việt

Türkçe

Русский

עברית

العربيّة

فارسی

हिंदी

বাংলা

ภาษาไทย

中文 – 简体

中文 – 繁體

日本語

한국어

Get API key

Cookbook

Community

Sign in

The Interactions API is now generally available. We recommend using this API for access to all the latest features and models.

Home

Gemini API

Docs

Send feedback

Interactions API

The Interactions API is our new interface and the most straightforward way<br>to build with Gemini models and agents. As of June 2026, it is Generally<br>Available and the recommended interface for all new projects.

While it is now considered legacy, the original<br>generateContent API<br>remains fully supported.

Why use the Interactions API?

New capabilities out of the box : Optional server-side conversation<br>state using previous_interaction_id, observable execution steps for<br>debugging and UI rendering, and background execution for long-running<br>tasks using background=true.

Lower cost with higher cache hit rates : Server-side state management<br>enables more efficient context caching across turns, reducing token costs<br>for multi-turn conversations.

Built for frontier models and agents : Purpose-built for thinking<br>models, multi-step tool use, and complex reasoning flows — simplifying<br>the process of building, debugging, and orchestrating agentic<br>applications.

Single API for models and agents : One unified interface for calling<br>Gemini models and agents directly such as Deep Research and custom<br>managed agents — no separate endpoints or patterns to learn.

Where new things launch : Going forward, new models and capabilities<br>beyond the core mainline family, along with new agentic capabilities<br>and tools, will launch on the Interactions API.

By default, the Interactions API stores requests so you can leverage<br>the server-side state management features by using<br>previous_interaction_id. You can opt into stateless behavior by setting<br>store=false. See the data retention section for<br>details.

Get started

Set up your coding agent : Connect to the Gemini Docs MCP and install<br>the gemini-interactions-api skill to give your assistant direct access to<br>the latest developer docs and best practices.<br>Set up your coding agent →

Migrate from generateContent : If you have an existing integration,<br>follow the Migration Guide to<br>transition to the Interactions API.

Get started : Get started in the Interactions API Get started<br>guide.

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

Image generation

Image understanding

Audio understanding

Video understanding

Document processing

Function calling

Structured output

Deep Research Agent

Flex inference

Priority inference

How the Interactions API works

The Interactions API centers around a core resource: the 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<br>interactions.create, you are<br>creating a new Interaction resource.

Server-side state management

You can use the id of a completed interaction in a subsequent call using the<br>previous_interaction_id parameter to continue the conversation. The server<br>uses this ID to retrieve the conversation history, saving you from having to<br>resend the entire chat history.

The previous_interaction_id parameter preserves only the conversation history (inputs and outputs)<br>using previous_interaction_id. The other parameters are interaction-scoped<br>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<br>want them to apply. This server-side state management is optional; you can also<br>operate in stateless mode by sending the full conversation history in each<br>request.

Data storage and retention

By default, the API stores all Interaction objects (store=true) in order to<br>simplify use of server-side state management features (with<br>previous_interaction_id), background execution (using background=true) and<br>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<br>set store=false in your...