Gemini 4 Carbon API:模型 ID、定价与你的第一个请求

从零接入 Google Gemini 4 Carbon API:详解模型 ID gemini-4-carbon、Interactions API 请求示例、思考 token 计费规则与 Apifox CLI 回归测试。

用 Apifox,节省研发团队的每一分钟

Gemini 4 Carbon API:模型 ID、定价与你的第一个请求

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

截至 2026 年 11 月 11 日,Google 的 Gemini 4 Carbon API 使用模型 ID gemini-4-carbon,在 2026 年 11 月 30 日之前的价格为每百万输入 token $2、每百万输出 token $10,之后恢复为 $4 与 $20。Google 已于 2026 年 11 月 10 日将其正式全面开放(GA),且仅在 Gemini API 的付费层级中提供。

本指南将带你从申请新密钥一路跑通第一个请求,解析决定实际账单的关键用量字段,并演示如何把接口回归测试交给你的编码 Agent 自动完成。

AI Coding 交流群

如果你也在用 AI 写代码,或者正在研究 Cursor、Claude Code 这些工具,欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流,还有各种新工具和新玩法。

AI Coding 交流群二维码

Gemini 4 Carbon 的模型 ID 是什么?

Gemini 4 Carbon 的模型 ID 为 gemini-4-carbon。你可以在发往 Gemini API Interactions 端点的请求体中将其作为 model 字段传入,也可以在 Python / JavaScript SDK 或 Google AI Studio 提示词中使用它。Google 将 Carbon 称为旗下最强的推理模型,建议将其用于高难度任务;而日常工程工作则继续以 Gemini 4 Argon 作为默认模型。

想先了解模型本身的背景,可以阅读 Gemini 4 Carbon 是什么。

项目 值 来源
模型 ID gemini-4-carbon Google AI Studio 文档
开放时间 2026 年 11 月 10 日 Google 发布公告
可用渠道 Gemini API 付费层级、Google AI Studio、Android Studio Google 发布公告
免费层级 不提供 Google AI Studio 文档
上下文窗口 1,048,576 tokens(由输入、思考与输出共享) Google AI Studio 文档
单次同步响应最大输出 65,536 tokens Google AI Studio 文档
超长解码(Long decode) 开启 background: true 时最高可达 1M tokens 减去输入长度 Google AI Studio 文档
思考等级(Thinking levels) low、medium(默认)、high Google AI Studio 文档
价格(至 2026 年 11 月 30 日) 每百万输入 token $2,输出 token $10 Google 发布公告
价格(2026 年 12 月 1 日起) 每百万输入 token $4,输出 token $20 Google 发布公告
缓存输入(隐式缓存) 每百万 token $0.10,12 月 1 日起为 $0.20 Google AI Studio 文档

如何获取用于 Gemini 4 Carbon 的 Gemini API 密钥?

Carbon 仅运行在付费层级上,因此光有一个普通 API 密钥还不够,你的密钥所属项目必须绑定 Cloud Billing 计费账户:

  1. 打开 Google AI Studio 中的 API keys 页面。新用户会自动创建一个项目和密钥;老用户可点击 Create API key。
  2. 在 API keys 或 Projects 页面上点击 Set up billing(设置计费)。
  3. 按照 Google 快速入门的要求,创建或关联一个 Cloud Billing 账户,添加付款方式并预充值至少 $5 的额度。
  4. 在终端中导出密钥:export GEMINI_API_KEY="YOUR_API_KEY"。

如果你想了解完全不需要 API 密钥的使用方式,可参考 Gemini 4 Carbon 免费使用方式汇总。

如何发送你的第一个 Gemini 4 Carbon API 请求?

Google 官方的 Carbon 快速入门使用 Interactions API:向 /v1beta/interactions 发送 POST 请求,并在请求体中传入 model 和 input。建议将模型名称保存在环境变量中,方便后续在 Carbon 与 Argon 之间一行切换。

使用 curl:

export GEMINI_MODEL="gemini-4-carbon"

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "'"$GEMINI_MODEL"'",
    "input": "Find the race condition in this retry loop and rewrite the lock safely.",
    "generation_config": {
      "thinking_level": "medium"
    }
  }'

使用 Python SDK(pip install -U google-genai):

import os
from google import genai

MODEL = os.environ.get("GEMINI_MODEL", "gemini-4-carbon")

client = genai.Client()  # 自动从环境变量读取 GEMINI_API_KEY

