Gemini API

Google's Gemini developer API: the stateful step-based Interactions API vs legacy generateContent, built-in tools (Search grounding, code execution, File Search), thinking levels and thought signatures, implicit vs explicit caching, Files API, tiers and the OpenAI-compatible layer.

Contents

The Gemini API (generativelanguage.googleapis.com, keyed through Google AI Studio) is Google’s developer API for Gemini models. As of November 2026 it has two generation surfaces. The Interactions API (POST /v1beta/interactions, GA since June 2026) is recommended for new projects, and new capabilities launch there first. The older generateContent API (contents made of parts, plus generationConfig) is legacy but fully supported (Interactions docs). An interaction is a stored, chronological list of steps (thoughts, function_call, function_result, model_output) that can be chained server-side, run in the background, or target an agent (e.g. Deep Research) instead of a model. Enterprise deployments of the same models go through Google Vertex AI, which has its own quotas and governance.

Interactions vs generateContent

AspectInteractions APIgenerateContent (legacy)
Unitinput → steps (typed)contents[].parts[] → candidates
Statestored by default; previous_interaction_idstateless; you resend contents
Agentsdeep-research-*, antigravity-* preview IDsno
Backgroundbackground=trueno
Batch APInot yetyes
Explicit cachingnot yet (implicit via chaining)yes (cachedContents)
Streamingstep.start / step.delta / step.stop eventsstreamGenerateContent

Sources: Interactions docs, streaming, context caching.

State semantics. store defaults to true. Paid-tier interactions are kept 55 days (configurable to 7, 14, 28 or 55) and free-tier ones 1 day. Only inputs and outputs carry across previous_interaction_id: tools, system_instruction and generation_config (including thinking_level) are scoped to one interaction and must be re-sent each turn. store=false disables both chaining and background mode (Interactions docs). Synthesis: this is the same trap as OpenAI’s previous_response_id, which also forgets instructions.

flowchart LR
    U["user_input step"] --> I["interactions.create<br/>model or agent"]
    I --> T["thought step<br/>(thought_signature)"]
    T --> FC["function_call step<br/>id, name, arguments"]
    FC --> App["Your code runs function"]
    App --> FR["function_result step<br/>call_id, result[]"]
    FR -->|"previous_interaction_id<br/>+ re-send tools & system_instruction"| I
    I --> MO["model_output step<br/>text + annotations"]

Tools

Custom functions are {type: "function", name, description, parameters}. The model emits function_call steps (id, name, arguments); you return function_result steps with call_id and a result array of content blocks, which on Gemini 3+ can include images, documents, audio or video. tool_choice is auto, any, none or validated, and allowed_tools restricts the set (Interactions function calling). VALIDATED (the default when built-in tools or structured output are combined) enforces schema adherence and reduces malformed calls. Parallel results may come back in any order and are matched by ID (function calling). See function calling.

Built-in tools:

ToolKey facts
google_searchInteractions output has google_search_call and google_search_result (with search_suggestions HTML you must render) plus url_citation annotations. On Gemini 3+: 5,000 free queries/month, then $14 per 1,000 queries, with a default 1,500 RPD (Search grounding)
Code executionPython only, 30 s per run, fixed libraries, auto-retries up to 5 times; no tool fee, tokens billed (code execution)
file_searchHosted RAG over persistent stores: chunking config, AIP-160 metadata filters, file_citation annotations. Storage and query embeddings are free and indexing is billed. Cannot be combined with Search grounding or URL context (File Search)
URL context, Maps grounding, computer uselisted as supported on Gemini 4 Carbon (models)

Remote MCP is not yet supported on Gemini 3 in the Interactions API (Interactions docs).

Thinking

Thinking is on by default for current models. thinking_level takes minimal / low / medium / high, with xhigh only on Gemini 4 Hydrogen and minimal unsupported on Gemini 4. Defaults vary by model. Thought summaries are opt-in (thinking_summaries: "auto"). Thought signatures are encrypted reasoning state: the server manages them in stateful mode, but in stateless mode you must resend every thought step unmodified, including built-in tool signatures. Thinking is billed as output, and max_output_tokens includes it (thinking docs; see extended thinking). In generateContent, signatures ride on function-call parts and must not be merged or moved (function calling).

