Google made Gemini 4 Hydrogen (gemini-4-hydrogen) generally available in the Gemini API on 12 November 2026. It is the fast, lower-cost member of the Gemini 4 family, it is on the free tier, and Google recommends it as the upgrade path from Gemini 3.8 Flash. It also adds a fourth thinking level, xhigh. This guide shows how to call it from Python, pick a thinking level, generate very long outputs, and migrate existing Gemini 3.8 Flash code without surprises.
All facts and code here come from Google’s What’s new in Gemini 4 Hydrogen guide and the Gemini API release notes.
What Gemini 4 Hydrogen gives you
| Item | Value |
|---|---|
| Model ID | gemini-4-hydrogen |
| Thinking levels | low, medium, high (default), xhigh |
| Context window | One unified 1,048,576-token window shared by input, thinking and output |
| Output per request | Up to 65,536 tokens per synchronous hop; longer with background execution |
| Paid-tier price | $1.50 per 1M input tokens, $7.50 per 1M output tokens (thinking tokens included) |
| Cached input | Implicit caching discounts cached input by 95%, to $0.075 per 1M tokens |
| Free tier | Yes, rate-limited, also in Google AI Studio |
Google positions it for everyday coding, tool-using agents, interactive web apps and multimodal document work. The heavier Gemini 4 Carbon and Gemini 4 Argon share the same 1M window and API design, so you can mix them in one workflow: Carbon plans, Hydrogen executes.
Step 1: Install the SDK and set your key
Hydrogen works with both generateContent and the newer Interactions API. The examples below use the Interactions API, as Google’s guide does.
pip install -U google-genai
export GEMINI_API_KEY="your-key-from-ai-studio"
The client reads GEMINI_API_KEY from the environment automatically.
Step 2: Your first request
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Write a Python function that validates an Indian PIN code and explain the edge cases.",
)
print(interaction.output_text)
With no extra settings, the model uses the high thinking level and the 64K synchronous output limit.
Step 3: Choose the right thinking level
The thinking level is your main lever for quality, latency and cost. Google’s guidance:
low: fewest tokens and lowest latency. Fast chat and high-throughput processing.medium: interactive coding, live UI prototyping and latency-sensitive tool calls.high(default): the recommended starting point for complex coding, agents and multimodal work.xhigh: the deepest reasoning. Keep it for hard, multi-step problems wherehighfalls short. It costs more tokens, adds latency and can “overthink” simple prompts.
Set it through generation_config:
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input=(
"Audit this retry queue for race conditions and rewrite the lock "
"acquisition so two workers can never process the same job:\n\n"
+ open("queue_worker.py").read()
),
generation_config={"thinking_level": "xhigh"},
)
print(interaction.output_text)
A practical way to choose: run your own evaluation prompts at all four levels with a generous max_output_tokens, then keep the lowest level that meets your quality bar. Here is a small harness:
import time
from google import genai
client = genai.Client()
PROMPT = "Refactor this function to be O(n) and add type hints:\n" + open("slow.py").read()
for level in ["low", "medium", "high", "xhigh"]:
start = time.perf_counter()
result = client.interactions.create(
model="gemini-4-hydrogen",
input=PROMPT,
generation_config={"thinking_level": level, "max_output_tokens": 65536},
)
elapsed = time.perf_counter() - start
print(f"--- {level}: {elapsed:.1f}s")
print("usage:", result.usage)
print(result.output_text[:400], "\n")
Compare the answers side by side and look at the usage numbers, because you are billed for thinking tokens as output.
Step 4: Generate outputs longer than 64K tokens
A single synchronous request returns up to 65,536 tokens. For longer work, such as a full migration spec or a large test suite, set background=True and raise max_output_tokens. The server then continues in 64K-token hops while you poll:
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Generate a complete multi-module migration specification and test suite for this service.",
background=True,
generation_config={
"max_output_tokens": 262144,
"thinking_level": "high",
},
)
while interaction.status in ("in_progress", "queued"):
time.sleep(5)
interaction = client.interactions.get(id=interaction.id)
text = "".join(
content.text
for step in interaction.steps
if step.type == "model_output"
for content in step.content
if content.type == "text"
)
print(text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
Two details matter here. First, max_output_tokens caps thinking and answer tokens together, so leave room for the answer. Second, if you set background=True but forget max_output_tokens, the server still stops at 65,536 tokens. The ceiling is 1,048,576 minus your input tokens.
Google’s suggested starting values: keep the default for standard tasks, remove old hard-coded caps such as 8,192, and use 131,072 or 262,144 with background execution for long, multi-step jobs.
Step 5: Migrate from Gemini 3.8 Flash
Hydrogen follows the Gemini 4 API design, so a few habits from Gemini 3.x will break or behave differently. Work through this checklist:
- Change the model string from
gemini-3.8-flashtogemini-4-hydrogen. - Set
thinking_levelon purpose. The default moves frommediumtohigh, so latency and token use can rise.minimalis rejected with an error. - Remove sampling parameters. Drop
temperature,top_pandtop_k. In-range values are ignored; out-of-range values return a400error. - Stop using explicit caching.
cachedContentsandcaches.createare not supported, so removecached_contentfields. Implicit caching is on by default for prompts of at least 4,096 tokens. - Rethink output caps. Input, thinking and output now share one 1M window, while a single request still tops out at 65,536 tokens.
- Declare tools natively. Don’t ask the model, through system instructions, to print raw JSON “tool calls” with no tools declared, because that can return
MALFORMED_FUNCTION_CALL. Use function calling or structured outputs. - Keep conversation state intact. In the Interactions API, pass
previous_interaction_idfor multi-turn and tool sessions. In client-managedgenerateContenthistories, send back earlier model turns and thought signatures unchanged.
A typical before/after looks like this:
# Before (Gemini 3.8 Flash habits)
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=prompt,
generation_config={"temperature": 0.2, "max_output_tokens": 8192},
)
# After (Gemini 4 Hydrogen)
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input=prompt,
generation_config={"thinking_level": "medium"}, # choose deliberately
)
Step 6: Pair Hydrogen with Carbon in multi-turn sessions
Because the Gemini 4 models share one API design, you can plan with the stronger model and execute with the cheaper one in the same session, chaining turns with previous_interaction_id:
from google import genai
client = genai.Client()
plan = client.interactions.create(
model="gemini-4-carbon",
input="Design the module boundaries for splitting our billing service into three packages.",
)
step = client.interactions.create(
model="gemini-4-hydrogen",
input="Now write the package skeletons and unit-test stubs for the plan above.",
previous_interaction_id=plan.id,
)
print(step.output_text)
Note that Carbon and Argon default to medium and cap at high, while Hydrogen defaults to high and supports xhigh.
Cost tips
- Start at
mediumorhighand only move toxhighwhen your tests show a clear quality gain. - Put long, stable context (docs, schemas, codebases) at the start of the prompt so implicit caching can apply.
- Watch
interaction.usagein development, because thinking tokens are billed as output at $7.50 per 1M. - Grounding with Google Search is billed per query on top of tokens.
Takeaway
Gemini 4 Hydrogen is a sensible default for everyday coding and agent work in the Gemini API: it is cheap, on the free tier, and has a 1M-token unified window. The real work in adopting it is choosing a thinking level based on your own evaluations and cleaning up Gemini 3.x habits like sampling parameters, explicit caches and low output caps. Read the official Gemini 4 Hydrogen guide before you switch production traffic.
