# Gemini 4 Hydrogen 新特性

Gemini 4 Hydrogen (`gemini-4-hydrogen`）为每个人带来尖端智能，为日常编码和智能体工作流程提供速度和效率。

Gemini 4 Hydrogen 在 Google AI Studio 和 Gemini API 中的免费和付费层均可用（跨GenerateContent 和 Interactions API）。喜欢 [Gemini 4 Carbon](/docs/whats-new-gemini-4-carbon) 和 [Gemini 4 Argon](/docs/whats-new-gemini-4-argon)，它具有统一的 1M-token 上下文窗口和长达 1M token 的长解码。它还增加了第四个思维层次， [`xhigh`](/docs/thinking#understanding-thinking-levels)，旁边 `low`, `medium`，以及默认的 `high`.

{% card-grid %}
{% card
   description="查看 token 限制、支持的功能和完整规格。"
   href="/docs/models/gemini-4-hydrogen"
   icon="id_card"
   title="模型详情" /%}

{% card
   description="在 AI Studio Build 中构建全栈 Web 应用程序。"
   href="https://aistudio.google.com/apps?model=gemini-4-hydrogen"
   icon="experiment"
   title="在 AI Studio 中构建" /%}

{% card
   description="使用 Gemini 3.8 Flash 迁移清单升级现有工作负载。"
   href="/docs/whats-new-gemini-4-hydrogen#migrate-from-gemini-3-8-flash"
   icon="rocket_launch"
   title="从 3.8 Flash迁移" /%}
{% /card-grid %}

本指南介绍了 Gemini 4 Hydrogen、API 更改、代码示例和迁移指南中的新增内容。

## 新型号  {% #new-model %}

| 模型                | 型号编号                | 思维层次                                  | 付费等级价格                      |
| ----------------- | ------------------- | ------------------------------------- | --------------------------- |
| Gemini 4 Hydrogen | `gemini-4-hydrogen` | `low`, `medium`, `high` （默认）， `xhigh` | $1.50 / 1M 输入，$7.50 / 1M 输出 |

有关完整规格，请参阅 [Gemini 4 Hydrogen 型号页面](/docs/models/gemini-4-hydrogen) 和 [最新 Gemini 模型](/docs/latest-model).

## 快速入门  {% #quickstart %}

发送请求至 `gemini-4-hydrogen` 使用 Interactions API。默认情况下，该模型使用 `high` 思维水平与64K同步输出token限制。

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Build an interactive single-file HTML token bucket rate-limiter simulator with live sliders for burst size and request traffic."
)

print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-4-hydrogen",
  input: "Build an interactive single-file HTML token bucket rate-limiter simulator with live sliders for burst size and request traffic.",
});

console.log(interaction.output_text);
```
{% /tab %}

{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Build an interactive single-file HTML token bucket rate-limiter simulator with live sliders for burst size and request traffic."
  }'
```
{% /tab %}
{% /tabs %}

## Gemini 4 Hydrogen 新特性  {% #whats-new-gemini-4-hydrogen %}

