Gemini 3.6 Flash Migration: 5 Critical API Changes That Will Break Your Code (And How to Fix Them)

高效码农

3 weeks ago

Gemini 3.6 Flash & 3.5 Flash-Lite Are GA: What Breaks, What’s Better, and How to Migrate

Google just made Gemini 3.6 Flash and Gemini 3.5 Flash-Lite generally available. That means they are production-ready, right now.

I’ve dug through the official release notes, and here’s the thing: these aren’t just “better models.” They come with API changes that will break your existing code if you aren’t paying attention. Specifically, temperature, top_p, and top_k are being shown the door.

This post cuts through the marketing. I’ll tell you exactly what each model does well, which one you should pick for your workload, and—most importantly—give you a step-by-step migration checklist so you don’t get caught out by HTTP 400 errors later.

New Models at a Glance: Specs and Cost

Let’s start with the practical stuff. What do you get, and what does it cost?

Gemini 3.6 Flash is positioned as the direct upgrade to 3.5 Flash. It’s stronger on agentic and multimodal tasks, but the headline grabber for engineering leads is the price drop: output tokens go from $9.00/1 Mt o * *$ 7.50/1M**. Input stays at $1.50/1 M . I t d oes n^{'} t so u n d l ik e m u c h, b u t a t sc a l e, t ha t$ 1.5 difference per million tokens adds up quickly on your monthly bill.

Gemini 3.5 Flash-Lite is the speed demon. It is the cheapest and fastest model in the 3.5 family. If you are parsing millions of PDFs, extracting structured JSON, or doing high-volume classification, the economics here are brutal: $0.30/1 M in p u t * * an d * *$ 2.50/1M output.

Model	Model ID	Default Thinking Level	Pricing (Input/Output per 1M)	Best For
Gemini 3.6 Flash	`gemini-3.6-flash`	`medium`	$1.50/$ 7.50	Complex agentic tasks, multimodal reasoning, code generation
Gemini 3.5 Flash-Lite	`gemini-3.5-flash-lite`	`minimal`	$0.30/$ 2.50	High-throughput data extraction, routing, subagent execution

Both support the 1M token context window, 64k max output tokens, native thinking, and the full tool suite—including Computer Use for UI automation. If you are building agents that need to click buttons on a screen, these models have you covered natively.

What’s Actually Better in Gemini 3.6 Flash?

It Finishes Multi-Step Workflows Faster

During my testing, 3.6 Flash is noticeably more decisive. It completes multi-step tasks with fewer reasoning steps, fewer conversational turns, and fewer tool calls compared to 3.5 Flash. The official docs refer to this as reducing “execution loop spiraling”—that annoying loop where the model keeps second-guessing itself.

For production APIs, this doesn’t just save tokens; it saves latency. Fewer back-and-forth cycles mean your users get results sooner.

Code Generation: Better Logic, But Watch the UI

If you are generating production code, 3.6 Flash is a solid upgrade. It produces higher-quality, ready-to-commit code with:

Fewer unwanted edits (it stops rewriting unrelated blocks of code).
Fewer debugging loops (it generates cleaner logic on the first pass).
Better instruction adherence, especially during diagnostic tasks.

But here is the trade-off: Human evaluators actually preferred the visual layout and styling of 3.5 Flash over 3.6 Flash. The new model is more functional, but it might make your frontend UIs look a bit more “engineer-designed.”

If you rely on the model for frontend work, mitigate this by feeding explicit design guidelines into the system_instruction—specific hex codes, spacing units, and font sizes. Don’t just say “make it beautiful.”

It Prefers to “Check First”

3.6 Flash has a quirk: it runs diagnostic scripts before making changes much more frequently than 3.5 Flash. This is great for complex back-end tasks because it reduces mistakes. For simple frontend tweaks, however, these “exploratory steps” add unnecessary overhead. Be aware of this if you’re using it for trivial fixes.

What’s Actually Better in Gemini 3.5 Flash-Lite?

Don’t let the “Lite” suffix fool you. This isn’t just a dumber model; it’s a specialized scalpel.

Throughput is the Killer Feature

If your workload is high-volume data parsing, document extraction, or JSON structuring, this model is a no-brainer. It has the highest throughput in the 3.5 family.

But here is the key nuance: reasoning has improved significantly over the previous Lite generation. On reasoning benchmarks like HLE, it jumped from 11.0% to 18.0%. On multimodal benchmarks like CharXIV, it went from 63.7% to 74.5%. This means tasks that previously required a heavier model (like 2.5 Flash) can now often be handled by Flash-Lite.

Tool Reliability for Subagents

If you are using Flash-Lite to orchestrate subagents (letting it call tools like search or code execution), you’ll find it more reliable than previous generations. It doesn’t drop the ball as often.

Crucial config note: By default, thinking_level is set to minimal for maximum throughput. If you are using it for complex subagent planning and it keeps “giving up” too early, explicitly bump the thinking_level to "medium" or "high". It makes a world of difference for autonomous planning.

Better Persona Consistency

For chatbots, 3.5 Flash-Lite holds its persona much better over multi-turn conversations compared to 3.1 Flash-Lite. It doesn’t forget who it is or what the rules were three messages ago.

⚠️ The Biggest Breaking Change: Deprecated Sampling Params

This is the section your engineering team needs to read.

Starting with Gemini 3.6 Flash and 3.5 Flash-Lite, temperature, top_p, and top_k are deprecated. The API currently ignores them, but Google explicitly warns that supplying them in future versions will return an HTTP 400 error.

Don’t wait for the error to hit production. Remove them now.

# ❌ STOP sending these parameters (Deprecated)
generation_config = {
    "temperature": 0.7,
    "top_p": 0.9,
    "top_k": 40,
}

The Fix: If you need deterministic outputs or specific formatting, use the system_instruction to define explicit rules, or use the Structured Outputs feature.

The “Prefilled Model Turn” is Dead

Another silent killer: You can no longer end your API request payload with a model turn.

In the old days, some devs pre-filled a model response (e.g., {"role": "model", "parts": [{"text": "Translation:"}]}) to force the model to continue from that point. This now results in a 400 Bad Request error.

// ❌ DO NOT DO THIS: Ending with a 'model' turn
{
  "contents": [
    {"role": "user", "parts": [{"text": "Translate 'Hello' to Chinese."}]},
    {"role": "model", "parts": [{"text": "Translation:"}]} /* ❌ ERROR */
  ]
}

The Fix: Switch to system_instruction for output formatting, or let the Interactions API manage history server-side.

New Thinking Config

Replace the old thinking_budget (which was token-based) with the new string enum thinking_level. Options are "minimal", "medium", or "high". It’s way easier to reason about.

The Migration Checklist

If you are moving to gemini-3.6-flash or gemini-3.5-flash-lite, follow this checklist to avoid a fire drill.

Moving to Gemini 3.6 Flash

Update the Model ID: Swap your target string to gemini-3.6-flash.
Kill Sampling Params: Strip temperature, top_p, top_k, and candidate_count (unsupported in 3.x) from your configs.
Update Thinking: Replace thinking_budget with thinking_level="medium" (or “high” for complex tasks).
Fix Turns: Ensure your last content turn is user. Remove any prefilled model turns. Shift to system_instruction for formatting constraints.
Audit Function Calling:
- If using Interactions API, ensure multimodal assets are in the response payload.
- If using generateContent, ensure FunctionResponse objects include call_id and name.
- If you hit Malformed_Function_Call errors, check the formatting rules for “pre-tool text” in the official docs.

Moving to Gemini 3.5 Flash-Lite

Update Model ID: gemini-3.5-flash-lite.
Set Thinking Effort:
- For high-volume extraction/routing: keep minimal (default) for speed.
- For subagents with tool calls: set thinking_level="medium" or "high" to prevent premature termination.
Apply the same API fixes (Sampling Params & Turn validation) as above.

Decision Matrix: Which Model Should You Actually Use?

Your Use Case	Legacy Model	Recommended Migration
Complex agents, code gen, multimodal reasoning	3.5 Flash / 3 Pro	3.6 Flash
High-volume parsing, document extraction	3.1 Flash-Lite / 2.5 Flash	3.5 Flash-Lite
Chatbots needing persona consistency	3.1 Flash-Lite	3.5 Flash-Lite (bump thinking level)
Frontend UI generation (visuals matter)	3.5 Flash	Proceed with caution on 3.6 Flash—test visual output first.

An Antigravity Update

There’s one more thing. Gemini 3.6 Flash is now the default model powering the Antigravity agent in Gemini Managed Agents. If you are using Antigravity for autonomous tasks (like fetching web data and saving as PDF), you don’t need to do anything. You just get the upgrade. There’s a new environment field in the API if you want to force a specific runtime environment.

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Read Hacker News, summarize the top 10, and save as PDF.",
    environment="remote",
)

