> ## AI Agent Context
> Get the complete documentation index at: https://aistudio.google.com/llms.txt
> Use this file to discover all available pages.
> For the full documentation in a single file, fetch: https://aistudio.google.com/llms-full.txt

# What's new in Gemini 4 Hydrogen

Gemini 4 Hydrogen (`gemini-4-hydrogen`) brings cutting-edge intelligence to everyone, with speed and efficiency for everyday coding and agentic workflows.

Gemini 4 Hydrogen is available on both the free and paid tiers in Google AI Studio and the Gemini API (across both GenerateContent and the Interactions API). Like [Gemini 4 Carbon](/docs/whats-new-gemini-4-carbon?generate-content=true) and [Gemini 4 Argon](/docs/whats-new-gemini-4-argon?generate-content=true), it features a unified 1M-token context window and long decode up to 1M tokens. It also adds a fourth thinking level, [`xhigh`](/docs/thinking?generate-content=true#understanding-thinking-levels), alongside `low`, `medium`, and the default `high`.

{% card-grid %}
  {% card description="View token limits, supported capabilities, and full specifications." href="/docs/models/gemini-4-hydrogen" icon="id_card" title="Model card" /%}

  {% card description="Build full-stack web apps in AI Studio Build." href="https://aistudio.google.com/apps?model=gemini-4-hydrogen" icon="experiment" title="Build in AI Studio" /%}

  {% card description="Upgrade existing workloads with the Gemini 3.8 Flash migration checklist." href="/docs/whats-new-gemini-4-hydrogen?generate-content=true#migrate-from-gemini-3-8-flash" icon="rocket_launch" title="Migrate from 3.8 Flash" /%}

{% /card-grid %}

This guide explains what's new in Gemini 4 Hydrogen, API changes, code examples, and migration guidance.

## New model  {% id="new-model" %}

| Model | Model ID | Thinking levels | Paid tier price |
| :--- | :--- | :--- | :--- |
| Gemini 4 Hydrogen | `gemini-4-hydrogen` | `low`, `medium`, `high` (default), `xhigh` | $1.50 / 1M input, $7.50 / 1M output |

For full specifications, see the [Gemini 4 Hydrogen model page](/docs/models/gemini-4-hydrogen) and [Latest Gemini models](/docs/latest-model?generate-content=true).

## Quickstart  {% id="quickstart" %}

Send a request to `gemini-4-hydrogen` using the `generateContent` API. By default, the model uses the `high` thinking level and a 64K streaming (or SDK) output token limit.

{% tabs %}
  {% tab label="Python" %}
  ```bash
  pip install -U "google-genai>=2.30.1"
  ```

  ```python
  from google import genai
  from google.genai import types
  
  client = genai.Client()
  
  response = client.models.generate_content(
      model="gemini-4-hydrogen",
      contents="Build an interactive single-file HTML token bucket rate-limiter simulator with live sliders for burst size and request traffic.",
      config=types.GenerateContentConfig(
          max_output_tokens=65536,
          thinking_config=types.ThinkingConfig(thinking_level="high"),
      ),
  )
  
  print(response.text)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```bash
  npm install "@google/genai@>=2.29.1"
  ```

  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({});
  
  const response = await ai.models.generateContent({
    model: "gemini-4-hydrogen",
    contents: "Build an interactive single-file HTML token bucket rate-limiter simulator with live sliders for burst size and request traffic.",
    config: {
      maxOutputTokens: 65536,
      thinkingConfig: {
        thinkingLevel: "high",
      },
    },
  });
  
  console.log(response.text);
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```bash
  curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts": [{"text": "Build an interactive single-file HTML token bucket rate-limiter simulator with live sliders for burst size and request traffic."}]
      }],
      "generationConfig": {
        "maxOutputTokens": 65536,
        "thinkingConfig": {
          "thinkingLevel": "high"
        }
      }
    }'
  ```

  {% /tab %}

{% /tabs %}

## What's new in Gemini 4 Hydrogen  {% id="whats-new-gemini-4-hydrogen" %}

* **Fast agentic execution:** Writes cleaner code, cuts fabricated claims by more than 5x compared to [Gemini 3.8 Flash](/docs/whats-new-gemini-3.8?generate-content=true) by flagging missing context instead of guessing, batches read and search tool calls in parallel, and better adapts when tool calls fail.
* **Four configurable thinking levels:** Supports `low`, `medium`, `high` (default), and a new `xhigh` level, giving you finer control over latency and cost and deeper reasoning when tasks need it. See the [thinking levels](/docs/whats-new-gemini-4-hydrogen?generate-content=true#understanding-thinking-levels) section for details.
* **Built for multi-model orchestration:** Works standalone for coding and agentic work, or pairs with Carbon and Argon to power parallel worker and verifier agents at lower latency without driving up token cost.
* **Stronger multimodal reasoning:** Reads and synthesizes tables, charts, dense PDFs, images, audio, and video with higher accuracy, and uses [agentic video understanding](/docs/video-understanding?generate-content=true#agentic-video-understanding) to inspect specific frames and visual details.
* **Unified 1M context window and long decode:** Input, thinking, and output tokens share one 1,048,576-token window (with a 64K per-request default and cap across both streaming and non-streaming calls), and long decode lets a single generation go up to 1M tokens minus your input. The latest Google GenAI SDKs continue for you by default. See [Long decode](/docs/long-decode?generate-content=true).
* **Default model for Managed Agents:** The [Antigravity agent](/docs/antigravity-agent) now uses Gemini 4 Hydrogen (`gemini-4-hydrogen`) by default.

## Choosing between Hydrogen, Carbon, Argon, and other models  {% id="choosing-between-models" %}

Gemini 4 Hydrogen, [Gemini 4 Argon](/docs/whats-new-gemini-4-argon?generate-content=true), and [Gemini 4 Carbon](/docs/whats-new-gemini-4-carbon?generate-content=true) share the same 1M unified context window, long decode architecture, and built-in tools. Pick the model that matches your reasoning depth, latency, and cost target:

* **Gemini 4 Hydrogen (`gemini-4-hydrogen`):** Fast and efficient while handling complex agentic workflows, at $1.50 per 1M input tokens and $7.50 per 1M output tokens. Use it for everyday coding, interactive web apps, tool-using agents, multimodal document workflows, and parallel subagent execution. **Recommended upgrade from Gemini 3.8 Flash and earlier Gemini 3 and 2.5 models.**
* **Gemini 4 Carbon (`gemini-4-carbon`):** Our strongest frontier model. Carbon spends more thinking tokens per turn to test hypotheses and verify edge cases on hard architecture, debugging, science, and security audits.
* **Gemini 4 Argon (`gemini-4-argon`):** Use Argon when you want a model that can handle the majority of advanced long-horizon tasks with lower token use than Carbon.
* **Gemini 3.5 Flash-Lite (`gemini-3.5-flash-lite`):** Our fastest, lowest-cost model. Keep Flash-Lite for high-volume classification, routing, and sub-second latency targets.

You can also pair Carbon and Hydrogen in one workflow. Have Carbon plan system interfaces or resolve hard roadblocks, then delegate code edits, parallel subagent tasks, and test runs to Hydrogen. For a full comparison, see [Latest Gemini models](/docs/latest-model?generate-content=true#compare-models).

## Understanding thinking levels  {% id="understanding-thinking-levels" %}

The [thinking level](/docs/thinking?generate-content=true) is your main control over quality, latency, and token use in Gemini 4 Hydrogen. The model defaults to `high` and introduces `xhigh`.

| Thinking level | Token use | When to use |
| :--- | :--- | :--- |
| `low` | Fewest tokens, lowest latency | Cost- and latency-sensitive workloads, such as fast chat and high-throughput processing. Still capable on agentic tasks. |
| `medium` | Lower token use, faster responses | Interactive coding, live UI prototyping, responsive chat, and latency-sensitive tool calls. |
| `high` (default) | Balanced intelligence and speed | Recommended default for most tasks, including complex coding, agentic execution, tool calling, and multimodal knowledge work. |
| `xhigh` | Most tokens, deepest reasoning | Reserve for hard, multi-step coding and agentic problems where `high` falls short, when you can trade higher latency and token use. |

Start with `high` for most complex tasks, and reserve `xhigh` for hard, multi-step problems where `high` falls short. Using `xhigh` increases latency and token use and can cause overthinking on simpler prompts. Run your evaluations at all four levels with a high `max_output_tokens` so the limit doesn't cut answers short. Then pick the lowest `thinking_level` that meets your quality bar. To learn more, see the [thinking guide](/docs/thinking?generate-content=true).

{% tabs %}
  {% tab label="Python" %}
  ```python
  from google import genai
  from google.genai import types
  
  client = genai.Client()
  
  response = client.models.generate_content(
      model="gemini-4-hydrogen",
      contents="Audit this payment retry queue for race conditions and rewrite the lock acquisition logic.",
      config=types.GenerateContentConfig(
          thinking_config=types.ThinkingConfig(
              thinking_level="xhigh",
          ),
      ),
  )
  
  print(response.text)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({});
  
  const response = await ai.models.generateContent({
    model: "gemini-4-hydrogen",
    contents: "Audit this payment retry queue for race conditions and rewrite the lock acquisition logic.",
    config: {
      thinkingConfig: {
        thinkingLevel: "xhigh",
      },
    },
  });
  
  console.log(response.text);
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```bash
  curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts": [{"text": "Audit this payment retry queue for race conditions and rewrite the lock acquisition logic."}]
      }],
      "generationConfig": {
        "thinkingConfig": {
          "thinkingLevel": "xhigh"
        }
      }
    }'
  ```

  {% /tab %}

