# Gemini 4 Carbon 新特性

Gemini 4 Carbon (`gemini-4-carbon`）是我们最强大的推理模型，专为跨复杂软件工程、多模态知识工作、科学推理和网络安全防御的持续智能体工作流程而构建。在难题上，Carbon 会花更多的时间思考 token 来探索假设、验证其工作并在响应之前检查边缘情况。

Gemini 4 Carbon 可在 Gemini API 的付费层和 Google AI Studio 中使用。喜欢 [Gemini 4 Argon](/docs/whats-new-gemini-4-argon)，支持统一的1M-token 上下文窗口，长解码可达1M token，思维级别可调（`low`, `medium`, `high`）以相同的每 token 价格。

{% card-grid %}
{% card
   description="查看 token 限制、支持的功能和完整规格。"
   href="/docs/models/gemini-4-carbon"
   icon="id_card"
   title="模型详情" /%}

{% card
   description="使用 Gemini 4 Carbon 构建和验证全栈 Web 和 3D 应用程序。"
   href="https://aistudio.google.com/apps?model=gemini-4-carbon"
   icon="experiment"
   title="在 AI Studio 中构建" /%}

{% card
   description="阅读 Gemini 4 Carbon 的实用提示和多智能体模式。"
   href="https://aistudio.google.com/learn/gemini-4-carbon-developer-guide"
   icon="rocket_launch"
   title="开发者指南" /%}
{% /card-grid %}

本指南介绍了 Gemini 4 Carbon 的新增功能、如何在碳和氩之间进行选择、API 更改、代码示例和迁移指南。

## 新型号  {% #new-model %}

| 模型              | 型号编号              | 默认思维水平   | 价格                                                                                                              | 说明                                           |
| --------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Gemini 4 Carbon | `gemini-4-carbon` | `medium` | 30, 2026 于 11 月上市，以 $2/1M 输入 token 和 $10/1M 输出 token 的促销价提供（$4/1M 输入，随后 $20/1M 输出）。参见 [定价](/docs/pricing) 了解详情。 | 我们最强大的推理模型，专为持续智能体编码、多模态知识工作、科学发现和网络安全防御而构建。 |

有关完整详细信息，请参阅 [Gemini 4 Carbon 型号页面](/docs/models/gemini-4-carbon) 和 [最新 Gemini 模型](/docs/latest-model)。有关介绍性定价的详细信息，请参阅 [定价部分](/docs/whats-new-gemini-4-carbon#pricing) 在此页面或 [定价页面](/docs/pricing#gemini-4-carbon).

## 快速入门  {% #quickstart %}

使用以下示例将请求发送到 `gemini-4-carbon` 使用推荐的默认值 `thinking_level` (`medium`）和 64K 输出 token 限制：

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a three.js script that renders a realistic 3D black hole with gravitational lensing."
)

print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-4-carbon",
  input: "Write a three.js script that renders a realistic 3D black hole with gravitational lensing.",
});

console.log(interaction.output_text);
```
{% /tab %}

{% tab label="REST" %}
```bash
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-4-carbon",
    "input": "Write a three.js script that renders a realistic 3D black hole with gravitational lensing."
  }'
