如何使用 https://api.openai.com 接口查詢余額

下面給你一份最常用、最穩定的「查餘額」速查筆記。整體邏輯是 先拿到「配額上限」(subscription) → 再拿到「已花費」(usage) → 自己相減 = 剩餘可用金額，如果你還有試用贈額，再另外查 credit_grants。

---

1. 官方（文件化）/v1/balances 端點

OpenAI Docs 裡最近掛出了一條 **GET https://api.openai.com/v1/balances**，會直接回傳當前可用餘額；如果你開發者平台左側已經能看到 Balances 這一節，直接用這條最省事。platform.openai.com

text
curl https://api.openai.com/v1/balances \
  -H "Authorization: Bearer sk-xxxxxxxx"

回傳格式類似：

json
{
  "object": "balance",
  "total_granted_usd": 120,
  "total_used_usd": 36.42,
  "total_available_usd": 83.58,
  "expires_at": 1751328000
}

若你的組織還沒開放這條端點，就用下面的「傳統 billing 三段式」方案。

---

2. 傳統三段式：subscription → usage → 自己算

目的	Method & URL	Header 用 API key 嗎？	備註
查配額上限 (hard limit)	GET https://api.openai.com/dashboard/billing/subscription	✅ Bearer sk-xxx	回傳 hard_limit_usd
查已用金額	GET https://api.openai.com/dashboard/billing/usage?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD	✅	total_usage 以「美分」為單位（除以 100 再用）
查試用贈額	GET https://api.openai.com/dashboard/billing/credit_grants	❌ 只認 session key (sess-xxx)	如果沒有試用額度可省略

資料來源：StackOverflow 回答中列出了三個端點並證實可用stackoverflow.com；Dev.to 文章給出了完整 cURL / Python 範例dev.to；而 credit_grants 在 2023 年後要求 session key，相關變動見部落格說明lmmsoft.github.io。

2-1. 配額上限（subscription）

bash
curl https://api.openai.com/dashboard/billing/subscription \
  -H "Authorization: Bearer sk-YOUR_KEY"

重點欄位

• hard_limit_usd – 組織的月度最高可花費上限
• soft_limit_usd – 會先觸發預警的門檻（可忽略或自行做提醒）

2-2. 已用金額（usage）

bash
# 取最近 100 天的用量
TODAY=$(date +%F)                # 2025-06-11
START=$(date -v-100d +%F)        # 2025-03-03

curl "https://api.openai.com/dashboard/billing/usage?start_date=$START&end_date=$TODAY" \
  -H "Authorization: Bearer sk-YOUR_KEY"

回傳裡 total_usage 單位是 美分，要先 total_usage / 100 才是美元。

2-3. 免費贈額（credit_grants）— 可選

如果你還有試用金，需要改用瀏覽器裡抓到的 sess-xxxxxxxx：

bash
curl https://api.openai.com/dashboard/billing/credit_grants \
  -H "Authorization: Bearer sess-xxxxxxxx"

回傳 total_available 就是剩餘試用金額；沒有試用額度時可以跳過這一步。

---

3. 一個最小 Python 範例

python
import datetime, requests

API_KEY = "sk-xxxxxxxx"

def get_subscription():
    return requests.get(
        "https://api.openai.com/dashboard/billing/subscription",
        headers={"Authorization": f"Bearer {API_KEY}"}
    ).json()

def get_usage(days=100):
    end = datetime.date.today()
    start = end - datetime.timedelta(days=days)
    url = "https://api.openai.com/dashboard/billing/usage"
    params = {"start_date": start.isoformat(), "end_date": end.isoformat()}
    resp = requests.get(url, params=params,
                        headers={"Authorization": f"Bearer {API_KEY}"})
    cents = resp.json()["total_usage"]
    return cents / 100          # 轉成美元

sub = get_subscription()
limit_usd = sub["hard_limit_usd"]
used = get_usage()
print(f"已用 ${used:.2f} / 配額上限 ${limit_usd:.2f}，剩餘 ${limit_usd - used:.2f}")

---

4. 常見坑 & 小貼士

1. 日期格式要用 YYYY-MM-DD，UTC 時區。
2. usage 端點一次查最長 100 天，再長就分段呼叫。
3. credit_grants 已不接受 secret key；若無 session key，直接忽略試用餘額即可。
4. 以上 billing 端點雖然沿用多年，但屬於「半官方」；OpenAI 可能隨時改動，務必加錯誤處理。
5. 如果 /v1/balances 已對你開放，直接改用它最簡單。

這樣就能把餘額監控做進你的腳本或後台了，祝開發順利！