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_deltadelta对象本就包含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 请求需要自己加上headers { x-api-key: sk-ant-xxxxxxxx, anthropic-version: 2023-06-01, content-type: application/json }用 SDK 时不建议手动覆盖anthropic-version让 SDK 自动处理即可import anthropic # 直接初始化不需要手动设置 anthropic-version client anthropic.Anthropic(api_keysk-ant-xxxxxxxx)如果你在某些老教程里看到default_headers{anthropic-version: ...}的写法且填的是一个未来或不存在的版本号直接删掉这行让 SDK 自动注入正确版本。第二步tools 字段 input_schema 写法Anthropic API 的 tools 定义使用标准 JSON Schema不存在strict这个原生字段。strict是 OpenAI Function Calling 的概念不要把两套 API 的写法混用。正确的 Anthropic tools 定义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.textinput_json_delta工具调用参数增量对应字段delta.partial_json注意事件类型是input_json_delta不是tool_use_delta。如果你在老代码或老教程里看到tool_use_delta这个类型名那是错的官方从未使用这个名称。正确的解析写法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的完整示例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推荐pip install anthropic --upgradeimport anthropic client anthropic.Anthropic(api_keysk-ant-xxxxxxxx) response client.messages.create( modelclaude-opus-5, max_tokens1024, messages[{role: user, content: 你好}] ) print(response.content[0].text)max_tokens是必填的漏了直接 400anthropic.BadRequestError: 400 {type:error,error:{type:invalid_request_error,message:max_tokens: field required}}路径二OpenAI 兼容协议有些工具只支持 OpenAI SDK 格式。通过聚合网关可以用 OpenAI 的 SDK 调 Claude 模型改base_url和model就行。以 OpenRouter 为例from openai import OpenAI client OpenAI( api_keyyour-openrouter-key, base_urlhttps://openrouter.ai/api/v1 ) resp client.chat.completions.create( modelanthropic/claude-opus-5, max_tokens1024, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)这条路径下anthropic-version头由网关自动处理你不用操心。各聚合网关均支持 OpenAI 兼容协议转发到 Anthropic 后端base_url换成对应网关地址、api_key换成网关 Key 即可其余代码不变具体定价和手续费以各平台官网当前公示为准。路径三聚合网关 Anthropic 原生协议部分聚合网关同时支持 Anthropic 原生协议换base_url即可具体地址以你使用的网关文档为准import anthropic client anthropic.Anthropic( api_keyyour-gateway-key, base_urlhttps://your-gateway.example.com/anthropic ) response client.messages.create( modelclaude-opus-5, max_tokens1024, messages[{role: user, content: 你好}] )这条路对团队比较友好——管理员后台能按 Model / User / API Key 维度看每一笔 Token 消耗和费用月底不用每个人单独报销。选网关时建议核实对方是否有官方渠道授权以及实际定价。路径四Claude Code / Cline 等工具配置Claude CodeClaude Code 的配置方式随版本变化较大建议以官方文档为准不要依赖第三方教程里的具体环境变量名称或配置文件字段名。ClineVS Code 插件Settings → API Provider 选 AnthropicBase 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-keyKey 错误、已撤销、或请求头字段名拼错去 console.anthropic.com 重新生成 Key400 invalid_request_error: max_tokens: field required请求体漏了 max_tokens加上max_tokens1024或你需要的值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 是否明确要求调用工具踩坑记录 / 常见问题 FAQQ: 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。填错了就是 404model: 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替换后其余代码不变改动量极小。