余额与花费查询

下面四个只读端点回答两个问题：「我还剩多少？」和「我花了多少？」，不用打开控制台。它们用你调模型时的同一把 API key 鉴权，不计费，由 RouteMux 自己应答。

你想知道	调用
这把 key 还能花多少？	`GET /v1/user/balance`
我的账户今天、本月花了多少？	`GET /v1/account/info`
这一把 key 花了多少，额度还剩多少？	`GET /v1/key/info`
我用的工具只认 OpenAI 的计费端点	`GET /v1/dashboard/billing/subscription`

key 的传法与调模型完全相同，见认证。所有金额单位都是 美元（USD）。

账户余额与花费

curl https://api.routemux.com/v1/account/info \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY"

{
  "data": {
    "wallet": {
      "available_credit_usd": "42.180000",
      "total_credit_usd": "42.180000",
      "negative_credit_limit_usd": "0.000000",
      "month_spend_usd": "57.820000",
      "day_spend_usd": "3.410000"
    },
    "burn_rate": {
      "avg_daily_usd": "1.927333",
      "days_remaining": 21
    },
    "alerts": { "balance_low_threshold_usd": "5.000000" },
    "auto_topup": null,
    "campaign_credits": []
  },
  "requestId": "…"
}

字段	含义
`wallet.available_credit_usd`	现在能花的钱：余额减去正在进行中的请求预留的金额。
`wallet.total_credit_usd`	包含上述预留在内的余额。
`wallet.negative_credit_limit_usd`	余额最低能降到多少，低于它新请求会被拒绝 —— 为 `0` 或一个很小的负数。见负余额。
`wallet.day_spend_usd`	今天已扣金额，从 UTC 0 点起算。
`wallet.month_spend_usd`	本自然月已扣金额，从本月 1 日 UTC 0 点起算。
`burn_rate.avg_daily_usd`	最近 30 天总花费除以 30。
`burn_rate.days_remaining`	按这个速度，可用余额还能撑几整天。最近 30 天没有花费时为 `null`。
`alerts.balance_low_threshold_usd`	你在控制台设置的低余额提醒阈值，未设置时为 `null`。
`auto_topup`	预留字段，目前恒为 `null`。
`campaign_credits`	账户上限定模型的活动额度。每一项包含 `campaignName`、`models`、`grantedUsd`、`remainingUsd`、`callsThisPeriod`、`nextRefreshAt` 和 `periodEndsAt`。

花费统计的是账户下所有 key 的合计，按实际扣费金额计算，用赠送额度支付的部分也算在内；失败的请求记为 0。一个请求在结算完成后才计入花费 —— 进行中时，它只通过预留金额让 available_credit_usd 变小。

单把 key 的花费与额度

curl https://api.routemux.com/v1/key/info \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY"

{
  "data": {
    "key": {
      "id": "…",
      "name": "prod-backend",
      "tags": [],
      "status": "active",
      "expires_at": null
    },
    "wallet": {
      "available_credit_usd": "42.180000",
      "today_spend_usd": "3.410000",
      "month_spend_usd": "57.820000"
    },
    "limits": {
      "monthly_credit_limit_usd": "50.000000",
      "monthly_used_usd": "12.500000",
      "monthly_remaining_usd": "37.500000",
      "daily_credit_limit_usd": null,
      "daily_used_usd": "0.830000",
      "daily_remaining_usd": null,
      "allowed_models": [],
      "rate_windows": []
    }
  },
  "requestId": "…"
}

这把 key 自己的花费在 limits 里，不在 wallet 里

这里的 wallet.* 与 /v1/account/info 一样，是整个账户的数据。这把 key 自己花了多少，看 limits.monthly_used_usd 和 limits.daily_used_usd。

字段	含义
`key.expires_at`	key 的过期时间，永不过期时为 `null`。
`limits.monthly_used_usd`	这把 key 从本月 1 日 UTC 0 点起的扣费；如果你之后重置过这把 key 的用量，则从重置时起算。
`limits.daily_used_usd`	这把 key 从额度时区当天 0 点起的扣费（额度时区在控制台的 key 设置里，默认跟随账户时区）；重置过则从重置时起算。
`limits.monthly_credit_limit_usd`、`limits.daily_credit_limit_usd`	这把 key 设置的花费上限。`null` 表示不限。
`limits.monthly_remaining_usd`、`limits.daily_remaining_usd`	上限减已用，最小为 `0`。不限时为 `null`。
`limits.allowed_models`	这把 key 限定可调的模型。为空表示你有权限的所有模型都能调。
`limits.rate_windows`	预留字段，目前恒为空。

简单余额

只想要一个数字的脚本和工具用这个：

curl https://api.routemux.com/v1/user/balance \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY"

{ "balance": 37.5, "is_active": true, "currency": "USD" }

balance 是这把 key 还能花的钱，取三者中最小的：钱包可用余额、这把 key 的月度剩余额度、每日剩余额度。所以设了小额上限的 key，这里显示的数会比钱包余额小。

和其他端点不同，它直接返回对象（没有 data 外层），balance 是数字而不是字符串。 base URL 只填到域名根的工具，也可以用不带 /v1 的 /user/balance。

OpenAI 格式的计费端点

有些工具通过 OpenAI 的计费端点读取余额。这两个端点都支持，带不带 /v1 前缀都可以：

curl https://api.routemux.com/v1/dashboard/billing/subscription \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY"

{
  "object": "billing_subscription",
  "has_payment_method": true,
  "soft_limit_usd": 37.5,
  "hard_limit_usd": 37.5,
  "system_hard_limit_usd": 37.5,
  "access_until": 0
}

hard_limit_usd 与上面的 balance 是同一个数。GET /v1/dashboard/billing/usage 恒返回 total_usage: 0，所以按「上限减用量」计算的工具得到的正好是你的真实余额。它不反映你花了多少 —— 查花费请用 /v1/account/info。

单次请求花了多少

这些端点只返回汇总，不返回单次请求的扣费。每个请求的精确扣费在控制台的日志里，见可观测性与用量。

key 本身不可用时

这些端点做的 key 检查与调模型完全相同。一把此刻调不了模型的 key，在这里同样会拿到错误，而不是余额：

情况	HTTP	错误码
没有传 key	401	`AUTH_API_KEY_REQUIRED`
key 不存在或已吊销	401	`AUTH_INVALID_API_KEY`
key 在控制台被停用	403	`AUTH_API_KEY_INACTIVE`
key 已过期	403	`AUTH_API_KEY_EXPIRED`
key 的 30 天额度用完	429	`LIMIT_API_KEY_QUOTA_EXHAUSTED`
key 的每日额度用完	429	`LIMIT_API_KEY_DAILY_QUOTA_EXHAUSTED`
账号被暂停	403	`AUTH_ACCOUNT_SUSPENDED`

所以成功的响应描述的一定是一把可用的 key —— is_active 为 true，key.status 为 active。如果想在某把 key 额度用完时仍能看到账户余额，请用一把不设上限的 key 来查。

频率限制

每把 key 每分钟最多调用这些端点 60 次，每个 IP 每分钟最多 300 次。超出会返回 HTTP 429 LIMIT_RATE_EXCEEDED，并带 Retry-After 头。每分钟查一次就足够了。

错误的返回格式与调模型相同，见错误。