Interactions API vs generateContent

A detailed comparison of Google Gemini’s two API paradigms — endpoints, request/response structures, state management, thinking, usage fields — with APIYI gateway compatibility test results

Since June 2026, Google has made the Interactions API Generally Available and recommends it for all new projects, while the classic generateContent API is now considered legacy but remains fully supported. Official docs (such as the Nano Banana image generation page) now offer a toggle between the two paradigms, which leaves many developers wondering: what exactly differs, and which one should I use through APIYI? This page gives a detailed comparison and tested conclusions.

APIYI gateway status (tested July 4, 2026 (UTC+8)): the Interactions API is not yet supported through the gateway — both /v1beta2/interactions and /v1beta/interactions return 404. When calling Gemini via APIYI, keep using the generateContent native format; all Gemini docs on this site are based on it. We will update this page once the gateway adds Interactions API support.

What the Two Paradigms Are

generateContent is the classic stateless interface: one request carries the full context, one response returns the full result, at POST /v1beta/models/{model}:generateContent. Google states that “while it is now considered legacy, it remains fully supported.”

The Interactions API is Google’s new interface, GA since June 2026, at POST /v1beta2/interactions. It is built around the core Interaction resource (one complete conversation turn or task), and the response is a chronological timeline of execution steps — model thoughts, tool calls and results, and the final output are all explicit steps. Google is explicit that new models beyond the core mainline family and new agentic capabilities will launch on the Interactions API going forward (source: ai.google.dev/gemini-api/docs/interactions-overview).

Core Differences at a Glance

Dimension	generateContent (classic)	Interactions API (new)
Endpoint	POST /v1beta/models/{model}:generateContent	POST /v1beta2/interactions
Input structure	contents[].parts[] (role-based multimodal parts)	input (string or content blocks; model name in the body)
Output structure	candidates[0].content.parts[]	steps[] timeline: user_input / thought / function_call / function_result / model_output
Multi-turn	Client resends the full history every turn	previous_interaction_id continues server-side (stateless mode also possible)
Thinking	thoughtsTokenCount counter; image models’ interim thinking drafts come back mixed into image parts	Returned explicitly as steps (type: "thought"), including thought text and interim images
Streaming	Dedicated :streamGenerateContent endpoint	Same endpoint with "stream": true in the body
Background execution	Not supported	"background": true for long-running tasks
Caching	Explicit caching + implicit caching	No explicit caching; previous_interaction_id significantly improves implicit cache hit rates
Server-side data retention	Requests not stored	store: true by default: 55 days on the paid tier, 1 day on the free tier, deletable; store: false opts out (but is incompatible with background and previous_interaction_id)
Usage fields	promptTokenCount / candidatesTokenCount / thoughtsTokenCount / totalTokenCount	total_thought_tokens / total_output_tokens etc. (snake_case)
Agent calls	Not supported	Same interface calls official agents such as Deep Research and Antigravity
Not yet available	— (most complete feature set)	Batch API, explicit caching, video_metadata, automatic function calling (Python), remote MCP on Gemini 3
SDK entry point	client.models.generate_content (google-genai)	client.interactions.create (google-genai ≥ 2.3.0 / @google/genai ≥ 2.3.0)

A common pitfall with the Interactions API’s server-side state: previous_interaction_id only carries over the conversation history. tools, system_instruction, and generation_config (including thinking_level, temperature, etc.) are interaction-scoped — you must re-send them on every turn or they silently stop applying.

Request & Response Structures (single text turn)

The generateContent example works directly against the APIYI gateway; the Interactions API example targets Google’s endpoint directly (not yet supported by APIYI):

generateContent (works on APIYI)

curl -X POST "https://api.apiyi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{ "text": "Tell me a joke." }]
    }]
  }'

curl -X POST "https://generativelanguage.googleapis.com/v1beta2/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Tell me a joke."
  }'

How the two response shapes differ for the same request:

