客户端、SDK、网关对「兼容」的约定，当前收敛成三条线协议：

1. OpenAI Chat Completions — POST /v1/chat/completions
2. OpenAI Responses API — POST /v1/responses
3. Anthropic Messages API — POST /v1/messages

Chat Completions 是跨厂商事实标准。Responses 是 OpenAI 2025-03 起的新主 API，agent / 内置工具 / 推理连续性落在这里。Messages 是 Claude 原生协议，因 Claude Code 成为第二标准。

OpenAI 官方：Chat Completions 继续支持、不会sunset；新项目推荐 Responses。被 sunset 的是 Assistants API（2026-08-26），迁到 Responses + Conversations，不是迁回 Chat Completions。

一句话对照

识别规则：看路径和请求体，不看模型名。

• 有 messages + 响应有 choices → Chat Completions
• 有 input（或顶层 instructions）+ 响应有 output / output_text → Responses
• 有必填 max_tokens + 顶层 system + 响应 content 块数组 → Messages

1. OpenAI Chat Completions

2023-03 起的对话 API。换 base_url 就能打 DeepSeek、Qwen compatible-mode、Moonshot、GLM、xAI、vLLM、Ollama、大多数网关。跨厂商移植仍写这套。

端点与认证

1
2
3

POST:{base}/v1/chat/completions
Authorization: Bearer $API_KEY
Content-Type: application/json

SDK 的 base_url 通常带 /v1。官方：https://api.openai.com/v1。

常见附属：GET /v1/models、POST /v1/embeddings。POST /v1/completions 是更旧的 prompt 补全，已 legacy。

请求

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "model": "gpt-4.1",
  "messages": [
    {"role": "system", "content": "你是助手。"},
    {"role": "user", "content": "用一句话解释 token。"}
  ],
  "temperature": 0.7,
  "max_completion_tokens": 512,
  "stream": false
}

响应

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1714000000,
  "model": "gpt-4.1",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 9,
    "total_tokens": 34
  }
}

finish_reason：stop / length / tool_calls / content_filter / function_call（弃用）。

工具调用时 message.content 常为 null，调用在 message.tool_calls[]：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_abc",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"location\":\"Boston, MA\"}"
      }
    }
  ]
}

回灌：同一 messages 里追加 role: "tool"，带 tool_call_id。必须客户端自己把 assistant 的 tool_calls 和 tool 结果都塞回下一轮。

流式

同端点，stream: true。每行 data: {json}，结束 data: [DONE]。对象类型 chat.completion.chunk，增量在 choices[0].delta.content。

1
2
3

{"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

工具流式：delta.tool_calls[].function.arguments 是 JSON 字符串碎片，按 index 拼接。

最小调用

1
2
3
4
5
6
7

from openai import OpenAI
client = OpenAI(api_key="sk-...", base_url="https://api.openai.com/v1")
r = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "ping"}],
)
print(r.choices[0].message.content)

2. OpenAI Responses API

OpenAI 现推的主 primitive。设计目标：把「一次模型动作」从一条粘在一起的 message，拆成类型化 item（message / reasoning / function_call / 内置工具调用）。同一请求内可跑完多步工具循环（agentic loop）。

Chat Completions 能做的文本 / vision / 自定义 function / structured output，Responses 都能做，并且是超集。新能力只上 Responses：web_search、file_search、code_interpreter、computer use、远程 MCP、image_generation 当工具、reasoning summary、background mode。

内部评测（官方）：同样 prompt，推理模型走 Responses 比 Chat Completions 在 SWE-bench 高约 3%；prompt cache 利用率高 40%–80%。

端点与认证

1
2
3

POST https://api.openai.com/v1/responses
Authorization: Bearer $OPENAI_API_KEY
Content-Type: application/json

认证与 Chat Completions 相同。附属：GET /v1/responses/{id}、POST /v1/responses/{id}/cancel、Conversations API、POST /v1/responses/compact。

请求

最简：input 可以是纯字符串。

1
2
3
4
5

{
  "model": "gpt-5.5",
  "instructions": "你是助手。",
  "input": "用一句话解释 token。"
}

