如何使用 Claude Sonnet 5.5 API：首次调用、effort、思考、工具与流式输出

要使用 Claude Sonnet 5.5 API，请向 https://api.anthropic.com/v1/messages 发送 POST 请求，带上 "model": "claude-sonnet-5-5"，把密钥放进 x-api-key header，并加上 anthropic-version: 2023-06-01。它的价格是每百万输入 token $2、每百万输出 token $10，最多可读取 100 万 token 的上下文、输出 128K，默认运行自适应思考，默认 effort 为 high。

Anthropic 于 2026 年 9 月 28 日发布 Sonnet 5.5（什么是 Claude Sonnet 5.5 一文介绍了规格与基准测试）。本指南会带你完成 curl、Python 和 TypeScript 的首次调用，然后讲解 effort、thinking、工具、流式、拒答和速率限制。正在迁移 Sonnet 5 代码？Sonnet 5.5 vs Sonnet 5 指南给出了每一项破坏性变更及修改前后的 JSON。下面每个请求都可以在 Apifox 中发送，并保存为带断言的测试。

Claude Sonnet 5.5 API 一览

来源：Sonnet 5.5 模型页和迁移指南。

Claude Sonnet 5.5 API 示例：你的第一次调用

创建一个密钥（Anthropic API key 指南有完整步骤），并把它导出为 ANTHROPIC_API_KEY，而不是硬编码在代码里。然后发送：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 4096,
    "output_config": {"effort": "medium"},
    "messages": [{"role": "user", "content": "Explain idempotency keys in two sentences."}]
  }'

Python SDK 会从环境中读取 ANTHROPIC_API_KEY：

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Explain idempotency keys in two sentences."}],
)
print(response.stop_reason)
for block in response.content:
    if block.type == "text":
        print(block.text)

TypeScript 的用法相同：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 4096,
  output_config: { effort: "medium" },
  messages: [{ role: "user", content: "Explain idempotency keys in two sentences." }],
});
for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}

请按 type 读取内容块。Thinking 默认开启，因此响应可能以 thinking 块开头，直接读取 content[0].text 的代码会出错。Thinking token 按输出计费，即使其文本被隐藏也计入 max_tokens，所以要在预期回复之外留出余量。

选择 effort 档位

通过 output_config.effort 设置的 effort 是你控制成本与质量的主要旋钮。Anthropic 为 Sonnet 5.5 重新校准了各档位，因此 Sonnet 5 上的设置不能沿用；请在你自己的评测上重新做一次扫描。提示词指南建议了以下起点：

差距很大。在 Anthropic 自己跑的 Terminal-Bench 4.0 中，Sonnet 5.5 在 high 下得分 43.0%，每次尝试 $1.94；在 max 下得分 70.6%，花费 $12.54。Sonnet 5.5 定价拆解详细推演了每次请求的成本。

有三点行为需要提前规划。从 medium 起，模型几乎每次回复前都会思考，哪怕只是一句问候，而靠提示词让它少思考并不可靠：请改为降低 effort。在 low 和 medium 下，它在长时 agentic 任务中容易提前请示确认。另外，在请求之间更改顶层 effort 会使提示词缓存失效。若想在对话中途切换档位并保留缓存，请使用按消息 effort（beta，header 为 anthropic-beta: mid-conversation-output-config-2026-07-01）：添加一条 role: "system" 且 content 为空的消息，并带上新的 output_config.effort。

控制 thinking：adaptive 或 between_tools

省略 thinking 字段，Sonnet 5.5 就会运行自适应思考。它会以 400 拒绝 {"type": "disabled"}。要关闭前置思考，请发送最低档设置 between_tools：

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 16000,
  "thinking": {"type": "between_tools"},
  "output_config": {"effort": "high"},
  "messages": [{"role": "user", "content": "..."}]
}

Sonnet 5.5 between_tools 的规则：

• 它仅在 low、medium 或 high 下可用。在 xhigh 或 max 下会返回 400。
• 它不接受其他字段。添加 display、budget_tokens 或 block_binding 会返回 400。
• 它不需要 beta header，且在所有平台上都可用。
• 设置它之后，effort 无法在对话中途更改。
• 未定义它的 SDK 版本会在类型检查时报错，所以请更新 SDK。

在自适应思考下，display 决定 thinking 块的内容。默认值 omitted 返回的每个 thinking 块都带有一个空的 thinking 字段和一个 signature。summarized 返回可读的摘要。updates（beta，header 为 thinking-display-updates-2026-08-18）只把进度更新作为文本返回。

进度更新是最容易让界面出问题的一项变更。Sonnet 5.5 会把工具调用之间写下的、超过一两句话的说明放进单独的 thinking 块，而不是 text。在默认的 omitted 下这些块是空的，于是过去会叙述自己步骤的 Agent 界面变得一片安静。请设置 display: "updates" 或 "summarized"，或者使用 between_tools，它会以文本返回这些说明。请把每个非空的 thinking 块渲染在紧随其后的 tool_use 块之前。在回复文本中索要推理过程会触发 reasoning_extraction 拒答，所以请改为读取这些块。

在不使用强制 tool_choice 的情况下调用工具

强制工具调用已被移除。tool_choice 为 {"type": "any"} 或 {"type": "tool", ...} 会返回 400 并给出这条信息，在 token 计数接口上也是如此：

tool_choice: type "tool" and "any" are not supported for this model.

