Skip to content
Giallo

Migrate to Gemini 4 Hydrogen: Checklist From Gemini 3.8 Flash and 2.5 Before 1 December

How to migrate to Gemini 4 Hydrogen from Gemini 3.8 Flash and 2.5: parameters to change, test plan, rollback and what happens on 1 December 2026.

Editorial team: Giallo Studio

Published on

Updated on

Reading time: 10 min

Diagram to migrate to Gemini 4 Hydrogen: from gemini-3.8-flash and gemini-2.5 through the checklist to gemini-4-hydrogen

Migrating to Gemini 4 Hydrogen means replacing the model ID with gemini-4-hydrogen and reviewing the settings that change compared with Gemini 3.8 Flash. Do it calmly before 1 December 2026, when Google starts automatically routing requests for Gemini 2.5 Pro and 2.5 Flash. The sources are the “What’s new in Gemini 4 Hydrogen” guide, the model list, the Gemini API price list and the Agent Platform model page, all accessed on 14 November 2026.

This page is for anyone who already has an integration in production: a management system, a chatbot, an automation. To understand what the model is, see Gemini 4 Hydrogen: what it is. The checklist reports Google’s documentation and a testing method we propose; Giallo has not carried out this migration on third-party systems.

In summary

  • From 1 December 2026, requests to gemini-2.5-pro are routed to gemini-3.8-flash and from gemini-2.5-flash to gemini-3.5-flash-lite, at the new model’s rates (model list, price list).
  • Google recommends Hydrogen as the upgrade from Gemini 3.8 Flash and from the earlier Gemini 3 and 2.5 models (official guide).
  • The ID change is not enough: Hydrogen starts at high, rejects minimal, ignores temperature, top_p and top_k and does not support explicit caching.
  • The output cap per request is 65,536 tokens within a single window of 1,048,576: an old low limit on max_output_tokens truncates responses.
  • From Carbon or Argon the request schema stays the same; the default reasoning level and the step cap change.
  • Plan the rollback in advance: model ID in configuration, testing on real cases at several reasoning levels, gradual rollout.

What happens on 1 December 2026 to Gemini 2.5 Pro and 2.5 Flash?

On 1 December 2026, Google stops serving gemini-2.5-pro and gemini-2.5-flash with the original model: requests are redirected to another model and billed at its rates. Both models are already deprecated and cannot be selected in AI Studio, with API access limited to those who used them. The information comes from the model list and the price list.

Model in your code What Google says on 14 November 2026 Where requests go
gemini-2.5-pro Deprecated; from 1 December 2026 automatic routing, 3.8 Flash rates (source) gemini-3.8-flash
gemini-2.5-flash Deprecated; from 1 December 2026 automatic routing, 3.5 Flash-Lite rates (source) gemini-3.5-flash-lite
gemini-2.5-flash-lite Not deprecated, served until further notice; for new projects Google points to Hydrogen or 3.5 Flash-Lite (source) No change announced
gemini-3.8-flash Stable model of the previous generation; no retirement date in the pages consulted No change announced
Why an automatic switch is a risk Routing guarantees that the request gets a response, not that it matches the previous one. It is a different model: style, length, timing and cost per request can change without a single line changing in your code. Choosing the destination model yourself, and testing it first, is the safest way to control timing and results. Our assessment, not Google’s.

For Gemini 2.5 Flash, the models page invites you to update the string to gemini-3.5-flash-lite; to see where Flash-Lite sits relative to the Flash tier, you will find prices and a comparison in Gemini 3.6 Flash vs 3.5 Flash. Hydrogen’s guide, on the other hand, points to Hydrogen as the upgrade from the 2.5 models and reserves Flash-Lite for high-volume classification and routing. The choice depends on the task: the comparison is in Hydrogen, Carbon and Argon.

What is the right order to migrate an existing integration?

