New Gemini API updates for Gemini 3

Source: Google Developers Blog

NOV. 25, 2025

What’s new in the Gemini API for Gemini 3

• Simplified parameters for thinking control
  Starting with Gemini 3, we introduce a new parameter called thinking_level to control the maximum depth of the model’s thinking process before it produces a response. Gemini 3 treats these levels as relative guidelines for reasoning rather than strict token guarantees.

  • "high" – for complex tasks that require optimal thinking (e.g., strategic business analysis, scanning code for vulnerabilities).
  • "low" – for latency‑ and cost‑sensitive applications such as structured data extraction or summarization.
    Read more here.

• Granular control over multimodal vision processing
  The media_resolution parameter lets you configure how many tokens are used for image, video, and document inputs, allowing you to balance visual fidelity with token usage. Set it per‑media part or globally to one of: media_resolution_low, media_resolution_medium, or media_resolution_high. If unspecified, the model uses optimal defaults based on the media type. Higher resolutions improve the model’s ability to read fine text or identify small details, but increase token usage and latency.

• Thought signatures to improve function calling and image‑generation performance
  Starting with Gemini 3, the API enforces the return of Thought Signatures—encrypted representations of the model’s internal thought process. By passing these signatures back in subsequent calls, you ensure Gemini 3 maintains its chain of reasoning across a conversation, which is critical for complex, multi‑step agentic workflows.

  • If you use the official SDKs (libraries) and standard chat history, thought signatures are handled automatically.
  • Function calling: strict validation on the current turn; missing signatures return a 400 error. See details here.
  • Text/chat generation: validation is not strictly enforced, but omitting signatures degrades reasoning and answer quality.
  • Image generation/editing: strict validation for all model parts, including a thoughtSignature; missing signatures return a 400 error.

• Grounding and URL context with structured outputs
  You can now combine Gemini‑hosted tools—specifically Grounding with Google Search and URL context—with structured outputs. This is powerful for agents that need to fetch live information from the web or specific webpages and extract that data into precise JSON for downstream tasks. See the example here.

• Updates to Grounding with Google Search pricing
  To better support dynamic agentic workflows, we are transitioning from a flat rate (US $35 / 1k prompts) to a more granular, usage‑based rate of US $14 / 1,000 search queries.

Best practices for using Gemini 3 Pro through our APIs

We have seen wide excitement for Gemini 3 Pro—especially for vibe coding, zero‑shot generation, mathematical problem solving, complex multimodal understanding, and many other use cases. To get the best results while pushing the boundaries of Gemini 3, follow these guidelines (more details here):

• Temperature – Keep the temperature parameter at its default value of 1.0.
• Consistency & defined parameters – Maintain a uniform structure throughout your prompts (e.g., standardized XML tags) and explicitly define ambiguous terms.
• Output verbosity – By default, Gemini 3 is less verbose and prefers direct, efficient answers. Request a more conversational or “chatty” response explicitly if needed.
• Multimodal coherence – Treat text, images, audio, and video as equal‑class inputs. Reference specific modalities clearly so the model synthesizes across them rather than analyzing them in isolation.
• Constraint placement – Put behavioral constraints and role definitions in the System Instruction or at the very top of the prompt to anchor the model’s reasoning process.
• Long‑context structure – When working with large contexts (books, codebases, long videos), place your specific instructions at the end of the prompt (after the data context).

Gemini 3 Pro is our most advanced model for agentic coding. To help developers get the best of its capabilities, we’ve worked with our research team to create a System Instructions template.

Agentic SI Template for the model that improved performance on several agentic benchmarks.
To start building with these new features, include the template in your system prompt and adjust the parameters as described above.

Check out the Gemini 3 documentation and read the Developer Guide for technical implementation details.

---

Previous | Next