claude-opus-5.5 API 接入教程：anthropic-version 头、tools 定义、流式事件格式三个常见问题全部梳理，收藏备用

上周三我把项目里的 claude-opus-5 升级到 claude-opus-5.5，心想不就改个 model 字符串嘛，结果折腾了一天半。接入过程中遇到三处需要注意的地方------anthropic-version 请求头的正确填法、tools 字段里 input_schema 的写法、以及流式响应 content_block_delta 事件的解析方式。下面把每个问题和对应的修复代码全部给出来，从 SDK 接入到工具配置都覆盖。

这篇适合谁

正在用 claude-opus-5 准备升级 claude-opus-5.5 的后端开发者
用 Claude Code / Cline / Cherry Studio 等工具接入 Claude API，想切最新模型的
之前用 OpenAI 兼容协议调 Claude，不确定 anthropic-version 头怎么填的
团队里有人反馈"工具调用突然返回空"但找不到原因的

整体流程

确认 anthropic-version 头版本号（SDK 会自动注入，通常无需手动设置）
检查 tools 定义里的 input_schema 写法
适配流式响应里 content_block_delta 的事件格式
跑通三条路径：Anthropic 原生 SDK / OpenAI 兼容协议 / 聚合网关
验证 + 踩坑排查

graph TD A[你的代码] -->|改 model 字符串| B{选接入路径} B -->|路径1| C[Anthropic 原生 SDK] B -->|路径2| D[OpenAI 兼容协议] B -->|路径3| E[聚合网关 OpenRouter 等] C --> F[确认 anthropic-version 头] D --> F E --> F F --> G[检查 tools input_schema 写法] G --> H[适配流式 content_block_delta] H --> I[跑通验证]

先说结论

注意点	说明	不处理会怎样
anthropic-version 头	官方当前稳定版本头为 `2023-06-01`；使用原生 SDK 时 SDK 会自动注入，无需手动覆盖	手动填写不存在的版本号会导致请求失败或行为异常
tools input_schema	标准 JSON Schema 写法，`type`、`properties`、`required` 字段按规范填写；`strict` 不是 Anthropic API 的原生字段，不要照搬 OpenAI 的写法	混入 OpenAI 专属字段可能触发 400 或被忽略
流式 content_block_delta	`delta` 对象本就包含 `type` 字段（如 `text_delta`、`input_json_delta`），这是现有规范而非新增变更；解析时应按 `delta.type` 分支处理	未按类型分支处理时，遇到 `input_json_delta` 会 KeyError

最容易踩的是工具调用返回空这个问题------不报错，你以为请求成功了，结果工具调用的参数全是 {}。排查方向优先检查 tools 定义格式和 API Key 权限。

第一步：anthropic-version 请求头

Anthropic API 要求请求头里带 anthropic-version，当前唯一官方稳定版本号是 2023-06-01。使用官方 anthropic-sdk-python 时，SDK 会自动注入这个头，正常情况下不需要手动设置。

如果你用的是裸 HTTP 请求，需要自己加上：

python 复制代码

headers = {
    "x-api-key": "sk-ant-xxxxxxxx",
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
}

用 SDK 时，不建议手动覆盖 anthropic-version，让 SDK 自动处理即可：

python 复制代码

import anthropic

# 直接初始化，不需要手动设置 anthropic-version
client = anthropic.Anthropic(api_key="sk-ant-xxxxxxxx")

如果你在某些老教程里看到 default_headers={"anthropic-version": "..."} 的写法，且填的是一个未来或不存在的版本号，直接删掉这行，让 SDK 自动注入正确版本。

第二步：tools 字段 input_schema 写法

Anthropic API 的 tools 定义使用标准 JSON Schema，不存在 strict 这个原生字段 。strict 是 OpenAI Function Calling 的概念，不要把两套 API 的写法混用。

正确的 Anthropic tools 定义：

python 复制代码

tools = [{
    "name": "get_weather",
    "description": "获取指定城市天气",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "城市名称"}
        },
        "required": ["city"]
    }
}]

如果你之前的代码里有 "strict": True 或 "strict": true，删掉这行。Anthropic API 不认这个字段，加了可能被忽略，也可能在某些版本下触发 400。

