DEV Community

Cover image for How to Use the GPT-6.1 Terra API?
Hassann
Hassann

Posted on Originally published at apidog.com

How to Use the GPT-6.1 Terra API?

如何使用 GPT-6.1 Terra API？

GPT-6.1 Terra 于 2026 年 10 月 26 日起在 OpenAI API 上以 gpt-6.1-terra 的名称提供。它支持 Responses API、Chat Completions 和 Batch，价格为每百万输入 token 1 美元、每百万输出 token 5 美元，最多可接受 922,000 个输入 token 和 128,000 个输出 token。如果你已经在使用 GPT-5.6 Terra，那么切换基本上只需要修改一行 model ID，但有几个设置值得先检查一下。

Try Apidog today

本指南涵盖了如何获取 API key、用 curl、Python 和 Node 发送你的第一个请求、六个 reasoning effort 级别、computer use 以及其他工具、成本控制，以及从 gpt-5.6-terra 迁移时需要测试的内容。关于模型的概述，请参阅 什么是 GPT-6.1 Terra。

API 支持的功能

功能 GPT-6.1 Terra
模型 ID gpt-6.1-terra (单个快照)
接口端点 Responses, Chat Completions, Batch
不支持 Realtime, Live, Assistants, fine-tuning, predicted outputs
输入 文本和图像
输出 文本
上下文窗口 1,050,000 tokens (922,000 输入, 128,000 输出)
Reasoning effort none, low, medium (默认), high, xhigh, max
特性 流式传输、结构化输出、函数调用、提示词缓存
工具（仅限 Responses） web_search, file_search, computer_use, code_interpreter, hosted_shell, apply_patch, skills, mcp, tool_search, image_generation

来源：OpenAI 的 GPT-6.1 Terra 模型页面。托管工具（Hosted tools）需要使用 Responses API，因此在进行新开发时请使用该 API。

GPT-6.1 Terra API 功能

第一步：获取 API key

在 OpenAI 平台控制台中创建一个 API key 并添加账单信息。Terra 没有免费层级：订阅 ChatGPT Plus 或 Pro 计划可以让你在 ChatGPT Work 和 Codex 中使用 Terra，但无法获得 API key。我们的指南 GPT-6.1 Terra 是否免费 解释了其中的区别。

将其导出（export），以便后续示例可以读取它：

export OPENAI_API_KEY="sk-..."
Enter fullscreen mode Exit fullscreen mode

速率限制取决于你的使用层级。模型页面列出了 Build 层级为每分钟 5,000 次请求和 100 万个 token，Launch 层级为每分钟 10,000 次和 400 万个，Grow 层级为每分钟 15,000 次和 4000 万个。

第二步：发送你的第一个请求

使用 curl，通过 Responses API：

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-terra",
    "reasoning": { "effort": "low" },
    "input": "Summarize the difference between PUT and PATCH in two sentences."
  }'
Enter fullscreen mode Exit fullscreen mode

使用官方 SDK 的 Python 示例：

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.1-terra",
    reasoning={"effort": "low"},
    input="Summarize the difference between PUT and PATCH in two sentences.",
)

print(response.output_text)
print(response.usage)
Enter fullscreen mode Exit fullscreen mode

Node 版本：

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6.1-terra",
  reasoning: { effort: "low" },
  input: "Summarize the difference between PUT and PATCH in two sentences.",
});

console.log(response.output_text);
console.log(response.usage);
Enter fullscreen mode Exit fullscreen mode

从一开始就打印 usage。它会告诉你输入、缓存和输出的 token 数量，而且 reasoning token 会按输出进行计费。

第三步：选择 Reasoning Effort 级别

Terra 支持六个 effort 级别。默认值为 medium。

Effort 级别 适用场景
none 分类、提取、格式化；确定性输出
low 简短回答、简单的工具调用、大多数聊天式工作
medium 默认值；通用编程和 Agent 步骤
high / xhigh 较难的多步推理
max 基准测试设置；最复杂的任务，最慢且最贵

有两点非常突出。

支持 none。 GPT-6.1 Sol 移除了该级别，因此这是两者之间实际差异之一。OpenAI 社区论坛上的一位开发者报告称，当设置 reasoning.effort: "none" 时，Terra 可以再次接受 temperature 和 top_p。对于需要大量进行数据标注或提取的流水线，none 可以提供最低的单次调用成本和可重复的输出。

Low effort 提升最大。 在 OpenAI 的内部事实准确性测试中，Terra 在 low effort 下的错误率从 GPT-5.6 Terra 的 53.6% 降至 16.7%。Artificial Analysis 还测得，与 GPT-5.6 Terra 相比，在较低 effort 级别上的提升（7 到 13 个百分点）大于在 max 级别上的提升（6 个百分点）。如果你在 GPT-5.6 Terra 上使用 high 以获得可接受的质量，在切换到 6.1 Terra 时，请先尝试 low 或 medium，而不要想当然地认为需要相同的设置。

第四步：使用工具，包括 Computer Use

OpenAI 在本次发布中重点宣传了“以更低的价格实现快速且强大的 computer use”。Computer use、网页搜索、文件搜索以及其他托管工具均可在 Responses API 上使用。网页搜索调用如下所示：

response = client.responses.create(
    model="gpt-6.1-terra",
    reasoning={"effort": "low"},
    tools=[{"type": "web_search"}],
    input="What changed in the latest OpenAPI Specification release?",
)
print(response.output_text)
Enter fullscreen mode Exit fullscreen mode

函数调用和结构化输出（structured outputs）的工作方式与其他 GPT-6 模型相同：在 tools 中定义函数 schema，或者在文本格式设置中传入 JSON schema，并验证返回的结果。要更深入地了解针对真实应用的 computer use，我们的 GPT-6 Astra computer use 指南 也适用于 Terra，且价格仅为 Astra 每 token 价格的十分之一。

