> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini 4 Hydrogen API 上线：价格、调用示例与 Gemini 3.8 Flash 对比

> Gemini 4 Hydrogen（gemini-4-hydrogen）API 接入说明：每 1M tokens 输入 $1.5、输出 $7.5，与 Google 官方价相同；OpenAI 兼容与 Gemini 原生调用示例、新增的 xhigh 思考级别，以及和 Gemini 3.8 Flash、Gemini 4 Argon 的价格与用法区别。

Gemini 4 Hydrogen（`gemini-4-hydrogen`）是 Google 2026 年 11 月 12 日正式发布的 Gemini 模型，面向日常编程和智能体任务，Google 把它作为 Gemini 3.8 Flash 的升级推荐。老张API从 11 月 14 日起提供，用 `default` 分组的 API Key 即可调用，每 1M tokens 输入 \$1.5、输出 \$7.5，与 Google 官方价相同。

* **发布日期**：2026 年 11 月 14 日
* **最后核对**：2026 年 11 月 14 日
* **当前状态**：有效；可在 `default` 分组调用

## 关键信息

| 项目 | 内容 |
| - | - |
| 模型 ID | `gemini-4-hydrogen` |
| Google 发布日期 | 2026 年 11 月 12 日（正式版） |
| 老张API上线 | 2026 年 11 月 14 日 |
| OpenAI 兼容端点 | `POST https://api.laozhang.ai/v1/chat/completions` |
| Gemini 原生端点 | `https://api.laozhang.ai/v1beta/models/gemini-4-hydrogen:generateContent` |
| 令牌分组与计费 | `default` 分组，按量计费（按 tokens） |
| 当前价格 | 每 1M tokens 输入 \$1.5、输出 \$7.5、缓存读取 \$0.075 |
| 上下文窗口（Google） | 1,048,576 tokens，整个窗口同一价格 |
| 单次输出上限（Google） | 默认 65,536 tokens |
| 思考级别 | `low`、`medium`、`high`、`xhigh`，Google 默认 `high` |
| 可用能力 | 函数调用、结构化输出（JSON Schema）、图片输入、流式输出 |

## 价格

以下为 2026 年 11 月 14 日公开价格配置中的单价，单位为美元每 1M tokens：

| 计价项 | 老张API | Google 官方价 |
| - | -: | -: |
| 输入 | \$1.5 | \$1.5 |
| 输出（含思考 token） | \$7.5 | \$7.5 |
| 缓存读取 | \$0.075 | \$0.075 |