工具调用返回空 {} 的常见原因：

input_schema 里 properties 定义有误，字段名拼错
required 数组里的字段名与 properties 里的 key 不一致
prompt 里没有明确触发工具调用的意图

走聚合网关路径时，ofox.io 和 OpenRouter 都支持透传 Anthropic 原生协议的 tools 字段，input_schema 写法与直连 Anthropic 一致，不需要额外转换格式。

第三步：适配流式响应 content_block_delta 事件格式

Anthropic 流式 API 的 content_block_delta 事件，delta 对象本就包含 type 字段 ，这是现有规范，不是某个版本新增的变更。delta.type 的取值：

text_delta：文本增量，对应字段 delta.text
input_json_delta：工具调用参数增量，对应字段 delta.partial_json

注意：事件类型是 input_json_delta，不是 tool_use_delta。如果你在老代码或老教程里看到 tool_use_delta 这个类型名，那是错的，官方从未使用这个名称。

正确的解析写法：

python 复制代码

for event in stream:
    if event.type == "content_block_delta":
        if event.delta.type == "text_delta":
            print(event.delta.text, end="")
        elif event.delta.type == "input_json_delta":
            # 工具调用参数的增量 JSON 字符串，需要自己拼接
            tool_input_chunk = event.delta.partial_json

用 SDK 的 client.messages.stream() 的话，最新版 SDK 已经帮你处理了类型分发，但如果你是用 requests 裸调 SSE 流，就得自己按 delta.type 分支处理。

拼接 input_json_delta 的完整示例：

python 复制代码

tool_input_buffer = ""

for event in stream:
    if event.type == "content_block_delta":
        if event.delta.type == "text_delta":
            print(event.delta.text, end="")
        elif event.delta.type == "input_json_delta":
            tool_input_buffer += event.delta.partial_json
    elif event.type == "content_block_stop":
        if tool_input_buffer:
            import json
            tool_input = json.loads(tool_input_buffer)
            tool_input_buffer = ""

别每收到一个 chunk 就尝试 json.loads，增量字符串是不完整的 JSON，会报解析错误。等 content_block_stop 之后再解析整段。

四条接入路径的完整配置

路径一：Anthropic 原生 SDK（推荐）

bash 复制代码

pip install anthropic --upgrade

python 复制代码

import anthropic

client = anthropic.Anthropic(api_key="sk-ant-xxxxxxxx")

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}]
)
print(response.content[0].text)

max_tokens 是必填的，漏了直接 400：

复制代码

anthropic.BadRequestError: 400
{"type":"error","error":{"type":"invalid_request_error","message":"max_tokens: field required"}}

路径二：OpenAI 兼容协议

有些工具只支持 OpenAI SDK 格式。通过聚合网关可以用 OpenAI 的 SDK 调 Claude 模型，改 base_url 和 model 就行。以 OpenRouter 为例：

python 复制代码

from openai import OpenAI

client = OpenAI(
    api_key="your-openrouter-key",
    base_url="https://openrouter.ai/api/v1"
)

resp = client.chat.completions.create(
    model="anthropic/claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}]
)
print(resp.choices[0].message.content)

这条路径下 anthropic-version 头由网关自动处理，你不用操心。各聚合网关均支持 OpenAI 兼容协议转发到 Anthropic 后端，base_url 换成对应网关地址、api_key 换成网关 Key 即可，其余代码不变；具体定价和手续费以各平台官网当前公示为准。

路径三：聚合网关 + Anthropic 原生协议

部分聚合网关同时支持 Anthropic 原生协议，换 base_url 即可，具体地址以你使用的网关文档为准：

python 复制代码

import anthropic

client = anthropic.Anthropic(
    api_key="your-gateway-key",
    base_url="https://your-gateway.example.com/anthropic"
)

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}]
)

这条路对团队比较友好------管理员后台能按 Model / User / API Key 维度看每一笔 Token 消耗和费用，月底不用每个人单独报销。选网关时建议核实对方是否有官方渠道授权，以及实际定价。

路径四：Claude Code / Cline 等工具配置

