Gemini 4 Carbon API 怎么接入？从开通到验证首次调用

使用准确的模型 ID gemini-4-carbon，并为所属 Gemini API 项目开通付费服务。新集成可从 Google 推荐的 Interactions API 开始。只有交互完成并返回可用文本，才算通过首次调用验收；HTTP 200 本身不够。

Carbon 已于 2026 年 11 月 10 日向付费 API 开发者公开开放，早先关于限量访问的公告已不能完整代表当前接入条件。本文按 2026 年 11 月 13 日的官方文档核对，从项目和密钥配置开始，直到保存一份可以检查的响应。

以下示例调用 Google 原生 API，不是 Ofox 端点。我们核对了文档中的请求格式，并使用合成数据测试响应解析器，没有为本文执行付费 Carbon 调用。因此，示例提示词是供你运行的检查任务，不是模型性能实测结果。如果还没确定用哪款模型，可以先看 Carbon、Hydrogen 与 Argon 的选择比较。

1. 确认密钥属于已开通付费的项目

你需要符合 Gemini API 使用条件的 Google 账号、能在 AI Studio 中访问的 Google Cloud 项目、属于该项目的 API Key，以及有效的 API 付费结算。这是四个不同的条件。订阅 Gemini 应用或 Google AI Ultra，并不会自动为程序使用的项目配置 API 结算。

1. 打开 Google AI Studio，选择准备使用的项目。如果已有 Cloud 项目，按需将其导入 AI Studio，不要仅为看到创建密钥按钮就另建一个无关项目。
2. 在该项目的 API Key 管理界面创建或选择密钥。在部署记录中保留项目名称或 ID，不要记录密钥明文，并确认终端或服务器加载的就是这个项目的密钥。
3. 在 AI Studio 的项目结算设置中，为同一个项目完成付费开通。当前流程可能使用 Prepay、提供 Prepay/Postpay 选择，或保留过渡期 Postpay，取决于账号状态。Prepay 开通可能要求至少支付 5 美元或等值本地货币。以账号实际显示的结算状态为准，绑卡不代表请求已经有可用资金。
4. 确认结算已启用，所需的预付余额可用。发请求前检查项目配额与地区资格；付费项目仍然有限额。

来源：Google 的 API Key 指南（英文）与结算指南（英文）。如果无法导入项目或创建密钥，请项目管理员核对这些操作所需的权限，不要通过公开密钥或随意扩大权限来解决按钮缺失的问题。

2026 年 11 月 13 日截取的官方英文公告。它用于核对面向开发者的公开发布情况，不证明你的账号已开通结算，也不是 API 调用成功截图。公告原文（英文）。

老密钥失效不一定是拼写错误

Google 现在默认在 AI Studio 创建 authorization key。当前文档说明，不受限制的 standard key 会被拒绝；已明确设置限制的 standard key 仍可使用。应检查密钥类型和限制，不要把所有旧密钥一概认定为无效。

将密钥放在服务端环境变量或密钥管理器中。本地终端使用 GEMINI_API_KEY，不要把明文写入并提交到仓库，也不要放入截图、问题反馈或浏览器 JavaScript。示例显式读取 GEMINI_API_KEY，这样可以避免旧的 GOOGLE_API_KEY 环境变量在 SDK 自动读取时优先生效，悄悄选中另一个项目。

运行前可以只检查变量是否存在，不显示其值：

python3 -c 'import os; print("Key configured:", bool(os.environ.get("GEMINI_API_KEY")))'

返回 True 只代表变量有值，不能证明密钥有效、项目正确或结算可用。下面的实际请求才会提供下一层证据。

2. 用 Python 完成一次有明确上限的调用

创建独立环境，避免其他应用中的旧 SDK 影响本次教程：

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 激活。安装的包是 google-genai，导入方式为 from google import genai，不要换成旧包 google-generativeai。基础 Interactions 支持与前台自动续接所需的最低版本不同。以上版本下限包含当前 Python 自动续接能力，尽管这次短请求刻意控制在单次响应范围内。参见 Interactions 文档（英文）和长输出文档（英文）。

将以下代码保存为 carbon_first_call.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 paid project.")

client = genai.Client(api_key=key)
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Return exactly three checklist items for reviewing an API integration.",
    store=False,
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 32768,
    },
)

