Gemini 4 Hydrogen API 怎么接入？Google 与 Ofox 两种方式

直接调用 Google 时，使用 gemini-4-hydrogen 和 Google API Key；通过 Ofox 的 Chat Completions 接口调用时，使用 google/gemini-4-hydrogen 和 Ofox Key。端点、凭据和响应解析方式必须配套。 切换协议时，只改模型名称并不够。

Google 于 2026 年 11 月 12 日向开发者发布 Hydrogen。Carbon 的 API 只面向付费层，而 Hydrogen 支持 Google 免费层和付费层。不过，免费访问仍取决于项目资格、验证状态和实际额度。本文按 2026 年 11 月 13 日 的文档与 Ofox 目录核对，从选择接入方式讲到保存并验证一份文本响应。

本文由 Ofox 发布。我们核对了请求格式，并用合成数据测试响应检查逻辑，没有进行付费 Hydrogen 推理，也没有测量速度或回答质量。下方是可自行运行的请求示例，不代表某个具体账户的线路已经通过真实调用测试。若还在选模型，可先看 Carbon、Hydrogen 与 Argon 的选择比较。本文引用的 Google 原始文档为英文。

先选接入方式，再创建 Key

下面两种示例通过不同服务调用同一模型系列。按自己的账户选择一种即可，不必两种都跑完才算完成教程。

Google 建议新项目使用 Interactions，同时继续支持 GenerateContent。Ofox 当前公开目录将 Hydrogen 标为支持 OpenAI、Gemini 两种协议，并在 OpenAI 路径下明确列出 /v1/chat/completions，因此本文采用这条已列出的路径。不能据此认为，把 Google Interactions 示例的 Base URL 换成 Ofox 就能直接运行。

Ofox 另有 Gemini 原生协议文档，对应的是另一套请求约定。通用协议文档列出某项功能，例如显式缓存，并不表示每个 Gemini 模型都支持。添加工具、流式输出或多模态输入之前，先确定自己采用的协议。

2026 年 11 月 13 日截取的官方开发者公告，证明的是发布信息，不是 API 实测或性能结果。英文原文。

准备 Google 项目，核对免费层验证

使用 Google 示例时，先打开 AI Studio 的 API Key 页面，确定请求归属哪个项目。新用户可能获得默认项目；已有 Cloud 项目可能需要导入 AI Studio。在目标项目下创建或选择 Key，再确认该项目的层级和可用配额。另一个项目的 Key 也可能鉴权成功，但消耗的是另一份额度。

Hydrogen 支持免费层，不等于每个新项目都立即可用。Google 的项目验证说明指出，额外创建的项目及在 AI Studio 之外创建的项目可能需要验证。受影响的请求会返回 403，错误中带有 FREE_TIER_VERIFICATION_REQUIRED。

如果遇到的正是这个错误：

1. 打开错误信息中的验证链接，或在 AI Studio 的 Projects 页面选择 Verify project。确认项目编号与当前 Key 所属项目一致。
2. 按 Google 流程使用受支持的实体手机完成设备验证。如果没有所需项目权限，请项目管理员处理。
3. 等到页面确认项目已验证，再重试一次下方的小请求。

同一项目下再创建一个 Key，并不会解除项目级验证要求。开通付费账单是另一条有费用的路径，不是每个 Hydrogen 用户都必须做的第一步。看到普通 403 时，先读具体原因，不要直接修改计费设置。

在 AI Studio 中查看实际限额。Google 按项目而非按 Key 限流，请求数和 token 等不同限额也可能分别触发。因此，同一项目的两个 Key 不会变成两份独立配额。本文不提供一个对所有账户都适用的免费 RPM 数字，请以项目与模型页面显示的限额为准。

将 Key 放在服务端环境变量 GEMINI_API_KEY 中，或由部署环境的密钥管理服务注入，不要放进浏览器代码或提交到仓库。Google 当前的 Key 文档区分授权型 Key 与标准 Key：AI Studio 新建 Key 默认是授权型；不受限制的标准 Key 会被拒绝，明确设置了限制的标准 Key 仍可使用。

下方程序显式读取 GEMINI_API_KEY，避免 SDK 自动读取环境变量时，由同时存在的 GOOGLE_API_KEY 优先命中另一个项目。本地 macOS/Linux 终端使用 export GEMINI_API_KEY="YOUR_GOOGLE_KEY"；PowerShell 使用 $env:GEMINI_API_KEY="YOUR_GOOGLE_KEY"。在自己的终端替换占位符，不要让密钥保留在共享的命令历史中；设置变量和执行程序要在同一个终端会话内完成。

用 Python 发起 Google 请求

