Menu

查詢剩餘積分

用 API 金鑰查詢這把金鑰目前還能使用多少積分。適合在大量送出任務前先確認餘額,或定期記錄用量。

GET /api/account/credits
X-Api-Key: sk-live-xxxx
  • 只需要帶 X-Api-Key,不需要其他參數。
  • 查詢不扣積分,但會計入頻率限制(見〈驗證方式〉)。

回應欄位

欄位 說明
credit_type 金鑰類型:paid(付費)或 trial(試用),分別對應開頭為 sk-live- 和 sk-test- 的金鑰
balance 剩餘積分(整數),意思依 credit_type 不同,見下方
expires_at 積分到期時間(ISO 8601)。付費積分沒有期限,一律是 null;試用是綁定額度的到期時間
as_of 這份資料的產生時間(ISO 8601)。餘額會隨扣款和退款即時變動,這個值代表查詢當下

付費金鑰(credit_type = paid)

balance 是帳號的付費積分餘額,同一個帳號的所有付費金鑰共用這個餘額。expires_at 一律是 null。

試用金鑰(credit_type = trial)

  • balance 是這把金鑰綁定的試用額度還剩多少。試用金鑰只會從這筆額度扣款(見〈積分與計費〉),所以這就是這把金鑰還能用的量,帳號裡其他試用額度不會算進來。
  • expires_at 是這筆額度的到期時間,一定有值。額度用完時 balance 是 0,expires_at 不變。
  • 額度到期後,這把金鑰呼叫任何 API(包含這個)都會回傳 401,不會回傳 balance: 0。

範例回應

以下數字僅供參考。

付費金鑰:

{
  "credit_type": "paid",
  "balance": 12000,
  "expires_at": null,
  "as_of": "2026-10-08T04:30:00.000000Z"
}

試用金鑰:

{
  "credit_type": "trial",
  "balance": 500,
  "expires_at": "2026-10-15T00:00:00.000000Z",
  "as_of": "2026-10-08T04:30:00.000000Z"
}

錯誤

狀態碼 原因
401 沒帶 X-Api-Key、金鑰不存在或已撤銷、試用金鑰的額度已到期(訊息內容見〈驗證方式〉)
429 超過頻率限制