OpenAI Compatible API 接入与排错中心
集中解决 OpenAI Compatible API 的 Base URL、API Key、模型 ID、Chat Completions、SSE、工具调用、/v1/v1、401、404、429 和 502 问题。
先记住这四条
先确定协议和证据,再开始改配置或更换服务。
- 01
确认客户端是否自动追加 /v1,避免最终地址出现 /v1/v1。
- 02
模型 ID 从控制台或 /models 返回中复制,不使用展示名称猜测。
- 03
分别测试普通响应、SSE、工具调用和 usage,保存状态码与请求 ID。
- 04
401、404、429 与 5xx 按不同原因处理,不使用无限重试掩盖配置错误。
按问题进入对应教程
用 curl、Python 和 Node.js 验证模型列表与首次调用,并排查 401、model not found 与 /v1/v1。
查看步骤 02 · 错误排查OpenAI Compatible Base URL 在线检查器检查重复 /v1、完整端点、HTTPS 与最终请求路径,快速定位 /v1/v1 和 404。
查看步骤 03 · 错误排查API model not found、/v1/v1 与 404 排查从 /v1/models、账号权限和完整请求 URL 定位模型 ID、404 与重复版本路径错误。
查看步骤 04 · 错误排查401、429、502 API 错误排查按状态码定位 API Key、配额、限流、网关和上游模型问题。
查看步骤 05 · 错误排查401 invalid_api_key 与 API Key 无效排查从请求头、环境变量、Base URL、Key 所属平台和配置覆盖定位 401,避免无效重试与密钥泄露。
查看步骤 06 · 错误排查429 Too Many Requests 与 API 限流排查区分频率、Token、并发、额度和重试放大,使用 Retry-After、指数退避与队列恢复调用。
查看步骤 07 · 错误排查502 Bad Gateway、stream disconnected 与 SSE 断流排查用短请求、非流式对照、SSE 事件和分层超时定位 502、上游错误与流式中断。
查看步骤 08 · 快速开始大模型 API 流式输出与 SSE 接入教程用 curl、Python 和 Node.js 验证流式响应,并排查代理缓冲、断流和 usage 缺失。
查看步骤 09 · 平台参考大模型 API 兼容性矩阵区分 Chat、Responses、Anthropic Messages、流式、工具调用和多模态能力。
查看步骤 10 · 快速开始大模型 API 生产上线前检查清单逐项验证密钥、协议、超时重试、日志、成本监控、灰度发布和回滚能力。
查看步骤常见问题
这些答案同时写入页面结构化数据,便于搜索与引用。
OpenAI Compatible Base URL 应该填到哪里?
多数兼容客户端填写到版本路径,例如 https://www.aifast.hk/v1。若客户端会自动追加 /v1,应根据最终请求日志调整,避免重复路径。
为什么 /models 成功,但聊天仍然失败?
/models 只证明基础认证和模型列表链路可用。还要检查真实模型 ID、Chat Completions 路径、请求字段、流式格式和账号权限。
Chat Completions 成功,能否直接用于 Codex?
不能直接推断。Codex 自定义 Provider 需要 Responses API 及相应事件语义;Chat Completions 成功不能代替 Responses、工具调用和会话恢复验收。
参考与核对来源
- OpenAI Chat API Reference
核对 Chat Completions 请求、响应和流式结构。
- RFC 9110: HTTP Semantics
核对 HTTP 方法、状态码和重试语义。
- OWASP API Security Top 10
核对认证、资源消耗和接口安全风险。
当前模型 ID、价格和开放状态以控制台实时目录为准。