Hydrogen arrived on November 12 as the fast execution model in the Gemini 4 family, the one Google built for everyday coding and agent work. Then comes the twist that shapes your bill. Gemini 4 Hydrogen thinks at high by default. A model sold on speed starts every job at the second deepest reasoning setting it has, and thinking tokens bill at the output rate.
That default is not a mistake. Google reports strong results at high, and plenty of agent work needs real reasoning before the first tool call. But routine work pays the same toll. A routing check, a summary, a short extraction and a hard debug session all start at high unless your code says otherwise. This tutorial puts that dial in your hands.
What You Will Build or Learn
You will end with a small Python helper that calls gemini-4-hydrogen at any of its four levels, plus the same call in raw REST for stacks that do not use the Python SDK. Along the way you will learn what each level is for, in the words Google uses in its thinking guide, and how to prove a level choice with numbers from your own workload instead of habit.
You will also learn the three facts that make this dial worth setting at all. Thinking tokens count as output tokens for billing, at $7.50 per million output tokens on the paid standard tier. Thinking, input and output all draw on one shared window of 1,048,576 tokens. And a single response segment caps at 65,536 output tokens, thinking included, so a deep level and a low cap can spend the whole budget on thought and return no answer at all.
Four levels, four lever pulls. The taller the pull, the more thought the model spends before it answers. Illustration: Dirty Static
Before You Begin
Learn the rejects first, because Hydrogen refuses two settings that older code may still carry. The level minimal is not supported on any Gemini 4 model, Hydrogen included, and a request that asks for it fails. The old thinking_budget control belongs to Gemini 2.5 and earlier models. Coverage of the Hydrogen migration notes and the thinking guide agree that Hydrogen rejects it, and sending thinking_level and thinking_budget together returns an error on Gemini 3 and later models in any case. One dial at a time, and on Hydrogen that dial is the level.
One scope note. This tutorial follows the Gemini API form of the setting, where the field sits inside thinkingConfig. Google Cloud documents the same levels for its enterprise platform, with the same values and the same default for Hydrogen, and the Python shape there uses thinking_config in the same way. The level names, the defaults and the rejects in this tutorial were checked against that Google thinking guide on November 13, 2026. No live call with a real key is claimed here.
| Level | Google guidance in short | Work it fits |
|---|---|---|
low | Fewer thinking tokens, faster responses, low task complexity | Routing, classification, short summaries, extraction |
medium | Balances reasoning quality and latency, moderate complexity | General coding, document questions, interactive work |
high | Deep reasoning, multi step problem solving, formal code checks, multi turn tool use. Default on Hydrogen | Agent runs, hard debugging, complex analysis |
xhigh | Maximum thinking capacity, for the hardest math, science, formal checks and long horizon software work | The few jobs where high visibly falls short |
Step 1: Install the SDK and Set Your Key
Action: install the Google Gen AI SDK, create a key in Google AI Studio, and store it in an environment variable. Keep the real value out of code, logs and chats, and use the placeholder form in every note you share.
pip install --upgrade google-genai
export GEMINI_API_KEY="your-key-here"
Expected result: the install completes and the variable is set for this shell session. The SDK client in the next steps reads that variable on its own, so no step in this tutorial pastes a key into a request by hand, apart from the REST header in Step 6, which reads the same variable.
Step 2: Make a First Call and Read the Thinking Count
Action: run this call with no thinking setting at all. This is your baseline, and on Hydrogen the baseline means high.
from google import genai
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-hydrogen",
contents="Explain in two sentences why a queue forms at a single open checkout.",
)
print(response.text)
print(response.usage_metadata)
Expected result: the answer prints, and the usage block prints with it. Find the thinking token count in that block. That count is the part of the bill most teams never look at, and it is the number every later step tries to control. Google also warns that a model can answer some simple requests with no thought parts at all, even with thinking on. Code that reads usage or thought summaries must handle a missing or empty count without failing.
Step 3: Set Low for Fast Routine Work
Action: add a thinking config with the level set to LOW. The Python form names the config classes from the SDK, and the level values are the enum members the Google guide lists, LOW, MEDIUM, HIGH and XHIGH.
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-hydrogen",
contents="Classify this ticket as billing, shipping or product help: My invoice shows the wrong total.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
thinking_level=types.ThinkingLevel.LOW
)
),
)
print(response.text)
print(response.usage_metadata)
Expected result: the same shape of answer returns, faster, with a lower thinking token count than the baseline on a prompt of this size. This is the level for high volume work where each call is simple and the cost of a rare miss is low. If the job is a fixed judgment with a fixed set of answers, consider whether it needs a chat model at all. Our tutorial on the Gemini Decisions API covers that narrower tool.
Step 4: Set Medium and High by Task, Not by Habit
Action: wrap the call in a small helper that takes the level as an argument. Your code can then route each task class to a level in one place, where a change is easy to review.
from google import genai
from google.genai import types
client = genai.Client()
def ask(prompt, level):
return client.models.generate_content(
model="gemini-4-hydrogen",
contents=prompt,
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_level=level)
),
)
draft = ask("Draft a commit message for a fix to a login timeout.", types.ThinkingLevel.MEDIUM)
review = ask("Review this function for race conditions and list each one you find.", types.ThinkingLevel.HIGH)
print(draft.text)
print(review.text)
Expected result: both calls return, and the usage blocks show the gap between the levels on real prompts from your own work. medium is the balance point Google describes, suited to moderate complexity. high earns its cost on multi step problems, formal code checks and tool use across turns. A note on long chats applies at both levels. Thought signatures, the encrypted record of reasoning state that Google uses to keep context across turns, travel with the response. If you use chat sessions or append complete responses to your history, the SDK handles them for you. If you rebuild history by hand, pass the returned parts back whole, or later turns can lose the thread.
Step 5: Reserve Xhigh for the Hardest Jobs
Action: set the level to XHIGH only for a job where high has already shown a real shortfall, such as a proof, a hard science problem or a long software task with many linked steps.
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-hydrogen",
contents="Prove that the sum of the first n odd numbers equals n squared, and check each step.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
thinking_level=types.ThinkingLevel.XHIGH
)
),
)
print(response.text)
print(response.usage_metadata)
Expected result: the answer takes longer to start and the thinking token count climbs well past the high run of a similar prompt. That trade is the point of the level, and it is also why it stays rare. xhigh is new with Hydrogen. No other Gemini 4 model in the Google table offers it, and Carbon and Argon stop at high. Treat it as a specialist tool, not as a new default with a better name.
Step 6: Set the Same Level in Raw REST
Action: for stacks without the Python SDK, send the level inside generationConfig in the request body. The field name in REST is thinkingConfig and the level field inside it is thinkingLevel, written as a plain string.
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" -H "Content-Type: application/json" -H "x-goog-api-key: $GEMINI_API_KEY" -d '{"contents": [{"parts": [{"text": "Summarize this release note in one line: The server now retries failed uploads twice."}]}], "generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}'
Expected result: a JSON response returns with the answer text and a usage block that carries the thinking token count under its REST name. Change only the string to move between low, medium, high and xhigh. If a request body still carries a thinkingBudget field from Gemini 2.5 era code, remove it before you debug anything else. That field is the most common reason a sound Hydrogen request comes back as an error.
Step 7: Prove the Cheapest Level That Still Passes
Action: build a small test set from your own work, ten to twenty prompts where you already know what a good answer looks like. Run each prompt at low, medium and high, and at xhigh only for the hard cases. Score each answer against your known good result, and record the thinking token count beside the score.
Expected result: a table you can defend. Most routine prompts pass at low or medium, and the saving against the high default is visible in the counts. A small set of prompts will need high, and those prompts define your routing rules in Step 4. Keep the test set and rerun it when Google updates the model, because a level that passed last month is a claim about a model version, not a law of nature.
Verification
Run these checks and record what you see. A call with no level set behaves as high, and its usage shows a thinking count on any prompt that needs thought. The same prompt at low returns with a lower count and a faster start. The REST call in Step 6 returns the same answer shape as the Python calls. Your test set table from Step 7 names, for each task class you run, the lowest level that passed, and your routing code uses those levels and no others.
Finish with the money check. Take one high volume prompt, price its thinking tokens at $7.50 per million, once at the high count and once at the lowest passing count from your test set. Multiply the gap by your monthly call volume. That figure is what this setting is worth to you, stated in your own numbers.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| The request returns a 400 error naming the thinking level | The level was set to minimal, which no Gemini 4 model supports | Use low as the floor on Hydrogen and remove any minimal value left from Gemini 3 era code |
| The request returns an error after a model switch from Gemini 2.5 | The body still carries thinking_budget or thinkingBudget, or it carries that field beside the level | Remove the budget field and set the level alone, as in Steps 3 and 6 |
| The response is empty and the finish reason reads as a token limit | Thinking spent the whole output cap before any answer text was produced | Raise the output token limit for that call, up to the 65,536 segment cap, or drop the level for that prompt |
xhigh runs feel slow and the bill climbs with no better answers | The level is set on prompts that do not need it, and the model overthinks simple work | Return those call sites to high or lower and reserve xhigh for jobs where high has failed in your test set |
| No thought summary or thinking count appears on a simple prompt | The model answered a low complexity request with no thought parts, which Google says can happen | Treat a missing count as zero for logging and never fail a request because the thought fields are empty |
| Changing the level seems to change nothing on a long chat | Rebuilt history dropped the thought signatures that carry reasoning state across turns | Use a chat session, or append complete response objects to history, so the SDK passes the signatures back for you |
Next Steps
Wire the levels into the places where work enters your system. Give each queue, route or tool a named level in config, so a change is a config edit with a review trail, and not a hunt through call sites. Then revisit the split itself once a month. Jobs that shrink to a fixed judgment can leave the chat model entirely, as the Decisions API tutorial linked in Step 3 shows. Jobs that grow in steps and tool calls may earn high more often than they did at first.
The habit worth keeping is simple to state and easy to skip. Never let a default choose your reasoning budget for you. Hydrogen starts at high because Google picked a safe general setting. Your workload is not general, and now your code can say so, one level per job.
Facts, level values, defaults and settings checked against the Google thinking guide and Hydrogen launch coverage on November 13, 2026. Prices are Google paid standard tier rates and can change. This procedure was verified against those documents and is not presented as a personal test run with a live key.
Sources
- Google Cloud, Thinking, Gemini Enterprise Agent Platform documentation, level values, defaults by model, thought signatures and pricing notes, checked November 13, 2026: https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/thinking
- Google, Gemini 4 Hydrogen launch post, via Yoopya coverage with the pricing, levels and context facts, November 13, 2026: https://www.yoopya.com/technology/artificial-intelligence/gemini-4-hydrogen-google-ai
- Hesham Saad, Gemini 4 Hydrogen, pricing, thinking levels and migration notes, November 12, 2026: https://heshamsaad.com/en/gemini-4-hydrogen/
- Smteon, Gemini 4 Hydrogen, specs, thinking levels and REST form, November 13, 2026: https://smteon.com/blog/gemini-4-hydrogen
- Hero and lever illustrations: Dirty Static
END OF TRANSMISSION
Stay curious. Question everything.