Practical Summary / Actionable Checklist

Model IDs must change: gemini-3.6-flash or gemini-3.5-flash-lite.
Immediately remove: temperature, top_p, top_k, candidate_count.
Replace: thinking_budget → thinking_level (minimal/medium/high).
Check conversation history: API rejects requests ending with a model turn. Use system_instruction instead.
Function Calling: Validate call_id and name exist (if using generateContent).
UI Gen Mitigation: Give very specific design specs in the prompt to counter 3.6 Flash’s weaker visual output.
Subagents on Lite: Turn thinking_level up to "high" if the agent stops too early.

FAQ

Q1: Can I use 3.6 Flash and 3.5 Flash-Lite simultaneously?
Yes. They are independent models with separate quotas. Mixing them by use case is the most cost-effective strategy.

Q2: How do I control randomness now that temperature is gone?
Use system_instruction to explicitly define output structure, or enable Structured Outputs. If you need extreme determinism, write it directly into the prompt (“You must output exactly this format”).

Q3: Do I have to switch from generateContent to the Interactions API?
Not strictly, but the Interactions API is recommended. It handles multi-turn history for you and avoids the model turn validation issue automatically.

Q4: Does Computer Use work on these models?
Yes, both support Computer Use as a native tool for agentic UI automation.

Q5: Will setting thinking_level to high on Flash-Lite slow it down significantly?
Yes. It adds internal reasoning tokens, increasing latency and cost. Only use it for complex multi-step reasoning. Keep it at minimal for bulk extraction.

Q6: My output quality dropped after removing the sampling params. What gives?
Old models relied on temperature to “soften” outputs. New models rely heavily on prompt clarity. Be more specific with your system_instruction—it usually recovers the quality, if not improves it.

Q7: What about candidate_count?
It’s unsupported in Gemini 3.x models. Remove it entirely.

That’s the core of it. Upgrade to 3.6 Flash for the better agentic reasoning, but clear your code of the deprecated sampling parameters first. Grab Flash-Lite for your batch jobs, but don’t forget to tweak thinking_level if you give it complex tools. The migration isn’t scary—most teams can knock this out in an afternoon. The biggest headache will be validating your function calling format, so start there.