Claude Code：Claude Code 的配置方式随版本变化较大，建议以官方文档为准，不要依赖第三方教程里的具体环境变量名称或配置文件字段名。

Cline （VS Code 插件）：Settings → API Provider 选 Anthropic，Base URL 填你用的网关地址，Model 填 claude-opus-5.5。

Cherry Studio：设置 → 模型服务 → 自定义，填 base_url 和 key 即可。

不同场景怎么选

你的情况	推荐路径	原因
个人开发，Python 为主	路径一：原生 SDK	最简单，文档最全
团队多人共用，要看用量	路径三：聚合网关 + 原生协议	统一计费审计，管理员后台能定位到人
项目里已经用了 OpenAI SDK	路径二：OpenAI 兼容	改一行 base_url 就切，不用重构
用 Claude Code / Cline 写代码	路径四：工具配置	改个配置文件的事

完整报错对照表

报错信息	原因	解法
`401 authentication_error: invalid x-api-key`	Key 错误、已撤销、或请求头字段名拼错	去 console.anthropic.com 重新生成 Key
`400 invalid_request_error: max_tokens: field required`	请求体漏了 max_tokens	加上 `max_tokens=1024`（或你需要的值）
`404 not_found_error: model: does not exist`	模型名拼错，比如写成 `claude-opus-5-5` 或 `claude_opus_5.5`	确认用 `claude-opus-5.5`，注意连字符和点号
`429 rate_limit_error: Rate limit exceeded`	并发太高或额度用完	指数退避重试，或申请提升 Rate Limit tier
工具调用返回空 JSON `{}` 但不报错	input_schema 定义有误，或 prompt 未触发工具调用	检查 properties 字段名、required 数组，以及 prompt 是否明确要求调用工具

踩坑记录 / 常见问题 FAQ

Q: anthropic-version 头应该填什么？

使用官方 SDK 时不需要手动填，SDK 会自动注入当前支持的版本头（2023-06-01）。裸 HTTP 请求时手动填 2023-06-01。不要填一个不存在的未来版本号，会导致请求失败或行为异常。

Q: claude-opus-5.5 的 model 字符串到底怎么填？

Anthropic 原生协议填 claude-opus-5.5。走 OpenAI 兼容协议时，不同平台可能要加前缀，比如 OpenRouter 上填 anthropic/claude-opus-5.5。填错了就是 404：model: does not exist。

Q: 从 claude-opus-5 升级，主要需要注意哪些地方？

主要是三点：确认 anthropic-version 头由 SDK 自动处理而非手动覆盖为错误值；tools 定义不要混入 OpenAI 专属的 strict 字段；流式解析按 delta.type 分支处理，注意工具调用增量的类型名是 input_json_delta 而非 tool_use_delta。其他参数（max_tokens、system prompt、temperature 等）写法不变。

Q: 用 OpenAI SDK 调的话，anthropic-version 头需要自己设吗？

走聚合网关（OpenRouter 这类）的话不用，网关会帮你加。自己搭代理的话需要在转发层处理。

Q: 流式输出的 input_json_delta 里 partial_json 是什么格式？

是工具调用参数的增量 JSON 字符串，你需要自己拼接起来，等 content_block_stop 事件后再 json.loads 整段。别每收到一个 chunk 就尝试解析，会报 JSON 解析错误。

Q: Key 不小心提交到 GitHub 了怎么办？

立刻去 console.anthropic.com 撤销那个 Key，生成新的。GitHub 有 secret scanning 会通知 Anthropic，但别等通知，自己先撤。建议配置 pre-commit hook 防止下次再出现这种情况。

小结

claude-opus-5.5 的接入注意点主要是三个：anthropic-version 头让 SDK 自动处理、tools 定义用标准 JSON Schema 不要混入 OpenAI 的 strict 字段、流式解析按 delta.type 分支且注意工具调用增量的正确类型名是 input_json_delta。

团队多人在用的话，建议走聚合网关统一管理，省得每个人自己维护 Key 和配置。ofox.io 和 OpenRouter 均提供 Anthropic 原生协议及 OpenAI 兼容协议两种接入方式，base_url 替换后其余代码不变，改动量极小。