{% /tabs %}

## Larger output and long decode  {% id="long-decode" %}

Gemini 4 Hydrogen supports per-request outputs up to 65,536 tokens across both streaming and non-streaming calls, and long decode up to the 1M unified context window:

* **Unified 1M-token context window:** Input, thinking, and output tokens share one 1,048,576-token window, so Hydrogen can use up to 1M tokens minus your input tokens for thinking and output combined.
* **Control reasoning depth with `thinking_level`:** The `thinking_level` field sets how much reasoning the model performs before answering. The `max_output_tokens` field caps combined thinking and output tokens, so leave enough room for the final answer.
* **64K per-request default and cap:** A single streaming or non-streaming request returns up to 65,536 tokens across both REST and the Google GenAI SDKs.

The latest Google GenAI SDKs run long decode for you by default. Use Python `google-genai` 2.30.1 or higher, or JavaScript `@google/genai` 2.29.1 or higher.

In these versions, `automatic_continuation` is `True` by default, so you do not need to set it. When you set `max_output_tokens` above 65,536, `generate_content` and `generate_content_stream` automatically continue across requests until the model finishes or reaches `max_output_tokens`, returning one combined response.

```python
response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents="Generate a complete multi-module migration specification and test suite for this service.",
    config=types.GenerateContentConfig(
        max_output_tokens=262144,
        thinking_config=types.ThinkingConfig(thinking_level="high"),
        automatic_continuation=True,  # Default.
    ),
)
```

