第 1 课

开通付费层 API Key,用 SDK 和 curl 调通 gemini-4-neon

认清调用 ID gemini-4-neon,开通付费层 API Key,并用 SDK 与 curl 发出第一个请求

图文22 分钟Gemini 官方文档 ↗

课程目录第 1 / 3 课

学习位置仅保存在当前浏览器,有效期 180 天。

01 / 图文教材

图文教材

本课对照官方文档「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 课再练文档输入和多轮会话。

官方文档「What's new in Gemini 4 Neon」页首屏

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

https://aistudio.google.com/docs/whats-new-gemini-4-neon

官方文档「Gemini 4 Neon」模型页规格表

2026-11-20 实拍,已滚动到 gemini-4-neon 规格表。

https://aistudio.google.com/docs/models/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}********"

官方「Getting started」页首屏

2026-11-20 实拍。

https://aistudio.google.com/docs/get-started

第 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 时,账单往往比「只看可见句子」预想的更高。下一课再按任务调整思考档。

官方「定价」页 Neon 段,已选 Standard

2026-11-20 实拍,页面当时停在 Gemini 4 Neon,并选中 Standard。表中数字与上表一致。

https://aistudio.google.com/docs/pricing

常见坑

  • 把 Key 写进源码或把完整 Key 打进日志。只导出环境变量,打印时最多保留前缀。
  • 在免费层项目里调用 gemini-4-neon。官方定价页写明 Neon 不在免费层提供,需要先开通付费。
  • 继续使用已停止维护的旧包 google-generativeai。Interactions API 需要 google-genai 2.3.0 或更高版本。
  • 漏掉 REST 请求里的 Api-Revision: 2026-05-20。官方「Getting started」的 curl 带有这个头。
  • 只看可见回答、忽略思考 tokens。思考 tokens 按输出计费,并占用统一上下文窗口。

小结

到这里,你已经用官方示例调通了 Interactions API,知道该读 output_text 和 steps,也能从 400 API_KEY_INVALID 判断密钥是否有效。下一课会按官方建议选择型号、设置思考档,并阅读 usage 里的思考 tokens。

本课资料

适用环境

  • 网页
  • iOS
  • Android
  • API

官方文档

Gemini ↗