← 回到模型管理

自定义模型接口

给要自己接模型的人看。照着抄就能用，不用问人。

三个概念，先分清

名称是什么干什么用
渠道一家服务商 + 一把密钥比如「一号通道」= DeepSeek + 某把 key
id（代号）你在界面上看到的、聊天记录里存的名字可以自己起，比如 d5、my-model
upstream真正发给服务商的模型名由服务商决定，比如 deepseek-flash

为什么要分开：同一个底层模型可以挂好几份（换不同密钥分开额度）， 界面上各叫各的名字，互不影响。

认证

所有写接口都要管理员身份。先登录拿 cookie，后续请求带着它：

# 1. 登录（成功后会在 cookie 里拿到会话）
curl -c cookie.txt -X POST https://kns-ai.com/api/login \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"admin","password":"你的密码"}'

# 2. 之后的每个请求都带上 -b cookie.txt

/ 加一个模型 POST/api/models/custom

往某个已有的渠道里加一个模型，不动这个渠道的其他模型。加完立即生效，不用重启。

字段必填说明
channel是渠道名，必须已存在（看 GET /api/channels）
id是代号，界面上显示和选择用它
name否界面上显示的名字，留空＝同 id
upstream否真实模型名，留空＝同 id
curl -b cookie.txt -X POST https://kns-ai.com/api/models/custom \
  -H 'Content-Type: application/json' \
  -d '{"channel":"一号通道","id":"d5","name":"D5 轻思考","upstream":"deepseek-flash"}'

# 返回
{"ok":true,"added":"d5","channel":"一号通道","channels":4,"models":15,"default":"d1"}

/ 删一个模型 DELETE/api/models/custom?channel=..&id=..

curl -b cookie.txt -X DELETE 'https://kns-ai.com/api/models/custom?channel=%E4%B8%80%E5%8F%B7%E9%80%9A%E9%81%93&id=d5'

# 渠道里至少要留一个模型；整条不要了请用「删渠道」

/ 加一整条渠道 POST/api/channels

接一家全新的服务商。接口要求符合 OpenAI 规范：POST {地址}/chat/completions、 GET {地址}/models、Authorization: Bearer <密钥>。

DeepSeek、通义、智谱、Kimi、Moonshot、OpenAI、vLLM、Ollama、One-API 都符合。

curl -b cookie.txt -X POST https://kns-ai.com/api/channels \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "某新渠道",
    "base_url": "https://api.example.com/v1",
    "api_key": "sk-xxxx",
    "models": [
      "gpt-4o-mini",
      {"id":"x1","name":"X1 轻","upstream":"gpt-4o-mini"}
    ]
  }'

# models 两种写法都行：纯字符串，或带 id/name/upstream 的对象
这条是整条覆盖：同名渠道会被完全替换，models 里没写的模型就会消失。 只想加一个模型请用上面的 /api/models/custom。

/ 查现状

接口用途
GET/api/channels所有渠道、密钥掩码、每条渠道下有哪些模型
GET/api/models界面上能选的模型清单（按优先级排序）
GET/api/version当前版本
POST/api/channels/test试连一个地址和密钥，返回可用模型列表（不保存）
DELETE/api/channels/{name}删掉一整条渠道

故障切换是怎么排的

同一个模型挂了，会按这个顺序往下试，全自动：

① 这个模型自己的渠道
② 同一个底层模型的其他通道（换一把密钥，比如主 key 欠费就换备 key）
③ 再换别的模型（重思考 → 混元 → 千问 → 智谱）

所以只要同一类模型挂了两个通道，一个出问题另一个就能顶上，用户感觉不到。

改完渠道或模型，服务端会自动重新加载，不用重启。 如果新加的模型不能用，先看：upstream 写对了吗？那个模型在该账号下有权限吗？余额够吗？