Gemini 4 Neon 接入配置教程 按官方文档操作:用付费档 API Key 调用 gemini-4-neon,即可在官方 SDK、兼容客户端或 Antigravity 中完成接入。

本站上午已介绍过 Gemini 4 Neon 发布与官方定价。本文只整理官方给出的接入步骤,不涉及第三方中转。如果你已经在用 Gemini 4 Hydrogen,请求结构不用改,把型号换成 gemini-4-neon 即可,细节也可对照 Gemini 4 Hydrogen 接入配置教程。命令和参数据官方文档整理,本文未在本地逐项实测。
接入前先确认这几项
- 型号 ID 必须写成
gemini-4-neon,不要写成gemini-4.0-neon,也不要加-preview。 - 该型号仅开放付费档,不提供 Free 档;Google AI Studio 和 Gemini API 都要使用已开通付费的项目。
- 付费档在整个 100 万上下文窗口内统一定价:每百万 token 输入 3.00 美元,输出 15.00 美元(含思考 token);隐式缓存命中后的输入为 0.15 美元。
- API 的上下文是输入、思考和输出共用的 1,048,576 token;同步响应默认和单次上限为 65,536 token。
- 思考档为
low、medium、high(默认)和xhigh。官方建议大多数复杂任务先用high,只有不够时再开xhigh。 - Gemini API 地址是
generativelanguage.googleapis.com。中国大陆访问 Google 服务可能受限,请先确认你的环境能正常打开 AI Studio,并遵守 Google 的服务条款和可用地区规定。

用 API 直接调用
1. 创建 API Key
打开 Google AI Studio 的 API Keys 页面,登录后新建一个 Key。官方建议写成环境变量,不要把密钥写进代码或提交到版本库:
export GEMINI_API_KEY="你的 API Key"
如果同时设置了 GEMINI_API_KEY 和 GOOGLE_API_KEY,官方 SDK 会优先使用 GOOGLE_API_KEY。官方文档还提醒:新创建的 Key 默认为授权密钥(auth key);未限制的标准密钥可能被拒绝,请按 AI Studio 提示把密钥限制在 Gemini API。
2. 用 curl 测试原生接口
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-neon:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"parts":[{"text":" 用一句话介绍你自己 "}]}]}'
返回 JSON 里出现 candidates 字段,就说明 Key、付费档和型号名都没问题。
3. 用官方 Python SDK 调用
先安装或升级官方 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-neon",
input="写一个带滑动条的单文件 HTML 限流模拟器",
generation_config={"thinking_level": "high"},
)
print(interaction.output_text)
需要更深推理时,把 thinking_level 改成 xhigh。需要超过 64K 的长输出时,官方建议设置 background=True,并把 max_output_tokens 调到 131,072 或 262,144(上限为 1,048,576 减去输入 token)。只开 background 却不提高上限时,服务端仍会在 65,536 token 处停止。官方还建议把 HTTP 客户端超时至少设为 15 分钟。
4. 怎么选思考档位
| thinking_level | 特点 | 适合场景 |
|---|---|---|
low |
token 最少,延迟最低 | 对成本和延迟敏感的对话、批量处理 |
medium |
较快,token 较少 | 交互式写代码、界面原型、低延迟工具调用 |
high(默认) |
质量和速度均衡 | 大多数编程、智能体和多模态任务 |
xhigh |
token 最多,推理最深 | high 解决不了的多步工程、分析或科学问题 |
max_output_tokens 限制的是思考 token 与最终输出之和。上限过低时,思考会把额度吃完,答案会被截断。官方建议先用 high 做评测,再选能满足质量要求的最低档位。
OpenAI 兼容客户端怎么填
Gemini API 官方提供 OpenAI 兼容接口。ChatBox、Cherry Studio 这类支持「OpenAI 兼容」的客户端,可以按下面三项填写:
| 配置项 | 填写内容 |
|---|---|
| API 地址(Base URL) | https://generativelanguage.googleapis.com/v1beta/openai/ |
| API Key | AI Studio 创建的 Gemini API Key |
| 模型 ID | gemini-4-neon |
在 Cherry Studio 里,也可以直接用内置的 Gemini 服务商:进入设置里的模型服务,选择 Gemini,填入 API Key,再手动添加模型 ID gemini-4-neon。客户端本身的用法见 Cherry Studio 安装使用教程。
用 OpenAI SDK 测试兼容接口时,可用 reasoning_effort 对应 Gemini 的思考档:
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-neon",
reasoning_effort="high",
messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
官方映射是:minimal 和 low 都对应 Gemini 4 的 low;xhigh 目前只适用于 gemini-4-neon 和 gemini-4-hydrogen。Gemini 4 无法关闭思考,不要把 reasoning_effort 设为 none。
在 Google Antigravity 中接入
按官方博客,Gemini 4 Neon 已滚动上线到付费的 Google AI Pro、Google AI Ultra 订阅,以及企业通过 Gemini for business 使用的 Antigravity 桌面应用、CLI 和 IDE 扩展。在 Antigravity 里,Neon 的上下文窗口上限是 512K token,和 API 的 100 万窗口不是同一规格,不要混用。

