第一次把聊天请求迁到 Anthropic Messages 的记录

第一次接触 Anthropic Messages API，容易把它理解成换了地址的聊天接口。它确实也接收对话、返回模型输出，但系统指令、内容块和工具结果的组织方式并不相同。下面以 OpenAI 的聊天补全接口为参照，逐项记录迁移时值得核对的地方；这里的对照不包含 OpenAI 的其他接口。

§ 入口相似，请求约定不同

Anthropic Messages：典型路径是 /v1/messages。直连官方服务时，通常使用 x-api-key 和 anthropic-version 请求头；版本头用于指定接口版本，不是选择模型。

OpenAI 聊天补全：典型路径是 /v1/chat/completions，通常通过 Authorization: Bearer 携带密钥。路径和认证方式属于协议约定，不能只改模型名称就期待请求通用。

Vana API 在 https://api.vanaapi.com 提供统一入口，除 OpenAI 兼容接口外，也支持 Anthropic Messages 和 Gemini 原生协议。使用 SDK 时，先确认它会自动补上哪些路径，再按接入说明配置密钥，避免重复拼接 /v1。

Anthropic Messages：系统指令放在请求顶层的 system 字段；messages 主要承载 user 和 assistant 消息。不要直接把另一种格式中的 system 消息原样搬进来。

OpenAI 聊天补全：系统级指令通常作为 messages 中的独立消息提交；具体角色支持取决于模型和接口。迁移时，应转换消息结构，而不是仅重命名字段。

Anthropic Messages：简单输入可以使用文本字符串，也可以使用内容块数组。响应的 content 通常是数组，文本块之外还可能包含工具调用等内容。读取结果时，应按块类型处理，不能默认第一个块就是完整答案。

OpenAI 聊天补全：文本回复常从 choices 中的 message.content 读取，工具调用则有相应字段。已有的文本提取函数通常需要调整；图片等多模态输入也不能直接照搬格式。

Anthropic Messages：max_tokens 是需要明确设置的输出上限，不是实际消耗量。响应中的 stop_reason 可帮助判断模型是正常结束、触及长度限制，还是准备调用工具。

OpenAI 聊天补全：输出限制参数随接口和模型而异，结束状态通常通过 finish_reason 表达。两边的字段和值并非逐项等价，尤其不能把“请求成功”理解为“答案完整”。

先用较短回答测试，再检查用量和结束原因。Vana API 按实际令牌用量计费，没有月费；调低输出上限有助于控制单次预算，但它不是费用预估器。

Anthropic Messages：流式响应包含消息和内容块的生命周期事件，需要累积文本增量，并留意最终状态。工具调用以 tool_use 内容块表达，执行结果通常通过后续 user 消息中的 tool_result 返回。

OpenAI 聊天补全：流式客户端通常处理 choices 中的 delta；工具结果则通过 tool 消息与调用标识关联。两边都需要应用执行工具，模型返回调用请求不代表工具已经运行。

因此，迁移范围不只有发送请求的函数，还包括流式解析器、工具参数校验和结果回填。涉及写文件、发消息等操作时，应保留确认与权限检查。

可以选择 Claude Haiku 4.5 做小规模验证，具体模型标识以平台提供的值为准。按顺序测试普通问答、多轮追问、流式响应，再加入工具调用，能更快定位问题属于协议转换还是应用逻辑。

如果项目已经使用 OpenAI SDK，可以先保留兼容接口；如果客户端依赖 Anthropic 原生消息结构，则优先选择对应协议。Vana API 可用于这两种接入路径，但协议可用不等于每个模型都支持相同功能。

准备实际验证时，可以创建一个 Vana API 账户，从一条不含敏感信息的短请求开始。先让消息结构、结束状态和用量记录都符合预期，再迁移完整工作流。