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 接入

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)

要点:

  1. Key 走环境变量,不要写死在代码里。
  2. model 用服务商支持的模型名,查 模型清单 确认;示例里的 GPT-5 有单独的价格与参数页。
  3. 流式输出把 stream=True 加上即可,接口结构不变。

Node.js 接入

javascript
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 做一次最小自检

bash
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)

链接失效时以厂商文档当前版本为准;页面内的价格与模型清单以 /pricing 和 /models 为准。

常见问题

换成兼容接口后,代码要改多少?

只改三个参数(base_url、api_key、model),SDK 和业务代码其余部分不用动,也不需要降级 SDK 版本。

兼容接口和官方接口有什么区别?

请求路径、请求体与返回结构一致,差别在计费方式、可用模型清单和上游线路;业务代码不需要感知这些差异。

一个 Key 能调多个厂商的模型吗?

能。model 参数决定路由到哪个模型,Key 只用于身份鉴权,因此同一个 Key 可以调用不同厂商的模型。支持范围见 模型清单,价格见 价格与计费。

下一步