```
{% /tab %}
{% /tabs %}

## Gemini 4 Carbon 新特性  {% #whats-new-gemini-4-carbon %}

* **扩展验证和智能体编码：** 跨复杂存储库、前端 UI 设计和 3D 场景运行更深入的构建和验证循环，隔离根本原因并根据测试检查修复。
* **多模态知识工作的更高精确度：** 更强大的源事实依据，在密集的 PDF、电子表格、幻灯片和工作区数据中减少不受支持的声明，并严格遵守输出模式。
* **科学和网络安全推理：** 改进了形式证明、实验数据分析、漏洞发现和根本原因修补的性能。
* **统一1M 上下文窗口和长解码：** 输入、思考和输出 token 共享一个 1,048,576-token 窗口，并且单个响应现在可以超过 64K token，最多为 1M token 减去您的输入。参见 [长输出](/docs/long-decode).
* **托管智能体支持：** 该 [Antigravity 智能体](/docs/antigravity-agent) 在 Gemini 托管智能体现在支持 `gemini-4-carbon`.

## 在碳、氩和其他型号之间进行选择  {% #choosing-between-models %}

Gemini 4 Carbon 和 [Gemini 4 Argon](/docs/whats-new-gemini-4-argon) 共享相同的 1M 统一上下文窗口、内置工具和每个 token 定价。主要区别在于每个模型每回合花费多少思考 token：

* **Gemini 4 Carbon (`gemini-4-carbon`):** 专为突破推理深度极限的任务而设计。 Carbon 每回合花费更多的时间思考 token 来彻底探索并验证其工作，与 Argon 相比，这增加了每回合 token 的使用和延迟。使用它进行复杂的根本原因调试、架构设计、密集多模态综合、科学证明和安全审计。
* **Gemini 4 Argon (`gemini-4-argon`):** 我们高效的 Gemini 4 前沿推理模型，非常适合最先进的软件工程和知识工作任务。与 Carbon 相比，它在交互式编码、日常功能工作和快速生产循环方面提供了 Gemini 4 智能，具有更快的响应速度和更低的 token 每回合支出。

有关模型选择的更多指导，请参见 [最新 Gemini 模型](/docs/latest-model#compare-models).

## 了解思维层次  {% #understanding-thinking-levels %}

该 [思维水平](/docs/thinking) 是您对质量、延迟和 token 在 Gemini 4 Carbon 中使用的主要控制：

| 思维层面          | 代币使用                | 何时使用                                            |
| ------------- | ------------------- | ----------------------------------------------- |
| `low`         | 最少的token，最低的延迟      | 更简单的任务和成本敏感的工作。也适用于需要轻松思考的分析和写作任务。艰巨的任务质量可能会下降。 |
| `medium` （默认） | 平衡                  | 推荐用于大多数任务，包括复杂的代码和智能体用例。                        |
| `high`        | 最多 token，最慢的先 token | 复杂的推理、困难的数学和科学，以及最困难的代码或智能体任务。与长输出的长解码完美搭配。     |

在所有三个级别上进行评估，然后选择符合您的质量标准的最低级别。要了解更多信息，请参阅 [思维指南](/docs/thinking).

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely.",
    generation_config={
        "thinking_level": "medium"  # Balanced reasoning effort for complex tasks
    }
)

print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  model: "gemini-4-carbon",
  input: "Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely.",
  generation_config: {
    thinking_level: "medium", // Balanced reasoning effort for complex tasks
  },
});

console.log(interaction.output_text);
```
{% /tab %}

{% tab label="REST" %}
```bash
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-4-carbon",
    "input": "Analyze this payment processing pipeline for race conditions during retry attempts and rewrite the transaction locks safely.",
    "generation_config": {
      "thinking_level": "medium"
    }
  }'
```
{% /tab %}
{% /tabs %}

## 更大的输出和更长的解码  {% #long-decode %}

Gemini 4 Carbon 可以在数学、科学和编码问题上思考更长时间。

* **使用 `thinking_level` 控制推理深度：** `thinking_level` 设置模型在回答之前推理的深度。 `max_output_tokens` 限制您的综合思维和输出 token。一旦思考加上输出命中，响应就会停止 `max_output_tokens`，因此将其设置得足够高，为最终答案留出空间。
* **通过后台执行生成过去的 64K token：** 标准同步响应停止于 65,536 token。要生成更长的响应，请设置 `background=True` 并提高 `max_output_tokens` 高于 65,536（直到统一的 1M-token 上下文窗口，减去您输入的 token）。我们的服务器为您生成 64K-token 连续跃点的响应。每跳添加一个 `model_output` 迈向 `interaction.steps`，因此将所有文本连接起来 `model_output` 交互完成时的步骤。

{% tabs %}
{% tab label="Python" %}
```python
import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete, rigorous proof of the prime number theorem.",
    background=True,
    generation_config={
        "max_output_tokens": 262144,
        "thinking_level": "high",
    },
)

while interaction.status in ("in_progress", "queued"):
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

# Each hop adds a model_output step, so join the text of all of them.
text = "".join(
    content.text
    for step in interaction.steps
    if step.type == "model_output"
    for content in step.content
    if content.type == "text"
)
print(text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
  model: "gemini-4-carbon",
  input: "Write a complete, rigorous proof of the prime number theorem.",
  background: true,
  generation_config: {
    max_output_tokens: 262144,
    thinking_level: "high",
  },
});

while (interaction.status === "in_progress" || interaction.status === "queued") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await client.interactions.get(interaction.id);
}

// Each hop adds a model_output step, so join the text of all of them.
const text = interaction.steps
  .filter((step) => step.type === "model_output")
  .flatMap((step) => step.content ?? [])
  .filter((content) => content.type === "text")
  .map((content) => content.text)
  .join("");
console.log(text);
console.log("Status:", interaction.status);
console.log("Usage:", interaction.usage);
```
{% /tab %}

