协议不匹配详解

「客户端能连上、密钥也没错，但就是报 404 / 400」——绝大多数情况是协议不匹配。 这一页讲清三种协议的差别，以及为什么它们不能互换。

一张表看懂

维度	OpenAI Chat Completions	OpenAI Responses	Anthropic Messages
ZiAI 端点	https://api.ziai.lol/v1/chat/completions	https://api.ziai.lol/v1/responses	https://api.ziai.lol/v1/messages
鉴权头	Authorization: Bearer	Authorization: Bearer	x-api-key 或 Authorization: Bearer
必需额外头	无	无	anthropic-version: 2023-06-01
对话字段	messages	input（也接受 messages）	messages
max_tokens	可选	用 max_output_tokens，且最小 16	必填
系统提示	messages 里的 system / developer 角色	同左，或 instructions	顶层独立 system 字段
工具调用	tools + tool_calls	tools + function_call 项	tools + tool_use / tool_result 内容块
思考控制	顶层 reasoning_effort	reasoning.effort（含 encrypted_content）	thinking: { type, budget_tokens }
响应结构	choices[].message.content	output[] + status	content[] 块数组 + stop_reason
用量字段	usage.prompt_tokens / completion_tokens	usage.input_tokens / output_tokens	usage.input_tokens / output_tokens
本站使用它的客户端	ChatBox、CherryStudio、WorkBuddy、ZCode	Codex	Claude Code、ZCode、CherryStudio

结论：请求体结构、必需字段、响应结构、流式事件全都不一样。把一个协议的地址填给另一个协议的客户端，必然失败。

请求与响应实例对比

同样的「你好」，三种协议的请求体长这样：

Chat Completions

curl https://api.ziai-demo.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxx" \
  -d '{
    "model": "模型ID",
    "messages": [{"role": "user", "content": "你好"}]
  }'

响应（节选）：

{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "你好！" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 3, "total_tokens": 12 }
}

Responses

curl https://api.ziai-demo.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxx" \
  -d '{
    "model": "模型ID",
    "input": "你好"
  }'

响应（节选）：

{
  "id": "resp_xxxx",
  "object": "response",
  "status": "completed",
  "output": [{
    "type": "message",
    "role": "assistant",
    "content": [{ "type": "output_text", "text": "你好！" }]
  }],
  "usage": { "input_tokens": 9, "output_tokens": 3, "total_tokens": 12 }
}

Anthropic Messages

curl https://api.ziai-demo.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: sk-xxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "模型ID",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'

响应（节选）：

{
  "id": "msg_xxxx",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "你好！" }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 9, "output_tokens": 3 }
}

注意 max_tokens 是必填的 —— 漏掉会直接 400。

流式事件也完全不同

协议	流式事件形态
Chat Completions	data: {"choices":[{"delta":{"content":"你"}}]} 逐块拼接
Anthropic Messages	带类型的生命周期事件：message_start、content_block_start、content_block_delta、message_stop
Responses	带类型的语义事件：response.output_text.delta、response.completed 等

所以「客户端能连上但输出乱掉 / 只出一个字 / 一直转圈」也可能是协议或转换层的问题，而不只是网络问题。

客户端的地址拼接规则

同样是「填地址」，各客户端的规则并不一致 —— 这是 404 的另一个来源：

客户端	你填的	客户端实际请求
ChatBox	主机 https://域名 + 路径默认 /v1/chat/completions	https://域名/v1/chat/completions
CherryStudio（自定义 OpenAI 兼容）	https://域名/v1	自动补 /chat/completions；也可用 # 结尾填完整地址
WorkBuddy（自定义协议关闭）	https://域名/v1	https://域名/v1/chat/completions
ZCode	OpenAI 地址 https://域名/v1；Anthropic 地址 https://域名	分别拼 /chat/completions 与 /v1/messages
Codex	base_url = "https://域名/v1"	https://域名/v1/responses
Claude Code	ANTHROPIC_BASE_URL=https://域名	https://域名/v1/messages
CC-Switch（代理接管时）	base_url = "https://域名"（前缀）	代理拼 /v1/chat/completions

CC-Switch 代理模式下规则相反

直连时 Codex 的 base_url 要带 /v1；由 CC-Switch 本地代理接管时，base_url 被当作前缀，代理自己拼 /v1/chat/completions。 两种模式填法相反，搞混就得到 /v1/v1/...。详见「完整 URL 模式」这个开关。

ZiAI 的协议转换能力

ZiAI 网关支持多种聊天格式互转：OpenAI Chat、OpenAI Responses、Anthropic Messages 等格式之间可以转换。

这意味着两件好事：

1. 非 Claude 模型也能通过 /v1/messages 调用 —— 客户端说 Anthropic 协议，后端是 OpenAI 格式渠道时，ZiAI 会转换；
2. 非 GPT 模型也能通过 /v1/responses 调用 —— 前提是 ZiAI 侧为该渠道开启了对应能力。

转换是有损的

协议转换不是无损映射，以下能力在转换后可能不完整或行为不同：

• 工具调用：tool_calls ↔ tool_use 块 ↔ function_call 项的结构差异较大，复杂工具链容易出问题
• 思考 / 推理参数：reasoning_effort、thinking.budget_tokens、reasoning.encrypted_content 三者语义不同，可能被忽略或降级
• 前缀缓存：转换层若注入了动态内容（例如每请求变化的计费标识头），会破坏上游的隐式前缀匹配，导致缓存命中率极低、费用升高
• 流式事件：转换需要重组事件序列，边界情况（如空 reasoning_content 占位）可能产生异常输出

能用原生协议就用原生协议：Claude 系模型优先走 /v1/messages，GPT 系模型优先走 /v1/responses 或 /v1/chat/completions。

协议不匹配时的三种解法

按优先级尝试

解法一：换一个有对应协议通道的模型（最简单）

用 curl 逐个端点测试，找出 ZiAI 上哪些模型支持你需要的协议：

# 列出可用模型
curl -s https://api.ziai-demo.com/v1/models \
  -H "Authorization: Bearer sk-xxxx" | jq -r '.data[].id'

然后对候选模型逐个打目标端点，能通的就用它。

---

解法二：用 CC-Switch 做本地协议转换（最通用）

CC-Switch 的本地代理能把 Codex 发出的 Responses 请求转成上游的 Chat Completions，再把流式响应转回 Responses 格式， 并覆盖推理内容与工具调用。

适用：ZiAI 上目标模型只有 Chat 通道，但你要接到 Codex。 操作：编辑 Codex 供应商 → 打开「需要本地路由映射」→ 填模型映射表 → 开启本地路由服务与 Codex 接管 → 重启 Codex。 详见 CC-Switch：上游格式怎么选。

---

解法三：换一个客户端（最省事）

如果 ZiAI 上目标模型只有 Chat Completions 通道，而你需要的是编程 Agent： ChatBox / CherryStudio / ZCode / WorkBuddy 都走 Chat 协议，可以直接用； 只有 Codex 强制要求 Responses。

快速自检清单

• 我知道我的客户端要求哪种协议（查配置速查表）
• 我用 curl 直接打过那个协议的端点，确认能通
• 地址的 /v1 层级符合该客户端的拼接规则
• 模型 ID 是从 /v1/models 或操练场逐字复制的
• 鉴权头正确（Claude Code 用 ANTHROPIC_AUTH_TOKEN）
• Anthropic 协议请求带了 anthropic-version 与 max_tokens

全部勾选后仍有问题 → 常见报错速查