Gemini 4 Hydrogen接入配置教程：API与CLI

浏览：4次阅读

发布日期：2026-11-13

Gemini 4 Hydrogen 接入配置 只需三步：在 Google AI Studio 创建 API Key，把模型名写成 gemini-4-hydrogen，再按客户端选择原生 Gemini 接口或 OpenAI 兼容接口。免费层和付费层都能调用，Gemini CLI 目前要用 -m 手动指定模型。

Gemini 4 Hydrogen接入配置教程：API与CLI插图 — 图片来源：Google Blog：Gemini 4 Hydrogen 开发者说明

Google 在 11 月 12 日发布了 Gemini 4 Hydrogen，定位是日常编程和 Agent 工作流的快速执行模型，发布细节、跑分和价格可以先看 Gemini 4 Hydrogen 发布解读。本文只讲怎么接入：API 调用、Gemini CLI 配置、Cherry Studio 等 OpenAI 兼容客户端配置，以及常见报错。

模型 ID：gemini-4-hydrogen。不要写成 gemini-4.0-hydrogen，也不要加 -preview。
可用范围：官方文档写明 Google AI Studio 和 Gemini API 的免费层、付费层都可用，支持 GenerateContent 和 Interactions API。免费层有速率限制。
价格：付费层每百万 token 输入 1.50 美元、输出（含思考 token）7.50 美元；隐式缓存命中的输入为 0.075 美元。100 万上下文内统一定价。
上下文：输入、思考和输出共用 1,048,576 token 窗口；单次同步输出上限 65,536 token。
网络：Gemini API 的地址是 generativelanguage.googleapis.com。中国大陆访问 Google 服务可能受限，请先确认你的环境能正常打开 AI Studio，并遵守 Google 的服务条款和可用地区规定。

打开 Google AI Studio，登录 Google 账号后进入「Get API key」，新建一个 Key。建议把它写进环境变量，不要直接写在代码里：

export GEMINI_API_KEY="你的 API Key"

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":" 用一句话介绍你自己 "}]}]}'

返回 JSON 里有 candidates 字段，就说明 Key 和模型名都没问题。

先安装或升级官方 SDK：pip install -U google-genai。官方快速上手用的是 Interactions API，默认 high 思考档：

from google import genai

client = genai.Client()  # 自动读取 GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="写一个 Python 函数，检查字符串是否是合法 IPv4 地址",
    generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)

thinking_level	特点	适合场景
low	token 最少，延迟最低	快速聊天、批量处理
medium	较快，token 较少	交互式写代码、UI 原型
high（默认）	质量和速度均衡	大多数编程和 Agent 任务
xhigh	token 最多，推理最深	high 解决不了的多步难题

官方建议先用 high，只有 high 不够时再开 xhigh；xhigh 会增加延迟和费用，简单问题上还可能「想太多」。

图片来源：GitHub：google-gemini/gemini-cli

截至发稿，Google 的发布公告没有提到 Gemini CLI。第三方测试（fyve.co.jp，2026-11-13）显示，Gemini CLI 0.68.0 的模型列表和 Auto 自动选择里都还没有 Hydrogen，但在配置了 Gemini API Key 的情况下，用 -m 直接写模型名可以调通：

# 用 API Key 登录方式
export GEMINI_API_KEY="你的 API Key"

# 交互模式指定模型
gemini -m gemini-4-hydrogen

# 非交互模式（一次性提问）gemini -m gemini-4-hydrogen -p "解释一下这个仓库的目录结构"

注意两点：

这不代表 CLI 已正式支持 Hydrogen。0.69 预览版加入了 /model 模型名校验，升级后若提示模型无效，请等官方发版后再用。
非交互模式下，未信任的工作目录会在执行前停住，可加 --skip-trust 或设置 GEMINI_CLI_TRUST_WORKSPACE=true。

如果 Gemini CLI 登录后报 403 或额度问题，可参考 Gemini CLI 403 报错解决方法。

图片来源：GitHub：CherryHQ/cherry-studio

Gemini API 官方提供 OpenAI 兼容接口，ChatBox、Cherry Studio、OpenCode 这类支持「OpenAI 兼容」的客户端都能这样接入：

配置项	填写内容
API 地址（Base URL）	`https://generativelanguage.googleapis.com/v1beta/openai/`
API Key	AI Studio 创建的 Gemini API Key
模型 ID	`gemini-4-hydrogen`
推理强度	`reasoning_effort`：low / medium / high / xhigh

在 Cherry Studio 里，也可以直接用内置的 Gemini 服务商：进入设置里的模型服务，选择 Gemini，填入 API Key，再手动添加模型 ID gemini-4-hydrogen。Cherry Studio 的基础用法见 Cherry Studio 安装使用教程。

用 OpenAI SDK 测试兼容接口：

from openai import OpenAI

client = OpenAI(
    api_key="你的 GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
resp = client.chat.completions.create(
    model="gemini-4-hydrogen",
    reasoning_effort="medium",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

官方映射规则：reasoning_effort 的 minimal 和 low 都对应 Gemini 4 的 low，xhigh 只有 gemini-4-hydrogen 支持；Gemini 4 无法关闭思考。