[Feature]: 暴露 quota / usage API 给第三方, 支持 real-time 拉取 (替代 T+1 延迟)

Feature Request: 暴露 quota / usage API 给第三方，real-time 替代 T+1 延迟

反馈时间：2026-06-08
反馈人：Plus 订阅用户 + CodexBar 第三方工具使用者

---

一、用户场景

我同时是 MiniMax Plus 订阅用户，也是 macOS 菜单栏用量监控工具 CodexBar（@steipete/CodexBar）的用户。

CodexBar 已经在监控 OpenAI Codex / Claude / Cursor / Gemini / MiniMax 等多家 provider，核心体验是：

• 实时显示会话 5h 滚动窗口剩余百分比 + 重置倒计时
• 实时显示每周配额剩余百分比
• 实时显示今日 token 用量 + 近 30 天费用
• 当用量接近耗尽时给出"≈ 30% 耗尽风险"等预警

这套体验依赖一个前提：上游服务方（OpenAI、Anthropic 等）提供官方、real-time、可被第三方调用的 usage / quota API。

---

二、现状（MiniMax 这边缺什么）

1. 没有公开的 usage / quota API
   • mmx-cli 内部有 mmx quota 命令，说明后端 API 是有的，但没文档化 / 没开放给第三方
   • CodexBar 的 MiniMax provider 只能 hack（本地 log 估算）— 数据不准确 + 延迟严重
2. 数据延迟一天（T+1）
   • 平台 dashboard 上 "今日 token 用量" 要到第二天才更新
   • 用户完全无法在消耗异常的当天自助定位
3. quota 数据存在已知 bug（不阻塞 feature request，但希望一起修）
   • #173: mmx quota show video 显示 100% 剩但实际 0/0
   • #48: Token Plan Plus 配置返 0
   • #47: cache 折扣不透明
   • #92: mmx quota show 与 Token Plan dashboard 数据不一致

---

三、建议方案

3.1 短期（先解决 "T+1 延迟"）

把现有内部 quota 端点的刷新频率从 T+1 改成 T+0 / near-real-time（流式或 ≤ 5 分钟延迟）。

3.2 中期（暴露给第三方）

参考 OpenAI 给 Codex 提供的使用量 API 体验：

• 公开 GET /v1/coding_plan/usage 或类似端点
• 至少返回以下字段（按 CodexBar 类工具够用为标准）：
  • current_window_remaining_percent（5h 滚动窗口）
  • current_window_resets_at（ISO 8601 timestamp）
  • weekly_remaining_percent
  • weekly_resets_at
  • today_token_used / today_cost_usd
  • month_token_used / month_cost_usd
  • last_refresh_at
• 走标准 Bearer token 鉴权（用户用 mmx auth login 拿到的 API key 即可调）
• 文档化 + 加 SDK（Node.js / Python / Swift 至少一门）

3.3 长期

• 在 mmx-cli 加 mmx quota serve 启动本地 proxy，让没装 SDK 的工具也能通过本地 socket 拉
• 把 mmx quota 的实现细节（参考 #92）也修一下，跟 dashboard 对齐

---

四、对 MiniMax 团队的价值

• 生态：第三方工具（CodexBar、Hammerspoon 脚本、Slack bot、Prometheus exporter）能自然接入，形成 MiniMax 用量可视化生态
• 降低客服压力：现在 T+1 + 没 API，用户消耗异常时无法自助定位，只能靠工单。开放 API 后这类 issue 大量减少
• 对标 OpenAI：OpenAI 的 usage API 已经是 de facto 行业标准，MiniMax 在做 "Codex 那种 agent CLI" 配套的可视化工具时也应该同步跟上

---

五、参考链接

• OpenAI Usage API: https://platform.openai.com/usage
• CodexBar: https://github.com/steipete/CodexBar
• 相关 issue（MiniMax 侧已知 quota 数据问题）：
  • #173 — video quota 数据不准确
  • #48 — Token Plan Plus 配置返 0
  • #47 — cache 折扣不透明
  • #92 — mmx quota show 与 dashboard 不一致

---

谢谢！

Start by tracing the existing mmx quota command and its internal quota endpoint, then review how mmx auth login supplies credentials. Define the public usage response, refresh behavior, authentication, documentation, and SDK scope; the work is done when third-party clients can retrieve accurate near-real-time quota and usage data through a documented interface.