Migrating from Gemini 3.8 Flash to Gemini 4 Hydrogen

To migrate from Gemini 3.8 Flash to Gemini 4 Hydrogen, you change the model name to gemini-4-hydrogen and then fix five things that now return an error or behave differently: the minimal thinking level, explicit caching, the sampling parameters, the output cap and the default thinking level. The remaining steps are fine-tuning around tool calls, conversation state and the bill.

This guide is a compilation based on Google's docs; I have not run the migration in a project of my own, and I have not tested the model myself. The steps come from the "What's new in Gemini 4 Hydrogen" page in AI Studio and the prices from the Gemini API pricing page; I checked both on November 14, 2026. For a complete, runnable code sample, see Google's page. Sources are at the end. For the model itself see What is Gemini 4 Hydrogen, for the price tiers Is Gemini 4 Hydrogen free, and who can use it, and for rivals the Hydrogen, Sonnet 5.5 and GPT-6.1 Terra comparison.

Do you have to migrate?

No, not as of today. Google has not published a retirement date for Gemini 3.8 Flash. The API release notes have no deprecation or shutdown entry for gemini-3.8-flash; in fact, 3.8 Flash is the routing target for gemini-2.5-pro requests from December 1, 2026. The wording Google uses for Hydrogen is "recommended upgrade."

Two things make the migration worth considering:

• The price advantage ends in January. 3.8 Flash is $0.75 per million input tokens and $3.75 for output through December 31, 2026. From January 1, 2027 it becomes $1.50 and $7.50, which is Hydrogen's price today.
• The gap Google reports is large. According to the announcement, Hydrogen scores 57% on Terminal-Bench 4.1 versus 18.2% for 3.8 Flash, and it finishes tasks 2.5 times faster at the default high setting. On the Artificial Analysis index, Hydrogen scores 51 at high and 3.8 Flash 31. The first two numbers are Google's own measurements.

This is my interpretation: no date is forcing your hand, but from January the price argument for staying on 3.8 Flash is gone. December is a reasonable window for testing the migration without rushing.

What changed?

Topic	Gemini 3.8 Flash	Gemini 4 Hydrogen
Model ID	gemini-3.8-flash	gemini-4-hydrogen
Window	Separate budgets: 1M input, 64K output	One window: 1,048,576 tokens shared by input, thinking and output
Max output	64K tokens	65,536 by default; up to 1,048,576 with long decode
Default thinking level	medium	high
Thinking levels		low, medium, high, xhigh; minimal returns an error
Thinking setting		thinking_level only; thinking_budget returns a 400 (DataCamp)
Caching	Your code may use explicit caching (cached_content, caches.create)	No explicit caching; implicit caching is on by default
Sampling parameters	Your code may set temperature, top_p, top_k	Should be removed: in-range values are ignored, out-of-range values return a 400
Standard price (per million tokens)	$0.75 / $3.75 through December 31, 2026; then $1.50 / $7.50	$1.50 / $7.50

The cells I left empty are places where my sources make no explicit statement about the 3.8 Flash side.

Step-by-step migration checklist

The order in Google's migration notes:

1. Change the model name. gemini-4-hydrogen instead of gemini-3.8-flash.
2. Review the output cap. On 3.8 Flash, input and output were separate budgets; Hydrogen has a single 1M window. Remove hard-coded low max_output_tokens caps or raise them to 65,536.
3. Choose the thinking level deliberately. The default is now high (it was medium on 3.8 Flash). xhigh was added; minimal returns an error. Google suggests testing both medium and high. Hydrogen accepts only thinking_level; as DataCamp reports, quoting the docs, thinking_budget returns a 400.
4. Remove explicit caching. Explicit caching is not supported: delete the uses of cached_content and caches.create. Implicit caching is on by default for prompts of at least 4,096 tokens and gives 95% off cached input.
5. Delete the sampling parameters. Remove the temperature, top_p and top_k fields. In-range values are ignored; out-of-range values return a 400.
6. Declare tools natively. Do not prompt the model to write raw-text JSON tool calls with zero declared tools; that can return MALFORMED_FUNCTION_CALL. Declare tools natively or use structured outputs.
7. Carry conversation state correctly. Use previous_interaction_id in the Interactions API. If you manage the history yourself with generateContent, send back prior model turns and thought signatures unchanged; do not copy one thought signature across parallel functionCall parts.
8. Pass both fields for long outputs. Output longer than 65,536 tokens needs both background: true and a max_output_tokens above 65,536. With background on but no max_output_tokens, the server stops at 65,536.
9. Recalculate the bill. All processed tokens are billed, including thinking tokens and internal grounding instructions. The default high means more thinking tokens than 3.8 Flash's medium default.

The fields Google's docs use look like this: the model ID and the thinking level. It is not a complete sample, only a request-configuration fragment; for the import lines and the full call, see Google's page.

model="gemini-4-hydrogen"
generation_config={"thinking_level": "xhigh"}

The long-decode example, sent through the Interactions API, turns on background execution and raises the output cap:

background=True
generation_config={"max_output_tokens": 262144, "thinking_level": "high"}

What errors should you expect?

Cause	Result
Sending minimal as thinking_level	Error
Sending thinking_budget	400 (DataCamp, quoting the docs)
Out-of-range temperature, top_p or top_k	400
In-range temperature, top_p or top_k	No error; the value is ignored
Asking for raw-text JSON tool calls with no declared tools	Can return MALFORMED_FUNCTION_CALL
background: true without max_output_tokens	The server stops at 65,536 tokens
Using cached_content or caches.create	Explicit caching is not supported; the docs tell you to remove it