First find out where the model is used, then change one thing at a time, and finally roll out gradually.

  1. Inventory. List every place where a model ID appears: code, environment variables, automation flows, per-client configurations, test environments.
  2. One place for the ID. Move the ID into a single setting, so that switching to gemini-4-hydrogen and rolling back are a one-value change.
  3. Parameter cleanup. Remove cached_content, temperature, top_p and top_k and fix low caps on max_output_tokens.
  4. Test set. Collect anonymized real cases, with the expected result written before the test.
  5. Multi-level comparison. Run the same suite on at least medium and high; Google suggests trying all four levels with a high max_output_tokens and choosing the lowest one that meets your quality threshold.
  6. Gradual rollout. Send a small share of traffic first, with the old model ready to take everything back.
  7. Closing. Remove the old ID only after costs, timings and errors have been read over a period you decided in advance.

What changes in the parameters compared with Gemini 3.8 Flash?

The table follows the migration section of the official guide and, for Agent Platform, the Google Cloud model page.

Area What to look for in your code (3.8 Flash and earlier) With Hydrogen What to do
Model gemini-3.8-flash gemini-4-hydrogen Change the model string
Window and output 1M of input and 64K of output in separate budgets A single window of 1,048,576 tokens for input, reasoning and output; 65,536 as the default and the per-request cap Remove low caps on max_output_tokens (Google cites 8,192) or raise them to 65,536
Reasoning medium as the default (3.8 Flash) high as the default, new xhigh, minimal returns an error Try medium and high on your own suite
Caching cachedContents, caches.create, field cached_content Implicit caching only, from at least 4,096 tokens, with a 95% discount on cached tokens (guide) Remove explicit caching
Sampling temperature, top_p, top_k Values ignored if in range, error 400 if out of range Remove the three parameters
Tools Instructions that ask for JSON “by hand”, with no tools declared Tools declared with function calling or structured output Declare the tools, otherwise you risk MALFORMED_FUNCTION_CALL
Status History rebuilt by your code previous_interaction_id in the Interactions API; in generateContent thought signatures returned unchanged Do not modify or copy the thought signatures
Long outputs Responses over 64K tokens background: true and max_output_tokens above 65,536 Use them only when needed
Costs Estimates made on the old model All processed tokens are paid for, reasoning included, at $7.50 per million output tokens (price list) Redo the estimates with real tokens

If you use Gemini Enterprise Agent Platform (formerly Vertex AI), a clarification applies: the model card says that a request with thinking_budget or with thinking_level set to MINIMAL returns an HTTP error 400.

Why should max_output_tokens and thinking_level be reviewed together?

Because the max_output_tokens cap counts reasoning and response together, and the high level uses more reasoning than medium. A cap chosen for the old model can run out before the final text begins. Google says so explicitly: the field “caps combined thinking and output tokens”, so room must be left for the response (guide).

For normal tasks, keep the default or omit the field. To spend less, lower the reasoning level, not the cap. For very long responses, set background to true and max_output_tokens at 131,072 or 262,144, up to 1,048,576 minus the input tokens; without max_output_tokens the server stops at 65,536.

As for the level: low gives fewer tokens and minimal latency, medium suits interactive coding and responsive chat, high is recommended for most tasks, xhigh is for problems where high is not enough, and on simple prompts it can reason more than necessary (known as overthinking). The general principle is in reasoning effort; what AI tokens are explains why reasoning is paid for as output.

Which habits from the old code stop working?

Low temperature for stable answers. With Hydrogen temperature, top_p and top_k can no longer be adjusted: on Agent Platform they are fixed at 1.0, 0.95 and 64. It follows, by our own reasoning, that repeatability can no longer come from temperature and must be sought elsewhere: a rigid output schema, clear instructions, checks on the result before writing it into the management system.

Explicit caching. Anyone who created a cache by hand must remove it. Implicit caching switches on by itself on prompts of at least 4,096 tokens: it helps to keep the stable parts at the start of the prompt, such as instructions and reference documents, and the parts that change with every request at the end. This arrangement is our own methodological advice, not a rule written by Google. On Agent Platform, from 12 January 2027, cache controls with TTL arrive, with cache writes at 1.25 times the input price by default (model page).

