OpenAI 兼容接口怎么接:base_url、key、model 三个参数一次说清
OpenAI 兼容接口的请求与返回结构与 OpenAI 一致,接入只需改 base_url、api_key、model 三个参数。(2026-11-21)
发布于 · 更新于
三个参数分别管什么
| 参数 | 作用 | 典型值 | 改错会怎样 |
|---|---|---|---|
base_url |
请求发到哪台服务器 | https://agent.kl-api.info/v1(OpenAI SDK) |
404 或连不上 |
api_key |
身份凭证 | sk- 开头的一串字符 |
401 lab token denied |
model |
调哪个模型 | gpt-5、claude-sonnet-4-6 |
404 model not found |
可填的模型名见 模型清单。三个参数里最容易错的是 base_url 的结尾,下面单独说。
base_url 结尾的 /v1 不是可选项
OpenAI 的 Python / Node SDK 会在 base_url 后面直接拼 /chat/completions。所以:
- OpenAI SDK:
base_url要写到/v1为止 ——https://agent.kl-api.info/v1 - Anthropic SDK:
base_url不要带/v1——https://agent.kl-api.info,因为该 SDK 自己会拼/v1/messages
这两条写反,症状都是 404,但打到的路径不一样,看一眼请求 URL 就知道错在哪:
| 写错的地方 | 实际请求路径 | 你会在日志里看到 |
|---|---|---|
OpenAI SDK 的 base_url 少了 /v1 |
https://你的域名/chat/completions |
缺路径段 |
Anthropic SDK 的 base_url 多了 /v1 |
https://你的域名/v1/v1/messages |
路径重复 |
Python 接入
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["KL_API_KEY"],
base_url="https://agent.kl-api.info/v1",
)
resp = client.chat.completions.create(
model="gpt-5",
messages=[{"role": "user", "content": "用一句话说明什么是 base_url"}],
)
print(resp.choices[0].message.content)
要点:
- Key 走环境变量,不要写死在代码里。
model用服务商支持的模型名,查 模型清单 确认;示例里的 GPT-5 有单独的价格与参数页。- 流式输出把
stream=True加上即可,接口结构不变。
Node.js 接入
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.KL_API_KEY,
baseURL: "https://agent.kl-api.info/v1",
});
const resp = await client.chat.completions.create({
model: "gpt-5",
messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);
注意 Node SDK 的参数名是 baseURL(大写 URL),Python 是 base_url,写错不会报错,只会回落到默认的 OpenAI 官方地址——这是最常见的一种「以为接上了其实没接上」。
用 curl 做一次最小自检
curl https://agent.kl-api.info/v1/chat/completions \
-H "Authorization: Bearer $KL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5","messages":[{"role":"user","content":"你好"}]}'
返回里只要有 choices[0].message.content,就说明三个参数都对了。这一步跑通再改业务代码,能省掉一半排查时间。
三种协议怎么选
| 协议 | 路径 | 适用 SDK | 什么时候选它 |
|---|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions |
OpenAI 官方 SDK、绝大多数第三方库 | 默认选它,兼容性最好 |
| OpenAI Responses | /v1/responses |
OpenAI 新版 SDK | 需要 Responses 专有特性时 |
| Anthropic Messages | /v1/messages |
Anthropic 官方 SDK、Claude Code | 用 Claude 系模型且要 Anthropic 原生参数 |
一张表看结论:新项目用 OpenAI Chat Completions 起步,需要 Anthropic 专有参数(如 anthropic-beta 请求头、缓存控制)时再切 Messages 协议,例如调用 Claude Sonnet 4.6。
常见报错与原因
401 lab token denied 是什么原因
这是网关返回的鉴权失败原文(完整响应里带 type: new_api_error 和一串 request id)。Key 本身错了或没带上。按顺序查:请求头里有没有 Authorization: Bearer 前缀、Key 是否被禁用、账户是否欠费。三种情况原文不同,看原文即可区分。
如果原文里出现的是厂商错误码(如 invalid_api_key),说明请求已经穿过网关、是上游拒绝的,属于上游鉴权问题,处理方向与网关层不同。
404 model not found 是什么原因
model 值不在服务商模型清单里。别猜名字,直接查 模型清单。同一个模型在不同服务商可能叫法不同。
请求超时或首字节很慢是什么原因
先分清是连不上还是算得慢:curl -w "%{time_connect} %{time_starttransfer}" 能分别看到连接耗时和首字节耗时。连接慢是链路问题,首字节慢是模型推理问题,处理方式完全不同。
参考来源(核对于 2026-11-21)
- OpenAI SDK 的
base_url需以/v1结尾:https://github.com/openai/openai-python/blob/main/README.md - Anthropic SDK 默认
base_url为https://api.anthropic.com(不带/v1):https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_client.py - GPT-5 上下文 272,000 输入 / 128,000 输出:https://openai.com/index/introducing-gpt-5-for-developers/
- Claude Sonnet 4.6 上下文 1M、$3/$15:https://claude.com/resources/articles/1m-context-ga
- 站内网关 401 原文
lab token denied:GET https://agent.kl-api.info/v1/models(不带 Key)实测,2026-11-21