Sampling: on Gemini 3.6 Flash and newer, temperature, topP and topK are silently ignored (generateContent reference). Synthesis: Anthropic returns 400 for the same thing, so code that tunes temperature fails loudly on Claude and silently on Gemini.

Caching, files, tokens

  • Implicit caching is automatic on Gemini 2.5+ with no guaranteed savings. It needs a 4,096-token minimum on Gemini 3/4, and on Gemini 4 agent loops the new request must add at least 2,050 tokens for the whole previous request to be cached. Explicit caching (cachedContents with a TTL, default 1 hour, plus hourly storage fees) is generateContent-only and not available on Gemini 4 (context caching; see prompt caching). Cached input costs 0.05x of base on Gemini 4 (pricing).
  • Files API: 2 GB per file and 20 GB per project. Files auto-delete after 48 hours, and use is free. Upload when a request exceeds 100 MB (PDF limit 50 MB) (Files API). Synthesis: the 48-hour expiry contrasts with Anthropic and OpenAI files, which persist until deleted. Durable corpora belong in File Search stores.
  • Tokens: Gemini 4 shares one 1,048,576-token window across input, thinking and output (65,536 default output cap). Images cost 258 tokens per 768 px tile and audio 32 tokens per second (tokens).
  • Structured output strips some JSON Schema keywords silently (minLength, maxLength, uniqueItems…) and returns 400 for over-complex schemas (structured outputs).

Limits, tiers, pricing

Limits apply per project, not per key: RPM, input TPM and RPD (reset at midnight Pacific), plus rolling 10-minute spend caps that return 429 RESOURCE_EXHAUSTED. Tiers depend on cumulative spend and account age: Tier 2 needs $100 and 3 days, Tier 3 needs $1,000 and 30 days (rate limits; see rate limits and retries). Batch and Flex are half price and Priority about 1.8x. Gemini 4 Carbon/Argon prices double on 2026-12-01, and free-tier data on some models may be used to improve Google products (pricing; see batch processing). Model lineup: Gemini 4 Carbon / Argon / Hydrogen, with 2.5 Pro/Flash deprecated and rerouted from 2026-12-01 (models).

OpenAI-compatible endpoint

Base URL .../v1beta/openai/. It supports Chat Completions (tools, images, audio, structured output, service_tier), embeddings, images and batch. It does not support the Responses API or a standalone Files API. reasoning_effort maps to thinking_level (to thinking_budget on 2.5), and none turns thinking off only on 2.5 models other than 2.5 Pro; Gemini 2.5 Pro, 3 and 4 cannot disable it. Native features need extra_body (thinking_config, cached_content). The layer is beta, and unknown parameters are silently ignored (OpenAI compat).

Failure modes and gotchas

  • Forgetting to re-send tools/system_instruction with previous_interaction_id silently changes behaviour (Interactions docs).
  • Editing, merging or dropping thought steps or signatures in stateless mode breaks multi-turn tool use (thinking docs, function calling).
  • max_output_tokens hit mid-reasoning gives a billed, incomplete response (thinking docs).
  • Expecting explicit caching or Batch on Interactions, or explicit caching on Gemini 4 (Interactions docs, context caching).
  • Errors mid-stream arrive as an error event (e.g. gateway_timeout) (streaming).

When to use / when not

Synthesis:

  • Use Interactions for new work, agents, Deep Research, and long-running background jobs, but decide deliberately between server-side state (55-day retention by default on paid tier) and stateless replay.
  • Stay on generateContent when you need the Batch API, explicit caching on Gemini 3.x, or Python automatic function calling.
  • Use Vertex AI instead of AI Studio keys for enterprise IAM, VPC-SC, data residency and provisioned throughput.
  • Prefer Gemini for very long multimodal inputs (video/audio) and Google Search grounding (web search APIs). Compare with the OpenAI Responses API and the Anthropic Messages API; Google ADK is the agent framework on top.

Sources

Suggest changes →