CodexBar Provider 用量 API 规格指南：MiniMax、Deepgram、Groq 与 LLM Proxy 对接要点
CodexBar Provider 用量 API 规格指南MiniMax、Deepgram、Groq 与 LLM Proxy 对接要点【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar本文基于仓库内 QA 技能参考文档.agents/skills/qa-test/references/api-specs.md编写围绕 CodexBar 在对接各 LLM 服务商用量统计接口时必须遵循的官方 API 规格展开哪些端点、哪种凭据类型、需要什么权限以及在修改 fetcher 之前应如何核对规格。读完本文你将掌握 MiniMax 三类 key 的差异、Deepgram 的 Management 权限要求、Groq 的 Prometheus 指标接口形态、以及 LLM ProxyLiteLLM 生态/v1/quota-stats的契约并能结合 GroqUsageFetcher.swift、LLMProxyUsageFetcher.swift、MiniMaxUsageFetcher.swift 等源码读懂实际调用链。CodexBar 通过统一的门菜单栏面板展示 OpenAI Codex、Claude Code 等工具的用量其中不少 provider 的用量统计来自服务商各自的计量 API 或 Web 控制台页面。由于这些 API 的凭据类型、权限模型和返回格式各不相同且服务商经常调整规格仓库要求开发与 QA 人员在修补 fetcher 之前先对照官方文档核对行为而不是凭旧经验直接改代码。本文即对这一API 规格指针工作流及其背后的实现细节做完整展开。为什么要先核对官方 API 规格在 CodexBar 的实时 QA 流程见 .agents/skills/qa-test/SKILL.md中遇到provider 工作/失败类报告时第一条规则就是当前 API 行为只以官方 provider 文档为准。api-specs.md对此给出的理由是——不同 provider 的用量接口在凭据模型上差异极大凭经验推断很容易踩坑。仓库的Known CodexBar QA Notes记录了四个真实踩坑点全部与规格核对直接相关OpenAI 只有 Admin API key 才是可用的用量 provider key项目级OPENAI_API_KEY可能以 403 失败于旧的 credit-balance 回退逻辑Deepgram 用量查询需要带 Management API 权限的 key/project仅转录用途的 key 会返回 403Groq 用量走的是 Prometheus 指标 API而不是普通推理端点MiniMax 的 pay-as-you-go API key 与 Token Plan / Coding Plan key 是不同类型放错 key 会导致用量不可用。因此在 patch 任何 fetcher 之前优先访问官方文档搜索llms.txt索引或对应的指标/配额文档页确认接口形态是保证修复一次到位的前提。下面按 provider 逐一展开规格要点与源码印证。MiniMax三种凭据、两类 key取数路径是分层的文档指针https://platform.minimax.io/docs/llms.txt。关键结论是key 类型不同pay-as-you-go按量付费API key 与 Token Plan / Coding Plan套餐key 是两种不同的凭据不能混用。从源码看CodexBar 的 MiniMax 用量取数实现了完整的凭据分层见 MiniMaxUsageFetcher.swiftWeb Cookie 路径以浏览器 Cookie 访问 Coding Plan 页面优先尝试解析页面内嵌的__NEXT_DATA__Next.js 数据其次解析 HTML 文本中的plan_name、可用次数、已用百分比、重置时间等字段MiniMaxUsageParser.parse并带有登出检测页面出现sign in/log in/登录/登入即抛invalidCredentials。API Token 路径以Bearer apiToken请求套餐余额接口。对.global区域默认先试全球端点若返回invalidCredentials再重试中国大陆端点避免旧配置回归。请求头中额外携带MM-API-Source: CodexBar标识来源见fetchAPIUsageOnce。余额补充通过user-center/payment/coding-plan?cycle_type3与v1/api/openplatform/coding_plan/remains、v1/token_plan/remains逐级 fallback随后尝试附加订阅元数据与账单历史account/amount分页拉取单页上限 100 条遇到 30 天窗口之前的记录即停止。凭据模式由 MiniMaxAuthMode.swift 的resolve(apiToken:cookieHeader:)决定三者都为空是.none有 API Token 优先.apiToken此时不再允许 Cookie否则回退.cookie。这也解释了文档中key 类型不同的根源——apiToken与cookie代表两套完全不同的认证体系而 Token Plan 与 Coding Plan 又对应不同的 remains 端点。因此配置 MiniMax 时需要先确认自己购买的是按量付费还是套餐Token Plan / Coding Plan再决定在 CodexBar 中填入 API Key 还是导入浏览器 Cookie填错类型时用量取数会静默不可用或直接报invalidCredentials。Deepgramusage/project API 要求 Management 权限与项目级 key文档指针https://developers.deepgram.com/llms.txt。核心约束是usage/project API 需要 Management 权限且必须使用 project-scoped项目级的 key。仅有转录transcription权限的 key 调用用量接口会返回 403——这也是 QA 笔记中记录的已知问题。CodexBar 的 Deepgram 集成通过 DeepgramProviderDescriptor.swift 将凭据建模为两层API key 项目project/workspaceID并通过workspaceIDValidationOrder: 5声明了校验顺序。环境变量约定见 DeepgramSettingsReader.swiftDEEPGRAM_API_KEY主 API keyDEEPGRAM_PROJECT_ID项目workspaceIDDEEPGRAM_API_URL可选端点覆盖缺省使用官方默认 API URL。由于 usage 查询是挂在具体 project 下的只有同时具备项目标识与 Management 权限的 key 才能返回有效数据。排查 Deepgram 用量失败时优先确认key 是否绑定到目标项目、该项目是否开通 Management API 权限、控制台地址https://console.deepgram.com/project/下能否看到用量页。Groq用量来自 Prometheus 指标 API而非推理端点文档指针https://console.groq.com/docs/prometheus-metrics。用量指标使用https://api.groq.com/v1/metrics/prometheus这是 Groq 区别于其他 provider 的最大特点——它暴露的不是一个用量余额 JSON 端点而是一套 Prometheus 兼容的查询接口。源码实现位于 GroqUsageFetcher.swift实际请求路径为{apiURL}/metrics/prometheus/api/v1/query以GETAuthorization: Bearer apiKey发起一次用量刷新并行执行四条 PromQL 查询queryScalar使用async let并发指标PromQL 查询展示含义请求速率sum(model_project_id_status_code:requests:rate5m)每分钟请求数输入 token 速率sum(model_project_id:tokens_in:rate5m)每分钟输入 token输出 token 速率sum(model_project_id:tokens_out:rate5m)每分钟输出 token缓存命中速率sum(model_project_id:prompt_cache_hits:rate5m)每分钟缓存命中响应解析在parseScalar中完成GroqPrometheusResponse解码status/data.result[].value[]取每个序列最后一个值累加value元素可能是数字也可能是字符串解码器对两者做了兼容PrometheusValue枚举。401/403 会被归类为accessDenied与key 无权限/失效的排查路径对齐。需要注意两点均有源码注释佐证GroqProviderDescriptor.swift 中该路径被描述为Enterprise-tier 的 Prometheus metrics fallback仅对开通了该功能的组织级 API key 生效标准 key 在此端点会得到 404 并直接视为无数据。该策略不是唯一来源fetch plan 按sourceModes: [.auto, .web, .api]组织.web模式优先走控制台平台 API用浏览器stytch_session_jwtsession cookie 认证返回真实 spend/token/request 历史仅在缺少会话或会话失效时才 fallback 到 Prometheus API key 路径shouldFallback对missingSession/invalidSession/accessDenied返回 true。因此Groq 用量是否可见取决于你的凭据类型有控制台会话则走console路径只有开通 Prometheus 指标功能的 org API key 则走metrics路径普通推理 key 两种都拿不到用量这是服务端权限决定的不是 bug。LLM Proxy / LiteLLMCodexBar 期望LLM-API-Key-Proxy兼容的/v1/quota-stats文档指针https://docs.litellm.ai/。CodexBar 对 LLM Proxy 的接入契约是需要 LLM-API-Key-Proxy 兼容的/v1/quota-stats端点外加一个 base URL。也就是说CodexBar 不直接对接 LiteLLM 的通用代理接口而是依赖其生态中提供配额统计的quota-stats服务。凭据配置约定见 LLMProxySettingsReader.swiftLLM_PROXY_API_KEY代理 API keyLLM_PROXY_BASE_URL代理 base URL支持通过enterpriseHost配置投影descriptor 中supportsEnterpriseHost: true。base URL 会像其他 provider 覆盖一样做安全校验key 以 Bearer token 形式发送到该 URL因此公共主机必须 HTTPS仅允许 loopback 或私网地址使用明文 HTTP且 URL 不得内嵌凭据ProviderEndpointOverrideValidator().validatedURLAllowingPrivateNetworkHTTP。端点的构造逻辑在 LLMProxyUsageFetcher.swift 的quotaStatsURL(baseURL:)若 base URL 路径末段不是v1自动追加v1再拼quota-stats。请求为GETBearer认证成功响应为 JSONCodexBar 会解码以下契约字段顶层providers以 provider 名称为 key 的统计对象每项含credential_count、active_count、exhausted_count、total_requests、tokensinput_cached/input_uncached/output、approx_cost、quota_groups顶层summarytotal_requests、approx_cost、total_tokens可选缺失时由各 provider 汇总quota_groups[].remaining_percent与reset_time用于计算全局最低剩余百分比与下一次重置时间。解码器同时兼容数组与字典两种quota_groups形态并对reset_time做 ISO8601含/不含小数秒双重解析同时过滤掉已过去的 reset 时间避免陈旧的过去时间点覆盖真正即将到来的重置点。最终展示上LLMProxyUsageSnapshot.toUsageSnapshot主指标是100 - minimumRemainingPercent的已用百分比辅以总请求数、总 token 数、近似花费approx_cost汇总并按请求量排序给出 Top 3 provider 明细行。面向用户的回答引用官方文档时附来源链接api-specs.md还规定了一条回答规范当在面向用户的答案中引用这些文档时应浏览当前页面并附上来源链接。这意味着引用 MiniMax、Deepgram、Groq、LiteLLM 的行为时应访问其当前文档页或llms.txt索引确认内容仍然有效而不是转述过期结论给出的答案应包含可追溯的官方出处便于用户自行核实权限要求或端点形态若文档内容与 CodexBar 行为不一致应以官方当前规格为准再评估是否需要调整 fetcher、设置项或测试见 QA Fix TriageWrong provider API/spec: inspect official docs, then patch fetcher/settings/tests。如何验证对接是否正确测试与 QA 矩阵仓库为上述四个 provider 的解析逻辑提供了针对性测试可作为规格核对后的回归依据GroqTests/CodexBarTests/GroqUsageFetcherTests.swift 覆盖 Prometheus 响应的标量解析与错误分类LLM ProxyTests/CodexBarTests/LLMProxyUsageFetcherTests.swift 覆盖quota-stats快照解析、URL 构造与quota_groups两种形态MiniMaxTests/CodexBarTests/MiniMaxAPITokenFetchTests.swift、MiniMaxCurrentTokenPlanResponseTests.swift、MiniMaxTokenPlanChangeTests.swift 覆盖 API token 取数、Token Plan 响应与多服务解析通用安全Tests/CodexBarTests/ProviderEndpointOverrideSecurityTests.swift 验证各 provider 端点覆盖的 HTTPS/私网白名单校验。在实时环境中可运行 QA 脚本Scripts/下的 provider 用量矩阵或按 .agents/skills/qa-test/SKILL.md 的指引使用打包 CLI 逐 provider 验证并遵循缺凭据则禁用该 provider、规格不符则先查官方文档再改 fetcher、行为变更需更新 CHANGELOG的修复原则。小结四个 provider 的用量接口形态差异是 CodexBar fetcher 维护中最容易出错的区域概括如下Provider官方规格入口凭据/权限要求核心端点或契约MiniMaxplatform.minimax.io/docs/llms.txtpay-as-you-go key 与 Token/Coding Plan key 类型不同支持 API Token 与浏览器 Cookie 两种模式v1/token_plan/remains、v1/api/openplatform/coding_plan/remains、Coding Plan 页面 HTML/__NEXT_DATA__Deepgramdevelopers.deepgram.com/llms.txtusage/project API 需要 Management 权限与项目级 key仅转录 key 会 403项目级 usage API需DEEPGRAM_API_KEYDEEPGRAM_PROJECT_IDGroqconsole.groq.com/docs/prometheus-metrics仅 Enterprise org key 可用 Prometheus 指标标准 key 404https://api.groq.com/v1/metrics/prometheus四条rate5mPromQL 查询LLM Proxy / LiteLLMdocs.litellm.ai/LLM-API-Key-Proxy 兼容服务需 base URL API key/v1/quota-stats自动补v1字段含quota_groups.remaining_percent、reset_time、approx_cost改动 fetcher 之前先到官方文档核对规格改动之后用仓库内对应测试与 live QA 矩阵回归验证即可把凭据类型不符权限不足端点形态变化这三类最常见问题挡在发布之前。【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考