OpenAI Compatible API 兼容性排查：SDK、Chat 与 Responses

一句话结论

“OpenAI Compatible”通常表示部分请求格式可以复用，但不代表 Chat Completions、Responses API、工具调用、图像、视频和 Anthropic Messages 全部兼容。

如果你遇到的是“OpenAI SDK 能发出请求，但实际业务仍失败”，先用OpenAI Compatible Base URL 检查器核对最终路径，再用模型质量检测验证模型声明、SSE 和工具调用，最后按API 错误排查手册定位具体状态码。

curl 成功但 OpenAI SDK 失败，先查哪一层？

先比较同一个模型、Key、协议与请求体，再判断是否为 SDK 兼容问题。curl 请求 Chat Completions 成功，不能证明 SDK 的 Responses 请求成功。HTTP 200 返回 HTML、缺少预期字段或流式未结束，也不能算兼容通过。

Python 的 base_url 与 JavaScript 的 baseURL 是不同客户端字段。先记录安装版本和最小请求差异，排错时关闭自动重试；超时后先核对用量日志，避免同一任务重复计费。分享记录前删除认证头、Cookie 和客户输入。

用官方 SDK 离线核对请求差异

同样填入 https://www.aifast.link/v1，Chat 方法追加 /chat/completions，Responses 方法追加 /responses。两者的请求体也不同，换 Base URL 不会自动转换协议。先对齐 curl 和 SDK 的路径、模型与字段，再增加业务参数。

Python 超时以秒计，Node 以毫秒计；不要把 timeout: 30 当成 30 秒。关闭 SDK 重试后，还需检查业务外层是否自动重试。这里的 30 秒只是排错示例，不是长任务的统一生产设置，也不保证超时后没有扣费。

Link 独立 GitHub 提供 [email protected] 的离线请求示例：SDK 的 fetch 被本地替身接管，不读取真实 Key、不发送模型请求，只输出固定演示的 URL、方法和请求体。依赖安装需要连接 npm；安装后的示例离线运行。它能展示客户端如何构造请求，不能证明 Link 模型、SSE 或工具调用已经通过。

下载并运行官方 SDK 离线示例

npm ci --prefix examples/sdk --ignore-scripts
node examples/sdk/capture-request.mjs chat
node examples/sdk/capture-request.mjs responses
npm test --prefix examples/sdk

先下载上方仓库，在仓库根目录运行。chat 输出 /v1/chat/completions 与 messages；responses 输出 /v1/responses 与 input。YOUR_MODEL_ID 为占位符，fixtureOnly: true 代表离线演示，不是线上调用成功。错误地址回归还会验证：把完整 /chat/completions 端点填进 baseURL，会造成端点重复。

本节于 2026-11-06 核对官方 SDK 文档；页面底部的实测日期不因此更新。需要真正验证账号权限和模型行为时，继续执行下文的单次限时请求，并自行核对用量。

接口能力矩阵

Link 站提供 GPT、Claude 与 Gemini 模型。下表说明需要分别验收的协议，不代表每个模型都支持全部能力。

2026-10-12 的目录包含图像生成型号 gpt-image-2。图片输入与图片生成使用不同接口；Gemini 的多模态能力也应按所选型号验证。当前目录未列出独立视频、Embedding 或 Rerank 型号，检索服务需另行核对。

Gemini 两种协议的配置与验证边界

如何区分目录声明与实测结果

这是一份核验清单，不是所有 Link 模型的已通过列表。请为所选模型和分组分别记录证据状态。

需要 SDK 初始化与最小请求时，阅读OpenAI Compatible API 接入教程；本页用于逐项记录目标业务的验收结果。

Chat 成功，为什么 Codex 或 Claude Code 仍失败？

一次 Chat Completions 成功，只能证明那次请求所用的模型、分组与 Chat 路径可用。Codex 需要单独核对 Responses；Claude Code 需要核对 Anthropic Messages。保留同一测试条件，逐项增加流式和工具调用，才能找出差异。

• Codex：核对 Provider 配置与 Responses 路径。不要把 Chat 响应直接当作 Responses 事件解析。
• Claude Code：核对根地址、认证变量与 Messages。不要把 OpenAI SDK 的配置原样套给 Claude Code。
• model not found 与 404：区分模型权限和路径错误。先检查同一个 Key 的可见模型，再判断端点。
• 502 与断流：核对终止事件及超时。收到 HTTP 200 或首个事件不等于完整任务已成功。

记录一个最小可复核结果

下面是待填写的验收模板，不是 Link 已通过的测试报告。一次只改变一个条件；填写响应证据前保持“未验证”，失败时停止自动重试并核对是否产生计费。删除 Key、Cookie、用户输入和个人信息后再分享。

Checked at / timezone:
Client / version:
Model ID / API Key group (no key):
Protocol / final request path:
HTTP status / Content-Type:
Non-streaming output: unverified
Stream terminal event: unverified
Tool call and result round-trip: unverified
Usage / billing record: unverified
Request ID / redacted error:

建议的验证顺序

1. 验证认证和模型列表

curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 30 \
  https://www.aifast.link/v1/models \
  -H "Authorization: Bearer ${AIFAST_LINK_API_KEY:?Set AIFAST_LINK_API_KEY locally before running}"

2. 验证最小 Chat 请求

curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 30 \
  https://www.aifast.link/v1/chat/completions \
  -H "Authorization: Bearer ${AIFAST_LINK_API_KEY:?Set AIFAST_LINK_API_KEY locally before running}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "Reply with OK only."}],
    "stream": false
  }'

先在本机设置独立的 AIFAST_LINK_API_KEY，并替换 YOUR_MODEL_ID。以上是待自行执行的示例，不是已完成的调用记录；生成请求可能计费。缺少 Key 时命令直接停止，每条请求最多等待 30 秒且不自动重试；超时不代表服务端没有处理或扣费。

3. 单独验证目标客户端需要的能力

• Codex：重点验证 Responses API 和工具事件。
• Claude Code：重点验证 Anthropic Messages 入口和认证变量。
• Dify：验证所选模型类型、凭据和工作流节点。
• OpenWebUI、Chatbox、Cherry Studio：验证 Base URL 自动拼接和模型 ID。
• Agent：单独测试工具调用、长任务、超时和失败恢复。

上线判断标准

只有目标业务真实使用的能力全部通过，才能判断该接入适合生产。建议保存：

• 最终请求 URL 和状态码。
• 响应 Content-Type。
• 请求 ID 或错误正文。
• 实际模型 ID。
• 客户端版本和配置方式。
• 流式、工具调用和超时测试结果。