对 Anthropic Messages API 与 OpenAI Chat Completions / Responses API 的请求/响应协议做由浅入深的调研，覆盖字段结构、流式事件、tool use、多模态、prompt caching、batch、以及跨厂商的「为什么」分析。
📘 不知道从哪开始？直接读
00-mental-model.md—— 5 分钟建立对三家协议的统一心智模型，比这份 README 更好懂。
调研原则：字段与枚举值一律从官方文档取证（WebFetch 实抓），不靠记忆编造。OpenAI 在线 Reference 部分页面需登录态（403），已用官方迁移指南 + SDK 示例交叉补全，详见各文末注记。英文版见
README.en.md。
按你想投入的时间选档位，每档都是闭环、不必按顺序读完：
读 00-mental-model.md。核心 aha：所有 LLM API 本质都是「上下文喂进去 → 模型思考 → 吐出停止信号 + 输出」，三家差异只是骨架上的三种变体。停止信号是 agent loop 的方向盘——这是最容易被忽略的关键点。
读 worked-example.md。一个天气 agent 在三家协议下的逐字节对照演练：同一个 tool-calling 两轮闭环，看 Anthropic / OpenAI Chat / OpenAI Responses 各自怎么写请求、怎么收流式事件、怎么回传工具结果。差异自然浮现。
需要查具体字段或子协议时，按厂商进：
Anthropic
messages-api.md— Messages API 请求/响应全字段（19 字段表 + stop_reason 6 枚举 + cache 三段式 usage）streaming-and-tools.md— SSE 8 类事件流 + tool_use/tool_result 闭环（含 Mermaid 时序图）advanced-features.md— prompt caching / batch / vision+PDF / extended thinking
OpenAI
chat-completions.md— Chat Completions 全字段 + 流式 + function calling + structured outputs（含 Mermaid 图）responses-api.md— 新版 Responses API：stateful + 7 类内置工具 + 迁移建议（含 Mermaid 图）
cross-cutting/analysis.md— 为什么各家有自己协议 / agent 字段语义 / OpenAI 为何走向 Responsesglossary.md— 26 个术语人话解释（SSE / content block / KV cache / stateless vs stateful / previous_response_id …）
llm-api-protocols/
├── README.md # 本文件
├── README.en.md # 英文导航摘要
├── 00-mental-model.md # ⭐ 心智模型入口（先读这个）
├── worked-example.md # ⭐ 同一 agent 在三家协议下的对照演练
├── glossary.md # 术语表
├── LICENSE
├── anthropic/
│ ├── messages-api.md # Messages API 全字段
│ ├── streaming-and-tools.md # 流式事件 + tool use（含 Mermaid 图）
│ └── advanced-features.md # caching / batch / 多模态 / thinking
├── openai/
│ ├── chat-completions.md # Chat Completions（含 Mermaid 图）
│ └── responses-api.md # Responses API（含 Mermaid 图）
└── cross-cutting/
└── analysis.md # 跨厂商「为什么」分析
| 维度 | Anthropic Messages | OpenAI Chat Completions | OpenAI Responses |
|---|---|---|---|
| 端点 | POST /v1/messages |
POST /v1/chat/completions |
POST /v1/responses |
| 认证 | x-api-key 或 Authorization: Bearer |
Authorization: Bearer |
Authorization: Bearer |
| 上下文载体 | messages + 顶层 system |
messages（含 system role） |
input + 顶层 instructions |
| 状态管理 | 无状态，客户端自管历史 | 无状态，客户端自管历史 | 有状态，previous_response_id 续接 + store |
| 工具模型 | tools + tool_choice，tool_use/tool_result 为 content block |
tools + tool_choice，assistant.tool_calls + tool role |
内置工具（web_search/code_interpreter/file_search/computer_use/mcp…）+ function |
| 推理/思考 | thinking 参数 + thinking content block（含 signature） |
o 系列 reasoning_effort，不暴露思考文本 |
reasoning 一等公民，含 encrypted_content |
| 输出 token 上限字段 | max_tokens（必填） |
max_tokens（o 系列改用 max_completion_tokens） |
max_output_tokens |
| 结束信号 | stop_reason：end_turn/max_tokens/stop_sequence/tool_use/pause_turn/refusal |
finish_reason：stop/length/tool_calls/content_filter |
status：completed/incomplete/failed + reason |
| 流式风格 | SSE，8 类事件（message_start → content_block_delta → message_delta/stop） | SSE，data: {delta} + data: [DONE]，stream_options.include_usage |
类型化事件（response.created / response.output_text.delta / response.completed…） |
| 多模态 | image / document content block | image_url / input_audio content | image / input_audio / input_file item |
| 缓存 | cache_control（ephemeral，4 断点，5m/1h ttl） |
自动 prompt caching（无显式控制） | 自动 + store 服务端状态 |
| 批处理 | /v1/messages/batches（异步，降本 50%） |
/v1/batch（异步，降本 50%） |
Batch 兼容接口 |
| token 计费字段 | usage：input/output/cache_read/cache_creation（含 thinking_tokens） |
usage：prompt/completion/total |
usage：input/output/total + reasoning tokens |
| 典型定位 | 协议暴露模型原生能力 | 通用、最广泛兼容 | agentic、内置工具、状态外包 |
-
为什么各家协议不同：不是字段命名的随意，而是模型架构（stateless vs stateful）、产品哲学（暴露原生能力 vs 平台化内置工具）、商业锁定、演进路径锁定的综合产物。
-
Agent 视角的字段语义：一个标准 agent loop 由
tools/tool_choice（动作空间）、stop_reason/finish_reason（循环控制信号：tool_use→执行→回传→继续，end_turn→停止）、usage（成本预算）、stream + delta（实时拦截）共同驱动；previous_response_id让 agent 把状态外包给 provider。 -
OpenAI 走向 Responses：Chat Completions 的 stateless + 全手搓 function calling 在 agentic 长链路工具调用下表达力不足；Responses 把内置工具、服务端状态、reasoning 下沉为协议一等公民，是 Assistants API 的继任者，代价是 vendor lock-in 加深与可观测性挑战。
- Anthropic：
docs.claude.com/docs.anthropic.com现 301 重定向至platform.claude.com/docs/en/api/...，均已实抓。 - OpenAI：
platform.openai.com/docs/api-reference/*部分返回 403（需登录态），已用developers.openai.com/api/docs/guides/migrate-to-responses迁移指南 + 官方 SDK 示例交叉补全字段。建议关键字段以官方在线 Reference 为准。
模型 ID、字段、价格随厂商迭代变化快。本调研快照日期：2026-06-21。如需更新，重新跑对应 agent 即可（每个文件独立、可单独刷新）。