Ollama 余额查询（Balance）

GET https://ollama.com/api/balance 返回剩余额度：套餐内还剩多少、购买的 credits 还剩多少。

版本基线 v0.40.12，官方 docs.ollama.com/api/balance。

一、调用

curl https://ollama.com/api/balance \
  -H "Authorization: Bearer $OLLAMA_API_KEY"

返回：

{
  "included": {
    "balance_usd": 72.5,
    "allowance_usd": 100,
    "period": {
      "from": "2026-09-15T09:30:00Z",
      "until": "2026-10-15T09:30:00Z"
    }
  },
  "purchased": {
    "balance_usd": 25
  }
}

二、字段解读

示例数据读下来：套餐 100 美元额度用了 27.5，剩 72.5；另外还有 25 美元购买的 credits 未用。

这个端点不接受任何查询参数，用量历史要去 13.21 云用量统计。

三、计费周期的规则

• included 的周期跟随套餐的月度重置计划——年付订阅也是按月重置
• 时间戳是 UTC，from 含、until 不含
• purchased 只统计未过期的 credits

关于第四点：购买的 credits 有有效期，过期的不会计入余额。所以「余额掉得比用得快」有时是 credits 过期而不是被消费了。

四、旧套餐的返回格式

带会话/周限额的旧套餐，included 里返回的是百分比而非金额：

{
  "included": {
    "session": {
      "remaining_percent": 75,
      "resets_at": "2026-10-01T07:00:00Z"
    },
    "weekly": {
      "remaining_percent": 40,
      "resets_at": "2026-10-05T00:00:00Z"
    }
  },
  "purchased": { "balance_usd": 25 }
}

两种格式结构不同，写代码要同时兼容 balance_usd 和 remaining_percent 两种字段。

五、限流

和用量接口共享同一个账号级配额。

六、团队场景

所有团队成员共享同一份 included 和 purchased 余额。这意味着任何成员的消耗都会体现在所有人的余额里——做预算管控时要考虑这一点。

七、Python 示例（兼容两种格式）

import os, requests

def balance():
    r = requests.get("https://ollama.com/api/balance",
                     headers={"Authorization": f"Bearer {os.environ['OLLAMA_API_KEY']}"})
    r.raise_for_status()
    return r.json()

d = balance()
inc = d["included"]

if "balance_usd" in inc:
    total = inc.get("allowance_usd", 0)
    left = inc["balance_usd"]
    pct = (left / total * 100) if total else 0
    print(f"套餐额度: ${left:.2f} / ${total:.2f}（剩 {pct:.0f}%）")
    p = inc.get("period", {})
    print(f"周期: {p.get('from','?')} → {p.get('until','?')}")
else:
    s = inc.get("session", {})
    w = inc.get("weekly", {})
    print(f"会话剩余 {s.get('remaining_percent','?')}%，{s.get('resets_at','?')} 重置")
    print(f"本周剩余 {w.get('remaining_percent','?')}%，{w.get('resets_at','?')} 重置")

print(f"购买 credits: ${d['purchased']['balance_usd']:.2f}")

八、做余额告警

def check_and_alert(threshold_pct=15):
    d = balance()
    inc = d["included"]
    if "balance_usd" in inc:
        left, total = inc["balance_usd"], inc.get("allowance_usd", 0)
        if total and left / total * 100 < threshold_pct:
            print(f"⚠️ 套餐额度仅剩 {left/total*100:.0f}%，即将耗尽")
            # 这里接你的告警通道（邮件 / IM webhook）
    if d["purchased"]["balance_usd"] < 5:
        print(f"⚠️ 购买 credits 仅剩 ${d['purchased']['balance_usd']:.2f}")

check_and_alert()

注意配合限流：别把这个检查放进高频循环，一分钟一次已经足够。

常见问题

动手试

## ① 查余额
curl -s https://ollama.com/api/balance \
  -H "Authorization: Bearer $OLLAMA_API_KEY" | python -m json.tool

## ② 一行看剩余百分比
curl -s https://ollama.com/api/balance \
  -H "Authorization: Bearer $OLLAMA_API_KEY" | python -c "
import sys,json
i=json.load(sys.stdin)['included']
print(f\"剩余 \${i['balance_usd']:.2f} / \${i.get('allowance_usd',0):.2f}\" if 'balance_usd' in i else f\"会话 {i['session']['remaining_percent']}% / 周 {i['weekly']['remaining_percent']}%\")"