多轮 / 多模态时 input 是 item 数组。简单 {role, content} 消息数组也能塞进 input（迁移期兼容）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "model": "gpt-5.5",
  "instructions": "你是助手。",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "这张图里有什么？"},
        {"type": "input_image", "image_url": "https://..."}
      ]
    }
  ],
  "max_output_tokens": 512
}

没有 n（只生成一条）。没有 presence_penalty / frequency_penalty 这一套 CC-only 采样项（以当前 schema 为准）。

响应

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

{
  "id": "resp_68af4030...",
  "object": "response",
  "created_at": 1756315696,
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "id": "rs_...",
      "type": "reasoning",
      "content": [],
      "summary": []
    },
    {
      "id": "msg_...",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "text": "..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 40,
    "total_tokens": 65
  }
}

SDK 提供 response.output_text，把所有 output_text 拼起来。手写解析不要假定 output[0] 是 message——前面经常先有 reasoning。

status：in_progress / completed / failed / cancelled / queued。

工具调用形状（与 CC 不同）

定义（扁平，无 function 包一层）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "type": "function",
  "name": "get_weather",
  "description": "Get weather",
  "parameters": {
    "type": "object",
    "properties": {"location": {"type": "string"}},
    "required": ["location"]
  }
}

模型吐出的是独立 item，不嵌在 message 里：

1
2
3
4
5
6
7

{
  "type": "function_call",
  "id": "fc_...",
  "call_id": "call_abc",
  "name": "get_weather",
  "arguments": "{\"location\":\"Boston, MA\"}"
}

回灌用另一个 item，call_id 必须对齐：

1
2
3
4
5

{
  "type": "function_call_output",
  "call_id": "call_abc",
  "output": "72°F, sunny"
}

两种多轮方式：

1. 服务端状态：下一请求只带 previous_response_id + 新 input（用户话或 function_call_output）。
2. 无状态：把上一轮 output 里的 reasoning / function_call 原样放进下一轮 input，再追加 function_call_output。丢掉 reasoning item 会打断推理连续性。store: false 时用加密 reasoning 字段回放。

previous_response_id 不免除 对先前上下文的计费：链上的历史仍按 input tokens 计。

内置工具同一 tools 数组：

1

{"tools": [{"type": "web_search"}, {"type": "function", "name": "get_weather", "parameters": {...}}]}

模型可在一次 responses.create 里连打多个内置工具，再给你最终文本。自定义 function 仍要你本地执行后回灌。

结构化输出

CC 的 response_format 迁到 text.format：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "model": "gpt-5.5",
  "input": "抽出发票字段。",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "invoice",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {"total": {"type": "number"}},
        "required": ["total"]
      }
    }
  }
}

schema 本身不变，只是位置变了。JSON mode 对应 text.format.type = "json_object"。

流式

同端点 stream: true。不要用 Chat Completions 的 choices[0].delta 解析器。事件带 type：

1
2
3
4

stream = client.responses.create(model="gpt-5.5", input="ping", stream=True)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

最小调用

1
2
3
4
5
6
7
8

from openai import OpenAI
client = OpenAI()
r = client.responses.create(
    model="gpt-5.5",
    instructions="你是助手。",
    input="ping",
)
print(r.output_text)

链式多轮：

1
2
3
4
5

r2 = client.responses.create(
    model="gpt-5.5",
    previous_response_id=r.id,
    input="把上一句翻译成英文。",
)

从 Chat Completions 迁过来的三件事

1. 路径 /v1/chat/completions → /v1/responses。
2. 读 choices[0].message.content → 读 output_text / 遍历 output（不要把每个 item 都当 message）。
3. 选状态策略：继续手传 history（input 里重放 item），或 previous_response_id / Conversations。

常见迁移错误：仍发 response_format；把 CC 的 tools[].function 套层原样丢给 Responses；回灌 function 结果不带 call_id；流式还在找 choices；丢掉 reasoning item。

GPT-6 Astra 的 tool calling 要求 Responses。Chat Completions 示例要用更早的模型。