请发送 auto，把工具标记为 strict: true 以确保其输入符合数据模型，并在提示词中告诉模型何时调用它：

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "input_schema": {
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"],
      "additionalProperties": false
    },
    "strict": true
  }],
  "tool_choice": {"type": "auto"},
  "messages": [{"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}]
}

一个请求最多可携带 20 个 strict 工具，且 strict 数据模型要求每个 object 都有 additionalProperties: false。在 Amazon Bedrock 上，Sonnet 5.5 不支持 strict 工具：请发送 auto 但不带 strict，并在代码中校验输入。

有两个循环细节很关键。请把每个 thinking 块连同它的 tool_use 块原样回传，空的也要带上。另外要预期偶发的大小写偏差，例如 bash 与声明为 Bash 的工具不匹配。提示词指南建议接受无歧义的匹配，或者返回一个 tool_result，用 is_error: true 说明准确的名称。

流式响应

在 body 中加上 "stream": true，或使用 SDK 的 stream 辅助方法。对于 agentic coding，提示词指南建议把 max_tokens 设为 128,000 并配合流式：

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=128000,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Review this diff for bugs: ..."}],
) as stream:
    for event in stream:
        if event.type == "content_block_delta" and event.delta.type == "text_delta":
            print(event.delta.text, end="", flush=True)
    final = stream.get_final_message()

Server-sent events 依次到达：先是 message_start，然后每个块会有 content_block_start、content_block_delta 和 content_block_stop，接着是 message_delta（携带 stop_reason）和 message_stop。在 omitted 下，thinking 块会流式发出一个空的 thinking_delta 和一个 signature_delta，然后文本才开始。在进度更新块打开之前，预计会有几秒钟的停顿。

stream.get_final_message()（TypeScript：stream.finalMessage()）会重建带签名的完整块。请把该内容原样作为 assistant 回合追加到历史中，并保持历史只追加。Sonnet 5.5 会对每个 thinking 块之前的对话内容签名，因此在 2026 年 8 月 31 日（00:00 UTC）当天或之后创建的账号上，编辑更早的历史后再回放某个块会返回 400。这些块还与其产生的账号绑定。

处理拒答与回退

拒答不是错误。你会得到 HTTP 200，带有 stop_reason: "refusal" 和一个 stop_details object，其 category 为 cyber、bio、frontier_llm、reasoning_extraction 或 general_harms，另外还有 explanation。请展示该说明而不是解析它，因为它的措辞并不稳定。请先根据 stop_reason 分支处理，再去读取 content。

服务端回退需要主动启用。加上 "fallbacks": "default" 和 anthropic-beta: server-side-fallback-2026-07-01 header（beta，仅限 Claude API），API 就会把 cyber 和 frontier_llm 类型的拒答在 Sonnet 5 上重试。其他三类不会重试。响应中的 model 字段会指明实际服务的模型，而 fallback 内容块会标记这次交接。

速率限制

Sonnet 5.5 有独立的速率限制，与 Sonnet 5 分开。速率限制页面列出了四档：

关于 429 的处理与退避，参见 rate limit exceeded 指南。

在 Apifox 中测试 Claude Sonnet 5.5 API

保存下来的请求能让 effort 对比和流式调试变得可重复。在 Apifox 中的设置如下：

1. 创建一个环境，并把 ANTHROPIC_API_KEY 添加为变量。以 {{ANTHROPIC_API_KEY}} 的形式在 x-api-key header 中引用它，放在 anthropic-version 和 content-type 旁边。
2. 创建一个指向 https://api.anthropic.com/v1/messages 的 POST 请求，粘贴首次调用的 body 并保存。
3. 添加断言：状态码为 200，$.stop_reason 等于 end_turn，$.usage.output_tokens 大于 0，且 $.content[*].type 包含 text。这样拒答会让测试失败，而不是静默通过。
4. 复制该请求并加上 "stream": true。Apifox 会逐事件展示 text/event-stream 响应，你可以依次看到空的 thinking_delta、signature_delta 和文本到达。
5. 再克隆一份，把 "model": "claude-sonnet-5" 改回去，并把这一对放在同一个目录中：相同的提示词、两个模型、并排对比 usage。

更通用的模式参见 testing LLM applications 和 testing AI agent APIs。

常见问题

Claude Sonnet 5.5 的模型 ID 是什么？在 Claude API、Google Cloud、Microsoft Foundry 和 Claude Platform on AWS 上是 claude-sonnet-5-5，不带日期后缀。在 Amazon Bedrock 上是 anthropic.claude-sonnet-5-5。

我能把 thinking 完全关掉吗？不能。disabled 会返回 400。between_tools 是最低档：不做前置思考，effort 取 low、medium 或 high。

为什么我的 Sonnet 5 请求在 Sonnet 5.5 上返回 400？请先检查 thinking.type: "disabled" 和强制的 tool_choice。Sonnet 5.5 vs Sonnet 5 指南涵盖了全部五项破坏性变更及其修复方法。

有免费的 Claude Sonnet 5.5 API 吗？Anthropic 的 API 是预付费的，也没有任何官方页面列出注册赠送额度。Claude 聊天订阅同样不包含 API 访问权限。免费 API 指南介绍了额度计划和最便宜的付费路径。

下一步

先用 medium 发送首次调用请求，再用 high 重跑一次，并拿你自己业务里的提示词比较 usage.output_tokens 和答案质量。如果你更习惯在终端里操作，请参阅 Claude Code 中的 Claude Sonnet 5.5。

HiFox：将 Agent 变成真正的队友

另外，我们也在思考，AI 如何从个人提效走进团队协作。

HiFox 是一个让人和 AI Agent 在同一个工作现场协作的平台：你可以像给同事分派任务一样指派 Agent，在任务看板中跟踪进度、查看结果，让 Agent 成为团队里的队友。

👉 立即体验 HiFox：https://hifox.com

AI Coding 交流群

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