To run the loop yourself, set `automatic_continuation=False`. If you call REST or use an older SDK, requests stop at 65,536 tokens per hop. For REST loops, third-party frameworks, token counting, and when to use long decode, see the [long decode guide](/docs/long-decode?generate-content=true).

{% callout type="note" %}
  On a hard task, the model can spend an entire 64K hop on thinking and return empty text with a `continuation_token`. This is normal, and the final answer arrives in later hops.

{% /callout %}

### Setting output token limits  {% id="setting-output-token-limits" %}

The `max_output_tokens` field caps combined thinking and output tokens for a generation, including all continuation requests. Use these starting values to prevent truncated answers while bounding spend:

* **Standard tasks:** Keep the 65,536 default or omit `max_output_tokens`.
* **Existing apps with a low cap:** Remove hardcoded low caps (such as 8,192) or raise `max_output_tokens` to 65,536. To use fewer tokens, lower the thinking level instead.
* **Long outputs and multi-step tasks:** Set `max_output_tokens` to 131,072 or 262,144, up to 1,048,576 minus your input tokens.

If a request uses all of `max_output_tokens`, it returns `finish_reason: "MAX_TOKENS"` and still includes a `continuation_token`. You can resume or start again.

* **Resume from the checkpoint:** Send the original request with the latest `continuation_token` and a higher `max_output_tokens`. If you do not raise `max_output_tokens`, the request returns `400 INVALID_ARGUMENT`.
* **Start again:** Send the original request with a higher `max_output_tokens` and no `continuation_token`.

## Migration checklist  {% id="migration-checklist" %}