3. Anthropic Messages API

Claude 原生协议。Claude Code、Anthropic SDK 只认这套。2025–2026 起 DeepSeek（https://api.deepseek.com/anthropic）、MiniMax（推荐走 Messages 拿满 thinking/tool）、Kimi、部分 Qwen 网关都加了 /v1/messages。

旧 Text Completions（\n\nHuman: / \n\nAssistant:）已弃用。

端点与认证

1
2
3
4

POST https://api.anthropic.com/v1/messages
x-api-key: $ANTHROPIC_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json

兼容层常见两种：只认 x-api-key，或同时接受 Authorization: Bearer。anthropic-version 多数网关忽略，SDK 会带。

附属：POST /v1/messages/count_tokens、POST /v1/messages/batches。

请求

1
2
3
4
5
6
7
8
9

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "你是助手。",
  "messages": [
    {"role": "user", "content": "用一句话解释 token。"}
  ],
  "temperature": 0.7
}

content 可以是字符串，等价于 [{type:"text", text:"..."}]。正式形态是块数组。常见块：text / image / tool_use / tool_result / thinking。

图片：

1
2
3
4

{
  "type": "image",
  "source": {"type": "base64", "media_type": "image/jpeg", "data": "<base64>"}
}

响应

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [{"type": "text", "text": "..."}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 25,
    "output_tokens": 200,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

stop_reason：end_turn / max_tokens / stop_sequence / tool_use / pause_turn / refusal / model_context_window_exceeded。

工具调用是 content 里的块，input 是对象不是字符串：

1
2
3
4
5
6

{
  "type": "tool_use",
  "id": "toolu_01",
  "name": "get_weather",
  "input": {"location": "Boston, MA"}
}

回灌：下一条 user 消息的 content 里放 tool_result，tool_use_id 对齐。下一轮要把上一轮完整 content（含 thinking / tool_use）原样追加进 assistant 消息。丢掉 thinking 块会校验失败。

流式

同端点。事件名与 data.type 一致。

顺序：

1. message_start — 空 content 的 Message，含 input usage
2. 每个块：content_block_start → 若干 content_block_delta → content_block_stop
3. message_delta — stop_reason + 最终 output usage
4. message_stop

文本增量：delta.type == "text_delta"。工具参数增量：input_json_delta（partial_json）。中间可能夹 ping。不要把所有 content_block_delta 都当文本。

Prompt cache

两种开法：

• 自动：请求顶层 "cache_control": {"type": "ephemeral"}，断点落在最后一个可缓存块，多轮会前移。
• 显式：在 tools / system / 某个 content block 上挂 cache_control。

默认 TTL 5 分钟，刷新命中免费；另有 1 小时档（写入更贵）。缓存前缀顺序固定：tools → system → messages。usage 里看 cache_creation_input_tokens / cache_read_input_tokens。

Responses 的 cache 主要靠稳定的 instructions + 服务端状态；Messages 是显式断点。两套机制不能对着抄字段名。

最小调用

1
2
3
4
5
6
7
8
9

import anthropic
client = anthropic.Anthropic()
r = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="你是助手。",
    messages=[{"role": "user", "content": "ping"}],
)
print(r.content[0].text)

横切对照

认证与路径

OpenAI 两条协议可以共用 SDK 对象：client.chat.completions.create vs client.responses.create。Messages 必须换 Anthropic SDK 或改 header。

系统提示、角色、内容模型

Responses 的 item 模型和 Messages 的 content block 更像：都把 reasoning / tool call 从「一条 assistant message」里拆出来。Chat Completions 把这些粘在 message + tool_calls 上。

采样与长度

移植最容易炸的两件事：Messages 漏 max_tokens；把 OpenAI 的 temperature: 1.5 打到 Claude。

结构化输出

CC → Responses 只改字段位置，schema 不用重写。

工具调用词汇

循环相同：声明 → 模型吐调用 → 本地执行 → 结果作为下一轮输入。字段和落点不同。

any ≈ required（必须调工具）。OpenAI 两套的 arguments 都是序列化 JSON 字符串；Anthropic 是已解析对象。网关漏转这个类型会让客户端二次 JSON.parse 或 TypeError。