{% tab label="REST" %}
```bash
ID=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-carbon",
    "input": "Write a complete, rigorous proof of the prime number theorem.",
    "background": true,
    "generation_config": {
      "max_output_tokens": 262144,
      "thinking_level": "high"
    }
  }' | jq -r '.id')

while true; do
  RESP=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$ID" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status')
  if [[ "$STATUS" != "in_progress" && "$STATUS" != "queued" ]]; then
    echo "$RESP" | jq -r '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
    break
  fi
  sleep 5
done
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
如果你设置 `background: true` 没有定义 `max_output_tokens`，服务器在 64K token 之后停止。
{% /callout %}

后台执行是运行长解码的推荐方法。它在服务器端运行连续循环，直到模型完成或达到 `max_output_tokens`。如果您需要对重试、退避和错误处理进行更细粒度的控制（或者不希望存储交互），您可以在 [Interactions API](/docs/long-decode#client-side-continuation) 或 [生成内容 API](/docs/long-decode?generate-content=true)。有关流式传输、重新连接、token 计数以及何时使用长解码的信息，请参阅 [长解码指南](/docs/long-decode).

### 设置输出 token 限制  {% #setting-output-token-limits %}

`max_output_tokens` 设置响应的最大组合思维和输出 token。将其设置得足够高，以便思考不会缩短答案，并将其设置得足够低，以便在硬提示用完所有答案时限制支出。

使用这些值作为起点：

* **标准任务：** 保留默认值 65,536 或不设置任何值。
* **限制低于 32K 的现有应用程序：** 提高 `max_output_tokens` 至少32,768. Gemini 4 Carbon可以比早期型号花费更多的思考极限。要少用token，就降低思维层次。
* **复杂的推理和编码：** 套装 `background: true` 并设置 `max_output_tokens` 到 131,072 或 262,144, 直至 1,048,576 减去您的输入 token。

## Gemini 4 Carbon 中的托管智能体  {% #managed-agents %}

该 [Antigravity 智能体](/docs/antigravity-agent) 在Gemini 托管智能体支持Gemini 4 Carbon。要使用它，请将模型设置为 `agent_config`:

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input=(
        "Audit https://web.dev for performance, Core Web Vitals, and SEO. "
        "Query Google's PageSpeed Insights API for both Mobile and Desktop strategies. "
        "Check search indexing with Google Search for site:web.dev. "
        "Format the output as a side-by-side scorecard table with prioritized fixes."
    ),
    environment="remote",
    agent_config={
        "type": "antigravity",
        "model": "gemini-4-carbon",
    },
)

print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  agent: "antigravity-preview-09-2026",
  input:
    "Audit https://web.dev for performance, Core Web Vitals, and SEO. " +
    "Query Google's PageSpeed Insights API for both Mobile and Desktop strategies. " +
    "Check search indexing with Google Search for site:web.dev. " +
    "Format the output as a side-by-side scorecard table with prioritized fixes.",
  environment: "remote",
  agent_config: {
    type: "antigravity",
    model: "gemini-4-carbon",
  },
}, { timeout: 300000 });

console.log(interaction.output_text);
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "agent": "antigravity-preview-09-2026",
    "input": "Audit https://web.dev for performance, Core Web Vitals, and SEO. Query Google'\''s PageSpeed Insights API for both Mobile and Desktop strategies. Check search indexing with Google Search for site:web.dev. Format the output as a side-by-side scorecard table with prioritized fixes.",
    "environment": "remote",
    "agent_config": {
      "type": "antigravity",
      "model": "gemini-4-carbon"
    }
  }'
```
{% /tab %}
{% /tabs %}