JSON requested “in words”. If the prompt tells the model to write a fake tool call without declaring any tools, the request can fail with MALFORMED_FUNCTION_CALL. Declare the tools with native function calling, or constrain the response with structured output. For the output contract and error handling, the same guidance applies: Gemini 4 Argon API, because the schema is the same.

Conversation state. With the Interactions API you use previous_interaction_id. If instead your code keeps the history with generateContent, the model’s turns and the thought signatures must be sent back identical on every turn, and a thought signature must not be copied across several parallel function calls.

What changes if you start from Carbon or Argon?

According to the guide, anyone using gemini-4-carbon or gemini-4-argon does not need to change the request schema: only the default values change.

Item Carbon and Argon Hydrogen
Model ID gemini-4-carbon, gemini-4-argon gemini-4-hydrogen
Default reasoning medium, maximum high high, with xhigh added
Non-streaming step via REST 32,768 tokens 65,536 tokens

The models can also be used together: planning with Carbon and execution with Hydrogen in the same session, with previous_interaction_id; Google points to a page on the limits of these mixed turns.

How do you test the migration and roll back without risk?

You test with real cases, compare several reasoning levels and prepare the rollback before release. A complete method is in evaluation, testing and rollback for Argon; here is the version for a production integration.

  • The model ID lives in a setting, not scattered across several files.
  • The suite contains typical cases, difficult cases and cases where the model must refuse or ask for help, each with an expected result written before the test.
  • Tests run with a high max_output_tokens because a low cap skews the comparison (Google guide).
  • For each request, the model, reasoning level, tokens, time and errors are logged.
  • An invalid result does not write to the management system or reply to the customer.
  • There is a retry limit and error handling for 429 RESOURCE_EXHAUSTED, which Google associates with the spend limits.
  • The previous model remains callable until the end of the observation period.

On the rollback, two clarifications. Anyone starting from 3.8 Flash goes back to gemini-3.8-flash; Google gives no retirement date in the pages consulted, but the models page should be re-read at every release. Anyone starting from Gemini 2.5 after 1 December 2026 no longer has 2.5 as a fallback, because those requests are routed: the comparison must be done before that date.

How does a software house that maintains the AI integration of a management system approach the migration?

An example, not a real case. The management system classifies support tickets and prepares draft replies. The code has a model ID repeated across several modules, a low temperature to get similar answers and a max_output_tokens of 8,192, the cap Google’s guide cites as one to remove.

The work, in order: ID in configuration, drop temperature, raise or remove the cap, an output schema that the management system checks before saving, then medium and high on the tickets from a past period. The result is a comparison of two columns of responses: where the tone changes, where the classification changes, where tokens increase. xhigh is tried only on the difficult cases. It is best to keep the test suite separate for each client, because the difficult cases are not the same.

And a customer support chatbot on WhatsApp?

Another declared example. A shop has a WhatsApp chatbot that answers questions about orders and returns and queries the management system through a tool. Speed and the tool’s correctness matter. Google points to low for fast chat and medium for responsive chat, while high is the recommended value for most tasks: measure the duration on all three and choose the lowest level that keeps the order answers correct. The tool must be declared natively, and if your code keeps the history, turns and thought signatures go back unchanged.

There is also a contractual point: the terms of the Gemini API allow only Paid Services when you make API-based applications available to users in the European Economic Area, Switzerland or the United Kingdom, so the project must have billing enabled. The rest of the data topic is in Gemini 4 Hydrogen for business; if you need to build the chatbot from scratch, you will find the path on the page WhatsApp chatbot.

How much does it cost to migrate, and when is it worth waiting?

Hydrogen costs $1.50 per million input tokens and $7.50 output, reasoning included (price list). Gemini 3.8 Flash costs $0.75 and $3.75 until 31 December 2026, then $1.50 and $7.50 from 1 January 2027, the same as Hydrogen. For the same tokens, then, staying on 3.8 Flash costs less until the end of the year; but tokens per response differ from model to model, and only testing on your own cases tells you which costs less. Worked examples and spending caps are in Gemini 4 Hydrogen pricing; for the general method, AI API cost: how to calculate it.

