OpenAPI 概览

OpenAPI 面向脚本、CLI 和自建面板，用个人 Access Token（mgpat_ 前缀）以你本人的身份读取账户数据。

Base URL：https://modelgo-web-api.modelgo.ai/api/openapi/v1
机器可读规格：OpenAPI JSON / YAML

认证

在控制台「个人设置 → 安全与登录 → Access Token」生成 Token（每个账号同时只有一个有效 Token）。完整明文只展示一次。

http

Authorization: Bearer mgpat_xxxxxxxx

只接受 Bearer Token；不接受控制台会话 Cookie / CSRF。
Token 跟随账号，不绑定租户；可访问该账号所有 active 成员租户。
改密、重置密码、停用账号会立即撤销 Token。

选择租户

用 X-Tenant-Id 指定租户；不传时使用账号的默认租户（余额、用量、费用三个接口的特殊行为见下）。

传了非成员租户 → 403 forbidden / access_denied。
余额、用量、费用：不传 X-Tenant-Id 时返回该账号全部有权限租户的列表 {"items":[...]}；传了则返回单对象。无权租户不会出现；单个租户读取失败时该项 error=unavailable（余额为 balance_status=unavailable）。

错误结构

所有失败使用真实 HTTP 状态码，响应体固定为：

json

{
  "error": {
    "code": "invalid_request",
    "error_class": "invalid_request",
    "reason": "status",
    "message": "human readable",
    "request_id": "...",
    "trace_id": "..."
  }
}

请按 code + reason 分支，message 仅供排查。

HTTP	code	说明
400	`invalid_request`	参数缺失或不合法，`reason` 指出字段
401	`invalid_token`	Token 缺失/格式错误/不存在/已撤销/已过期
401	`unauthorized`	单次调用不存在或不在可见范围（不区分）
403	`forbidden`	非租户成员 / 角色无权
404	`not_found`	资源或路径不存在
409	`conflict` / `idempotency_conflict`	资源状态冲突 / 幂等键复用
429	`rate_limited`	超出限流，按 `Retry-After` 重试
500/503	`internal_error` / `idempotency_unavailable`	服务端错误 / 幂等存储不可用

限流

接口	每 Token 限额
余额	60 / 分钟
用量、费用、调用详情	30–60 / 分钟
管理 Key / 导出写入	10 / 分钟

超限返回 429，带 Retry-After 与 X-RateLimit-Limit/Remaining/Reset。

约定

金额是结算币种（国内 CNY、海外 USD）的十进制字符串，不做汇率换算。
时间是 UTC RFC3339。
列表与导出使用 opaque cursor（cursor + has_more/next_cursor）。
写操作（创建/修改/删除 Key、创建导出）必须带 Idempotency-Key；同键同请求重放同一响应，同键不同请求返回 409 idempotency_conflict。