展开本页目录
开始前准备什么
- 记录 SDK 名称、版本、最终路径、状态和脱敏字段。
- 从模型页面与自己的权限确认目标协议。
- 先取消工具、流式、图片与高级参数，只留一条文字。
- 识别 SDK 协议
- 匹配路径与认证
- 修正输入形状
- 更换响应解析
- 验一次小任务
下载三种协议修复夹具
3 组完整前后 JSON，含图片对象和示意错误。
下载离线检查器
检查固定结构，不访问模型端点。
路径、输入和认证放在一起看
OpenAI 客户端通常发送 Bearer 认证；Anthropic SDK 使用自己的认证与版本头。具体 Key 权限和通道接受的认证以配置与实际请求确认。不要把响应下载 CDN、主站教程地址或控制台 URL 当 API 入口。
| 协议 | 最终路径 | 基本输入 | 客户端 Base URL |
|---|---|---|---|
| Chat Completions | /v1/chat/completions | model + messages | OpenAI SDK 通常为 https://api.apizt.com/v1 |
| Responses | /v1/responses | model + input | OpenAI SDK 为 /v1；目标通道需支持 Responses |
| Anthropic Messages | /v1/messages | model + max_tokens + messages | Anthropic SDK 为 https://api.apizt.com 根地址 |
- 协议
- Chat Completions
- 最终路径
- /v1/chat/completions
- 基本输入
- model + messages
- 客户端 Base URL
- OpenAI SDK 通常为 https://api.apizt.com/v1
- 协议
- Responses
- 最终路径
- /v1/responses
- 基本输入
- model + input
- 客户端 Base URL
- OpenAI SDK 为 /v1；目标通道需支持 Responses
- 协议
- Anthropic Messages
- 最终路径
- /v1/messages
- 基本输入
- model + max_tokens + messages
- 客户端 Base URL
- Anthropic SDK 为 https://api.apizt.com 根地址
Chat 请求发到 Responses 的完整修复
DEMO-MODEL 是说明占位，错误文字是协议演示；不能直接用于生产或当作已捕获错误。若目标通道不支持 Responses，应选择 Chat 模型实现与 Chat 请求，而不是删字段后继续撞同一个端点。
一条文字的协议切换示意
json
{
"before": {"endpoint":"/v1/responses","body":{"model":"DEMO-MODEL","messages":[{"role":"user","content":"仅回答 OK"}]}},
"illustrativeError": {"error":{"code":"missing_required_parameter","message":"Missing required parameter: input.","param":"input"}},
"after": {"endpoint":"/v1/responses","body":{"model":"DEMO-MODEL","input":"仅回答 OK"}}
}三组下载夹具，展示完整转换
| 问题 | 缺失 / 混入字段 | 修复 |
|---|---|---|
| Chat body → Responses endpoint | messages 存在，input 缺失 | 构造 Responses input 与 input_image |
| Responses body → Chat endpoint | input 存在，messages 缺失 | 构造 Chat messages 与 image_url 对象 |
| Chat 图片 → Messages endpoint | image_url 类型不属于原生 Messages | 改为 image + source，并保留 max_tokens |
- 问题
- Chat body → Responses endpoint
- 缺失 / 混入字段
- messages 存在，input 缺失
- 修复
- 构造 Responses input 与 input_image
- 问题
- Responses body → Chat endpoint
- 缺失 / 混入字段
- input 存在，messages 缺失
- 修复
- 构造 Chat messages 与 image_url 对象
- 问题
- Chat 图片 → Messages endpoint
- 缺失 / 混入字段
- image_url 类型不属于原生 Messages
- 修复
- 改为 image + source，并保留 max_tokens
本站绘制的内容说明图：本页完整 before/error/after 夹具解释结构转换，不是仅替换端点路径。
返回和流式也要一起转换
只改请求体后，客户端仍按旧结构取值，可能出现 HTTP 200 但正文空白、工具丢失或永远等待。用该 SDK 的实际响应类型解析，记录结束事件；不能把“收到第一段”当完整成功。
| 协议 | 文字返回入口 | 工具 / 流式注意 |
|---|---|---|
| Chat | choices[].message.content | tool_calls、role=tool；流式 delta 需合并 |
| Responses | output 中的 message / output_text | function_call / call_id；事件类型不同 |
| Messages | content 中的 text 块 | tool_use / tool_result；原生事件与结束原因 |
- 协议
- Chat
- 文字返回入口
- choices[].message.content
- 工具 / 流式注意
- tool_calls、role=tool；流式 delta 需合并
- 协议
- Responses
- 文字返回入口
- output 中的 message / output_text
- 工具 / 流式注意
- function_call / call_id；事件类型不同
- 协议
- Messages
- 文字返回入口
- content 中的 text 块
- 工具 / 流式注意
- tool_use / tool_result；原生事件与结束原因
![三种协议返回文本的解析入口：choices[].message.content、output、content、delta](/images/help-specific/diagrams/errors-openai-api-protocol-mismatch--errors-openai-api-protocol-mismatch-2-output.svg)
本站绘制的内容说明图：请求体与返回解析必须成套转换；收到首段文字不等于完整流结束。
SDK 默认协议可能与你预期不同
- OpenAI Agents 默认模型路径使用 Responses，兼容 Chat 的接入应显式使用 OpenAIChatCompletionsModel。
- Anthropic SDK、Claude Code 和 Claude Agent 的配置与验收不同；同一个 Key 文本不代表完全相同的请求。
- Spring AI 2.0 的底层客户端已变化，按当前版本核对 Base URL，避免旧配置拼出重复 /v1。
- 图片、工具、structured output、缓存和 reasoning 都需要目标型号支持，不能由“OpenAI compatible”一句话推断。
先离线查形状，再用准确型号验收
3 组前后请求通过本地形状检查；检查器不发送网络请求，也不确认目标通道供应。修复后用自己的 Key、准确 Model ID 发一次最小文字，再逐个加回图片、工具和流式。
下载检查器与协议 JSON 到同一目录
bash
python3 check-request-fixtures.py protocol-fixtures.json怎样确认已经完成
- SDK 实际协议、路径和请求体一致。
- 认证来自目标账号，Key 未写入源码。
- 响应和结束事件按同一协议解析。
- 每项高级能力在准确型号与通道单独测试。
常见问题
同一个模型可以同时用 Chat 和 Responses 吗？
只有目标服务、通道与权限都提供两种协议时才可以；两者的功能与参数仍需分别验证。
404 一定是 Base URL 错了吗？
也可能是服务未提供该协议、路径或转发配置。保存最终请求 URL，再核对协议供应。
为什么返回 200，页面却没内容？
客户端可能仍按另一协议的响应结构取正文，或没有正确处理流式结束。检查原始脱敏结构与 SDK 解析方式。