第 1 课
开通付费层 API Key,用 SDK 和 curl 调通 gemini-4-neon
认清调用 ID gemini-4-neon,开通付费层 API Key,并用 SDK 与 curl 发出第一个请求
课程目录第 1 / 3 课
学习位置仅保存在当前浏览器,有效期 180 天。
图文教材
本课对照官方文档「What's new in Gemini 4 Neon」「Gemini 4 Neon」模型页、「Getting started」「使用 API Key」「定价」编写。命令在 2026-11-20 核对;成功回复采用官方「Getting started」页的示例 JSON,400 为同日用假 Key 实打。
本课目标
- 认清调用 ID
gemini-4-neon,以及上下文、模态和付费层限制 - 在 Google AI Studio 创建 API Key,开通付费层,并导出环境变量
- 用官方 Python SDK 和 curl 向 Interactions API 发出第一个请求
- 看懂
steps数组和 SDK 提供的output_text - 用假 Key 复现 400
API_KEY_INVALID,确认请求打到了官方接口
前置条件
- 已有 Google 账号
- 本机有 curl,以及 Python 3.9 或更高版本
- 会在终端里设置环境变量
- 已按官方计费说明准备好付费层项目。Neon 不在免费层提供,见: https://aistudio.google.com/docs/pricing
第 1 步:先认清要调用的模型
Gemini 4 Neon 是 2026 年 11 月 18 日发布的型号。调用时 model 参数写 gemini-4-neon,不要写成 gemini-4 或旧的预览名。
官方模型页给出的关键规格(2026-11-20 核对):
| 项目 | gemini-4-neon |
|---|---|
| 定位 | 复杂软件工程、知识工作与科学流程;介于 Hydrogen 与 Carbon 之间 |
| 输入模态 | 文本、图片、音频、视频、PDF |
| 输出模态 | 文本 |
| 不支持 | 图像生成、音频生成、Live API;不支持显式缓存 |
| 统一上下文窗口 | 1,048,576(输入、思考和输出共用) |
| 默认同步输出上限 | 65,536 |
| long decode 输出上限 | 最高 1,048,576 减去输入 |
| 思考档 | low、medium、high(默认)、xhigh |
| 可用性 | Gemini API 付费层;免费层不可用 |
官方还写明:它同时支持 generateContent 和 Interactions API。Interactions API 自 2026 年 6 月起正式可用,是官方建议新项目使用的接口。本课全程跟做 Interactions API。第 2 课再专门练思考档,第 3 课再练文档输入和多轮会话。

2026-11-20 用无头 Chrome 对下面这个地址实拍,1280 宽首屏。

2026-11-20 实拍,已滚动到
gemini-4-neon规格表。
第 2 步:创建 API Key,开通付费层,并导出环境变量
按官方「Getting started」和「使用 API Key」的步骤,先到 Google AI Studio 创建密钥:
https://aistudio.google.com/apikey
官方写明:新用户会自动创建项目和 API Key,可在 API keys 页复制;若需要新密钥,点击 Create API key,按对话框添加一对密钥和项目。自 2026 年 5 月 28 日起,在 AI Studio 新创建的密钥默认是 authorization key(绑定服务账号、默认只开通 Gemini API)。不要把真实 Key 写进代码、笔记本或聊天记录。
Neon 只在付费层提供。官方「Getting started」写到:要提高限额,可在 API keys 页点击 Set up billing,或查阅 Billing 指南。没有付费项目时,后面的请求即使 Key 本身有效,也无法按本课调用 gemini-4-neon。
创建成功后,在当前终端会话里导出环境变量。官方示例是:
export GEMINI_API_KEY="YOUR_API_KEY"
官方 SDK 会自动读取这个环境变量。若只想确认变量在,可以打印前几位:
echo "Key 前缀:${GEMINI_API_KEY:0:7}********"

