写脚本接入 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 内部维护连接池,复用才有意义:

python
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 是必填:

python
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:

javascript
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);

流式输出

长输出一定要开流式,否则容易在默认超时上被掐断。

Python
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)
Node.js
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
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 其它 频率或并发超限 指数退避重试
python
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 和地址验掉:

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

常见问题

Python 里 base_url 到底带不带 /v1?

按 SDK 分:openai 的 base_url 必须带 /v1,因为 SDK 自己拼的是 /chat/completions;anthropic 的不带 /v1,它的默认值是 https://api.anthropic.com,SDK 再拼 /v1/messages。Anthropic SDK 多写 /v1 会打到 /v1/v1/messages,报 Invalid URL (POST /v1/v1/messages)。

401 lab token denied 和 401 Invalid token 有什么区别?

前者是请求里根本没有带 Authorization 头,网关走的是匿名鉴权分支;后者是带了 Key 但 Key 无效、被禁用或余额不足。看到 lab token denied 先检查代码里有没有真的把 Key 传进去,别去查 Key 本身。

报 429 到底是限流还是 Key 错了?

看原文。消息是 You have used invalid tokens multiple times 说明是**用错 Key 触发**的临时封禁,按出口 IP 记、封 120 秒,等满就好,查额度没有用;其它 429 才是真的频率或并发超限,按指数退避重试。

流式输出到一半断了怎么办?

先用非流式跑一次确认 Key、地址、模型都对,再开流式。断流多见于本地代理、公司网关拦截长连接,或客户端默认超时太短。SDK 里把 timeout 调大,并在外层自己包一层 retry,别指望断点续传——OpenAI 与 Anthropic 的流式都不支持从断点继续。

为什么要从环境变量读 Key,写死在脚本里不行吗?

能跑,但会被提交进仓库。脚本一旦推到 GitHub、发给同事或被打包,Key 就跟着走,而且网关侧无法区分是谁在用。用 os.environ["KL_API_KEY"] 或 process.env.KL_API_KEY 读,缺失时让程序直接报错退出。