Messages API 是什么
Messages API 是 Anthropic 的对话接口：向 /v1/messages 发 POST 请求，system 作为顶层参数单独传，messages 里只放 user 与 assistant 轮次。它和 OpenAI 的 Chat Completions 长得像但不通用：长度参数必填、内容以块数组组织、工具结果通过 user 消息里的结果块回填。迁移时按这几点逐项改，比整体重写配置更稳。
基本信息
| 接口地址 | https://api.anthropic.com/v1/messages |
|---|---|
| 方法 | POST，JSON 请求体 |
| 鉴权头 | x-api-key，另需 anthropic-version 指定接口版本 |
| 必填参数 | model、max_tokens、messages |
| system | 顶层参数，不放进 messages 数组 |
| 返回结构 | content 为块数组，文本在文本块中 |
与 Chat Completions 的字段对照
| 维度 | Messages API | Chat Completions |
|---|---|---|
| 系统指令 | 顶层 system 参数 | system 或 developer 角色消息 |
| 消息内容 | content 为块数组 | 字符串或块数组 |
| 长度限制 | max_tokens 必填 | 可选，或用新接口的等价参数 |
| 工具定义 | 单独的 tools 参数，结构自有格式 | tools 参数，函数式结构 |
| 工具结果 | 以 user 消息中的结果块提交 | 以 tool 角色消息提交 |
| 流式 | 逐事件推送，事件类型区分明确 | data 行推送增量片段 |
典型使用场景
- 长文档问答：把整份文档放进请求做摘要、比对与问答
- 编码任务：跨文件理解与补丁生成，配合工具调用
- 结构化抽取：用输出格式约束把文本转成字段
- 智能体编排：作为多轮工具链中的决策模型
- 内容审校：按给定规则逐条检查稿件并给出修改意见
最小请求与多轮写法
最小请求与多轮写法
curl -s 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-4-5","max_tokens":1024,"system":"你是合规审查助手","messages":[{"role":"user","content":"差旅报销上限是多少？"}]}'
# 多轮：把上一轮返回的 assistant 内容按块原样追加进 messages
# 工具调用：先返回工具调用请求，执行后把结果作为 user 消息里的结果块提交
# anthropic-version 缺失或被服务端判定过期时会直接报错输出内容可能包含多个块（文本块、工具调用块），程序解析时应按块类型分支处理，不要默认只取第一个块。
长提示词建议用清晰的标签或分隔结构组织资料与指令：模型对结构化输入的遵循度明显更高，出问题时也更容易定位是哪一段的内容导致的。
max_tokens 是必填项：从其他协议迁移时漏掉它是最常见的 400 错误来源，建议在封装层做默认值。