OpenAI compatible API Key 怎么用？从配置到首次调用
简答：OpenAI compatible API Key 的用法可以概括为：把 Key 放进 Authorization: Bearer 请求头，在客户端设置服务商提供的 Base URL，再使用该服务商已授权的模型名发起一次请求。官方 OpenAI API 可直接使用 /v1/responses；第三方兼容接口必须以其文档确认的路径、协议和模型列表为准。
定义：OpenAI compatible API Key 是用于访问遵循部分 OpenAI 请求格式的模型接口凭据，但它不代表所有服务都支持相同的 Base URL、接口路径、模型字段和响应格式。
先记住：兼容 API 只需要核对三个参数
使用 OpenAI compatible API Key 前，先准备三项信息：API Key、Base URL 和模型名。API Key 用于身份认证；Base URL 决定请求发往哪个 API 服务；模型名必须是当前账户或项目允许调用的标识。
这类接口的“兼容”通常只表示部分请求结构接近 OpenAI，并不自动保证所有接口、参数、流式事件或工具调用都一致。官方 OpenAI API 的认证格式是 Authorization: Bearer API_KEY，官方文档也建议把 Key 保存在服务端环境变量或密钥管理系统中，而不是写进浏览器代码。OpenAI API Reference
| 参数 | 正确形式 | 常见错误 |
|---|---|---|
| API Key | 作为 Bearer 凭据发送 | 多复制空格、使用已删除 Key、把 Admin Key 当普通调用 Key |
| Base URL | 以服务商文档为准，确认是否已经包含 /v1 | 重复拼接 /v1、把完整接口路径再当 Base URL |
| 模型名 | 使用当前模型列表中已授权的 ID | 凭记忆填写旧模型名、名称大小写不一致、账户没有权限 |
第一步：获取并安全保存 API Key
如果使用官方 OpenAI API，应在 API Key 管理页面创建密钥。完整密钥通常只在创建时显示；如果没有保存，不能依赖页面再次查看，应创建新 Key 并更新应用配置。已删除的 Key 不能继续使用。OpenAI Help Center：Where do I find my OpenAI API Key?
如果使用第三方兼容服务，Key 应从该服务自己的账户控制台或管理入口获取。公开资料无法确认某个服务的具体申请流程、权限规则或有效期时，应以当前账户页面和服务商文档为准，不要把其他平台的 Key 直接混用。
建议把密钥放进环境变量：
export OPENAI_API_KEY="你的_API_Key"Windows PowerShell 可以使用：
setx OPENAI_API_KEY "你的_API_Key"重新打开终端后再运行程序。不要把真实 Key 提交到 Git 仓库、前端 JavaScript、浏览器开发者工具或截图中。官方 SDK 会读取 OPENAI_API_KEY 环境变量，Python SDK 还建议使用 .env 配合环境变量，避免把密钥写入源码。OpenAI Developer quickstart
第二步：确认 Base URL 与接口路径的关系
Base URL 不是随意填写的网站首页，也不一定是完整的接口地址。你需要先确认客户端会如何拼接路径，再决定是否包含 /v1。
- 官方 OpenAI API：官方示例请求地址为
https://api.openai.com/v1/responses，请求头使用 Bearer 认证。 - 第三方兼容服务：如果文档把 Base URL 写成类似
https://example.com/v1，客户端通常会在后面继续拼接资源路径；如果文档要求填写根域名，则不要自行补上/v1。 - 完整接口路径：
/v1/responses或/v1/chat/completions是资源路径，不应在已经包含完整路径的情况下再次拼接。
可以用这个公式自查：最终请求地址 = Base URL + SDK 或代码追加的资源路径。如果结果出现 /v1/v1、重复的 /responses，优先修正 Base URL，而不是更换 Key。
OpenAI Python 和 Node.js 官方 SDK 都提供自定义 Base URL 配置；这说明 SDK 层面可以切换兼容端点，但不代表目标服务一定完整支持 Responses API。OpenAI Python SDK OpenAI Node.js SDK authentication
第三步：先用 curl 发起一次最小请求
先用 curl 验证，比同时排查客户端、插件和代码更容易定位问题。官方 OpenAI Responses API 的最小请求如下，模型名应以当前官方模型文档和账户可用范围为准：
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "你的可用模型名",
"input": "Say hello in one sentence."
}'如果你使用第三方兼容服务，不要直接照抄上面的域名、路径或模型名。将 URL、模型和协议替换为该服务当前文档明确提供的值；公开资料无法确认时，先查看控制台的模型列表或请求示例。
成功判定不应只看 HTTP 200，还要确认响应中存在服务商文档声明的输出字段。Responses API 与 Chat Completions API 的请求体和返回结构不同，不能只替换 URL 就假定两者完全兼容。OpenAI 当前文档将 Responses 作为主要 API 表面，同时官方 Python SDK 仍说明 Chat Completions 可继续使用。OpenAI API Reference OpenAI Python SDK README
Python 和 Node.js 中怎么配置兼容 Key
Python 示例使用官方 SDK 的 api_key 与 base_url 参数。下面的 Base URL 只是格式示例，必须替换成你已核实的兼容服务地址：
import os
from openai import OpenAI
api_key = os.environ.get("OPENAI_API_KEY")
base_url = os.environ.get("OPENAI_BASE_URL")
if not api_key:
raise RuntimeError("缺少 OPENAI_API_KEY")
if not base_url:
raise RuntimeError("缺少 OPENAI_BASE_URL")
client = OpenAI(api_key=api_key, base_url=base_url)
response = client.chat.completions.create(
model="你的可用模型名",
messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(response.choices[0].message.content)Node.js 示例：
import OpenAI from "openai";
const apiKey = process.env.OPENAI_API_KEY;
const baseURL = process.env.OPENAI_BASE_URL;
if (!apiKey) throw new Error("缺少 OPENAI_API_KEY");
if (!baseURL) throw new Error("缺少 OPENAI_BASE_URL");
const client = new OpenAI({ apiKey, baseURL });
const response = await client.chat.completions.create({
model: "你的可用模型名",
messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(response.choices[0].message.content);如果目标服务只声明支持 Responses API，就把代码改为对应的 responses.create 请求；如果只支持 Chat Completions，就不要强行调用 /responses。具体支持范围必须以服务商当前文档为准。
Cursor、Cline、Dify 和 Open WebUI 的通用配置顺序
- 先确认工具是否允许自定义 OpenAI-compatible Provider、Base URL 或 API Endpoint。
- 把 API Key 填入密钥字段，不要把
Bearer前缀重复写进只要求纯 Key 的输入框；如果工具明确要求完整请求头，再按其说明填写。 - 填写 Base URL，并确认工具是否会自动追加
/v1。 - 模型名填写服务端已授权的精确 ID，不要填写展示名称或自定义别名。
- 先关闭流式输出、工具调用和高级参数，发送一条最短文本；最小请求成功后，再逐项开启流式、函数调用或多模态能力。
不同工具的字段名称和协议支持会变化，因此不能把一个客户端的配置截图或参数名原样套到另一个客户端。遇到连接失败时，先用同一组 Key、Base URL 和模型名跑 curl，再回到工具内逐项对照。
401、403、404 和超时：按现象排查
| 现象 | 先检查什么 | 下一步 |
|---|---|---|
| 401 Unauthorized | Key 是否为空、复制错误、已删除或 Bearer 格式错误 | 重新创建或轮换 Key，并确认程序读取的是当前环境变量 |
| 403 Forbidden | 项目、账户、模型或接口权限 | 查看账户页面和服务商文档确认授权范围，不要仅靠更换模型名猜测 |
| 404 Not Found / model not found | URL 是否重复 /v1，模型 ID 是否准确 | 先打印最终请求地址，核对接口协议与模型列表 |
| 429 Too Many Requests | 速率限制、并发或账户额度 | 降低并发、按文档退避重试，并查看用量与限制说明 |
| 超时或流式中断 | 网络、客户端超时、流式协议是否支持 | 先关闭流式并发送短请求，再逐项恢复超时和流式设置 |
OpenAI API Reference 将错误码、限流和请求 ID 作为生产排查内容；对于第三方兼容服务，错误字段和限制可能不同，最终应以实际响应和服务商文档为准。OpenAI API Reference
安全清单：Key 能用不等于可以随便放
- 服务端读取环境变量，浏览器端不要直接保存长期 API Key。
- 为不同项目分配不同 Key，便于撤销、轮换和定位用量。
- 日志中不要打印完整 Authorization 请求头或完整错误对象中的凭据。
- 发现 Key 泄露后，立即删除或撤销旧 Key，再更新部署环境。
- 将用量、请求失败率和限流响应纳入监控；第三方服务的计费、并发和额度以当前账户页面为准。
官方文档明确提醒不要分享 API Key，也不应将其暴露在客户端代码中。OpenAI API Reference
常见问题
OpenAI compatible API Key 和 OpenAI API Key 是同一种东西吗？
不一定。它们都可能通过 Bearer Token 认证，但 Key 的签发方、权限、计费、模型范围和接口地址由具体服务决定。兼容接口只能说明请求格式存在相似部分，不能证明两个平台的 Key 可以互换。
Base URL 应该填写到 /v1 吗？
没有统一答案。要看客户端是否自动追加 /v1，以及服务商文档给出的是根地址、版本地址还是完整接口路径。最终请求中出现 /v1/v1 时，通常需要回头检查 Base URL 和客户端的自动拼接规则。
为什么 Key 正确仍然返回 401？
优先检查程序是否读取了正确的环境变量、Authorization 是否使用 Bearer 格式、Key 前后是否有空格、Key 是否已被删除，以及请求是否发到了签发该 Key 的服务端。不要先假设是模型问题。
为什么返回 404 model not found？
可能是模型 ID 拼写错误、模型已下线、账户没有权限，也可能是 Base URL 或接口路径不正确。先用服务商当前模型列表核对精确 ID，再检查最终请求地址。
可以把 API Key 放在 Cursor、Cline 或前端网页里吗？
如果工具或网页代码会把 Key 暴露给浏览器、插件日志或其他用户，就不适合放长期密钥。更稳妥的方式是使用服务端代理、环境变量或工具提供的安全凭据存储，并按需轮换。
相关阅读
- 继续看 401 invalid api key 的一行 cURL 排查
- 继续看 404 model not found 的 Endpoint 与模型排查
- 如果你在 Cursor 中配置，查看 Base URL、Key 和模型名教程
- 如果你在 Dify 中配置，查看兼容模型 API 接入步骤
- 如果你使用 Claude Code，查看 API 接口与模型映射排查