* **快速智能体执行：** 与以前相比，编写更清晰的代码，将捏造的声明减少 5 倍以上 [Gemini 3.8 Flash](/docs/whats-new-gemini-3.8) 通过标记缺失的上下文而不是猜测，并行批量读取和搜索工具调用，并在工具调用失败时更好地适应。
* **四个可配置的思维级别：** 支持 `low`, `medium`, `high` （默认），以及一个新的 `xhigh` 级别，让您可以更好地控制延迟和成本，并在任务需要时进行更深入的推理。请参阅 [思维层次](/docs/whats-new-gemini-4-hydrogen#understanding-thinking-levels) 部分了解详细信息。
* **专为多模型编排而构建：** 独立工作用于编码和智能体工作，或与 Carbon 和 Argon 配合使用，以较低的延迟为并行工作器和验证器智能体提供动力，而不会增加 token 成本。
* **更强的多模态推理：** 更准确地读取和合成表格、图表、密集的 PDF、图像、音频和视频，并使用 [智能体视频理解](/docs/video-understanding#agentic-video-understanding) 检查特定的框架和视觉细节。
* **统一1M 上下文窗口和长解码：** 输入、思考、输出token共用一个1,048,576-token窗口。使用后台执行或客户端延续，响应可以从 64K 一直运行到 1M token。参见 [长输出](/docs/long-decode).
* **托管智能体的默认型号：** 该 [Antigravity 智能体](/docs/antigravity-agent) 现在使用 Gemini 4 Hydrogen (`gemini-4-hydrogen`）默认情况下。

## 在氢、碳、氩和其他型号之间进行选择  {% #choosing-between-models %}

Gemini 4 Hydrogen, [Gemini 4 Argon](/docs/whats-new-gemini-4-argon), 和 [Gemini 4 Carbon](/docs/whats-new-gemini-4-carbon) 共享相同的1M统一的上下文窗口、长解码架构和内置工具。选择与您的推理深度、延迟和成本目标相匹配的模型：

* **Gemini 4 Hydrogen (`gemini-4-hydrogen`):** 快速高效地处理复杂的智能体工作流程，每个 1M 输入为 $1.50，每个 token 为 $7.50，每个 1M 输出为 token。将其用于日常编码、交互式 Web 应用程序、使用智能体的工具、多模态文档工作流程和并行子智能体执行。 **建议从 Gemini 3.8 Flash 以及早期的 Gemini 3 和 2.5 型号升级。**
* **Gemini 4 Carbon (`gemini-4-carbon`):** 我们最强大的前沿模型。 Carbon 每轮都会花费更多的思考 token 来测试假设并验证硬架构、调试、科学和安全审计的边缘情况。
* **Gemini 4 Argon (`gemini-4-argon`):** 当您想要一个能够处理大多数高级长期任务且 token 使用率低于 Carbon 的模型时，请使用 Argon。
* **Gemini 3.5 Flash-Lite (`gemini-3.5-flash-lite`):** 我们最快、成本最低的型号。保留 Flash-Lite 以实现大容量分类、路由和亚秒级延迟目标。

您还可以在一个工作流程中配对碳和氢。让 Carbon 规划系统接口或解决硬障碍，然后将代码编辑、并行子智能体任务和测试运行委托给 Hydrogen。如需完整比较，请参阅 [最新 Gemini 模型](/docs/latest-model#compare-models).

## 了解思维层次  {% #understanding-thinking-levels %}

该 [思维水平](/docs/thinking) 是您对 Gemini 4 Hydrogen 中质量、延迟和 token 使用的主要控制。该模型默认为 `high` 并介绍 `xhigh`.

| 思维层面        | 代币使用               | 何时使用                                                            |
| ----------- | ------------------ | --------------------------------------------------------------- |
| `low`       | 最少的token，最低的延迟     | 对成本和延迟敏感的工作负载，例如快速聊天和高吞吐量处理。仍然有能力执行智能体任务。                       |
| `medium`    | token 使用率更低，响应速度更快 | 交互式编码、实时 UI 原型、响应式聊天和延迟敏感的工具调用。                                 |
| `high` （默认） | 平衡智力和速度            | 大多数任务的推荐默认值，包括复杂编码、智能体执行、工具调用和多模态知识工作。                          |
| `xhigh`     | 最token，最深刻的推理      | 为困难的、多步骤的编码和智能体问题保留，其中 `high` 当您可以使用更高的延迟和 token 进行交易时，就达不到要求了。 |

开始于 `high` 对于最复杂的任务，并保留 `xhigh` 对于困难的、多步骤的问题，其中 `high` 达不到要求。使用 `xhigh` 增加延迟和 token 使用，并可能导致对简单提示的过度思考。在所有四个级别上进行高评价 `max_output_tokens` 所以限制不会缩短答案。然后选最低的 `thinking_level` 符合您的质量标准。要了解更多信息，请参阅 [思维指南](/docs/thinking).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Audit this payment retry queue for race conditions and rewrite the lock acquisition logic.",
    generation_config={
        "thinking_level": "xhigh"
    }
)

print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-4-hydrogen",
  input: "Audit this payment retry queue for race conditions and rewrite the lock acquisition logic.",
  generation_config: {
    thinking_level: "xhigh",
  },
});

console.log(interaction.output_text);
```
{% /tab %}

{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Audit this payment retry queue for race conditions and rewrite the lock acquisition logic.",
    "generation_config": {
      "thinking_level": "xhigh"
    }
  }'
```
{% /tab %}
{% /tabs %}

## 更大的输出和更长的解码  {% #long-decode %}

Gemini 4 Hydrogen 支持高达 65,536 token 的同步输出和高达 1M 统一上下文窗口的长解码：

* **控制推理深度 `thinking_level`:** 该 `thinking_level` 字段设置模型在回答之前执行多少推理。的 `max_output_tokens` 字段 caps 结合思考并输出 token，因此为最终答案留有足够的空间。
* **通过后台执行或继续生成过去的 64K token：** 同步响应在流式和非流式请求中每跳最多支持 65,536 token。要生成更长的输出，请设置 `max_output_tokens` 高于 65,536（最多 1,048,576 减去您的输入 token）并设置 `background` 到 `true` 因此我们的服务器在 64K-token 跳中继续，或者在最新的 Google GenAI SDK 中使用客户端继续。

{% tabs %}
{% tab label="Python" %}
```python
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)

# Join text across all 64K continuation hops.
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)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

let interaction = await 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_progress" || interaction.status === "queued") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await client.interactions.get(interaction.id);
}

// Join text across all 64K continuation hops.
const text = interaction.steps
  .filter((step) => step.type === "model_output")
  .flatMap((step) => step.content ?? [])
  .filter((content) => content.type === "text")
  .map((content) => content.text)
  .join("");
console.log(text);
console.log("Status:", interaction.status);
console.log("Usage:", interaction.usage);
```
{% /tab %}

{% tab label="REST" %}
```bash
ID=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }' | jq -r '.id')

while true; do
  RESP=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$ID" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status')
  if [[ "$STATUS" != "in_progress" && "$STATUS" != "queued" ]]; then
    echo "$RESP" | jq -r '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
    break
  fi
  sleep 5
done
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
如果你设置 `background` 到 `true` 无需设置 `max_output_tokens`，服务器在 65,536 token 之后停止。
{% /callout %}

后台执行是运行长解码的推荐方法。对于自定义重试控制或未存储的交互，请在 [Interactions API](/docs/long-decode#client-side-continuation) 或 [生成内容 API](/docs/long-decode?generate-content=true)。有关流式传输和 token 计数的详细信息，请参阅 [长解码指南](/docs/long-decode).

### 设置输出 token 限制  {% #setting-output-token-limits %}

该 `max_output_tokens` 字段 caps 结合思考并输出 token 进行响应。使用这些起始值可以防止答案被截断，同时限制支出：

* **标准任务：** 保留 65,536 默认值或省略 `max_output_tokens`.
* **现有的低上限应用程序：** 删除硬编码的低位大写字母（例如 8,192）或提高 `max_output_tokens` to 65,536. 要少用token，就降低思维水平吧。
* **长输出和多步骤任务：** 套装 `background` 到 `true` 并设置 `max_output_tokens` 到 131,072 或 262,144, 直至 1,048,576 减去您的输入 token。

## 更新了 Antigravity 智能体  {% #managed-agents %}

由于其改进的性能和推理能力， [Antigravity 智能体](/docs/antigravity-agent) 在 Gemini 中，托管智能体现在是用 Gemini 4 Hydrogen 构建的（`gemini-4-hydrogen`）默认情况下。

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input=(
        "Audit https://web.dev for performance, Core Web Vitals, and SEO. "
        "Query Google's PageSpeed Insights API for both Mobile and Desktop strategies. "
        "Check search indexing with Google Search for site:web.dev. "
        "Format the output as a side-by-side scorecard table with prioritized fixes."
    ),
    environment="remote",
)

print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });

const interaction = await client.interactions.create({
  agent: "antigravity-preview-09-2026",
  input:
    "Audit https://web.dev for performance, Core Web Vitals, and SEO. " +
    "Query Google's PageSpeed Insights API for both Mobile and Desktop strategies. " +
    "Check search indexing with Google Search for site:web.dev. " +
    "Format the output as a side-by-side scorecard table with prioritized fixes.",
  environment: "remote",
}, { timeout: 300000 });

console.log(interaction.output_text);
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Audit https://web.dev for performance, Core Web Vitals, and SEO. Query Google'\''s PageSpeed Insights API for both Mobile and Desktop strategies. Check search indexing with Google Search for site:web.dev. Format the output as a side-by-side scorecard table with prioritized fixes.",
    "environment": "remote"
  }'
```
{% /tab %}
{% /tabs %}

底层 Gemini 模型 [可以配置](/docs/antigravity-agent#model-selection) 使用 `agent_config`.

## 迁移清单  {% #migration-checklist %}

{% callout type="note" %}
如果您使用支持技能的编码智能体，例如 Antigravity，请安装 [gemini-api-dev技能](/docs/coding-agents#gemini-api-dev) 要自动执行此升级：

```none
/gemini-api-dev migrate my app to Gemini 4 Hydrogen
```
{% /callout %}

### 从 Gemini 3.8 Flash 及更早版本迁移  {% #migrate-from-gemini-3-8-flash %}

Gemini 4 Hydrogen 采用与碳和氩相同的 Gemini 4 API 设计。升级时查看这些更改 `gemini-3.8-flash` 或更早的 Gemini 3 型号：

* **更新型号ID：** 更改您的模型字符串 `gemini-3.8-flash` 到 `gemini-4-hydrogen`.
* **统一账号1M 上下文窗口：** Gemini 3.8 Flash 将 1M 输入和 64K 输出预算分开。 Hydrogen 在输入、思考和输出 token 之间共享一个 1,048,576-token 窗口，同时在流式和非流式调用中保持 65,536 单请求默认值和上限。删除硬编码低 `max_output_tokens` 上限或将其提高到 65,536.
* **配置 `thinking_level`:** 氢气默认为 `high` 而不是 `medium`，添加 `xhigh`，并拒绝 `minimal` 有错误。测试 `medium` 和 `high` 在您的评估套件上平衡速度和成本。
* **Move off explicit 上下文缓存:** Gemini 4 Hydrogen 不支持显式缓存（`cachedContents` 和 `caches.create`）。删除 `cached_content` 请求中的字段。 [隐式缓存](/docs/caching) 默认情况下，在至少 4,096 token 的提示下运行，并在缓存命中时将缓存输入 token 折扣 95%。
* **Remove sampling parameters:** 删除 `temperature`, `top_p`, 和 `top_k` 来自请求。如果发送，服务器将忽略范围内的自定义值。超出范围的值返回 `400` 验证错误。
* **声明本机工具或结构化输出模式：** 不要通过系统指令提示模型使用零声明的工具发出自定义原始文本 JSON 工具调用，这可能会返回 `MALFORMED_FUNCTION_CALL`。始终使用本机声明工具 [函数调用](/docs/function-calling) 或约束 JSON 响应 [结构化输出](/docs/structured-output).
* **保留对话状态和思想签名：** 使用 `previous_interaction_id` 在 Interactions API 中进行多轮和工具调用会话。在客户管理中 `generateContent` 历史记录，返回先前的模型回合，并且思想签名在每个回合中都保持不变。不要跨并行复制思想签名 `functionCall` 零件。
* **对 64K 之后的输出使用后台执行：** 套装 `background` 到 `true` 和 `max_output_tokens` 高于 65,536 的响应长度超过 64K token（或在最新 SDK 中使用客户端延续）。
* **查看 token 账单估算：** 我们对模型处理的每个 token 进行计数和计费，包括思考 token 和内部事实依据系统指令和函数声明。

### 从 Gemini 4 Carbon 和 Argon 迁移或与之配对  {% #migrate-from-gemini-4-argon %}

如果你跑 `gemini-4-carbon` 或 `gemini-4-argon` 今天，添加或切换到 `gemini-4-hydrogen` requires no request schema changes:

* **更新型号ID：** 套装 `model` 到 `gemini-4-hydrogen` 用于独立请求或子智能体轮流。
* **检查默认思维水平：** 氢气默认为 `high` 并支持 `xhigh`，而碳和氩默认为 `medium` 并上限为 `high`。套装 `thinking_level` 当你想要的时候 `medium` 或 `xhigh` 行为。
* **64K 非流式跃点：** Hydrogen 跨 REST 和 SDK 调用的每个非流式跃点最多支持 65,536 token，而 Carbon 和 Argon 上的每个非流式 REST 跃点为 32,768 token。
* **跨回合切换模型：** 路线规划转向 `gemini-4-carbon` 执行变成 `gemini-4-hydrogen` 在一个多轮会话中使用 `previous_interaction_id` （或通过保留 [无状态模式下的思维步骤](/docs/thinking#stateless-mode);看到 [多圈模型兼容性](/docs/interactions-overview#limitations)).

## 价格  {% #pricing %}

Gemini 4 Hydrogen 可在 Gemini API 和 Google AI Studio 的免费套餐中使用，并在整个 1M 上下文窗口的付费套餐上使用固定标准定价：

* **免费等级：** 免费（有速率限制；请参阅 [速率限制](/docs/rate-limits))

* **输入token：** $1.50 与 1M token *   **缓存输入 token：** 隐式缓存将缓存的输入折扣为 95%，每个 1M token 为 $0.075。

* **输出token，包括思考token：** $7.50 与 1M token

我们对模型处理的每个 token 进行计数并计费，包括思考 token 以及使用事实依据时的内部工具系统指令和函数声明。 事实依据和 Google 搜索仍按查询计费。

有关完整的等级详细信息和速率限制，请参阅 [定价页面](/docs/pricing#gemini-4-hydrogen) 和 [速率限制页面](/docs/rate-limits).

## 其他型号  {% #other-models %}

* [最新 Gemini 模型](/docs/latest-model)
* [Gemini 4 Carbon](/docs/whats-new-gemini-4-carbon)
* [Gemini 4 Argon](/docs/whats-new-gemini-4-argon)
* [Gemini 3.8 Flash](/docs/whats-new-gemini-3.8)
* [Gemini 3.6 Flash 和 3.5 Flash-Lite](/docs/whats-new-gemini-3.6)
* [查看所有型号](/docs/models)

## 后续步骤  {% #whats-next %}

* 阅读 [长解码指南](/docs/long-decode) 用于流式传输、重新连接和 token 计数。
* 了解思维水平和思维总结如何在 [思维指南](/docs/thinking).
* 了解异步作业 [后台执行引导](/docs/background-execution).
* 配置托管编码工作流程 [Antigravity 智能体指南](/docs/antigravity-agent).
* 测试并完善提示 [Google AI Studio](https://aistudio.google.com/prompts/new_chat?model=gemini-4-hydrogen).