payload = interaction.model_dump(mode="json")
Path("carbon-response.json").write_text(
    json.dumps(payload, indent=2), encoding="utf-8"
)
text = interaction.output_text or ""
print("Interaction:", interaction.id)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
if interaction.status != "completed" or not text.strip():
    raise SystemExit("No completed text result; inspect carbon-response.json.")
print(text)

运行 python carbon_first_call.py。这会发送付费请求。 先选一种方式执行，不要把 Python 和 REST 示例自动连续跑一遍，造成重复测试。32,768 token 是思考与可见输出合计的上限，不是费用预测，也不是要求模型生成这么多文字。简短提示词配合 low 思考档位，让这一步聚焦接入检查，而不是复杂研究任务。

成功时，程序应显示交互 ID、completed 状态、用量和三条有意义的检查项。除了状态，还要读答案：交互完成，不代表格式和内容要求必然满足。保存 JSON 便于排查；之后若把示例提示词换成客户数据，响应文件也应按可能包含敏感业务信息的文件处理。

本例设置 store=False，因为只做单轮请求。它关闭该交互用于后续检索或服务端对话续接的存储，不是对所有供应商日志政策的全面承诺。默认值是 store=true。不要把这个设置直接复制到后台任务，或依赖 previous_interaction_id 的示例中。

3. 用 REST 调用，并从正确字段提取文本

REST 便于看清客户端实际发出的请求。需要 curl，以及运行解析器的 Python 3。先将请求体保存为 carbon-request.json：

{
  "model": "gemini-4-carbon",
  "input": "Return exactly three checklist items for reviewing an API integration.",
  "store": false,
  "generation_config": {
    "thinking_level": "low",
    "max_output_tokens": 32768
  }
}

发送到 Interactions 端点：

curl --silent --show-error --fail-with-body --max-time 900 \
  'https://generativelanguage.googleapis.com/v1beta/interactions' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @carbon-request.json \
  --output carbon-response.json

服务端返回错误体时，也会将其保存到文件以便检查。如果 curl 退出码非零，说明传输或 HTTP 请求需要排查，不能当作已经拿到答案继续执行。900 秒是明确设置的客户端超时，不代表 Carbon 每次都需要 15 分钟。客户端超时也不能证明服务端已停止处理，因此不要未经检查就立即重复可能计费的任务。

output_text 是 SDK 提供的便捷属性，不是 REST 响应字段。 REST 文本位于 steps 中，具体在 model_output 项的 text 内容里。如果仍按 GenerateContent 的 candidates，或旧示例的 outputs 解析，可能把有效响应误判为空。

把下面代码保存为响应文件旁的 inspect_carbon.py：

import json
import sys
from pathlib import Path


def extract_text(payload):
    return "".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"
    )


def inspect(path):
    payload = json.loads(Path(path).read_text(encoding="utf-8"))
    if "error" in payload:
        raise SystemExit("API error: " + json.dumps(payload["error"]))
    text = extract_text(payload)
    print("Interaction:", payload.get("id"))
    print("Status:", payload.get("status"))
    print("Usage:", json.dumps(payload.get("usage")))
    if payload.get("status") != "completed" or not text.strip():
        raise SystemExit("No completed text result; inspect the saved response.")
    print(text)


if __name__ == "__main__":
    inspect(sys.argv[1] if len(sys.argv) > 1 else "carbon-response.json")

运行 python3 inspect_carbon.py carbon-response.json。它会合并所有文本片段，不假设第一个 step 就是最终答案；对于未完成或仍需执行动作的交互，也不会误报成功。解析器可用于监控检查，但不要把失败直接接到无限自动重试循环上。

我们已用合成的完成、空结果、错误与多 step 响应做本地测试。这些测试验证的是提取逻辑与失败处理，不证明 Google 线上 API 的鉴权、可用性、延迟或回答质量。

4. 接入真实任务前，先理解这些参数

首次请求故意不加工具、大文件和长时间 Agent 循环。基础接入成功后，再逐项增加。根据 Carbon 开发者指南（英文），需要注意以下边界：

