Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Gemini API — surface tracking

  • Last verified: 2026-09-23 (changelog fetched directly)
  • Plugin: nexus.llm.gemini (plugins/providers/gemini/)
  • Batch surface: none — Gemini is not wired into nexus.llm.batch

How this API is versioned

The version is in the URL path, and it differs by deployment:

  • AI Studio (generativelanguage.googleapis.com): v1beta or v1. v1beta is the preview channel — early features, subject to breaking change. v1 is stable. All models are served by both.
  • Vertex AI (<region>-aiplatform.googleapis.com): v1, a different API surface with its own shapes, not merely a different version of the same one.

Nexus sends v1beta on AI Studio and v1 on Vertex.

The practical consequence for Nexus: the AI Studio path is on the preview channel by construction, which is what makes explicit context caching reachable there. It also means a v1beta breaking change is in-contract for Google and will arrive without a version bump.

Model families, as of the last check

The changelog’s Sept 2026 entries show the active lineup is 3.5 / 3.6 / 3.7 / 3.8, and that on 2026-09-18 Gemini 2.5 was restricted to active users — new projects are directed to 3.5 Flash-Lite or 3.8 Flash.

This demotes thinking.mode: budget to a legacy path. thinkingBudget is the 2.5-era control; a new project cannot reach a model that accepts it. The mode stays supported for existing deployments, but mode: level is the one to document first and to reach for on anything new.

The changelog shows no recent changes to thinking levels or budgets, so the implementation shipped in v0.29.0 is current. The last context-caching entry was April 2025, and the Batch API has been stable since its 2025 launch. The most recent breaking change was a May 2026 schema shift in the Interactions API, which Nexus deliberately does not speak.

What Nexus pins

ThingValueSet in
AI Studio generateContenthttps://generativelanguage.googleapis.com/v1beta/models/<model>:<op>auth.go:358
AI Studio cachedContentshttps://generativelanguage.googleapis.com/v1beta/cachedContentsauth.go:405
AI Studio file upload/upload/v1beta/filesfiles.go:80
Vertexhttps://<region>-aiplatform.googleapis.com/v1/projects/<p>/locations/<l>/publishers/google/models/<model>:<op>auth.go:351
Vertex cachedContents.../v1/.../cachedContentsauth.go:402

Feature matrix

FeatureAPINexusNotes
generateContent / streamingGA both versions✅
Tool callingGA✅tool_choice.go
thinkingConfig.thinkingLevel3.x✅mode: level, minimal|low|medium|high
thinkingConfig.thinkingBudget2.5✅mode: budget, incl. -1 dynamic / 0 off
Mutual exclusion of the twoenforced by API (400)✅Guaranteed by thinking.go merge
includeThoughtsGA✅Emission ungated — a role’s value works end to end
Thought signaturesGA✅pkg/roundtrip gemini_thought_signatures — load-bearing, a 400 without it
Per-role thinking blockn/a (Nexus concept)✅Since v0.29.0
Explicit context cachingv1beta only on AI Studio⚠️Nexus is on v1beta there, so reachable. Vertex path uses /v1/cachedContents — support unverified.
Code executionGA✅code_execution config key
MultimodalGA✅multimodal.go, modality.go
Files APIGA✅files.go
Vertex AI authGA✅auth.go, incl. Workload Identity
Native web search groundingGA✅plugins/search/gemini_native/
Batch APIGA❌Gemini is absent from nexus.llm.batch entirely
Live APIv1beta only❌Bidirectional streaming; no Nexus surface
Agents / Webhooks APIv1beta only❌Out of scope — Nexus is the agent harness
Computer Use toolv1beta only❌
MCP server tools (native)v1beta only❌Nexus has its own MCP client
Priority / Flex service tiersv1beta only❌Cost-relevant; no config surface
Audio output configv1beta only❌
Interactions APIseparate surface❌Explicitly out of scope — different field names

Changes needing accommodation

Open, ranked.

  1. Vertex explicit caching is unverified — and a documentation attempt failed. The v1beta-only rule is documented for AI Studio; Nexus calls /v1/cachedContents on Vertex (auth.go:402) and nothing confirms that route behaves the same. The Vertex context-caching overview page was fetched on 2026-09-23 and does not state the API version path, the resource name, or how it differs from AI Studio. Resolving this needs the Vertex API reference or a live call — do not repeat the overview page, it does not answer it.
  2. cache.min_tokens is inert. The token-count probe was never implemented and lookup is read-only, so the key parses and does nothing. Documented in the reference as of v0.29.0.
  3. No batch support. Gemini has a Batch API; nexus.llm.batch covers Anthropic and OpenAI only. A deployment batching a Gemini role has no path.
  4. v1beta is a preview channel. Breaking changes there are in-contract. Moving AI Studio to v1 would cost explicit context caching — a real trade-off, not a free hardening.

Shapes of change to watch for.

  • A v1beta feature graduating to v1, which may change its shape on the way.
  • A new thinkingLevel value. Nexus clamps Anthropic’s xhigh/max down to high; a genuinely new Gemini level would need adding to the vocabulary.
  • Thought-signature handling changes — this path is load-bearing and its absence is an immediate 400 INVALID_ARGUMENT.

Verification basis

Changelog fetched directly on 2026-09-23. The v1 vs v1beta feature split comes from Google’s “API versions explained” page via search summary, not a direct fetch — treat the v1beta-only list as indicative and confirm a specific feature before depending on it. The Nexus column is read from the code and cites files.

References

  • API versions explained (v1 vs v1beta) — https://ai.google.dev/gemini-api/docs/api-versions
  • Release notes (the page to diff against Last verified) — https://ai.google.dev/gemini-api/docs/changelog
  • Thinking — https://ai.google.dev/gemini-api/docs/thinking
  • Context caching — https://ai.google.dev/gemini-api/docs/caching
  • Vertex AI Gemini API — https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference