OpenAI compatible API endpoint 怎么填？
简答：先看软件字段名称：如果字段叫 Base URL 或 API Endpoint，通常填写服务商的基础地址，例如 https://api.openai.com/v1 或 http://localhost:1234/v1，不要把 /chat/completions 一起填进去。然后分别填写 API Key 和 Model ID，最后用 /models 或 /chat/completions 发一次最小请求验证。是否添加 /v1，必须以服务商文档和客户端是否自动拼接路径为准。
定义：OpenAI compatible API endpoint 是一个遵循部分 OpenAI 请求格式的接口入口，通常由 Base URL、认证方式、模型 ID 和具体资源路径共同组成。
先按这张表填写：Endpoint、Base URL、API Key 和模型名不是一回事
如果你正在配置 Cursor、Dify、OpenWebUI、SDK 或其他支持自定义接口的软件，先不要直接复制一个完整请求地址。大多数配置页面会把请求拆成多个字段：Base URL 负责确定服务入口，API Key 负责认证，Model ID 负责指定模型，客户端再自动补上 /chat/completions、/responses 或其他资源路径。
本文是 onomeo.cyou 的第三方技术整理页面，不代表任何接口服务商的官方网站。接口字段、模型列表和兼容能力可能变化，正式接入前应以对应服务商当前文档和实际响应为准。
| 配置项 | 应该填写什么 | 常见错误 |
|---|---|---|
| Base URL / API Endpoint | 服务商的基础 API 地址，通常包含协议、域名和必要的版本路径 | 填写了完整的 /chat/completions，或重复添加 /v1 |
| API Key | 对应服务商签发的密钥；本地服务有时可以留空或使用占位值 | 把不同服务商的 Key 混用，或把前后空格一起复制 |
| Model ID | 服务商返回或文档列出的准确模型标识 | 填写展示名称、旧别名、大小写错误或不存在的模型 |
| Request Endpoint | 由客户端和协议决定的最终路径，例如 /v1/chat/completions | 把完整请求路径再次粘贴到 Base URL 字段 |
以 OpenAI 的 Chat Completions 为例，官方请求地址是 https://api.openai.com/v1/chat/completions，但配置客户端的 Base URL 通常应填写 https://api.openai.com/v1，具体字段行为还要看软件是否会自动追加路径。可参考 OpenAI Chat Completions 官方接口说明。
到底要不要加 /v1？用“客户端拼接规则”判断
/v1 不是所有兼容接口都必须存在，也不是所有软件都要求你手动填写。正确判断方法是先确认配置字段的语义，再观察软件实际发送的请求。
- 字段叫 Base URL：通常填写基础地址，例如
https://api.openai.com/v1、https://openrouter.ai/api/v1或http://localhost:1234/v1。 - 字段叫完整 Endpoint：按照软件文档要求填写完整资源地址，不能套用 Base URL 的规则。
- 软件自动补路径：如果程序会把输入地址与
/chat/completions拼接，就不要把该路径写入 Base URL。 - 服务商文档没有 /v1：不要自行补上。DeepSeek 官方示例的 OpenAI SDK 配置使用
https://api.deepseek.com，其请求方式和模型名称应以当前官方文档为准，可参考 DeepSeek API 官方首次调用说明。 - 出现重复路径：如果日志显示
/v1/v1/...，说明客户端和你填写的地址都添加了版本路径；删除其中一处后再试。
因此，不要把“所有 OpenAI compatible API 都必须加 /v1”当成固定规则。OpenRouter 官方开发者页面明确使用 https://openrouter.ai/api/v1 作为兼容接口入口；LM Studio 官方示例则使用 http://localhost:1234/v1。两者都说明了一个共同原则：配置时填 Base URL，具体资源路径由客户端或请求代码继续拼接。
参考：OpenRouter 官方开发者页面、LM Studio OpenAI 兼容接口文档。
云端与本地服务怎么填：可直接套用的示例
下面的地址只表示官方文档中公开的接口示例，不代表所有客户端都支持全部协议能力。模型 ID 需要从对应服务商的模型列表、控制台或 /models 响应中确认，不建议凭记忆填写。
| 场景 | Base URL 示例 | API Key | 模型名 | 注意事项 |
|---|---|---|---|---|
| OpenAI | https://api.openai.com/v1 | 填写 OpenAI API Key | 填写当前可用模型 ID | 最终请求可使用 /chat/completions 或其他官方支持的资源 |
| OpenRouter | https://openrouter.ai/api/v1 | 填写对应 API Key | 通常是供应商与模型组成的标识 | 官方示例使用兼容的 Chat Completions 格式 |
| DeepSeek | https://api.deepseek.com 或按目标客户端文档填写 | 填写 DeepSeek API Key | 使用官方文档列出的模型 ID | 官方 SDK 示例与某些图形化客户端的 Base URL 写法可能不同 |
| Ollama 本地服务 | http://localhost:11434/v1/ | 客户端要求时可填占位值 | 填写本机已安装模型标识 | 本地服务通常忽略 Key；Docker 内的 localhost 不一定指向宿主机 |
| LM Studio | http://localhost:1234/v1 | 按客户端要求留空或填写占位值 | 使用 LM Studio 中的模型标识 | 先在 LM Studio 中启动本地服务器 |
Ollama 官方文档给出了本地 http://localhost:11434/v1/ 的 OpenAI 客户端示例，并说明本地服务要求提供一个 Key 值但会忽略它，可参考 Ollama OpenAI 兼容接口文档。LM Studio 官方文档则列出 /v1/models、/v1/responses 和 /v1/chat/completions 等兼容路径，可参考 LM Studio OpenAI Compatibility Endpoints。
Docker 场景：如果 OpenWebUI 或其他客户端运行在容器里，容器中的 localhost 通常指向容器自身，而不是宿主机。OpenWebUI 官方连接指南建议，在特定 Docker 场景下将宿主机地址改为 host.docker.internal，但实际可达性还取决于操作系统、网络模式和容器配置，可参考 OpenWebUI OpenAI-Compatible 连接指南。
用最小请求验证：先测地址，再测模型和功能
配置页面保存成功，不等于接口真的可用。建议按“地址—认证—模型—协议功能”的顺序验证，日志中只保留脱敏后的 URL、状态码和错误类型，不要打印完整 API Key。
- 先请求模型列表：如果服务支持模型发现，可尝试：
curl "$BASE_URL/models" \
-H "Authorization: Bearer $API_KEY"其中 BASE_URL 应该是你准备填入客户端的 Base URL，例如 https://api.openai.com/v1，而不是已经带有 /models 的完整地址。部分兼容服务不实现模型列表接口，返回 404 或 405 不一定代表聊天接口不可用；这时应从官方文档获取 Model ID 后手动填写。
- 再发最小 Chat Completions 请求：
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"messages": [{"role": "user", "content": "Reply with OK"}],
"stream": false
}'成功判定不应只看 HTTP 200，还要检查响应是否包含可读取的消息内容，例如 Chat Completions 常见结构中的 choices[0].message.content。OpenAI 官方接口说明也将响应描述为包含 choices 的 Chat Completion 对象，具体字段仍以目标服务实际返回为准。
注意协议差异：Chat Completions、Responses API 和 Anthropic Messages 并不是只改一个 URL 就能完全互换。即使某服务声明兼容 OpenAI，也可能只支持文本对话，不支持工具调用、结构化输出、视觉输入或流式事件。先用普通文本请求验证，再单独验证你真正需要的功能。
401、403、404 和连接失败怎么分流
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| 401 Unauthorized | Key 是否为空、复制错误、前后有空格，Authorization 是否由客户端自动添加 | 重新生成或复制对应服务的 Key，确认没有把其他平台的 Key 填入 |
| 403 Forbidden | 账号权限、项目权限、模型权限、来源限制或网关策略 | 查看响应正文和服务商控制台，不要只根据状态码判断原因 |
| 404 Not Found | Base URL 是否多了或少了 /v1，是否重复拼接路径，模型 ID 是否存在 | 打印最终请求地址，分别测试 /models 与 /chat/completions |
| 连接超时 | 域名解析、代理、防火墙、Docker 网络、本地服务是否启动 | 先用 curl 测试同一环境，再确认容器访问宿主机的地址 |
| 流式输出中断 | 客户端是否支持 SSE、网关是否转发流式响应、模型是否支持流式 | 先将 stream 设为 false，确认非流式请求正常后再测试流式 |
最小排错闭环是：确认 Key → 确认 Base URL → 确认最终请求地址 → 确认 Model ID → 发送非流式最小请求 → 再测试工具调用或流式输出。不要把某个兼容网关的行为直接当成所有 OpenAI-compatible API 的统一规则。
常见问题
OpenAI compatible API endpoint 可以直接填 https://api.openai.com/ 吗？
如果软件字段是 Base URL，通常应根据客户端规则填写 https://api.openai.com/v1；如果软件会自动补版本路径，则可能要求填写不带 /v1 的地址。最可靠的方法是查看该软件的字段说明，并检查最终请求是否出现 /v1/v1。
Base URL 要不要写 /chat/completions？
大多数 Base URL 配置不需要写。通常只填写基础地址，例如 https://openrouter.ai/api/v1，客户端再拼接 /chat/completions。只有当字段明确要求完整 Endpoint URL 时，才按照该软件文档填写完整路径。
API Key 可以留空吗？
云端服务一般不能留空，需要填写该服务签发的 Key。部分本地服务不做认证，客户端仍可能要求输入一个值；例如 Ollama 官方本地示例使用占位值，服务端会忽略它。不要把云端密钥写入前端代码、公开仓库或未脱敏日志。
为什么 /models 返回 404，但聊天请求可能还能用？
有些兼容服务没有实现模型列表接口，或使用了非标准模型发现路径。因此 /models 失败不能单独证明聊天接口不可用。可以从官方文档确认 Model ID，手动填写后直接发送一个非流式 Chat Completions 最小请求。
Docker 里填写 localhost 为什么连不上本地模型？
因为容器中的 localhost 通常指向容器自身，而不是宿主机。可根据运行环境尝试 host.docker.internal、宿主机局域网 IP 或容器网络服务名，并确认本地模型服务器监听在容器可访问的地址和端口。
相关阅读
- 继续看 OpenAI compatible API Key、Base URL 与模型名的完整配置
- 如果返回 401，按 API Key 和认证头逐项排查
- 如果返回 404，查看模型不存在、权限和 Endpoint 的分流方法
- 如果请求超时，按连接、代理和 SDK 分层定位
- 在 Dify 中配置 OpenAI 兼容模型接口
参考资料
- OpenAI Chat Completions API 官方接口说明
- OpenRouter 官方开发者页面（openrouter.ai）
- DeepSeek API 官方首次调用说明（api-docs.deepseek.com）
- Ollama OpenAI 兼容接口官方文档（docs.ollama.com）
- LM Studio OpenAI Compatibility Endpoints 官方文档（lmstudio.ai）
- OpenWebUI OpenAI-Compatible 连接指南（docs.openwebui.com）