文档目录

控制台与管理接口

用脚本调控制台接口:换令牌、任务与账单端点、管理权限、分页与时间口径。

内容最后核对:2026-11-18

本页目录

可以用脚本或 API 方式调用

可以。控制台接口与模型接口用两套凭据:模型调用用 API 密钥(sk-ag- 开头),控制台接口用登录后拿到的访问令牌(Authorization: Bearer <access_token>)。两者不通用,也不能互相替代。

换令牌

# 1. 用账号口令登录,换一对令牌(访问令牌默认 15 分钟有效)
curl -s -X POST "$BASE/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"username":"you@example.com","password":"your-password"}'

响应:

{"access_token": "eyJhbGciOi...", "refresh_token": "6f1c...",
 "token_type": "Bearer", "expires_in": 900,
 "user": {"id": 7, "username": "you", "role": "user"}}
# 2. 带着访问令牌调接口
curl -s "$BASE/api/jobs?page=1&size=20" -H "Authorization: Bearer $ACCESS"

# 3. 过期后换新令牌,不必重新输口令
curl -s -X POST "$BASE/api/auth/refresh" \
  -H 'Content-Type: application/json' \
  -d '{"refreshToken":"6f1c..."}'

脚本里要注意的四件事

  • 访问令牌会过期。 有效期由本站配置(默认 15 分钟),过期返回 401 auth.token_expired;用刷新令牌换新的即可。
  • 刷新令牌一次性。 每换一次,响应里给出新的一对,旧刷新令牌立即失效。脚本必须保存最新值,否则下一次刷新会被拒(401 auth.session_revoked)。
  • 开启两步验证的账号,登录第一步不返回令牌,而是返回 {"totp_required": true, "challenge_token": "..."};再调 POST /api/auth/totp/login({"challengeToken": "...", "code": "123456"})才拿到令牌。
  • 少数敏感操作需要二次验证。 查看渠道密钥、修改渠道密钥、审批这类动作,在账号开启两步验证时要求 5 分钟内验证过:先调 POST /api/auth/stepup({"code": "123456"}),返回 {"validForSeconds": 300},再执行原操作。

不需要令牌的端点

站点元信息、公告、模型广场、登录注册与找回密码这些匿名可读,其余都要令牌:

端点说明
GET /api/meta站点地址、货币与换算口径、注册开关
GET /api/announcements已上架且已到发布时间的公告
GET /api/square/models模型广场的价目与能力(不含上游线路信息)
GET /api/auth/status登录页需要的开关状态

用 API 密钥调 /api/** 会被拒:401 auth.key_on_console。这是刻意的 —— 一把能改自己余额的密钥,等于没有余额。

任务

端点说明
GET /api/jobs分页列表,按 status 筛选(page + size)
GET /api/jobs/{id}单个任务(含 upstreamId、failCode、settleStatus)
GET /api/jobs/{id}/events状态迁移流水
GET /api/jobs/{id}/content产物字节(访问令牌即可,与 API 密钥无关)
POST /api/jobs/{id}/poll立即向上游查一次,不必等自动轮询
POST /api/jobs/{id}/refresh-url续期产物链接
POST /api/jobs/{id}/cancel取消

控制台的「异步任务」页就是这几个端点的组合。poll 是排障用的:自动轮询有间隔,手动触发一次能立刻看到上游的答复。

账号与密钥

端点说明
GET /api/keys / POST /api/keys列出 / 签发密钥(明文只在创建响应里出现一次)
POST /api/keys/{id}/status?enabled=启用 / 停用
DELETE /api/keys/{id}删除
GET /api/me当前身份、角色、可用模型分组

没有「改额度」的端点:额度是账户级的,密钥本身没有上限(见鉴权与密钥)。

用量与账单

端点说明
GET /api/logs使用日志(range / status / q / page / pageSize,每页上限 200)
GET /api/billing/balance余额
GET /api/billing/ledger流水
GET /api/billing/orders充值订单
GET /api/meta站点元信息:api_base_url、货币、换算口径、注册开关

管理接口

管理端点(渠道、模型、定价、用户、公告、支付)都需要对应的权限,不是「登录了就能改」。权限按资源划分,管理员可以只给某人「公告」的权限而不给「渠道」。

管理员与敏感操作都会留下记录:谁、什么时候、改了什么。这也是排障时判断「这个配置是谁改的」的唯一可靠来源。

分页与筛选

筛选参数按端点不同。日志的 status 同时接受归类值与原始值(failed、SUBMIT_FAILED 都能筛),因为两个都有调用方在用;任务的 status 同理。

时间

接口返回 UTC。控制台按浏览器时区渲染。自己写脚本时注意:时间串可能不带时区后缀,要按 UTC 解析;带偏移的(+08:00)原样保留。