1. 桌面应用或 IDE 扩展
到 Antigravity 下载页 安装桌面应用,或在 VS Code、JetBrains、Android Studio 等编辑器里安装官方扩展,然后用 Google 账号登录。打开对话后,点击输入框下方的模型选择器,选择 Gemini 4 Neon。官方说明:在包含该型号的套餐里,Neon 会出现在选择器顶部;如果当前还没有选定模型,它会成为新对话的默认项。思考档可选 Low、Medium、High(默认)和 Extra,其中 Extra 对应 API 里的 xhigh。
如果要把规划交给 Neon、把具体改代码交给 Hydrogen,选择 Orchestrator (Neon)。它会在同一次任务里自动切换,不必手动换模型。Orchestrator 是固定配置,不能再单独改思考档。
Neon 不会出现在 Free 档和 Plus 档的模型列表里。Google AI Pro 需使用付费计划,或符合条件的试用设备;企业用户走 Gemini Enterprise。模型列表里没有 Neon 时,先核对套餐,不要改模型名去试。
2. Antigravity CLI
在 macOS 或 Linux 上,官方安装命令是:
curl -fsSL https://antigravity.google/cli/install.sh | bash
agy --version
Windows 可用官方给出的 irm https://antigravity.google/cli/install.ps1 | iex。首次运行会引导选择配色、渲染模式,并确认是否信任当前工作目录。本机已登录 Antigravity 应用时,CLI 会尝试读取系统钥匙串里的会话;否则会打开浏览器完成登录。
如果要改用 Gemini API Key(适合无浏览器的环境),需要同时做两件事,只导出环境变量不会生效:
# 写入 ~/.gemini/antigravity-cli/settings.json
{"modelProvider": "gemini"}
export GEMINI_API_KEY="你的 API Key"
agy
此时标题栏会显示 Gemini API key,而不再显示账号邮箱。Key 必须来自已开通付费档、并且能调用 gemini-4-neon 的项目。若要改回账号登录,删掉 modelProvider 后重新启动 CLI。
指定 Neon 的常用写法如下。可用 agy models 查看当前账号能用的型号标识。
# 交互选择
# 启动后输入 /model,选 Gemini 4 Neon 或 Orchestrator (Neon)
# 启动时指定型号(Extra High 思考档)agy --model gemini-4-neon-xhigh
# 使用 Orchestrator (Neon)
agy --model "Orchestrator (Neon)"
# 非交互执行一条任务
agy -p "给注册表单加上输入校验并跑测试" --model "Orchestrator (Neon)"
在 CLI 里,思考档是 low、medium、high 和 xhigh,也可以使用 --effort xhigh。选中 Orchestrator 时,/effort 和 --effort 都不适用。
从其他 Gemini 型号迁移
- 已在使用 Carbon、Argon 或 Hydrogen 时,把型号改成
gemini-4-neon即可,不必改请求结构。 - Neon 默认思考档是
high,并支持xhigh。Carbon 和 Argon 默认是medium,最高到high。 - 必须使用付费档项目,Free 档无法调用。
- 从 Gemini 3.8 Flash 或更早型号迁过来时:不要沿用过低的
max_output_tokens;不要再传temperature、top_p、top_k,越界会返回 400;不要使用minimal;不要再使用显式缓存cachedContents,改走默认的隐式缓存(提示至少 4,096 token 时自动生效);工具调用应走原生函数调用或结构化输出。
常见报错与解决
404 NOT_FOUND:模型找不到
多半是型号名写错,例如 gemini-4.0-neon 或加了 -preview。改成 gemini-4-neon,也可以调用 ListModels 或 OpenAI 兼容的 /models 接口确认。如果名称正确仍返回找不到,再确认项目是否已开通付费档。
400 INVALID_ARGUMENT
常见原因是 thinking_level 写了 minimal,请求里带了 cached_content,或传入了越界的 temperature / top_p / top_k。按上一节的迁移清单删改即可。
回答为空或被截断
max_output_tokens 同时限制思考和输出。去掉过低的硬编码上限,或改用更低的思考档。需要超过 64K 的长输出时,设置 background=True 并提高上限。
429 RESOURCE_EXHAUSTED
请求过密或额度用尽时会出现。降低并发、加重试间隔,并在 AI Studio 核对付费档配额。Antigravity 的速率限制以套餐说明为准。
MALFORMED_FUNCTION_CALL
不要靠系统提示词让模型输出自定义的 JSON 工具调用,应改用原生 Function Calling 声明工具,或用结构化输出约束 JSON。
Antigravity 列表里没有 Neon,或 API Key 登录失败
桌面应用里看不到 Neon,通常是当前套餐不包含该型号(例如 Free 档或 Plus 档),请核对是否为付费的 Google AI Pro、Ultra 或 Gemini Enterprise。CLI 若在启动时提示没有 GEMINI_API_KEY,说明 settings.json 里写了 "modelProvider": "gemini",但环境变量没导出;只设置 GOOGLE_API_KEY 或把密钥放进 .env 文件,官方 CLI 都不会读取。
常见问题
Gemini 4 Neon 能在 Free 档使用吗?
不能。官方文档写明该型号仅开放付费档,Google AI Studio、Gemini API 和 Antigravity 都是如此。
Claude Code 能直接调用 Gemini 4 Neon 吗?
不能直接调用。Claude Code 使用 Anthropic Messages 协议,官方 Gemini API 没有提供这一接口。本文不涉及第三方协议转换。日常开发请使用官方 SDK、OpenAI 兼容客户端或 Google Antigravity。
Antigravity 和 API 的上下文窗口一样吗?
不一样。Gemini API 是统一的 100 万 token 窗口;Antigravity 文档写明 Neon 在该产品中的上下文上限是 512K token。
信息来源
- Gemini API 文档:What's new in Gemini 4 Neon
- Gemini API 文档:Using Gemini API keys
- Gemini API 文档:OpenAI compatibility
- Google Antigravity 文档:Choose a model
- Google Antigravity 文档:Get started
- Google Antigravity 文档:Authenticate
- Google Antigravity 博客:Gemini 4 Neon in Google Antigravity(2026-11-18)
- Google 官方博客:Introducing Gemini 4 Neon(2026-11-18)
核实时间:2026-11-19(Asia/Shanghai)。命令、配置项和限制均据上述官方文档整理,本文未在本地逐项实测。