Worth moving now

  • If you still use gemini-2.5-pro or gemini-2.5-flash: after 1 December 2026, requests change model without you deciding it.
  • If you already have a test suite and an ID in configuration.

It can wait

  • If you are on gemini-3.8-flash and it works, because Google gives no retirement date in the pages consulted.
  • If the task is high-volume classification, where Google points to Flash-Lite.

What mistakes make a model migration risky?

Four, all avoidable.

  1. Changing only the ID and releasing. With the default high level and the old output cap, behavior can change without any line saying why.
  2. Leaving temperature in the code “just in case”. With an in-range value it is ignored and gives the illusion of a control that is not there; out of range, the request fails with 400.
  3. Waiting for 1 December to observe the new behavior. After that date 2.5 is no longer available as a point of comparison.
  4. Not logging tokens and errors. Without this data you cannot tell whether a cost increase comes from the reasoning level or from a cap that is too high.

Where to start this week?

Start with an inventory of model IDs and the points where automatic routing would change a result for the customer. Then move the ID into configuration and remove the parameters Hydrogen ignores. The rest follows the order of the steps above.

If you want an outside check, Giallo can do a first pass over the integration with you: inventory of IDs, parameters to fix and a test suite on your cases, comparing the current model with Hydrogen. It starts with an AI Consulting. The performance figures Google reports are in Gemini 4 Hydrogen benchmarks.

Giallo Studio guides: methodology and sources

Want to apply this to your business?In 30 minutes, free of charge: the first process to automate and its estimated return, in writing.

Book the free audit

How we apply it in the company

Related resources

AI consulting services and process automation

FAQ

What happens to Gemini 2.5 Pro and Gemini 2.5 Flash on 1 December 2026?

From 1 December 2026, requests to gemini-2.5-pro are automatically routed to gemini-3.8-flash, and requests to gemini-2.5-flash to gemini-3.5-flash-lite, at the rates of the destination model. Google has already removed both models from AI Studio selection and limits API access to existing users.

Is changing the model ID enough to move to Gemini 4 Hydrogen?

No. The gemini-4-hydrogen ID is only the first step: the default reasoning level, the output cap, caching and the sampling parameters all change. If you do not review them, you risk 400 errors, truncated responses or higher costs than expected.

Can I still set temperature, top_p and top_k with Gemini 4 Hydrogen?

No. Google asks you to remove them from requests: values within the limits are ignored, and values outside the limits return a 400 error. On Agent Platform the values are fixed: temperature 1.0, topP 0.95, topK 64.

Does Gemini 4 Hydrogen support explicit context caching?

No. It does not support cachedContents or caches.create: remove the cached_content fields from your requests. Implicit caching remains, active by default from 4,096 tokens upward, with a 95% discount on input tokens found in the cache.

If I already use Gemini 4 Carbon or Argon, what do I need to change to move to Hydrogen?

The request schema does not change: only the gemini-4-hydrogen ID is needed. Check the reasoning level, because Hydrogen starts at high and allows xhigh, while Carbon and Argon start at medium and go up to high.

Will Gemini 3.8 Flash be shut down?

In the pages consulted on 14 November 2026, Google gives no retirement date for Gemini 3.8 Flash, which the model list presents as the stable model of the previous generation. It does recommend Hydrogen as the upgrade, and from 1 January 2027 the two models have the same price.

How do I roll back if the migration to Gemini 4 Hydrogen causes problems?

By keeping the model ID in a configuration setting rather than in the code, so that rolling back to gemini-3.8-flash is a one-value change. For those coming from Gemini 2.5, after 1 December 2026 the fallback point is the model Google routes to, because from that date requests no longer reach 2.5.

Put it into practice

Let's turn this guide into your first live workflow.

Tell us what process you want to lighten: we evaluate feasibility, return and first operational step.