interaction = client.interactions.create(
    model=MODEL,
    input="Find the race condition in this retry loop and rewrite the lock safely.",
    generation_config={"thinking_level": "medium"},
)

print(interaction.output_text)
print(interaction.usage)

以上两段代码均遵循 Google 官方文档中的示例。由于撰写本文的机器上没有绑定付费 Carbon 密钥,我们未在本机实际执行这两段代码,首次接入时请对照你自己的真实响应核对返回结构。

来自 Google 迁移说明的三个细节可以帮你省去不少排查时间:

  • 移除采样参数。 temperature、top_p 和 top_k 会被 Carbon 直接忽略,建议从请求体中删掉。
  • 调高超时时间。 高难度提示词可能需要数分钟才能完成推理。Google 建议开启后台执行(background execution),或者将 HTTP 客户端超时设为至少 15 分钟。
  • 在服务端保存对话状态。 进行多轮对话和工具调用时,请传入 previous_interaction_id,而不必每轮重发整段历史记录。

已经在用 Argon?我们的 Gemini 4 Argon API 指南使用的是完全相同的请求结构。

如何解读响应中的 usage 与思考 token?

每次 interaction 调用都会返回一个 usage 对象。以下是直接决定账单金额的字段:

  • total_input_tokens:你发送的输入总量,包含系统指令和工具声明。
  • total_thought_tokens:模型在给出最终回答前用于内部推理思考的 token 数量。
  • total_output_tokens:最终可见的回答文本。
  • total_tokens:以上各项之和。

最需要紧盯的字段是 total_thought_tokens。Google 的思考机制指南明确指出,响应侧的计费基准是“输出 token 与思考 token 之和”,因此思考过程同样按每百万 token $10(12 月起为 $20)的输出单价计费。Google 还表示,为了探索和验证结果,Carbon 在每一轮中“比 Argon 消耗更多的思考 token”。在处理高难度提示词时,思考 token 往往占据了整张账单的大头。

Gemini 4 Carbon 请求计费与上下文示意图:输入 token 按输入费率计费,思考 token 与输出 token 均按输出费率计费,三者共享同一个 1M token 上下文窗口

max_output_tokens 同时限制了“思考 + 输出”的总和。如果你把这个值设得太低,Carbon 可能会在思考阶段就把预算用光,导致最终回答被截断。Google 给出的起点建议如下:

  • 常规任务: 保持默认值 65,536。
  • 当前上限低于 32K 的应用: 至少调高到 32,768。
  • 复杂推理与编码: 设置 background: true,并将上限设为 131,072 或 262,144 tokens。

开启 background: true 后,Google 服务端会以 64K token 为步长持续生成响应。你只需轮询该 interaction,直到其状态离开 in_progress 或 queued,然后将每个 model_output 步骤中的文本拼接起来即可。

该选哪个 Gemini 4 Carbon 思考等级(thinking level)?

思考等级是你平衡生成质量、延迟和成本的核心开关。根据 Google 的 思考机制指南 和 Carbon 文档:

思考等级 Token 消耗 适用场景
low 消耗最少,延迟最低 简单且对成本敏感的任务、轻量分析与写作
medium(默认) 均衡 大多数任务,包括复杂编码与 Agent 工作
high 消耗最多,首字延迟最慢 高难度数学、科学问题,以及最棘手的编码或 Agent 任务

Google 建议在全部三个等级上跑一遍你的评测集,并保留能满足质量门槛的最低档位。在 Carbon 上,low 与 high 之间的差额就是你的预算去向。

什么时候该把任务发给 Gemini 4 Carbon 而不是 Argon?

Google 对此说得非常直接:“Argon 依然是绝大多数软件工程与知识工作的理想选择。”这两款模型共享 1M 上下文窗口、内置工具以及完全相同的首发单 token 价格,因此真正的区别在于每轮调用消耗多少 token。建议将复杂的根因调试、架构设计、高密度多模态综合分析、数学证明和安全审计交给 Carbon;而将交互式编码、日常功能开发和需要快速反馈的生产循环留在 Argon 上。我们的 Gemini 4 Carbon 与 Argon 对比做了更深入的拆解;如果你正在将 Carbon 与 Anthropic 的最新模型做权衡,可参考 Gemini 4 Carbon 对比 Claude Fable 5.2 以及 Claude Fable 5.2 API 指南。

单次 Gemini 4 Carbon API 调用成本是多少?

