写脚本接入 KL API
脚本接入只改两处:OpenAI SDK 的 base_url 带 /v1,Anthropic SDK 不带,Key 读环境变量不写死。(2026-11-22)
更新于
准备工作
- Python 3.9+ 并装了 openai 或 anthropic SDK,或 Node.js 18+ 并装了 openai 包
- 一个 KL API 的 API Key(在控制台创建)
- 知道要用的模型 ID,见 [模型清单](/models)
这篇和快速开始有什么不同
快速开始 是「跑通一次」;这篇是「写进项目里」——可复用的 client、流式、错误分支、并发控制。已经跑通过一次的话,直接从第二节看。
四个地址,别混
两套协议、两个地址,混一个就报错:
| 用途 | 值 | 说明 |
|---|---|---|
OpenAI SDK base_url |
https://agent.kl-api.info/v1 |
带 /v1,SDK 自己拼 /chat/completions |
Anthropic SDK base_url |
https://agent.kl-api.info |
不带 /v1,SDK 自己拼 /v1/messages |
| 环境变量(OpenAI 系工具) | OPENAI_BASE_URL / OPENAI_API_KEY |
读这几个变量的工具会自动生效 |
| 环境变量(Anthropic 系工具) | ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN |
Claude Code 等工具读这组 |
注意
Anthropic SDK 默认地址是 https://api.anthropic.com,本身不含 /v1。照着 OpenAI 的习惯给它加 /v1,请求会变成 /v1/v1/messages,报错原文是 Invalid URL (POST /v1/v1/messages)——这个报错看起来像地址写错,其实是写多了。
Python:一个可复用的 client
不要在每次调用里新建 client,SDK 内部维护连接池,复用才有意义:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["KL_API_KEY"], # 缺失时这里直接 KeyError,比静默传空串好
base_url="https://agent.kl-api.info/v1",
timeout=60.0,
max_retries=2,
)
resp = client.chat.completions.create(
model="gpt-5",
messages=[{"role": "user", "content": "用一句话说明 HTTP 401 是什么"}],
)
print(resp.choices[0].message.content)
print(resp.usage) # 计费按这里返回的 token 数走
Anthropic 协议用另一个 client,注意 max_tokens 是必填:
import os
import anthropic
client = anthropic.Anthropic(
api_key=os.environ["KL_API_KEY"],
base_url="https://agent.kl-api.info", # 不带 /v1
)
msg = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024, # 必填,漏了直接报参数错误
messages=[{"role": "user", "content": "用一句话说明 HTTP 401 是什么"}],
)
print(msg.content[0].text)
Node.js
字段名和 Python 不一样:baseURL(大写 URL)、apiKey:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.KL_API_KEY,
baseURL: "https://agent.kl-api.info/v1",
timeout: 60_000,
maxRetries: 2,
});
const resp = await client.chat.completions.create({
model: "gpt-5",
messages: [{ role: "user", content: "用一句话说明 HTTP 401 是什么" }],
});
console.log(resp.choices[0].message.content);
console.log(resp.usage);
流式输出
长输出一定要开流式,否则容易在默认超时上被掐断。
stream = client.chat.completions.create(
model="gpt-5",
messages=[{"role": "user", "content": "写 200 字介绍 HTTP 缓存"}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
const stream = await client.chat.completions.create({
model: "gpt-5",
messages: [{ role: "user", content: "写 200 字介绍 HTTP 缓存" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
curl -N 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":"写 200 字介绍 HTTP 缓存"}],"stream":true}'
提示
curl 加 -N 关掉本地缓冲,否则你会以为没返回。流式返回的是 SSE,每行以 data: 开头,最后一行是 data: [DONE]。
Responses 还是 Chat Completions
网关两条路都开着,选哪个看你的场景:
| 接口 | 路径 | 什么时候用 |
|---|---|---|
| Chat Completions | /v1/chat/completions |
兼容性最好,绝大多数 SDK、客户端、中转工具默认走这条 |
| Responses | /v1/responses |
需要 OpenAI 新版 Responses 语义(如内置工具调用链路)时 |
提示
模型是否支持某条接口,和网关是否支持是两件事。用 /models 里的 ID 先跑一次非流式小请求,确认能返回再决定用哪条。
错误处理:按状态码分支
四类错误,处理方式完全不同,别用一个大 except 全吞了:
| 状态码 | 原文特征 | 真实原因 | 该怎么办 |
|---|---|---|---|
| 401 | lab token denied |
请求没带 Authorization 头 |
检查代码有没有把 Key 传进 client |
| 401 | Invalid token |
Key 无效、被禁用或余额不足 | 换 Key,别重试 |
| 404 | Invalid URL (POST /v1/...) |
路径拼错,多为多写了 /v1 |
核对 base_url |
| 429 | You have used invalid tokens multiple times |
错 Key 触发临时封禁,按出口 IP | 停手核对 Key,等满 120 秒 |
| 429 | 其它 | 频率或并发超限 | 指数退避重试 |
import time
import openai
for attempt in range(3):
try:
resp = client.chat.completions.create(
model="gpt-5",
messages=[{"role": "user", "content": "ping"}],
)
break
except openai.RateLimitError as e:
if "invalid tokens multiple times" in str(e):
raise SystemExit("Key 无效,已触发 120 秒临时封禁;请核对 Key 后等待再试") from e
time.sleep(2 ** attempt) # 1s、2s、4s
except openai.AuthenticationError as e:
raise SystemExit(f"鉴权失败,不要重试:{e}") from e
注意
不要对 401 做重试循环。 同一个出口 IP 在窗口内累计 6 次用错 Key 会进 120 秒黑名单,而封禁期内每多试一次都会续期——你以为在调试,其实在把自己越锁越久。封禁期间连不带 Key 的请求也会被拦。
验证
不写代码,先把 Key 和地址验掉:
curl https://agent.kl-api.info/v1/models -H "Authorization: Bearer $KL_API_KEY"
能返回模型列表就说明 Key 和地址都对;返回 Invalid token 是 Key 的问题,返回 HTML 是地址的问题。
验证状态
| 项目 | 状态 |
|---|---|
/v1/models、/v1/chat/completions、/v1/responses、/v1/messages 四条路径存在,错误 Key 返回 JSON 401 |
已实测(2026-11-22,原文 Invalid token) |
不带 Authorization 头返回 lab token denied(匿名分支) |
已实测(2026-11-22) |
| 错 Key 累计触发 120 秒封禁,封禁期内不带 Key 也 429 | 已实测(2026-11-22) |
Anthropic SDK 多写 /v1 会打到 /v1/v1/messages,报 Invalid URL |
已实测(Claude Code,2026-11-22) |
| 上面三段示例代码用真 Key 实跑 | 未验证 |
/v1/responses 的返回结构与工具调用 |
未验证(只确认路径存在) |
未验证项会在用真 Key 跑通后更新本表,不提前标成「已验证」。
参考来源(核对于 2026-11-22)
- Anthropic SDK 默认
base_url为https://api.anthropic.com(不含/v1):anthropic-sdk-python 源码_client.py - 接口地址、环境变量命名与最小示例:快速开始
- 报错原文与分层排查:API 报 401、429、超时怎么排查
- 模型 ID 与协议支持:模型清单