看懂 Anthropic Messages API：从请求到回复的七步入门

先把消息接口理解成一次完整交接

1. 调用 Anthropic Messages API，可以理解为向模型递交一份工作材料：你希望它遵守什么要求、此前聊过什么，以及这次最多生成多少内容。服务端接收材料后，返回一条助手消息。先看清这条主线，再认识字段，比直接照抄复杂示例更容易排错。

它不是自动保存全部聊天记录的聊天室。普通多轮调用需要由你的程序保留历史，并在下一次请求时重新提交相关消息。

把请求地址、身份凭证和正文分开看

2. 原生接口通常向 /v1/messages 发送 POST 请求。请求头里的 x-api-key 用于提供密钥，anthropic-version 用于指定接口版本，Content-Type 则声明正文使用 application/json。密钥应留在服务端，不要写进公开网页或代码仓库。

接入中转服务时，地址和鉴权方式应以服务商文档为准。不能只替换域名，就假定所有请求头、路由和功能都与原生接口完全一致。

先认识请求正文里的四个核心字段

3. 新手可以先关注 model、max_tokens、system 和 messages。model 选择模型；max_tokens 设置本次生成的词元上限，而不是固定输出长度。词元也不等于汉字数。

• model 应填写服务端实际接受的模型标识；例如选择 Claude Haiku 4.5 时，应先核对文档中的对应标识。
• system 用于放置整体要求，例如使用简体中文、面向初学者解释，并明确回答边界。
• messages 用于承载本次问题与需要保留的对话历史。

在原生 Messages API 中，system 是顶层字段，不是 messages 数组里的 system 角色消息。这一点容易与其他接口混淆。

用角色和内容块组织对话材料

4. messages 是一个数组，每条消息主要包含 role 和 content。入门时通常只会用到 user 与 assistant：前者表示提交给模型的输入，后者表示此前的助手回复。

纯文本输入的 content 可以直接使用字符串，也可以使用内容块数组。数组中的每个块通过 type 说明类型，例如 text。图片、工具请求与工具结果也使用各自的结构，所以不要把 content 永远当成普通字符串。

从回复中提取文本并检查停止原因

5. 返回值通常包含 id、model、role、content、stop_reason 和 usage。真正的回答位于 content 中；程序应识别并拼接文本块，而不是直接把整个响应对象显示给用户。

stop_reason 帮助你判断模型为何停下。end_turn 通常表示这一轮自然结束，max_tokens 表示触及生成上限，tool_use 则表示需要处理工具请求。usage 提供词元使用信息，可用于成本核算，但不能脱离计费规则直接推算金额。

把工具调用和流式输出当成后续扩展

6. 工具调用不是模型直接执行你的程序。你先在 tools 中描述工具，模型返回 tool_use 内容块；应用检查参数并执行，再用 tool_result 回传结果，关联对应的工具调用标识，随后继续请求模型。执行敏感操作前仍需权限检查。

开启 stream 后，返回的是一系列事件，而不是一次性完成的消息对象。建议先跑通非流式文本请求，再增加流式拼接、异常处理和工具循环，避免同时排查多个问题。

接入 Relay365 前先确认协议路线

7. 如果需要按量使用多个模型家族，Relay365 可以作为统一接入的候选。其接口基础地址为 https://api.api365relay.com，使用 OpenAI 客户端时添加 /v1。它支持 Claude Code、Codex、Gemini CLI 和 OpenAI SDK，但客户端兼容并不意味着请求正文都采用 Anthropic Messages 格式。

先确认你走的是原生 Messages 路线，还是 OpenAI 兼容路线，再核对模型标识、鉴权方式与功能支持。需要统一管理多模型调用时，可以创建一个 Relay365 账户，从小额请求开始验证。无论选择哪条路线，先读懂请求、内容块和停止原因，后续接入都会更稳妥。