推理

上限字段把 thinking + 可见文本算在一起。上限过小会只产出 thinking、正文为空。

流式事件不能混解析

三套解码器不能共用。用 CC 解析器读 Responses 流会找不到 choices。

状态

previous_response_id 省的是重传字节和 cache 友好性，不是免掉历史 token 账单。

生态：谁说哪种话

「OpenAI 兼容」在市面上几乎总是 Chat Completions，不等于实现了 Responses。内置工具、previous_response_id、语义流式事件、扁平 tools 定义，要逐项对文档。

LiteLLM 可以把 Messages 映射到 Responses：messages → input，system → instructions，max_tokens → max_output_tokens，thinking → reasoning。反向同样要处理 item ↔ block。

转换陷阱

1. 系统提示位置。CC 的 role: system → Responses 的 instructions 或 Messages 的 system。反向要塞回 messages[0]。
2. 读输出。choices[0].message.content / output_text / content[0].text 三套。Responses 的 output[0] 经常是 reasoning，不是文本。
3. tools 套层。CC 有 function 包一层；Responses 和 Messages 都扁平。
4. 工具参数类型。两个 OpenAI 协议 arguments 是字符串；Anthropic input 是对象。
5. 工具结果角色。CC 用 tool；Responses 用 function_call_output item；Messages 仍是 user + tool_result。
6. id 字段名。tool_call_id / call_id / tool_use_id。对不上就 400。
7. max_tokens 必填。只有 Messages 强制。CC/Responses 可选，但字段名还不一样。
8. temperature 量纲。1.5 在两条 OpenAI 协议合法，在 Anthropic 非法。
9. 流式解析器。三套事件完全不同。
10. 思考块必须回放。Messages 的 thinking、Responses 的 reasoning item，丢掉会拒或变笨。CC 没有对等的一等 item。
11. response_format vs text.format vs output_config。结构化输出三个家。
12. 把 Responses 当「改个 URL 的 CC」。简单字符串 input 能跑；tools / 多轮 / 流式会在形状上炸掉。
13. previous_response_id 与兼容层。多数国内 CC 兼容层没有这个语义；链式状态一接就 404/忽略。
14. header 与 base 后缀。OpenAI SDK base 带 /v1；Anthropic SDK base 不要再拼 /v1。

相邻格式（不计入三种）

怎么选

自建中枢时：用 类型化 item/block（Responses item 或 Messages content block）做内部表示。用 CC 的 messages 当中枢会丢掉 reasoning / thinking / 内置工具调用。

三格式最小请求并排

Chat Completions：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "system", "content": "你是助手。"},
      {"role": "user", "content": "ping"}
    ]
  }'

Responses：

1
2
3
4
5
6
7
8

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "instructions": "你是助手。",
    "input": "ping"
  }'

Messages：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

curl 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-6",
    "max_tokens": 1024,
    "system": "你是助手。",
    "messages": [{"role": "user", "content": "ping"}]
  }'

官方文档

• Chat Completions：https://developers.openai.com/api/reference/resources/chat
• Responses：https://developers.openai.com/api/reference/resources/responses
• 从 CC 迁 Responses：https://platform.openai.com/docs/guides/migrate-to-responses
• Responses 流式事件：https://developers.openai.com/api/reference/resources/responses/streaming-events
• Function calling（两套 OpenAI 形状）：https://developers.openai.com/api/docs/guides/function-calling
• Anthropic Messages：https://platform.claude.com/docs/en/api/http/messages/create
• Anthropic 流式：https://docs.claude.com/en/docs/build-with-claude/streaming
• Anthropic Prompt cache：https://docs.claude.com/en/docs/build-with-claude/prompt-caching
• 参数对照（含 CC / Responses / Messages）：https://hidekazu-konishi.com/entry/llm_api_parameter_compatibility_reference.html

字段名、temperature 是否还接受、thinking 档位、哪代模型强制走 Responses 做 tool calling，随模型代际会变。对接前以各家当前 API reference 为准。