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 where high falls 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:

  1. Change the model string from gemini-3.8-flash to gemini-4-hydrogen.
  2. Set thinking_level on purpose. The default moves from medium to high, so latency and token use can rise. minimal is rejected with an error.
  3. Remove sampling parameters. Drop temperature, top_p and top_k. In-range values are ignored; out-of-range values return a 400 error.
  4. Stop using explicit caching. cachedContents and caches.create are not supported, so remove cached_content fields. Implicit caching is on by default for prompts of at least 4,096 tokens.
  5. Rethink output caps. Input, thinking and output now share one 1M window, while a single request still tops out at 65,536 tokens.
  6. 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.
  7. Keep conversation state intact. In the Interactions API, pass previous_interaction_id for multi-turn and tool sessions. In client-managed generateContent histories, 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 medium or high and only move to xhigh when 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.usage in 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.