根据 Google 官方定价,在 2026 年 11 月 30 日之前,Gemini 4 Carbon 为每百万输入 token $2、每百万输出 token(含思考)$10;12 月 1 日起恢复为 $4 与 $20。

为了直观换算到单次调用,假设有一条包含 2,000 输入 token、6,000 思考 token 和 1,500 输出 token 的请求(注:以下为算术示例数字,并非实测记录):

  • 输入:2,000 x $2 / 1M = $0.004
  • 思考 + 输出:7,500 x $10 / 1M = $0.075
  • 总计:目前约为 $0.079,12 月 1 日起约为 $0.158

不同提示词触发的思考 token 数量差异极大,因此请务必读取你自己的 usage 对象。完整的价格计算、12 月涨价影响及单任务成本对比可查看 Gemini 4 Carbon 定价解析。

让你的编码 Agent 用 Apifox CLI 测试 Carbon API

在调优过程中,你会反复修改思考等级、输出上限和提示词。与其每次改完都靠肉眼去盯 JSON 响应,不如让你的编码 Agent(Claude Code、Codex、Cursor)配合 Apifox CLI 编写一条可重复运行的自动化测试。

先安装 CLI 并完成登录:

npm install -g apifox-cli@latest
apifox auth login --with-token <YOUR_APIFOX_TOKEN>
apifox test-case category --project <PROJECT_ID>

然后给你的 Agent 发送一条提示词:

In Apifox project <PROJECT_ID>, create a test case for
POST https://generativelanguage.googleapis.com/v1beta/interactions
with the x-goog-api-key header read from the GEMINI_API_KEY variable in
environment <ENV_ID>. Send model "gemini-4-carbon",
a short prompt and thinking_level "low", and assert: HTTP 200, status is
"completed", usage.total_thought_tokens exists, and usage.total_tokens is
below 20000. Validate the CLI schema, run it and summarize any failures.

在测试中使用 low 档位可以让每次回归运行的成本保持在最低水平。Agent 会读取 schema、校验 payload 并运行用例(以下命令参数均对照 Apifox CLI 2.2.12):

apifox test-case category --project <PROJECT_ID>
apifox cli-schema get test-case-create
apifox cli-schema validate test-case-create --file case.json
apifox test-case create --project <PROJECT_ID> --file case.json
apifox test-case run <CASE_ID> --project <PROJECT_ID> -e <ENV_ID> -r cli,json
工作流示意图:开发者编写一条提示词,编码 Agent 运行 Apifox CLI 的 cli-schema、test-case create 与 run 命令调用 Gemini 4 Carbon Interactions 端点,并汇总输出测试通过或失败报告

其中针对 token 预算的断言非常实用:如果某次提示词改动导致思考 token 暴涨并突破了你设定的阈值,测试就会在账单失控前直接报错拦截。把 -r cli,json 换成 -r junit,同一条命令就能直接放进 CI 流水线中运行。

常见问题

Gemini 4 Carbon API 是免费的吗? 不是。Google 文档明确指出 Gemini 4 Carbon 不在 Gemini API 的免费层级中提供。你需要一个绑定了 Cloud Billing 且预充值至少 $5 的付费层级项目。在个人消费端,Google 正在向 Gemini 应用、AI 模式和 Antigravity 中的 Google AI Ultra 订户逐步开放 Carbon。

Vertex AI 上可以使用 Gemini 4 Carbon 吗? Google 的发布公告点名了 Gemini API、Google AI Studio、Android Studio、Gemini 企业版、Antigravity 和 CodeMender,并未提及 Vertex AI,因此在基于 Vertex AI 做排期前请先核对 Google Cloud 的模型列表。

Gemini 4 Carbon 的上下文窗口是多大? 1,048,576 tokens,由输入、思考和输出共同分享。单次同步响应上限为 65,536 tokens;开启后台执行(background execution)后,单次响应最高可运行至 1M tokens 减去你的输入长度。

我可以使用 generateContent 代替 Interactions API 吗? Google 的 Carbon 快速入门使用的是 Interactions API,同时其文档在客户端超长解码续写场景中提到了 GenerateContent API。如果你的现有应用已经在使用 generateContent,建议在全面迁移前先实测直接替换模型 ID 是否可用。

如何从 Gemini 4 Argon 切换到 Carbon? 将模型字符串从 gemini-4-argon 改为 gemini-4-carbon 即可。Google 表示无需修改请求结构。由于 Carbon 思考耗时更长,建议同步调高 max_output_tokens 和 HTTP 超时时间,并在非必要时将 thinking_level 保持在 medium。