{% callout type="note" %}
  If you use a coding agent that supports skills, such as Antigravity, install the [gemini-api-dev skill](/docs/coding-agents#gemini-api-dev) to automate this upgrade:

  ```none
  /gemini-api-dev migrate my app to Gemini 4 Hydrogen
  ```

{% /callout %}

### Migrate from Gemini 3.8 Flash and earlier  {% id="migrate-from-gemini-3-8-flash" %}

Gemini 4 Hydrogen uses the same Gemini 4 API design as Carbon and Argon. Review these changes when upgrading from `gemini-3.8-flash` or earlier Gemini 3 models:

* **Update model ID:** Change your model string from `gemini-3.8-flash` to `gemini-4-hydrogen`.
* **Account for the unified 1M context window:** Gemini 3.8 Flash separates 1M input and 64K output budgets. Hydrogen shares one 1,048,576-token window across input, thinking, and output tokens while keeping the 65,536 single-request default and cap across both streaming and non-streaming calls. Remove hardcoded low `max_output_tokens` caps or raise them to 65,536.
* **Plan for long decode:** For tasks above 65,536 tokens, use the latest SDK (`google-genai>=2.30.1` or `@google/genai>=2.29.1`, where `automatic_continuation=True` is enabled by default) or add a `continuation_token` loop.
* **Configure `thinking_level` (and replace `thinking_budget`):** Hydrogen defaults to `high` rather than `medium`, adds `xhigh`, and rejects `minimal` with an error. `thinking_budget` still works and maps to the nearest `thinking_level`, but it returns a warning. Test `medium` and `high` on your evaluation suite to balance speed and cost.
* **Move off explicit context caching:** Gemini 4 Hydrogen does not support explicit caching (`cachedContents` and `caches.create`). Remove `cached_content` fields from requests. [Implicit caching](/docs/caching?generate-content=true) runs by default on prompts of at least 4,096 tokens and discounts cached input tokens by 95% on cache hits.
* **Remove deprecated parameters:** Remove `temperature`, `top_p`, `top_k`, and `candidate_count` from requests. The server ignores in-range custom sampling values if sent. Out-of-range values return a `400` validation error.
* **Declare native tools or structured output schemas:** Do not prompt the model via system instructions to emit custom raw-text JSON tool calls with zero declared tools, which can return `MALFORMED_FUNCTION_CALL`. Always declare tools natively with [function calling](/docs/function-calling?generate-content=true) or constrain JSON responses with [structured outputs](/docs/structured-output?generate-content=true).
* **Increase client timeouts:** Set HTTP client timeouts to at least 20 minutes per call.
* **Preserve conversation state and thought signatures:** In client-managed `generateContent` histories, return prior model turns and [thought signatures](/docs/thinking?generate-content=true#signatures) unchanged across every turn. Do not copy a thought signature across parallel `functionCall` parts.
* **Review token billing estimates:** We count and bill every token the model processes, including thinking tokens and internal grounding system instructions and function declarations.

### Migrate from or pair with Gemini 4 Carbon and Argon  {% id="migrate-from-gemini-4-argon" %}

If you run `gemini-4-carbon` or `gemini-4-argon` today, adding or switching to `gemini-4-hydrogen` requires no request schema changes:

* **Update model ID:** Set `model` to `gemini-4-hydrogen` for standalone requests or subagent turns.
* **Check default thinking level:** Hydrogen defaults to `high` and supports `xhigh`, whereas Carbon and Argon default to `medium` and cap at `high`. Set `thinking_level` when you want `medium` or `xhigh` behavior.
* **64K non-streaming REST hops:** Hydrogen supports up to 65,536 tokens per non-streaming REST request, whereas Carbon and Argon cap single non-streaming REST hops at 32,768 tokens.
* **Switch models across turns:** Route planning turns to `gemini-4-carbon` and execution turns to `gemini-4-hydrogen` in one multi-turn session without stripping [thought signatures](/docs/thought-signatures?generate-content=true#model-behavior).

## Pricing  {% id="pricing" %}

Gemini 4 Hydrogen is available on the free tier of the Gemini API and in Google AI Studio, and uses flat standard pricing on the paid tier across the full 1M context window:

* **Free tier:** Free of charge (rate-limited; see [rate limits](/docs/rate-limits))
* **Input tokens:** $1.50 per 1M tokens  *   **Cached input tokens:** Implicit caching discounts cached input by 95%, to $0.075 per 1M tokens.

* **Output tokens, including thinking tokens:** $7.50 per 1M tokens

We count and bill every token the model processes, including thinking tokens and internal tool system instructions and function declarations when using grounding. Grounding with Google Search remains billed per query.

For complete tier details and rate limits, see the [pricing page](/docs/pricing#gemini-4-hydrogen) and [rate limits page](/docs/rate-limits).

## Other models  {% id="other-models" %}

* [Latest Gemini models](/docs/latest-model?generate-content=true)
* [Gemini 4 Carbon](/docs/whats-new-gemini-4-carbon?generate-content=true)
* [Gemini 4 Argon](/docs/whats-new-gemini-4-argon?generate-content=true)
* [Gemini 3.8 Flash](/docs/whats-new-gemini-3.8?generate-content=true)
* [Gemini 3.6 Flash and 3.5 Flash-Lite](/docs/whats-new-gemini-3.6?generate-content=true)
* [See all models](/docs/models)

## What's next  {% id="whats-next" %}

* Read the [long decode guide](/docs/long-decode?generate-content=true) for streaming, reconnection, and token counting.
* Learn how thinking levels and thought summaries work in the [thinking guide](/docs/thinking?generate-content=true).
* Learn about asynchronous jobs in the [background execution guide](/docs/background-execution).
* Configure managed coding workflows in the [Antigravity agent guide](/docs/antigravity-agent).
* Test and refine prompts in [Google AI Studio](https://aistudio.google.com/prompts/new_chat?model=gemini-4-hydrogen).