· reAPI Team
Gemini 4 Hydrogen API Tutorial: Thinking Levels, Streaming, and Native Requests
Learn Gemini 4 Hydrogen native requests, four thinking levels, streaming, token usage and explicit continuation, using Google's GenerateContent format.

Gemini 4 Hydrogen accepts native GenerateContent requests and offers four thinking levels: low, medium, high and xhigh. High is the default. Its shared context and continuation system make it useful for coding and agent tasks, but they also mean that a short visible answer can use a substantial thinking budget.[1]
This tutorial follows Google's documented REST format: send a request, inspect the result, change the thinking level and handle streaming or continuation. The examples call Google's Gemini API with a Google key. For the integrated reAPI endpoint, use the Gemini 4 Hydrogen Playground and live group prices or native API documentation. The examples below retain Google's host and Google credentials; do not mix credentials between services.
TL;DR
- Put the stable model ID in the request URL and the prompt in
contents. Authenticate Google's endpoint with a Google API key in thex-goog-api-keyheader.[2] - Start with high thinking. Evaluate lower levels for responsive work and xhigh for harder problems; extra thinking can increase latency and token use.[1]
- Gemini 4 Hydrogen permits up to 65,536 output tokens per hop for both complete JSON and streaming responses. The unified 1,048,576-token window is shared by input, thinking and output.[1]
- Read candidate parts, finish reasons and usage. A successful HTTP response does not show that a proposed code change works.[2]
- Continue a long answer only with the returned continuation token and the original request. Direct REST leaves each follow-up request under your control.[3]
Send a native Gemini 4 Hydrogen request
For direct Google access, create a key in Google AI Studio and configure the project for the usage tier you need. Google's free and paid tiers have different limits; an account subscription for a consumer product is separate from API access.[1][4] Keep the credential in an environment variable on your server. A reAPI key is not a Google key and cannot authenticate this Google endpoint.
The following request asks for a small, checkable code fix. It uses low thinking to illustrate an explicit selection, rather than implying that low is the model's default. Save the body as request.json:
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Fix this Python function so separate calls do not share a list: def append_item(item, items=[]): items.append(item); return items. Include one test that catches the bug."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": { "thinkingLevel": "low" }
}
}Send the Gemini 4 Hydrogen request to its model-specific URL:
curl --fail-with-body \
'https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent' \
-H "x-goog-api-key: $GOOGLE_GEMINI_KEY" \
-H 'Content-Type: application/json' \
--data-binary @request.jsonThe field names and nesting follow the official GenerateContent contract.[2] The output cap in this example is an illustrative budget, not a recommendation for every task. Thinking uses part of that allowance, so inspect the finish reason before deciding the answer is complete.
Gemini 4 Hydrogen uses a native conversation representation: a content item has a role and an array of parts. Do not replace that body with OpenAI-style messages while retaining the same endpoint. For follow-up turns, preserve the complete model parts, including function calls and any thought signatures, rather than reconstructing the history from displayed text alone.[2]
Read Gemini 4 Hydrogen responses and usage
A native response contains candidates and may include usage and prompt-feedback information. Candidate content holds the response parts; the finish reason belongs to the candidate. A continuation token also belongs to the candidate, rather than to an individual text part.[2]
For a simple text interface, collect text parts that are not marked as thoughts. Keep the original response separately when your application needs tool calls, signatures or continuation state. Available thought summaries are not a promise that the model exposes all of its private reasoning.[2][5]
For the code example, the acceptance check is concrete: make separate calls without supplying a list and confirm that the second result does not retain the first item. Run the returned test and inspect the implementation. This is a suggested evaluation procedure, not a claim that we executed the example or measured model quality.
Usage deserves a separate check. Google bills thinking tokens as output, and native usage can distinguish prompt, cached-input, candidate, thought and tool-use tokens.[2][4] A short final answer therefore does not necessarily mean a small bill. Compare complete tasks, including any explicit continuation and additional tool charges, rather than comparing the length of displayed prose.
Gemini 4 Hydrogen supports implicit caching, but not explicit cached-content resources. Google's documented minimum for eligible implicit caching is 4,096 prompt tokens; a repeated prompt does not guarantee a hit. Use returned cached-input usage to determine whether the request benefited.[1]
Choose a Gemini 4 Hydrogen thinking level
For Gemini 4 Hydrogen, the thinking level is the main documented control for the reasoning tradeoff. It is not a fixed token count, and choosing a higher level does not guarantee a better result on every prompt.[1]
| Level | Google's suggested use | Tradeoff to evaluate |
|---|---|---|
| low | Cost- or latency-sensitive workloads | Whether the reduced thinking still meets the task's quality bar |
| medium | Interactive coding, UI prototyping and responsive tool calls | Response time and correctness together |
| high | Default for complex coding, agents and multimodal work | A starting point for a representative evaluation |
| xhigh | Difficult multi-step problems where high falls short | Extra token use and latency; possible overthinking on simpler tasks |
Source: Google's Hydrogen migration guide and thinking documentation.[1][5]
Run the same acceptance checks at each level. Record completion, errors, token usage and elapsed time under the same conditions. A model that returns quickly but needs another repair request can be less useful for your application than one that takes longer and passes the check. That is an evaluation question, not a universal ranking of the levels.
Gemini 4 Hydrogen defaults to high when you omit the thinking setting. Carbon and Argon default to medium, so copying a request without an explicit level changes the starting behavior when you switch models.[1] The Carbon guide and Argon guide cover their different intended roles.
Do not tune an old sampling recipe and assume it has the same effect here. Google says in-range custom temperature, topP and topK values are ignored on Hydrogen, while out-of-range values can still produce an error. Deprecated thinking budgets are also distinct from current thinking levels; let the documented model contract govern those choices.[1]
Stream Gemini 4 Hydrogen without mixing protocols
For native streaming, keep the request body and change the operation to streamGenerateContent, with alt=sse. The curl -N option prevents output buffering:
curl -N --fail-with-body \
'https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:streamGenerateContent?alt=sse' \
-H "x-goog-api-key: $GOOGLE_GEMINI_KEY" \
-H 'Content-Type: application/json' \
--data-binary @request.jsonThis selects the streaming operation; an OpenAI-style stream flag is not what chooses native SSE.[2] A consumer should parse complete SSE events and their JSON payloads rather than treating every network chunk as a complete JSON object. Network reads can divide an event in the middle of a string.
Gemini 4 Hydrogen streaming still returns native candidate data. Handle content parts, finish information and usage alongside visible text. Retain opaque signatures and continuation tokens when supplied. A text-only renderer can display the answer while a separate conversation record preserves the fields needed for the next turn.[2]
Streaming improves the way an application receives output; it does not remove the output budget or guarantee that the first event contains answer text. A difficult task can spend time on thinking before delivering the final response.[3] Treat a disconnection as an incomplete observation and inspect the last valid state before choosing whether to retry or continue.
Continue a long response within the shared window
The context window and the per-hop cap answer different questions. The window limits the combined input, thinking and output state. The hop cap limits how much one response delivers before continuation is needed. Gemini 4 Hydrogen uses a 65,536-token per-hop default and cap for both JSON and SSE, within its shared 1,048,576-token context.[1][3]
When a candidate finishes with CONTINUATION and supplies a continuation token, send the original body again with that token added at the top level. Keep the original contents, tools and generation settings. Do not append the partial answer to the original contents, and do not subtract the completed hop from the configured total output budget.[3]
A thinking-only hop can have no visible answer text. That is different from a malformed response. At MAX_TOKENS, the configured total budget has been reached; Google's guide describes increasing the total budget when resuming with the token.[3] Check the finish reason rather than interpreting every empty answer as a request failure.
Direct REST usage is reported per hop. Sum the relevant usage across completed hops for total cost, while using the first prompt count to describe the original input size.[3] Keep a request log that associates each explicit follow-up with the original task. This makes a long result explainable when you later inspect token use.
Current Google GenAI SDKs can automatically continue long decode by default. If you move from raw REST to an SDK, review its continuation and retry configuration before assuming one client method invocation means one HTTP request. Google recommends a long read timeout for these operations, but client settings cannot extend a hosting platform's own request deadline.[3]
FAQ
What is the model ID for Gemini 4 Hydrogen?
The stable ID is gemini-4-hydrogen. Native REST places it in the URL path under models, while contents and generation settings belong in the request body.[2][6]
Can I turn thinking off?
No. Google documents low, medium, high and xhigh for this model, with high as the default. Lowering the level changes the tradeoff; it does not disable thinking.[5]
Why did my answer stop before the context window was full?
The request's output budget or the per-hop limit can stop a response before the shared window is full. Inspect the candidate finish reason and continuation state before sending another request.[3]
Does streaming allow a larger Hydrogen hop than JSON?
No. Both use the documented 65,536-token per-hop cap for Gemini 4 Hydrogen. That differs from Carbon and Argon's lower non-streaming REST cap.[1]
Is Gemini 4 Hydrogen free?
Google lists free and paid API tiers with different limits. That is a Google offering, not a free reAPI allowance; check the current Google pricing page for the tier you intend to use.[4]
How do I use a reAPI key or select a reAPI group?
Use the endpoint in the reAPI native documentation with your reAPI key. The Gemini 4 Hydrogen model page discovers the available groups and their current rates. Select a group in the Playground or use the returned gemini-4-hydrogen:GROUP_ID model ID in your request. One key works across available groups, with no custom group header; the bare model ID uses the configured default. The Google-hosted examples above require Google credentials.
Make the first result checkable
Start with a small request whose output you can verify. Keep the raw response, check the finish reason and usage, and compare thinking levels with the same acceptance criteria. When you need a longer result, handle continuation explicitly instead of treating the shared context window as a single-response promise.
For task selection and comparison with Carbon, return to the Gemini 4 Hydrogen model guide. For the exact current wire fields, use Google's GenerateContent reference. A request that succeeds is the beginning of validation: the useful question is whether the completed work passes your own checks.
References
- Google. What's new in Gemini 4 Hydrogen. Retrieved November 14, 2026 from aistudio.google.com/docs/whats-new-gemini-4-hydrogen.
- Google. GenerateContent API reference. Retrieved November 14, 2026 from aistudio.google.com/api-reference/generate-content/generate-content.
- Google. Long decode. Retrieved November 14, 2026 from aistudio.google.com/docs/long-decode.
- Google. Gemini API pricing. Retrieved November 14, 2026 from aistudio.google.com/docs/pricing.
- Google. Thinking. Retrieved November 14, 2026 from aistudio.google.com/docs/thinking.
- Google. Gemini 4 Hydrogen model documentation. Retrieved November 14, 2026 from aistudio.google.com/docs/models/gemini-4-hydrogen.