Claude Opus 4.7 — API 使用指南

本页面介绍 Opus 4.7（模型标识：claude-opus-4-7）的主要破坏性变更、迁移建议与示例代码。请在将请求从 Opus 4.6 升级到 4.7 时参照下面的要点。

重要破坏性变更（从 Opus 4.6 → 4.7）

1. 采样参数移除（会导致 400 错误）

   • temperature、top_p、top_k 在 Opus 4.7 中被移除。向 4.7 传入这些字段会返回 HTTP 400。迁移时必须从请求体中删除这些字段。

2. budget_tokens 完全移除

   • 旧版中可能通过 thinking:{type:"enabled",budget_tokens:N} 控制预算；在 4.7 上此字段不再适用，提交将返回 400。请使用 thinking:{type:"adaptive"}。注意：在 4.6 上可能作为过渡保留的 budget_tokens 逃生通道，在 4.7 上不可用。

3. Assistant prefill（助手预填）被移除

   • 将最后一条 assistant 消息当作 prefill 的做法在 4.7 上会返回 400。请改用 output_config.format（结构化输出）或把必要的上下文放入 system 提示中。

4. Thinking 内容默认隐藏（静默变化）

   • thinking 块仍然会流式输出事件，但文本会默认为空（被省略/omitted）。要在 4.7 中看到思考内容，必须显式设置 thinking:{type:"adaptive",display:"summarized"}。默认 display 为 omitted，虽然不会报错，但在 UI 上会给人“长时间停顿”的错觉。

缓存与前缀规则（Opus 4.7）

• 最小可缓存前缀：4096 tokens。少于该长度时会静默不缓存。
• 缓存命中规则：严格前缀匹配（任何字节级变化都会使后续缓存失效）。
• 渲染顺序影响缓存：tools 与 system messages 顺序会影响断点；在最后一个 system 块作为断点，可同时缓存 tools + system 内容。
• 每个请求最多允许 4 个断点。

常见导致静默失效的坑：

• 在 system prompt 中动态插入 datetime.now() 或其他非确定性内容。每次不同都会导致缓存失效。
• 使用 json.dumps() 生成 system/tool payload，未加 sort_keys=True 会导致字节顺序不稳定。
• 中途修改 tools 列表或切换模型都会使缓存全部失效。

验证是否命中缓存：查看响应中的 usage.cache_read_input_tokens 字段，长期为 0 表示存在导致静默失效的因素。

迁移示例

错误示例（Opus 4.6 风格，在 4.7 上会触发 400）：

# 旧写法（Opus 4.6）—— 在 4.7 上会返回 400
message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    temperature=0.7,
    top_p=0.9,
    messages=[...],
    thinking={"type":"enabled","budget_tokens":10000},
)

正确写法（Opus 4.7）：

# 新写法（Opus 4.7）
message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    output_config={"effort":"xhigh"},
    messages=[...],
    thinking={"type":"adaptive","display":"summarized"},
)

JavaScript 示例（旧 → 新）：

// 旧（4.6，错误）
await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 16000,
  temperature: 0.7, // 在 4.7 上不可用，会导致 400
  messages: [...],
  thinking: { type: "enabled", budget_tokens: 10000 }, // 不可用
});

// 新（4.7，正确）
await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 16000,
  output_config: { effort: "xhigh", format: "json" },
  messages: [...],
  thinking: { type: "adaptive", display: "summarized" },
});

Assistant prefill: 推荐替代方案

• 如果您之前依赖于最后一条 assistant 消息作为预填，请改为：
  • 将必要的结构化输出约束写入 output_config.format 或 output_config.json_schema，或
  • 把上下文/约束放入 system 提示（注意避免动态、不稳定的内容以免缓存失效）。

示例（使用 output_config 要求 JSON 输出）：

{
  "model": "claude-opus-4-7",
  "max_tokens": 1024,
  "messages": [{"role":"user","content":"请按 schema 返回结果"}],
  "output_config": {
    "format": "json",
    "json_schema": {"type":"object","properties":{"summary":{"type":"string"}}}
  }
}

额外提示

• 升级前请在测试环境中批量校验：搜索并移除 temperature、top_p、top_k、budget_tokens 字段，并验证流式 thinking 行为。
• 注意 Opus 4.7 的最小缓存前缀与缓存命中规则，调整 system/tool 的组织方式以提高缓存命中率。

---