GPT-Load
GitHub
快速开始 →
文档/ 参考

管理 API

管理台本身就是调用这套接口的。需要脚本化管理分组和密钥时可以直接用。

认证§

/api 下的受保护接口都使用 Bearer 认证：

请求头
Authorization: Bearer 你的 AUTH_KEY 或访问密钥
  • AUTH_KEY——管理权限，可读写配置，也能执行 Reveal 等敏感操作
  • 访问密钥——只允许读取自身范围内的首页、模型、用量和脱敏请求日志， 不能修改配置，也不能查看上游凭据

需要写入或调用路由检查时必须使用 AUTH_KEY。

访问密钥当前只允许读取 /api/auth/session、/api/home、/api/home/statistics、/api/models、/api/usage、/api/logs 和 /api/logs/{request_id}；其他管理路由返回 403。

认证失败锁定§

避免脚本反复重试错误密钥

同一个直接对端地址在 30 分钟内连续 5 次管理认证失败，会被锁定 30 分钟。锁定期间返回 429 和 Retry-After；使用正确的 AUTH_KEY 成功认证会清除失败计数。

响应约定§

统一的返回结构，成功与失败靠 code 区分：

成功
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
失败
{
  "code": "错误标识",
  "message": "人类可读的说明"
}

成功时 code 是数字 0，失败时是字符串标识—— 判断时注意类型。

data 在成功和失败响应中都是可选字段；没有返回数据时会直接省略， 不要假设它始终存在或始终是对象。message 会随Accept-Language 本地化。

程序应判断 code 和结构化 data，不要解析本地化的message。完整错误码与恢复方式见 错误与恢复参考。

写入前提§

请求头哪些接口要求合同
Idempotency-KeyPOST /api/groups
POST /api/groups/{group_id}/credentials/import
POST /api/groups/{group_id}/credentials/connect
POST /api/groups/{group_id}/credentials/{credential_id}/reset-credits/consume
POST /api/access-keys
POST /api/access-keys/{id}/rotate		必须且只能有一个值，格式为规范的小写 UUID v4；同一逻辑操作重试时复用原值
If-MatchPUT /api/settings先读取设置响应中的 ETag，再原样带回；冲突时重新读取并合并
JSON 请求体使用严格合同

声明 JSON 请求体的端点只接受单个对象；未知字段、重复字段、尾随的第二个 JSON 值都会被拒绝。 采用空对象合同的无参数操作只接受空请求体或 {}。

主要资源§

路径用途
/api/auth/session确认当前 Bearer 身份类型
/api/home首页摘要、统计与订阅账号概览
/api/health运行态健康状态
/api/logs请求日志列表与详情
/api/usage用量与成本统计
/api/settings全局运行时设置
/api/system部署信息与版本更新检查
/api/route/inspect只读路由检查
/api/channels渠道描述符、字段与能力
/api/models项目模型列表与上游模型发现
/api/model-prices模型价格查询、同步、修改、重置与删除
/api/groups分组列表、创建、详情、设置、模型与删除
/api/groups/{group_id}/credentials凭据管理，含批量导入、查看真实值、下载
/api/credential-stages订阅凭据的授权、导入、轮询与暂存状态
/api/access-keys访问密钥，含限额与查看真实值
自动化脚本要固定版本

本表记录稳定资源边界，不复制仍在演进的全部端点字段。 当前版本的完整路由合同由代码中的 internal/control/http_routes.go 定义； 自动化脚本应固定 GPT-Load 的精确版本，并在升级后回归实际调用。

几个例子§

列出所有分组
curl http://127.0.0.1:3001/api/groups \
  -H "Authorization: Bearer $AUTH_KEY"
查看健康状态
curl http://127.0.0.1:3001/api/health \
  -H "Authorization: Bearer $AUTH_KEY"
路由检查：这个请求会走哪
curl -X POST http://127.0.0.1:3001/api/route/inspect \
  -H "Authorization: Bearer $AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"protocol":"openai-completions","external_model":"gpt-4o","access_key_id":1}'

access_key_id 是管理台中访问密钥的数字 ID。 路由检查只计算当前配置下的候选结果，不会向上游发送真实请求。

导入凭据：带幂等键
curl -X POST http://127.0.0.1:3001/api/groups/1/credentials/import \
  -H "Authorization: Bearer $AUTH_KEY" \
  -H "Idempotency-Key: 7f6a7f86-3f58-4ae3-a1a1-46d3b8d17b71" \
  -H "Content-Type: application/json" \
  -d '{"credentials":"sk-example"}'

注意事项§

不要暴露到公网

管理接口能读取所有渠道凭据的真实值（/reveal 一类的端点就是干这个的）。AUTH_KEY 泄漏等于全部上游密钥泄漏。
必须限制来源，配置方式见 安全与上生产。

  • 脚本里别硬编码 AUTH_KEY——用环境变量或密钥管理工具
  • 接口会随版本调整——自动化脚本升级后要回归验证
  • 不要自行改变幂等键——结果不明时复用原值；新的逻辑操作再生成新值
← 上一页环境变量
管理 API - GPT-Load