如果迁移的应用原本设置了很小的输出上限，Google 建议至少留出 32,768 个思考/输出 token。这是预算分配，不代表每次都按上限消耗。适用时降低思考档位，并查看实际用量，不要按答案字数猜费用。模型价格适用条件与可复算比较见 Gemini 4 选型指南。

从首次调用扩展到长任务时

不要只增大 max_output_tokens，其他代码一字不动。长输出文档（英文）区分了前台续接、流式与后台执行。新版本 SDK 可以合并前台多次响应；自建 REST 客户端则必须处理 requires_continuation，并向后续请求传递所需的续接信息。

后台任务需要启用存储、保存交互 ID，并设置有时间边界的轮询。queued 和 in_progress 表示等待中；completed 表示可以开始验证结果；incomplete、failed、cancelled 是不同的结束状态。requires_action 表示需要执行工具动作，并不代表最终答案已准备好。提高预算或设置 background=true 都不保证输出一定达到某个长度。本文的首次调用示例不实现这套独立的长任务控制器。

使用服务端对话历史时，previous_interaction_id 会携带之前的对话，但不会继承 tools、system_instruction 或 generation_config。下一轮仍需要这些配置时，应重新发送。Interactions 默认保存响应；Google 付费层默认保留 55 天，也提供更短的配置选项。应主动决定存储方式，而不是照搬示例后忽略它。

5. 按故障发生的顺序排查

读取结构化错误，记录端点、准确模型 ID、项目标识、SDK 版本和时间，排除密钥明文。先修复最早失败的环节，再调整提示词或提高 token 预算。

Google 的故障排查文档（英文）说明了错误分类。站内 Argon API 报错排查也介绍了如何区分路由、配额与响应问题，但其中 Argon 特有的细节不能直接当作 Carbon 结论。以后加入工具调用，若出现签名验证错误，可按 missing thought signature 排查指南处理具体协议问题，不要直接丢弃历史消息。

迁移已有 Gemini 客户端

保留可工作的基线，每次只改一个边界。Google 原生 GenerateContent API 仍受支持；推荐新项目使用 Interactions，不等于所有正常运行的客户端都必须立即重写。

迁移时，请求格式和响应解析器要一起更新。只把模型名换成 gemini-4-carbon，却仍从 candidates 读取结果，不算迁移完成。同时检查思考档位、移除显式缓存引用与过时的采样假设，并重新评估超时和输出限制。JavaScript Interactions 客户端中的 generation_config、thinking_level、max_output_tokens 使用 snake_case，不要套用 GenerateContent 配置字段的大小写。

重新接入工具和客户文件前，先运行相同的无敏感内容检查提示词。随后再用一个有明确验收标准的代表任务测试。首次检查成功，只验证了接入路径，不能证明生产中的多步 Agent 已经可靠。

这套示例能直接通过 Ofox 使用吗？

本文由 Ofox 发布，但上面的代码使用 Google 原生密钥和端点。我们在 2026 年 11 月 13 日检查的公开 catalog 快照中没有列出 Carbon。这是带日期的目录观察，不证明任何账号或未来路由都不支持。我们没有验证 Ofox Carbon 调用，也不声称改一下 Base URL 就能通过 Ofox 跑通本文。

接入 Ofox 时，先核对准确模型的当前可用性与支持协议，再按 Ofox Gemini API 文档配置对应路由的端点、鉴权与请求格式。Ofox API Key 与 Google Key 应分开管理。有 Gemini 兼容路由，不代表支持 Google Interactions 端点或 Carbon 的所有能力。

如果 Ofox 路由返回错误，按 Ofox 错误处理指南检查实际响应。Google 结算账号、Ofox 余额和应用订阅是不同体系，在一处充值不会为另一处的请求付款。

首次调用通过后，留下什么记录？

确认完成前，保存以下不含密钥的证据：

• 准确模型、端点、SDK 版本和项目标识。
• 一份包含交互 ID、状态与用量的响应。
• 提取出的可见文本，并确认满足三条检查项要求。
• 该请求使用的思考档位、输出预算与存储设置。
• 遇到过的错误，以及真正解决它的具体修改。

这份基线可以帮助区分权限、协议和输出问题。以后增加工具或更大提示词时，如果基线仍正常而新任务失败，就检查新增部分，不必反复创建密钥、更换结算项目或重跑整个 Agent。