当前 SDK 使用 Python 3.11 或更新版本，先创建隔离环境。我们的本地检查使用 Python 3.11 和 google-genai 3.3.0，该包声明的最低 Python 版本为 3.11。本示例使用 google-genai，不是旧的 google-generativeai。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade 'google-genai>=2.34.0'
python -m pip show google-genai

Windows PowerShell 的激活命令为 .venv\Scripts\Activate.ps1。示例设置的版本下限包含 Python 前台续接支持，不过本次短请求会保持在 Hydrogen 的单次响应预算内。将以下程序保存为 hydrogen_google.py：

import json
import os
from pathlib import Path
from google import genai

key = os.environ.get("GEMINI_API_KEY")
if not key:
    raise SystemExit("Set GEMINI_API_KEY for the intended Google project.")

client = genai.Client(api_key=key)
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Give exactly three short bullet points about avoiding duplicate API retries.",
    store=False,
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 65536,
    },
)
Path("hydrogen-google.json").write_text(
    json.dumps(interaction.model_dump(mode="json"), indent=2),
    encoding="utf-8",
)
print("Saved hydrogen-google.json")
print("Interaction:", interaction.id)
print("Status:", interaction.status)

运行 python hydrogen_google.py，请求会实际发送到 Key 所属项目；付费层调用会计费。程序会保存收到的响应，即使交互没有产生可用文本，也不会把它直接当成成功。继续使用后面的检查程序验收结果。

示例提示词很短，思考档位设为 low。65,536 是思考与可见输出合计的 token 上限，不是要求生成这么多 token，也不是必然扣除的用量。上限过小，可能在推理后没有足够空间输出正文。验证接入时应保持输入简短，查看实际 usage，不要将上限直接当成消耗量。

store=False 表示本次是一次性、不保存交互状态的调用。后台任务或依赖 previous_interaction_id 的会话不能原样照搬这个设置；它也不等于对服务商所有日志行为作出承诺。Interactions 概览说明了具体存储约定。

通过 Ofox Chat Completions 发起请求

使用 Ofox 时，按 API Key 设置与使用说明创建或选择 Key，并在服务端或本地终端设置 OFOX_API_KEY。macOS/Linux 使用 export OFOX_API_KEY="YOUR_OFOX_KEY"，PowerShell 使用 $env:OFOX_API_KEY="YOUR_OFOX_KEY"，在本地替换占位符。调用前检查账户可用余额和当前 Hydrogen 模型页（英文）。Google 免费层额度不能支付 Ofox 请求，Ofox 余额也不能支付 Google 端点的请求。

本次完整公开目录快照包含 133 个模型，其中列出了 google/gemini-4-hydrogen。这证明的是该日期的目录条目及标注的协议，不是成功推理记录，也不能保证所有账户、供应商或未来配置都具有相同行为。

将以下内容保存为 hydrogen-ofox-request.json：

{
  "model": "google/gemini-4-hydrogen",
  "messages": [
    {
      "role": "user",
      "content": "Give exactly three short bullet points about avoiding duplicate API retries."
    }
  ],
  "max_tokens": 65536,
  "stream": false
}

在终端中用 curl 发送：

curl --silent --show-error --fail-with-body --max-time 900 \
  'https://api.ofox.ai/v1/chat/completions' \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @hydrogen-ofox-request.json \
  --output hydrogen-ofox.json

该请求遵循 Ofox 的 Chat Completions 端点与参数文档。以后改用 OpenAI 兼容 SDK 时，注意 /v1 只出现一次：Base URL 为 https://api.ofox.ai/v1，完整 REST 地址还需带上 /chat/completions。

示例有意省略 temperature、top_p 和供应商专用的思考参数。Google 原生 generation_config 对象不是 OpenAI Chat Completions 参数，不能直接粘贴过来并假设网关会透传。若要在某条 Ofox 路径上配置推理，先核实该路径文档规定的参数映射；下文的原生四档表格不证明任意兼容字段都能生效。

curl 退出码非零，表示 HTTP 或传输操作失败。检查保存的错误体，共享日志前移除密钥。这里的超时值只是客户端等待上限，不是延迟预测。超时也不证明上游已经停止处理，不要立即连续重发可能计费的请求。

按所用协议验证响应

HTTP 200 可能对应尚未完成的交互、工具请求，或没有可用文本的结果。反过来，读取了另一套 API 的字段，也会让正常响应看起来是空的。Google SDK 提供 interaction.output_text 便捷属性，但保存的交互资源使用 steps；Chat Completions 则使用 choices。

将完整检查程序保存为 check_hydrogen.py。它只读取本地文件，不发网络请求，也不会重新提交推理。

import json
import sys
from pathlib import Path