The sneakiest row in the table is the fourth: an in-range temperature value does not raise an error, it simply does nothing. Your code keeps running but the setting has no effect, so deleting the field is cleaner than leaving it in silently.

Cost impact

There are three separate effects, and they do not all push in the same direction.

Unit price. Through December 31, 2026, Hydrogen costs twice what 3.8 Flash costs. A request with 100,000 input tokens and 5,000 output tokens costs 0.1 × $0.75 + 0.005 × $3.75 = $0.09375 on 3.8 Flash and 0.1 × $1.50 + 0.005 × $7.50 = $0.1875 on Hydrogen. From January 1, 2027, the two models cost the same for the same token counts.

Thinking tokens. The token counts may not stay the same. Because the default level is high instead of medium, the model produces more thinking tokens, and those are billed at the output price. Artificial Analysis's measurement of Hydrogen shows how the level affects the bill (Intelligence Index v5.0.1):

Thinking level	Index	Cost per index task	Time per task
low	27	$0.29	1.3 min
medium	41	$0.80	3.7 min
high (default)	51	$1.87	7.8 min
xhigh	54	$3.16	14.1 min

The high level costs more than twice as much as medium and brings 10 points in return. If you migrate without specifying anything, you run at the second most expensive level.

The token-savings claim. Google says early partner tests used 12% to 23% fewer tokens than 3.8 Flash (complex graphs, SQL, data-heavy workflows). That is a result reported for those partners' workloads; it is not a guarantee for yours.

On caching there is one convenience: implicit caching works on its own, and cached input costs $0.075 per million tokens. All the tiers are in the pricing post.

If you are coming from Argon or Carbon

The migration in this direction is much shorter because the request schema is the same: you change only the model name. The differences you need to know:

• Hydrogen runs at high by default and supports xhigh; Argon and Carbon default to medium and stop at high.
• On non-streaming hops Hydrogen allows 65,536 tokens; on Argon and Carbon the limit on REST is 32,768 per hop.
• To switch models in the middle of a conversation, use previous_interaction_id.

The price difference also works in your favor in this direction: Argon and Carbon are $2 / $10 through November 30, 2026, and $4 / $20 from December 1; Hydrogen is $1.50 / $7.50.

A test plan before you switch production

This section is my suggestion; it is not an order given in the docs. Each item rests on a data point above.

1. Use your own evaluation set. Prepare a small set of tasks from the work your product actually does, and compare the two models on the same set. Someone else's benchmark does not measure your work.
2. Try medium and high side by side. This is Google's suggestion too. On Artificial Analysis the gap is 10 points and more than twice the cost; only measuring will show which side weighs more on your work.
3. Watch the refusals. According to the model card, unjustified refusals got worse by 5.57 percentage points compared with 3.8 Flash in automated safety comparisons. Check whether harmless requests the old model answered are turned down by the new one.
4. Watch the output length. Artificial Analysis calls Hydrogen "very verbose": at xhigh it spent 304 million output tokens on the index, against a median of 77.3 million. Output tokens are the expensive line on the bill.
5. Trigger each case in the error table. In particular, sampling parameters that are silently ignored and background outputs that stop at 65,536 are cases that may not show up as errors.
6. Keep the way back open. Read the model name from configuration. Because there is no shutdown date for 3.8 Flash, going back to the old model is possible if something goes wrong.

One note if you build terminal-based agents: in the independent measurements Hydrogen trails Claude Sonnet 5.5 on this kind of work. The numbers are in the comparison post.

Frequently Asked Questions

Is Gemini 3.8 Flash being shut down?

No retirement date has been published, and the API release notes contain no shutdown entry. Google describes Hydrogen as the "recommended upgrade."

Is changing the model name enough?

No. The minimal thinking level returns an error, explicit caching is not supported, out-of-range sampling parameters return a 400, and the default thinking level becomes high instead of medium.

Can you set temperature on Hydrogen?

No. Google says to remove the temperature, top_p and top_k fields; in-range values are ignored and out-of-range values return a 400.

Is Hydrogen more expensive than 3.8 Flash?

Through December 31, 2026, its unit price is double ($1.50 / $7.50 versus $0.75 / $3.75). From January 1, 2027, the unit prices are equal; but because the default high level produces more thinking tokens, your bill may still differ.

I was using explicit caching. What should I do?

Remove the uses of cached_content and caches.create. On Hydrogen, implicit caching works on its own for prompts of at least 4,096 tokens and gives 95% off cached input.

How do you get output longer than 65,536 tokens?

With long decode: pass background: true together with a max_output_tokens above 65,536. The upper limit is 1,048,576 tokens; without max_output_tokens the server stops at 65,536.

Sources

• Google AI Studio, What's new in Gemini 4 Hydrogen (checked on November 14, 2026): migration steps, error behavior, code fields, notes on moving from Argon and Carbon.
• Google AI Studio, Gemini 4 Hydrogen model page: window, output limit, thinking levels, caching support.
• Google AI Studio, Gemini API pricing (checked on November 14, 2026): prices and dates for Hydrogen, 3.8 Flash, Argon and Carbon.
• Google AI Studio, Gemini API release notes: no shutdown entry for 3.8 Flash, the gemini-2.5-pro routing.
• Google, Introducing Gemini 4 Hydrogen (November 12, 2026, updated November 13): the speed, Terminal-Bench 4.1 and token-savings claims against 3.8 Flash.
• Google DeepMind, Gemini 4 Hydrogen model card: the 5.57 percentage point change in unjustified refusals.
• Artificial Analysis, Gemini 4 Hydrogen and the model leaderboard: index, cost and time by thinking level; output token count; 3.8 Flash's index score.
• DataCamp, Gemini 4 Hydrogen (Josef Waples, November 13, 2026): thinking_budget returning a 400.