Google Gemini API Knowledge Patch

Google Gemini API Knowledge Patch

Load this skill when building or reviewing applications that call the Gemini API, migrate to the Google Gen AI SDK, use Interactions, manage function calls or structured output, choose current endpoints, or diagnose quota and billing behavior.

Prefer project manifests, runtime responses, and tests when they disagree with guidance here. Pin concrete endpoint IDs for reproducible workloads, and check lifecycle metadata before deploying a long-lived integration.

Reference Index

Breaking Changes First

Migrate Interactions consumers to typed steps

Current Interactions responses expose typed steps, not a flat outputs array. Treat model output, thoughts, client function calls, and server-side tool activity as separate step variants. Streaming clients must assemble indexed steps from step.start, step.delta, and step.stop; the final completion event does not repeat them.

For continuation, return prior steps as input or submit a function_result with the matching interaction and call IDs. See Interactions API.

Preserve thought signatures with function calls

When manually managing Gemini 3.x history, replay each opaque thought signature unchanged on the exact function-call part that carried it. A sequential loop must preserve all signed calls in the current turn. Parallel calls must remain grouped in one model message, followed by their grouped function responses.

The SDK handles this when the complete response is appended to history. REST and compatibility-layer clients must preserve the fields themselves. See Function Calling and Thought Signatures.

Replace legacy SDK packages and shapes

Use the GA Google Gen AI packages and a centralized client. Move generation options into each call's config; in Python use client.aio for async calls. In JavaScript read response.text directly and iterate the object returned by generateContentStream. See Google Gen AI SDK Migration.

Remove unsupported generation controls

For gemini-3.6-flash and gemini-3.5-flash-lite, remove temperature, top_p, and top_k; they are ignored and future generations can reject them. Replace thinking_budget with string-valued thinking_level where supported, and do not send candidate_count to Gemini 3.x.

Do not prefill a final model turn: a request ending in a non-empty model turn is rejected. Put output constraints in system_instruction or response_format instead.

Migrate before endpoint shutdowns

Aliases move, preview endpoints disappear, and stable families have scheduled successors. Pin concrete IDs, record lifecycle metadata with the deployment, and schedule migrations before the published cutoff. Use Models, Media, and Lifecycle for the current mappings and dates.

Common Implementation Patterns

Create an Interactions function

Declare each custom function directly in the tools array:

weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Get weather for a city.",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}

interaction = client.interactions.create(
    model="MODEL_ID",
    input="Weather in Paris?",
    tools=[weather_tool],
)

Use tool_choice for automatic, forced, prohibited, or validated calling. Return client-executed results with both name and call_id; results may contain multiple typed text or image blocks.

Continue a streamed function call

Capture the function ID and name from step.start, concatenate every argument fragment for the same event index, and parse JSON only when the call is complete. If the interaction ends in requires_action, execute the function and create a continuation with previous_interaction_id plus a matching function_result.

Server-side tools do not require this round trip. A request may combine them with client functions; only an outstanding client function produces requires_action.

Request typed final output

Interactions use a top-level, discriminated response_format:

response_format={
    "type": "text",
    "mime_type": "application/json",
    "schema": Result.model_json_schema(),
}

Multiple modalities use an array of text, image, or audio format entries. Their deltas may interleave, so route each delta by its type. For structured JSON streaming, concatenate text fragments in order and validate once the document is complete.

Use the centralized generation client

from google import genai

client = genai.Client()
response = client.models.generate_content(
    model="MODEL_ID",
    contents="Summarize the input.",
    config={"max_output_tokens": 200},
)

Python callables passed as tools execute automatically unless automatic function calling is disabled. Pydantic response schemas are validated into response.parsed. Cached content is created through client.caches and then referenced by name in generation configuration.

Choose a stable endpoint deliberately

For new general coding and agentic workloads, evaluate gemini-3.7-flash. For existing Interactions workloads, account for endpoint-specific thinking defaults and remove controls the selected endpoint ignores. For deterministic operations, never depend on *-latest aliases.

Image, video, audio, TTS, embedding, and Live workloads have distinct endpoint families and lifecycle schedules. Confirm the modality and input constraints in Models, Media, and Lifecycle.

Operational Checks

Diagnose a 400 response

Check, in order:

1. The last non-empty turn is not a prefilled model turn.
2. Every required Gemini 3.x function call retains its thought signature.
3. Parallel calls and responses were not interleaved.
4. A legacy generateContent function response includes both call_id and function name.
5. Removed sampling fields and unsupported candidate_count are absent.
6. Function and response schemas are not excessively large or deeply nested.
7. Structured or XML pre-tool prose is not provoking a malformed call.

Diagnose a 429 response

Rate dimensions, a rolling spend-rate ceiling, account funds, and project spend caps are independent. A project can have RPM and TPM available yet hit the paid-tier spend-rate limit. Keys in one project share quota, while the billing plan and account cap apply across linked projects.

Failed 400 and 500 requests still consume quota even when their tokens are not billed. Consult Limits and Billing before changing retry behavior or distributing keys.

Review streaming code

• Consume through the terminal event or finish_reason; a signature can arrive on an empty-text part.
• Dispatch extensible events and deltas by type, logging and skipping unknown variants rather than failing the stream.
• Keep per-index state for interleaved steps and modalities.
• Assemble partial function arguments and structured JSON before parsing.
• Expect the completion event to carry status and usage, not the assembled output steps.

Review long-lived deployments

• Pin endpoint IDs and track their lifecycle stage and shutdown date.
• Plan around introductory pricing end dates and account-wide spend caps.
• Prefer event-driven completion for batch jobs and long-running operations.
• Preserve Live session resumption handles and handle GoAway before disconnect.
• Do not design around model tuning; the API no longer offers a tunable model.