* 价格不分档：输入超过 200K tokens 也按同一单价，不像 Gemini 3.1 Pro 那样分段加价。
* 思考 token 按输出单价计费。例如一次请求输入 43 tokens、正式回答和思考合计 135 个输出 token，扣费约 \$0.0011。
* Hydrogen 默认思考级别是 `high`，简单问题也会先思考。只要短回答时传 `low`，输出 token 和费用都会明显减少，见下方「思考级别」。
* 缓存读取是 Google 的隐式缓存：同一段 4,096 tokens 以上的前缀被重复发送时，命中部分自动按缓存价计费。Hydrogen 不支持显式缓存（`cachedContents`），从 Gemini 3.8 Flash 迁移时要去掉这部分参数。
* 每次请求的 token 用量和扣费可在[调用日志](https://api2.laozhang.ai/log)查看，当前单价以[模型与价格总表](https://docs.laozhang.ai/models.md#vendor-google-text)为准。

## 和 Gemini 3.8 Flash、Gemini 4 Argon 怎么选

| 对比项 | `gemini-4-hydrogen` | `gemini-3.8-flash` | `gemini-4-argon` |
| - | - | - | - |
| 老张API上线 | 2026 年 11 月 14 日 | 2026 年 9 月 3 日 | 2026 年 10 月 14 日 |
| 老张API当前单价（输入 / 输出） | \$1.5 / \$7.5 | \$0.75 / \$3.75 | \$2 / \$10 |
| Google 官方价变化 | 不变 | 2027 年 1 月 1 日起 \$1.5 / \$7.5 | 2026 年 12 月 1 日起 \$4 / \$20 |
| 默认思考级别 | `high` | `medium` | `medium` |
| 最高思考级别 | `xhigh` | `high` | `high` |
| 显式缓存（Google） | 不支持 | 支持 | 不支持 |

* **从 Gemini 3.8 Flash 升级**：Google 的说明是 Hydrogen 在编程和智能体任务上明显强于 3.8 Flash、完成任务更快。按当前单价 Hydrogen 贵一倍；Google 的 3.8 Flash 首发价到 2026 年 12 月 31 日，2027 年 1 月 1 日起两者官方单价相同。
* **和 Gemini 4 Argon 比**：Google 发布时公布的综合评测中，Hydrogen 在默认 `high` 级别的分数略高于 Argon，单价比 Argon 低 25%；12 月 1 日 Argon 按官方价调整后，Hydrogen 不到 Argon 的一半。复杂编程、调试和科学推理的难题仍可先比较 [Gemini 4 Carbon](https://docs.laozhang.ai/announcements/gemini-4-carbon-2026-11.md)。
* 以上效果说明来自 Google，上线前用自己的样例比较效果、耗时和[调用日志](https://api2.laozhang.ai/log)里的 token 用量。三个模型调用方式相同，切换只需改 `model`。

## 调用示例

在[令牌管理](https://api2.laozhang.ai/token)创建 API Key：令牌分组选 `default`，计费模式选择按量优先（推荐）或按量计费。然后在终端设置环境变量：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

> [tab] OpenAI 兼容
>
> ```bash theme={null}
> curl https://api.laozhang.ai/v1/chat/completions \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gemini-4-hydrogen",
>     "reasoning_effort": "low",
>     "messages": [
>       {"role": "user", "content": "写一个 Python 函数，把 \"1h30m\" 这样的时长字符串转换成秒数。"}
>     ]
>   }'
> ```

> [tab] Gemini 原生
>
> ```bash theme={null}
> curl "https://api.laozhang.ai/v1beta/models/gemini-4-hydrogen:generateContent" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "contents": [
>       {"role": "user", "parts": [{"text": "写一个 Python 函数，把 \"1h30m\" 这样的时长字符串转换成秒数。"}]}
>     ],
>     "generationConfig": {
>       "thinkingConfig": {"thinkingLevel": "low"}
>     }
>   }'
> ```

> [tab] Python
>
> ```python theme={null}
> import os
> from openai import OpenAI
>
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=600.0,
>     max_retries=0,
> )
> response = client.chat.completions.create(
>     model="gemini-4-hydrogen",
>     reasoning_effort="low",
>     messages=[{"role": "user", "content": "写一个 Python 函数，把 \"1h30m\" 这样的时长字符串转换成秒数。"}],
> )
> print(response.choices[0].message.content)
> print(response.usage)
> ```

* OpenAI 兼容接口的回答在 `choices[0].message.content`，思考 token 数在 `usage.completion_tokens_details.reasoning_tokens`。
* Gemini 原生接口的回答在 `candidates[0].content.parts[].text`，思考 token 数在 `usageMetadata.thoughtsTokenCount`，`modelVersion` 为 `gemini-4-hydrogen`。
* 已经在用 Gemini 3.8 Flash 的代码，把 `model` 或 URL 里的 `gemini-3.8-flash` 换成 `gemini-4-hydrogen` 即可，API Key 不用改；用到显式缓存的要先去掉。
* 图片、流式、多轮对话等原生写法见 [Gemini 协议](https://docs.laozhang.ai/api-reference/gemini.md)，工具调用写法见[函数调用](https://docs.laozhang.ai/api-capabilities/function-calling.md)。

## 思考级别

| 接口 | 参数 | 可用值 |
| - | - | - |
| Gemini 原生 | `generationConfig.thinkingConfig.thinkingLevel` | `low`、`medium`、`high`、`xhigh` |
| OpenAI 兼容 | `reasoning_effort` | `low`、`medium`、`high` |

* 不传时按 Google 默认的 `high`，比 Gemini 3.8 Flash 的默认 `medium` 思考更多。
* `xhigh` 是 Hydrogen 新增的最高级别，思考 token 通常是 `high` 的几倍，Google 提醒简单问题用它容易"想太多"。只在难题上使用。
* 需要 `xhigh`，或想精确控制思考级别，请用 Gemini 原生接口；OpenAI 兼容接口只填上表列出的三个值。
* Gemini 原生接口传 `minimal` 会报错，最低用 `low`。
* 思考和正式回答共用 `maxOutputTokens`（OpenAI 兼容接口为 `max_tokens`）。上限设得太小，可能还没写出回答就用完，思考 token 照样计费；需要省钱时降低思考级别，而不是压低输出上限。
* Google 说明 Gemini 4 Hydrogen 会忽略 `temperature`、`top_p`、`top_k`，传了不报错，但不改变输出。

## 影响范围

* **适用**：在用 Gemini 3.8 Flash 做编程、智能体或批量文本任务、想换更强模型的项目，以及想用比 Gemini 4 Argon 更低单价的项目。`default` 分组、计费模式为按量优先或按量计费的 API Key 即可调用。
* **不受影响**：本次上线没有调整已有模型。`gemini-3.8-flash`、`gemini-4-argon`、`gemini-4-carbon` 等 Gemini 模型继续可用，现有集成不需要修改。

## 常见问题

### Gemini 4 Hydrogen 的模型 ID 是什么？

`gemini-4-hydrogen`。Google 只发布了这一个正式版 ID，没有 `-preview` 或带日期的版本。OpenAI 兼容接口写在 `model` 字段，Gemini 原生接口写在 URL 路径里。

### Google 有免费层，为什么还要用老张API调用？

Google 的免费层限额以项目为单位，且免费层的数据会被 Google 用于改进产品。在老张API上用老张API的 API Key 和 Base URL `https://api.laozhang.ai` 即可调用，不需要 Google 账号或 AI Studio API Key，余额预付、按 token 计费，单价与 Google 付费层相同。

### Gemini 4 Hydrogen 比 Gemini 3.8 Flash 贵吗？

按单价，现在贵一倍：Hydrogen 输入 \$1.5、输出 \$7.5，3.8 Flash 输入 \$0.75、输出 \$3.75。3.8 Flash 是 Google 的首发价，到 2026 年 12 月 31 日为止，2027 年 1 月 1 日起官方价与 Hydrogen 相同。实际每次请求花多少还取决于思考 token，用 `low` 级别能大幅减少输出 token。

### 一次请求为什么输出 token 比回答长得多？

输出 token 包含思考 token。Hydrogen 默认 `high` 级别，即使问题很简单也会先思考；`usage.completion_tokens_details.reasoning_tokens`（原生接口为 `usageMetadata.thoughtsTokenCount`）就是思考部分。只要短回答时传 `low`。

### 支持图片、PDF 或音视频输入吗？

支持图片输入：OpenAI 兼容接口用 `image_url`（URL 或 Base64），Gemini 原生接口用 `inlineData` 或 `fileData`。Google 列出的输入类型还包括视频、音频和 PDF，写法见[图片理解 API](https://docs.laozhang.ai/api-capabilities/vision-understanding.md)和 [Gemini 协议](https://docs.laozhang.ai/api-reference/gemini.md)。模型只输出文字，不生成图片或语音。

### 长请求超时怎么办？

默认 `high` 级别下，一次请求可能需要几十秒，`xhigh` 更久。客户端超时设到 600 秒左右，并改用流式输出：

* OpenAI 兼容接口：请求中加 `"stream": true`。
* Gemini 原生接口：改用 `streamGenerateContent?alt=sse`。

## 来源与相关链接

* [Google：Gemini 4 Hydrogen 模型页](https://ai.google.dev/gemini-api/docs/models/gemini-4-hydrogen)：模型 ID、上下文窗口、输出上限、输入类型和支持的工具。
* [Google：What's new in Gemini 4 Hydrogen](https://ai.google.dev/gemini-api/docs/whats-new-gemini-4-hydrogen)：思考级别、隐式缓存和从 Gemini 3.8 Flash 迁移的注意事项。
* [Google：Gemini API 价格](https://ai.google.dev/gemini-api/docs/pricing)：Hydrogen、3.8 Flash 和 Argon 的官方价。
* [Google：Gemini API 更新日志](https://ai.google.dev/gemini-api/docs/changelog)：2026 年 11 月 12 日正式发布。
* [模型与价格总表](https://docs.laozhang.ai/models.md#vendor-google-text)：老张API当前单价。
* [Gemini 3.8 Flash 上线公告](https://docs.laozhang.ai/announcements/gemini-3-8-flash-2026-09.md)
* [Gemini 4 Carbon 上线公告](https://docs.laozhang.ai/announcements/gemini-4-carbon-2026-11.md)
* [文本生成 API：协议选择与常用模型](https://docs.laozhang.ai/api-capabilities/text-generation.md)
* [Gemini 协议：generateContent](https://docs.laozhang.ai/api-reference/gemini.md)
* [老张API最新公告](https://docs.laozhang.ai/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.