def validate(payload, route):
    if "error" in payload:
        raise ValueError("API error: " + json.dumps(payload["error"]))
    if route == "google":
        if payload.get("status") != "completed":
            raise ValueError("Interaction is not completed: " + str(payload.get("status")))
        text = "".join(
            part.get("text", "")
            for step in payload.get("steps", [])
            if step.get("type") == "model_output"
            for part in step.get("content", [])
            if part.get("type") == "text"
        )
    elif route == "ofox":
        choices = payload.get("choices") or []
        if not choices:
            raise ValueError("No Chat Completions choices in response")
        choice = choices[0]
        if choice.get("finish_reason") != "stop":
            raise ValueError("Text did not finish normally: " + str(choice.get("finish_reason")))
        text = (choice.get("message") or {}).get("content") or ""
    else:
        raise ValueError("Route must be google or ofox")
    if not isinstance(text, str) or not text.strip():
        raise ValueError("No usable text; inspect the saved JSON")
    return text

def main():
    if len(sys.argv) != 3:
        raise SystemExit("Usage: python check_hydrogen.py google|ofox response.json")
    payload = json.loads(Path(sys.argv[2]).read_text(encoding="utf-8"))
    try:
        text = validate(payload, sys.argv[1])
    except ValueError as exc:
        raise SystemExit(str(exc))
    print("Response ID:", payload.get("id"))
    print("Usage:", json.dumps(payload.get("usage")))
    print(text)

if __name__ == "__main__":
    main()

Google 示例运行 python check_hydrogen.py google hydrogen-google.json，Ofox 示例运行 python check_hydrogen.py ofox hydrogen-ofox.json。通过时会打印响应 ID、usage 和可见文本。还要人工阅读文本，确认它确实包含三条简短、相关的要点。检查器验证的是协议完成状态及非空文本，不判断模型建议是否事实正确。

我们用本地合成样例检查了完成、空文本、错误、未完成和工具响应等情况，也覆盖了 Google 文本分散在多个输出步骤中的情况。这些测试证明检查逻辑的行为，不证明线上鉴权、配额、延迟或回答质量。在工具应用中，tool_calls 可以是正确的结束原因；但本次要求最终纯文本答案，所以检查器会将其判为未通过。

选择思考档位，不要与输出长度混淆

Hydrogen 原生 API 支持四个思考档位，默认 high；Carbon 与 Argon 默认则是 medium。Google 的思考文档描述的是推理投入，不是固定字数设置。

这些是测试起点，不是 Ofox 跑分结果。比较不同档位时，保持输入和验收标准不变，记录精确模型、档位、响应状态、耗时、usage，以及通过或失败的原因。每次只改一个设置；可见回答更短，不代表思考 token 更少。

Hydrogen 的输入、思考和输出共享 1,048,576 token，不是一百万输入额度再加一百万答案额度。默认同步思考与输出预算为 65,536，单次流式或非流式响应支持这一上限。更长输出需要长输出文档中的续接或后台执行机制。

首次检查不要直接设置一百万输出 token。以后使用后台执行时，保存任务 ID，明确处理等待中和终态；仅设置 background=true 不会提高默认输出上限。本教程验收的是短前台请求，不是完整的长任务控制器。

Hydrogen 的输出是文本。模型卡列出了图片、视频、音频和 PDF 输入，但不支持原生图像生成、音频生成或 Live API。读取图片进行分析与生成新图片是两种能力。先让文本基线通过，再增加一种模型支持的输入。

按失败所在环节排查

在诊断记录中同时保留端点、模型字符串、项目或账户、SDK 版本及具体错误，共享前去除凭据。一个字段错误时，不必重建整套接入环境。

Ofox 错误按 Ofox 错误处理说明排查；Google 错误分类见官方排错文档。Argon API 报错指南也展示了如何区分路径、配额和解析问题，但其中模型专属设置不是 Hydrogen 的默认值。

以后扩展工具时，通过所选 API 的原生工具字段声明工具，不要只在提示词里要求模型打印一种自创调用格式，再期待执行器自动识别。按协议保留会话历史和签名；若具体错误涉及签名，可看缺失 thought signature 的排查方法。

留下一份可复现的调用基线

当你有一份已保存响应、正确的完成标志、满足三条要点要求的可用文本，以及归属目标项目或账户的 usage 记录，就可以继续添加下一项功能。将模型、路径、SDK 版本和配置一并记下，不要把密钥写入记录。

下一次只增加一项变化：真实任务提示词、受支持的文件输入、流式输出，或一个已声明工具。新版本失败时先重跑原基线，以此区分接入退化与新增功能问题。

若接下来需要判断更难的任务是否该交给 Carbon，可参考 Gemini 4 选型指南。Carbon 的访问条件和首次调用设置不同，见 Carbon API 接入教程。Hydrogen 成功响应能证明当前集成路径可用，不能证明账户、参数和解析器可以不加修改地复制到所有服务。