2026-11-20 实拍。
第 3 步:安装官方 Python SDK,发出第一个 Neon 请求
Interactions API 需要 Google GenAI SDK 2.3.0 或更高版本。官方「Getting started」给出的安装命令是:
pip install -U google-genai
新建 example.py。下面就是官方「What's new in Gemini 4 Neon」页 Quickstart 里的 Python 示例。官方原文把整句提示写在一行;这里只为排版折行,拼接后与官方原句一致,未改任何单词:
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-neon",
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)
python example.py
这是一次计费调用。官方写明:默认使用 high 思考档,以及 64K 同步输出上限。思考 tokens 按输出计费。这条官方 Quickstart 提示偏长、默认思考档也偏高,第一次联调就会消耗思考 tokens。若你只想先用更短的输入确认链路,可以暂时把 input 换成官方「Getting started」里的短句 Explain how AI works in a few words,但必须把该页示例中的 gemini-4-hydrogen 改成 gemini-4-neon。官方「迁移到 Neon」写明:从其他 Gemini 4 型号切过来,只需改模型 ID,请求结构不用改。
第 4 步:用官方 curl 再发一次
官方「Getting started」的 REST 示例默认写的是 gemini-4-hydrogen。按同一页的迁移说明,这里只把 model 改成 gemini-4-neon,其余请求头和路径保持官方原样,包括 Api-Revision:
curl -X POST \
"https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-4-neon",
"input": "Explain how AI works in a few words"
}'
完整接口地址单独占一行,避免横向溢出:
https://generativelanguage.googleapis.com/v1beta/interactions
第 5 步:看懂官方给出的对照结果
Interactions API 把一次回合写成一个 Interaction 资源。官方 SDK 提供 interaction.output_text,用来直接读取最终文本。REST 则返回完整资源,其中包括 steps。
官方「Getting started」用下面这段 JSON 说明字段结构。示例里的 model 是 gemini-4-hydrogen,提示是短句 “Explain how AI works in a few words”。官方 Neon 页没有给出固定样例回复,本课不编造 Neon 的成功输出。你用 gemini-4-neon 跑出来的文字和 Token 数不会与下面逐字相同,但应能看到 status 为 completed 的资源、type 为 thought 或 model_output 的步骤,以及一段可见文本:
{
"id": "v1_ChdpQUFvYXI...",
"status": "completed",
"usage": {
"total_tokens": 197,
"total_input_tokens": 8,
"total_output_tokens": 12
},
"created": "2026-06-09T12:01:25Z",
"steps": [
{
"type": "thought",
"signature": "EvEFCu4FAQw..."
},
{
"type": "model_output",
"content": [
{
"type": "text",
"text": "<官方例句见代码块下方,原文未改>"
}
]
}
],
"object": "interaction",
"model": "gemini-4-hydrogen"
}
官方 text 字段的原句是:
AI learns patterns from data, then uses those
patterns to make predictions or decisions on new data.
上面两行只为排版折行,拼起来就是官方原句,未改动任何单词。
这段示例来自:
https://aistudio.google.com/docs/get-started
请注意两点。第一,steps 里常常先出现 thought 步骤,可见回答在 model_output 里;不要假设文本一定在某个固定下标。第二,上面这条官方短示例的 usage 没有单独写出思考 tokens。下一课会对照「Gemini thinking」页里带 total_thought_tokens 的官方 usage。
采用官方文档示例,本环境未用真实密钥跑出成功回复。
第 6 步:用假 Key 复现 400
在确认地址和请求体无误后,可以用一个明显无效的 Key 看报错长什么样。把环境变量临时换成假值,再发一次(不要用你的真 Key 做这次实验):
export GEMINI_API_KEY="AIza-test-invalid-key-kun-course"
curl -X POST \
"https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-4-neon",
"input": "ping"
}'
2026-11-20 00:02(Australia/Perth,与 Asia/Shanghai 同时区)在本课用上述假 Key 实打,HTTP 状态码为 400。响应正文是一个只含一项的 JSON 数组,核心字段如下:
[
{
"error": {
"code": 400,
"message": "API key not valid. Please pass a valid API key.",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "API_KEY_INVALID",
"domain": "googleapis.com",
"metadata": {
"service": "generativelanguage.googleapis.com"
}
}
]
}
}
]
完整实录见本课工作目录中的 transcripts/401-body.json(文件名沿用实录习惯,实际 HTTP 状态码是 400,不是 401)。如果你看到的是 reason 为 API_KEY_INVALID,说明请求已经打到官方接口,问题在密钥,而不在 URL 或模型 ID。
同日若完全不带 x-goog-api-key 头,实打得到的是 HTTP 403,status 为 PERMISSION_DENIED,message 为 Permission denied on the service.,reason 为 ACCESS_DENIED。
做完后把环境变量改回真实 Key:
export GEMINI_API_KEY="YOUR_API_KEY"
第 7 步:对照官方刊例价
在继续加大请求之前,先按官方定价页看一眼成本。下面是 2026-11-20 再次打开官方定价页、Standard 档确认的刊例价,单位是每 100 万 tokens,美元。Neon 在完整 1M 窗口上采用均一价,没有另外的长上下文加价。免费层写的是 Not available。
| 计费项 | 免费层 | 付费层 Standard |
|---|---|---|
| 输入 | 不可用 | $3.00 |
| 输出(含思考 tokens) | 不可用 | $15.00 |
| 上下文缓存 | 不可用 | $0.15(仅隐式缓存) |
同一页的其他调用档(2026-11-20 核对):
- Batch:输入 $1.50,输出 $7.50,缓存 $0.075
- Flex:输入 $1.50,输出 $7.50,缓存 $0.075
- Priority:输入 $5.40,输出 $27.00,缓存 $0.27
官方还写明:模型处理的每一个 token 都会计数并计费,包括思考 tokens,以及使用接地时的内部工具系统指令和函数声明。Google Search 接地在 Gemini 3 及更新型号之间共享每月 5,000 次免费请求,超出后每 1,000 次 $14,并受每天 1,500 次的上限约束。一条用户请求可能触发多次搜索,按实际搜索次数计费。
因为默认思考档是 high,第一次用 Neon 时,账单往往比「只看可见句子」预想的更高。下一课再按任务调整思考档。

2026-11-20 实拍,页面当时停在 Gemini 4 Neon,并选中 Standard。表中数字与上表一致。
常见坑
- 把 Key 写进源码或把完整 Key 打进日志。只导出环境变量,打印时最多保留前缀。
- 在免费层项目里调用
gemini-4-neon。官方定价页写明 Neon 不在免费层提供,需要先开通付费。 - 继续使用已停止维护的旧包
google-generativeai。Interactions API 需要google-genai2.3.0 或更高版本。 - 漏掉 REST 请求里的
Api-Revision: 2026-05-20。官方「Getting started」的 curl 带有这个头。 - 只看可见回答、忽略思考 tokens。思考 tokens 按输出计费,并占用统一上下文窗口。
小结
到这里,你已经用官方示例调通了 Interactions API,知道该读 output_text 和 steps,也能从 400 API_KEY_INVALID 判断密钥是否有效。下一课会按官方建议选择型号、设置思考档,并阅读 usage 里的思考 tokens。

