日晷 · 接入文档
兼容 OpenAI 接口规范。把 Base URL 换成网关地址即可,现有代码基本无需改动。
- Base URL
https://api.ylyrigui.com- 接口协议
- OpenAI 兼容(
/chat/completions、/models等) - 鉴权方式
Authorization: Bearer <你的 API Key>- 数据格式
- JSON(流式输出为 SSE)
快速开始
第一步:拿到 API Key
API Key 由服务方签发,形如 sk-gw-xxxxxxxx…。请妥善保管 —— 它等同于你的账号,泄露后他人可以消耗你的额度。
第二步:发起第一次调用
curl https://api.ylyrigui.com/p/kopilot/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"messages": [{"role": "user", "content": "你好"}]
}'
只用改一个地方。 如果你已经在用 OpenAI SDK,把
base_url 指向
https://api.ylyrigui.com/p/<路由短名> 即可,其余代码不用动。
鉴权方式
支持三种携带方式,任选其一:
| 方式 | 写法 | 建议 |
|---|---|---|
| 请求头(标准) | Authorization: Bearer sk-gw-… | 推荐 |
| 自定义头 | x-api-key: sk-gw-… | 兼容部分客户端 |
| URL 参数 | ?key=sk-gw-… | 仅调试用,会留在日志里 |
无论用哪种方式,密钥都不会被转发给上游 —— 网关会剥离它并替换成上游凭据。
可用路由
每个路由对应一组上游能力,路径格式为 /p/<路由短名>/<接口路径>。
Kopilot 全模型
/p/kopilot
gpt-6-astragpt-5.6-solgpt-5.6-terragpt-5.6-lunaclaude-fable-5-1claude-opus-5claude-fable-5claude-sonnet-5grok-4.6grok-4.5
模型列表
当前可用的模型:
gpt-6-astragpt-5.6-solgpt-5.6-terragpt-5.6-lunaclaude-fable-5-1claude-opus-5claude-fable-5claude-sonnet-5grok-4.6grok-4.5
也可以随时通过接口获取:GET https://api.ylyrigui.com/p/<路由短名>/models
代码示例
Python(openai 官方 SDK)
from openai import OpenAI
client = OpenAI(
api_key="sk-gw-你的密钥",
base_url="https://api.ylyrigui.com/p/kopilot",
)
resp = client.chat.completions.create(
model="gpt-6-astra",
messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
Python(流式)
stream = client.chat.completions.create(
model="gpt-6-astra",
messages=[{"role": "user", "content": "写一首短诗"}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
Node.js(openai SDK)
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "sk-gw-你的密钥",
baseURL: "https://api.ylyrigui.com/p/kopilot",
});
const resp = await client.chat.completions.create({
model: "gpt-6-astra",
messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);
Node.js(原生 fetch,流式)
const res = await fetch("https://api.ylyrigui.com/p/kopilot/chat/completions", {
method: "POST",
headers: {
Authorization: "Bearer sk-gw-你的密钥",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gpt-6-astra",
messages: [{ role: "user", content: "你好" }],
stream: true,
}),
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
process.stdout.write(decoder.decode(value, { stream: true }));
}
流式输出
在请求体里加上 "stream": true,响应会变成 text/event-stream(SSE),逐块返回。
data: {"choices":[{"delta":{"content":"你"}}]}
data: {"choices":[{"delta":{"content":"好"}}]}
data: {"choices":[],"usage":{"prompt_tokens":5,"completion_tokens":2,"total_tokens":7}}
data: [DONE]
网关是边收边发的,不会缓存整个响应再返回。如果你在客户端看到「卡很久然后一次性出现」,
多半是中间有代理开启了响应缓冲 —— 请检查 CDN 或企业网关是否对 SSE 做了缓冲。
响应格式
成功时与 OpenAI 规范一致。错误时统一返回以下结构,无论错误来自网关还是上游:
{
"error": {
"message": "人类可读的错误说明",
"type": "invalid_request_error",
"code": "invalid_request"
}
}
错误码
| HTTP | code | 含义与处理建议 |
|---|---|---|
| 401 | unauthorized | 密钥缺失、无效、过期或已停用。检查请求头。 |
| 402 | insufficient_balance | 余额不足。请联系服务方充值。 |
| 403 | forbidden | 不在允许范围:模型未授权、来源 IP 受限、或账号被停用。 |
| 404 | not_found | 路由短名不存在,检查 URL 里的 /p/xxx。 |
| 405 | method_not_allowed | 该路由不允许此 HTTP 方法。 |
| 429 | rate_limit_exceeded | 超出速率限制(RPM/TPM)。按 Retry-After 响应头退避重试。 |
| 429 | quota_exceeded | 配额用尽(请求数 / token / 金额)。 |
| 502 | upstream_error | 网关无法连接上游。稍后重试;持续出现请联系服务方。 |
| 503 | route_disabled | 路由或上游已停用。 |
| 504 | upstream_timeout | 上游超时。长回答请考虑改用流式,或缩短 max_tokens。 |
限流与配额
以下限制按 API Key 维度生效,具体数值以服务方配置为准:
| 限制 | 说明 |
|---|---|
| RPM | 每分钟请求数上限。超出返回 429。 |
| TPM | 每分钟 token 数上限。超出返回 429。 |
| 请求数配额 | 密钥生命周期内的总调用次数上限。 |
| token 配额 | 密钥生命周期内的总 token 上限。 |
| 金额配额 | 密钥生命周期内的总消费上限。 |
| IP 白名单 | 可选。启用后仅允许指定来源 IP 调用。 |
收到 429 时请读取
Retry-After 响应头(单位:秒),按其指示等待后重试,
并加指数退避。不要在收到 429 后立刻重试,那只会让情况更糟。
计费说明
- 费用按「每次调用固定价 + 每 1K token 单价」计算,具体单价见上方可用路由。
- token 数优先取上游返回的
usage字段,精确到实际消耗。 - 极少数上游不回传
usage时,会按请求与响应的字节数估算,并在用量记录里标记为「估」。 - 余额不足时调用会被直接拒绝(402),不会产生欠费。
- 每次调用都会记录:时间、状态码、模型、token、费用、延迟、来源 IP。可通过账户中心查询。
常见问题
返回 401,但密钥看起来没问题
- 确认是
Authorization: Bearer sk-gw-…,Bearer 后面有一个空格 - 确认密钥没有多余的空格或换行(从网页复制时容易带上)
- 确认密钥未被吊销或过期
返回 403,模型不在允许列表
你的密钥或所用路由限制了可用模型。错误信息里会列出可选值。调用
GET /p/<路由短名>/models 可以拿到完整列表。
能否直接连上游,不经过网关?
不能。网关负责鉴权、限流、计费与审计,是唯一的接入入口。
支持 Function Calling / 图片输入 / 其他高级参数吗?
支持。网关是透明转发 —— 请求体和响应体逐字节透传,不做任何解析或改写
(除了检查 model 字段用于白名单校验)。上游支持什么,你就能用什么。
响应时间多长算正常?
非流式调用通常在数秒内返回,取决于模型和回答长度。建议对长回答使用流式,体验更好也更不容易超时。