Google Gemini API Knowledge Patch

Google Gemini API Knowledge Patch

Use this skill for Gemini API implementation, migration, model selection, function calling, structured output, streaming, billing, and lifecycle work. Start by identifying which API surface the project uses: generateContent, the Interactions API, Live, Batch, or an OpenAI-compatible endpoint. Also identify the language SDK and whether conversation history is managed by the SDK or assembled manually.

Prefer concrete model IDs when reproducibility matters. Treat moving aliases, preview endpoints, quotas, billing state, and lifecycle dates as operational inputs that should be checked before deployment.

Reference index

Migration priorities

Use the current SDK packages

Replace the legacy packages with google-genai, @google/genai, or google.golang.org/genai. Create one client and access models, files, caches, and other services through it. Generation configuration is per call; Python async methods live under client.aio.

JavaScript responses are flattened: use response.text, and iterate the value returned by generateContentStream directly. Python callables passed as tools execute automatically unless automatic function calling is disabled.

See SDK migration for language-specific examples and changes to structured responses, caches, and embeddings.

Migrate Interactions clients to typed steps

Current Interactions responses use typed steps, not flat outputs. POST /interactions returns output steps; GET /interactions/{id} returns the full timeline. For stateless continuation, replay the entire preceding steps array as input, then append a user_input step.

The SSE lifecycle is:

interaction.created
  → step.start → step.delta → step.stop
  → interaction.completed
  → [DONE]

The completion event does not contain assembled steps. Accumulate indexed deltas, tolerate unknown event variants, and parse function arguments or structured JSON only when the corresponding output is complete.

Python and JavaScript SDK 2.0.0+ select the new schema. Older clients and REST revision headers had a dated transition ending June 8, 2026; use the exact revision rules in Interactions API when maintaining transition-era code.

Remove unsupported generation controls

On gemini-3.6-flash and gemini-3.5-flash-lite, remove temperature, top_p, and top_k; they are deprecated and ignored, and future generations will reject them. Replace thinking_budget with string-valued thinking_level when moving to 3.6 Flash, and remove candidate_count for Gemini 3.x.

Do not send a prefilled model turn as the last non-empty turn. Use system_instruction or response_format to constrain the answer instead. For legacy generateContent with Gemini 3.x, every FunctionResponse needs both call_id and function name.

Thought signatures are conversation state

For Gemini 3.x function calling, return each opaque thought signature unchanged on the exact model part where it arrived. This is mandatory even with minimal thinking when history is manually assembled. Official SDK history handling is safe when the complete response object is appended.

Sequential tool loops must retain every signed model-call step since the most recent user message containing ordinary content. A user message containing only a function response does not start a new turn.

Parallel calls must stay grouped:

model: [FC1 + signature, FC2]
user:  [FR1, FR2]

Only the first parallel function call carries the signature. Do not interleave calls and results. Also consume streamed responses through finish_reason, because a non-call signature can arrive on an empty-text part. See Thought signatures for version differences, the compatibility envelope, and documented sentinels for imported traces.

Function calling

Interactions custom functions are direct {"type": "function", ...} entries in tools; their parameters are object schemas. tool_choice supports auto, any, none, and preview validated, with allowed_tools for filtering. Very large or deeply nested schemas can fail in forced-call mode.

For a streamed client-side call, capture its ID and name at step.start, concatenate argument fragments by event index, and parse only after completion. If the interaction ends in requires_action, execute the function and continue with previous_interaction_id plus a matching call_id. Server-side tools run without that round trip and expose paired call/result steps.

Gemini 3-series function results can contain multiple typed blocks, including images. Preserve the function name and call ID. Remote MCP tools accept only Streamable HTTP; MCP server names cannot contain hyphens.

Avoid requiring XML, YAML, or JSON prose immediately before a tool call, which can trigger Malformed_Function_Call. Prefer a dedicated notes function or, secondarily, Markdown notes. See Function calling and tools.

Structured output

Put Interactions structured JSON controls in top-level response_format as a text format with mime_type: application/json and schema. The same field can be an array for multiple modalities. Image settings also move there, and audio uses a typed audio format rather than response_modalities.

Schemas may recurse with $ref: "#". Supported features include nullable unions, boolean or schema-valued additionalProperties, date/time formats, numeric bounds, and prefixItems, minItems, and maxItems. Keep schemas reasonably sized and shallow.

Structured streaming yields partial JSON text. Concatenate all text fragments in order and validate once complete. On 3-series models, built-in tools and a structured final response can be combined as a preview feature. See Structured outputs.

Model and lifecycle choices

gemini-3.7-flash is the GA coding and agentic model. Its introductory pricing ends December 31, 2026. Other current production choices include gemini-3.6-flash and gemini-3.5-flash-lite; both support a one-million-token context, 64k maximum output, and native Computer Use.

Do not assume a -latest alias remains on one generation. Before deploying, check the concrete successors and cutoff dates for embedding, image, Gemini 2.5, and Flash-Lite workloads in Models and lifecycle.

The API no longer offers model tuning. Current capabilities instead include multimodal embeddings, native image and short-video endpoints, stateful Live sessions, event-driven long-running operations, and Deep Research agents.

Billing and quota guardrails

Billing plan, usage tier, and account spend cap belong to the Cloud Billing account and are inherited by linked projects; request quotas are per project, shared by all its keys. A billing-account cap or zero Prepay balance stops all linked projects. Project spend caps and balance enforcement can lag by roughly ten minutes, so they are not hard real-time circuit breakers.

Handle RPM, input TPM, and RPD independently. Paid tiers can also hit a rolling ten-minute spend-rate limit and receive 429 RESOURCE_EXHAUSTED while ordinary quota remains. Failed 400/500 requests consume quota but are not token-billed; GetTokens consumes neither inference quota nor billable tokens.

Priority inference and Batch have distinct limits. Consult Billing and limits before capacity planning or changing billing accounts.

Implementation checklist

1. Identify the API surface, SDK package and major version, concrete model ID, and whether history is automatic or manual.
2. Check lifecycle status, shutdown dates, aliases, and pricing assumptions.
3. For Interactions, confirm typed steps, response formats, and the correct raw SSE or typed-SDK delta representation.
4. Preserve thought signatures, call IDs, function names, ordering, and all history required for continuation.
5. Assemble streamed arguments and JSON before parsing; skip and log unknown extensible event variants.
6. Treat billing-account state, project quotas, spend rate, traffic class, and enforcement lag as separate controls.