第五步：控制成本

Terra 的费率已经很低了，以下四个设置可以进一步降低成本：

  • 提示词缓存（Prompt caching） 是自动的。缓存后的输入价格为每百万 0.05 美元，而全新输入为 1 美元。将稳定的内容（系统提示词、工具 schema、参考文档）放在提示词的前面。缓存写入的价格为每百万 1.25 美元（30 分钟保留期），或 2.50 美元（12 小时保留期）。请参阅我们的 GPT-6 提示词缓存指南。
  • Batch 将异步任务的所有费率减半：输入 0.50 美元，输出 2.50 美元。我们的 OpenAI Batch API 指南 展示了完整流程。
  • Flex 可以通过 service_tier: "flex" 在常规请求中提供相同的半价费率，代价是响应变慢并偶尔出现 429 错误。
  • 272K 门槛。 超过 272K 输入 token 的提示词会按 2 倍的输入和缓存费率以及 1.5 倍的输出费率对整个请求进行计费。如果你即将达到该阈值，请删减检索到的上下文，避免超过该门槛。

快速模式（Fast mode）则恰恰相反：以 2 倍的标准费率（输入 2 美元，输出 10 美元）换取更快的响应速度。GPT-6.1 Terra 定价指南 在一张表格中列出了所有费率。

GPT-6.1 Terra 定价

从 gpt-5.6-terra 迁移

模型 ID 的修改只有一行。以下是需要围绕它进行检查的事项：

  1. 价格。 输入从 2 美元降至 1 美元，缓存输入从 0.20 美元降至 0.05 美元，输出从 12 美元降至 5 美元。更新任何硬编码费率的成本仪表盘或预算警报。
  2. Effort 设置。 在较低的 effort 级别重新测试。low 级别的质量提升最为显著。
  3. 知识截止日期。 Terra 的知识截止日期为 2026 年 6 月 1 日。假设使用较旧截止日期的提示词，或具有日期敏感预期答案的测试，可能会发生变化。
  4. 输出长度和格式。 新模型可能会写出更长或更短的回答。检查 usage.output_tokens 以及任何期望固定格式的解析器；在格式关键的场景下请使用结构化输出。
  5. 速度。 OpenAI 表示，Terra 完成任务的平均速度比 Astra 和 GPT-6.1 Sol 快 3 倍以上。针对较慢模型微调的超时设置没有问题，但围绕长时间等待构建的重试和轮询逻辑现在可能会造成浪费。
  6. Codex。 如果你的团队使用 Codex，Terra 需要 Codex CLI 0.159.0 或更高版本：codex -m gpt-6.1-terra。

OpenAI 尚未公布 GPT-5.6 Terra 的弃用日期，因此你可以在进行比较时同时运行这两个模型。

让你的编程 Agent 使用 Apidog CLI 验证迁移

第 1 到 6 步正是你不应该手动去做的检查。将你的编程 Agent 指向 Apidog CLI，它可以构建测试、在两个模型上运行它，并告诉你发生了什么变化。

只需设置一次：

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
Enter fullscreen mode Exit fullscreen mode

然后给 Claude Code、Codex 或 Cursor 一个提示词：

In Apidog project <id>, add POST https://api.openai.com/v1/responses as an endpoint.
Create a test case that sends my production prompt with model {{MODEL}} and reasoning
effort low, and asserts: status 200, output_text not empty, output matches our JSON
schema, usage.output_tokens under 3000. Run it with MODEL=gpt-5.6-terra and again with
MODEL=gpt-6.1-terra against the <env> environment, then compare tokens and failures.
Enter fullscreen mode Exit fullscreen mode

Agent 会读取每个 schema，验证其负载（payload）并运行两次测试用例：

apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "MODEL=gpt-5.6-terra" -r cli,json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "MODEL=gpt-6.1-terra" -r cli,json
Enter fullscreen mode Exit fullscreen mode

将你的 OpenAI key 保存在 Apidog 环境中。当 Terra 测试通过后，使用 -r junit 将其添加到 CI 中，这样后续的提示词或模型变更就不会静默地破坏契约；我们的 Apidog CLI CI/CD 指南 提供了流水线文件，Apidog CLI in Codex 介绍了 Codex 的配置。

常见问题（FAQ）

什么是 GPT-6.1 Terra 模型 ID？ gpt-6.1-terra。它只有一个快照，同时也是默认值。

GPT-6.1 Terra 是否支持 Chat Completions？ 是的。它支持 Responses、Chat Completions 和 Batch。诸如网页搜索和 computer use 等托管工具需要使用 Responses API。

我可以为 GPT-6.1 Terra 设置 temperature 吗？ 一份社区报告指出，当设置 reasoning.effort: "none" 时是可以的。在其他 effort 级别下，在发送采样设置之前请先查看模型页面。

GPT-6.1 Terra 是否支持 Realtime API？ 不支持。不支持 Realtime、Live、Assistants 和 fine-tuning。

GPT-6.1 Terra 的速率限制是多少？ 这取决于你的层级：从 Build 层级的每分钟 5,000 次请求和 100 万个 token，到 Grow 层级的每分钟 15,000 次和 4000 万个 token 不等。

下一步

在一个端点上替换模型 ID，在较低的 effort 级别重新测试，并让你的 Agent 使用 Apidog CLI 对比两次运行结果。如果数据表现依然良好，就可以全面推广。不确定 Terra 还是 Sol 更适合你的工作负载？请阅读 GPT-6.1 Terra vs GPT-6.1 Sol。

Top comments (0)