generateContent response

{
  "candidates": [
    {
      "content": {
        "parts": [{ "text": "Why did the chicken cross the road? ..." }],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 12,
    "totalTokenCount": 16
  }
}

{
  "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?" }]
    }
  ]
}

Multi-turn Conversations Compared

This is where the two paradigms feel most different. generateContent requires resending the entire history every turn; the Interactions API only needs the previous turn’s id:

generateContent (resend full history)

curl -X POST "https://api.apiyi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "role": "user",  "parts": [{ "text": "Hi, my name is Phil." }] },
      { "role": "model", "parts": [{ "text": "Hello Phil! How can I help?" }] },
      { "role": "user",  "parts": [{ "text": "What is my name?" }] }
    ]
  }'

curl -X POST "https://generativelanguage.googleapis.com/v1beta2/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "previous_interaction_id": "int_123",
    "input": "What is my name?"
  }'

Beyond saving history-plumbing code, server-side continuation makes it much easier for implicit caching to hit the conversation prefix — Google says this lowers token costs in multi-turn scenarios. The trade-off is that data is stored on Google’s side by default (55 days on the paid tier); businesses with data-compliance requirements should evaluate the store semantics.

Differences for Image Models

Gemini 3 image models (such as gemini-3-pro-image) think by default, and the two paradigms present the “interim thinking drafts” completely differently:

• generateContent (APIYI’s current gateway format): interim thinking drafts come back as ordinary image parts inside candidates[0].content.parts (with thoughtSignature, without a thought flag). In testing a single response can contain 2–10 images, each billed at 1120/2000 tokens into the output — always iterate over parts and take the last one as the final version. Full measurements and reconciliation rules: Usage Fields & Output Explained.
• Interactions API: thinking is made explicit as type: "thought" steps (thought text and interim images), with the final image in the model_output step; the SDKs also provide .output_image / .output_text convenience properties. Interleaved text-and-image output (e.g. illustrated stories) still requires manually iterating over steps.

APIYI Gateway Compatibility Test

Probed against api.apiyi.com with a test key on July 4, 2026 (UTC+8):

Test	Request	Result
POST /v1beta2/interactions + Bearer auth	minimal gemini-2.5-flash request	❌ 404 (Invalid URL)
POST /v1beta/interactions + Bearer auth	same	❌ 404 (Invalid URL)
POST /v1beta2/interactions + x-goog-api-key auth	same	❌ 404 (Invalid URL)
POST /v1beta/models/{model}:generateContent	text/image models	✅ Works (all Gemini docs on this site are based on it)

Conclusion: the APIYI gateway does not yet forward the Interactions API, so Interactions-only capabilities — server-side continuation, agent calls, background execution — are currently unavailable through the gateway.

Recommendations

1. Via APIYI: keep using generateContent. It has the most complete feature set (Batch, explicit caching, and video_metadata are in fact generateContent-only), and Google has committed to fully supporting it — there is no near-term deprecation risk.
2. Multi-turn with generateContent: assemble the history client-side; see Gemini Native Format and Multi-turn Conversations.
3. If you call Google directly and consider migrating to the Interactions API, watch four things: tools / system_instruction / generation_config must be re-sent every turn; store defaults to on with 55-day retention on the paid tier; Batch API and explicit caching are not yet available; upgrade google-genai / @google/genai to 2.3.0+.
4. When the Interactions API becomes worth watching: when you need official agents (Deep Research, Antigravity), background: true long-running tasks, or want server-side state to cut multi-turn token costs. We will update this page as soon as APIYI adds support.

Related Docs

Gemini Native Format

The complete guide to the generateContent native format via APIYI

Gemini Response Handling

Parsing candidates, parts, and finishReason correctly

Usage Fields & Output Explained

Image-model usageMetadata semantics and measured thinking-draft behavior

Multi-turn Conversations

Implementing multi-turn chat on a stateless interface