控制台与管理接口
用脚本调控制台接口:换令牌、任务与账单端点、管理权限、分页与时间口径。
内容最后核对: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)原样保留。