有关更多选项，请参阅 [选型](/docs/antigravity-agent#model-selection) 在 Antigravity 智能体指南中。

## 迁移清单  {% #migration-checklist %}

{% callout type="note" %}
使用编码智能体自动执行此迁移。如果您使用支持技能的编码智能体（如 Antigravity），请安装 [gemini-api-dev技能](/docs/coding-agents#gemini-api-dev) 并运行：

```none
/gemini-api-dev migrate my app to Gemini 4 Carbon
```
{% /callout %}

### Migrate from Gemini 4 Argon  {% #migrate-from-gemini-4-argon %}

如果你已经跑了 `gemini-4-argon`，升级到 `gemini-4-carbon` requires no request schema changes:

* **更新型号ID：** 更改您的模型字符串 `gemini-4-argon` 到 `gemini-4-carbon`.
* **Account for longer thinking:** 在复杂任务上，碳每回合比氩花费更多的思考 token。保留 `thinking_level` 在 `medium` (default) unless a workload needs `high`，并确保您的 `max_output_tokens` HTTP 超时允许更长的推理过程。
* **Keep Argon where speed matters:** 保留 [`gemini-4-argon`](/docs/whats-new-gemini-4-argon) 与 Carbon 相比，您希望在交互式编码、日常功能工作和快速生产循环方面获得更快的响应和更低的 token 每回合支出。

### Migrate from Gemini 3 and earlier  {% #migrate-to-gemini-4-carbon %}

* **更新型号ID：** Change your target model string to `gemini-4-carbon`.
* **评论 `max_output_tokens`:** 如果您今天明确设置了它，请考虑提出它。我们推荐至少 32,768,，因为 Gemini 4 Carbon 可以在思考上花费更多的限制。
* **配置思维层次：** 选择 `low`, `medium` （默认），或 `high`，并测试您在这三个方面的工作量。
* **Move off explicit 上下文缓存:** 显式缓存（`cachedContents` / `caches.create`) is not supported on Gemini 4 Carbon. Remove calls that create or reference `cached_content` 来自您的要求。 [隐式缓存](/docs/caching) 默认情况下启用至少 4,096 token 的提示，并在缓存命中时将缓存输入 token 折扣 95%。
* **Remove sampling parameters:** 删除 `temperature`, `top_p`, 和 `top_k` 来自您的要求。如果提供，它们将被忽略。
* **对长输出使用后台执行：** 对于需要 64K token 以上的任务，设置 `background` 为真且 `max_output_tokens` 大于 65,536.
* **增加客户端超时：** 硬提示可能需要几分钟的时间。使用后台执行，或将 HTTP 客户端超时设置为至少 15 分钟。
* **在服务器上保留对话状态：** 使用 `previous_interaction_id` 用于多轮和函数调用对话。
* **检查您的成本估算：** 模型处理的每个 token 都会计费，包括使用事实依据时的内部工具系统指令和函数声明（请参阅 [价格](/docs/whats-new-gemini-4-carbon#pricing)).

## 价格  {% #pricing %}

Gemini 4 Carbon 于 11 月之前以促销价发售 30, 2026：

* **输入token：** $2.00 根据 1M token（$4.00 从 12 月开始 1, 2026）*   **缓存输入 token：** 隐式缓存将每 1M token 的缓存输入折扣 95% 至 $0.10（$0.20 从 12 月开始 1, 2026）。

* **输出token，包括思考token：** $10.00 与 1M token（$20.00 从 12 月开始 1, 2026）

模型处理的每一个token都会被统计和计费，包括思考token和使用事实依据时的内部工具系统指令和函数声明。 事实依据和 Google 搜索也仍按查询计费。

Gemini 4 Carbon 在免费套餐中不可用。有关完整的定价等级，请参阅 [定价页面](/docs/pricing#gemini-4-carbon).

## 其他型号  {% #other-models %}

* [最新 Gemini 模型](/docs/latest-model)
* [Gemini 4 Hydrogen](/docs/whats-new-gemini-4-hydrogen)
* [Gemini 4 Argon](/docs/whats-new-gemini-4-argon)
* [Gemini 3.8 Flash](/docs/whats-new-gemini-3.8)
* [Gemini 3.6 Flash 和 3.5 Flash-Lite](/docs/whats-new-gemini-3.6)
* [查看所有型号](/docs/models)

## 后续步骤  {% #whats-next %}

* 阅读 [Gemini 4 Carbon 开发者指南](https://aistudio.google.com/learn/gemini-4-carbon-developer-guide) 用于提示和多智能体模式。
* 阅读 [长解码指南](/docs/long-decode) 用于流式传输、重新连接和 token 计数。
* 了解思维水平和思维总结如何在 [思维指南](/docs/thinking).
* 了解长期运行的作业 [后台执行引导](/docs/background-execution).
* 处理 Word、PowerPoint 和 Excel 文件 [文档理解指南](/docs/document-processing#office-documents).
* 测试并完善提示 [Google AI Studio](https://aistudio.google.com/prompts/new_chat?model=gemini-4-carbon).
