額度及方案說明

這裡提供完整的開發指南與最佳實踐，幫助您快速上手。

核心概念

說明額度與請求頻率兩種限制的差別、如何從回應讀取用量、如何主動監控，以及撞到上限時會收到哪些錯誤碼與對應的處理方式。

本服務有兩種互相獨立的限制。額度以當期累計用量計算，用完必須加購額度或等到下一個合約期，重試無效；請求頻率以每分鐘請求數（RPM）計算，超過只要放慢速度或稍後重試即可恢復。兩種限制在回應中都會同時回報帳戶層與 API Key 層兩個維度；目前契約期間內所有 API Key 共用帳戶層的上限，因此實際天花板由帳戶方案決定。

額度的兩個維度

兩個維度會分別累計。目前所有 API Key 在契約期間共用帳戶層的額度與 RPM 上限，尚未開放為單把金鑰指定較低的上限，因此兩者分母相同；但分子各自獨立——帳戶層累計所有金鑰的用量，金鑰層只累計該把金鑰自己的用量。因此帳戶下有多把金鑰時，key_percent 會低於 user_percent。

維度	回應欄位	計算方式	超過時的錯誤碼
帳戶層	user_percent	整個帳戶的當期用量 ÷ 帳戶額度上限	quota_exceeded_user（429）
API Key 層	key_percent	本次使用的金鑰當期用量 ÷ 該金鑰的有效額度上限（分子只計這把金鑰自己的用量；分母目前取帳戶層上限）	quota_exceeded_key（429）

目前所有 API Key 共用帳戶層上限

額度與 RPM 目前只在帳戶層設定，契約期間內所有 API Key 一律套用同一組上限，尚未開放為單把金鑰指定較低的值。請注意「上限共用」不等於「兩個百分比相同」：用量仍分別累計，key_percent 只計該把金鑰自己的用量，因此帳戶下有多把金鑰時 key_percent 會低於 user_percent，實際會先撞到上限的是 user_percent。建立多把金鑰的用途是區隔使用環境與便於單獨撤銷，而不是分配額度。請仍然在程式中一併處理 key_percent 欄位與 quota_exceeded_key、rate_limited_key 兩個錯誤碼——它們會照常回傳，未來開放金鑰層上限時你的程式碼不需要改動。

文字翻譯與語音辨識端點的成功回應都會帶回 usage.quota_percent.used，值為 0–100 的帳戶層累計用量百分比；SSE 模式則放在 meta 事件的 data.usage 內。

翻譯端點回應中的 usage 欄位；used 為帳戶層累計百分比（0–100）。

json

{
  "translated_text": "Today's meeting is rescheduled to 3 PM.",
  "detected_source_lang": "zh-TW",
  "usage": {
    "quota_percent": {
      "used": 12
    }
  },
  "forced_replacement_count": 0
}

主動監控：GET /api/v1/usage

這是唯讀端點，不消耗額度、也不佔用每分鐘請求數預算，適合在呼叫業務端點前後查詢或由服務端定期輪詢。與業務端點的差異是：不必發出實際請求就能查，而且會同時回傳帳戶層與金鑰層兩個維度。

查詢當期用量的 curl 範例。

bash

curl "https://abemono.abestar.com.tw/api/v1/usage" \
  -H "X-API-Key: $ABESTAR_API_KEY"

回應範例；兩欄皆為 0–100 的百分比。此例中帳戶當期用量為上限的 35%，其中 12% 來自本次使用的這把金鑰，其餘來自帳戶下的其他金鑰。金鑰層上限目前繼承帳戶層，因此 key_percent 不會高於 user_percent。

json

{
  "user_percent": 35,
  "key_percent": 12
}

建議在 80% 設一條警戒線

額度用盡後請求會直接被拒絕，沒有緩衝空間。建議在服務端定期呼叫 GET /api/v1/usage，任一維度達到 80% 就發出內部告警並聯絡業務團隊調整上限，避免在尖峰時段才發現被擋。由於帳戶層累計所有金鑰的用量，user_percent 通常會是先觸發告警的那一個。

超過限制時的錯誤與處理

錯誤碼	HTTP	意義	建議處理
rate_limited_user	429	帳戶層每分鐘請求數超限。	以指數退避重試，並降低同時併發的請求數。
rate_limited_key	429	這把金鑰的每分鐘請求數超限。	退避後重試並降低同時併發的請求數。目前所有金鑰共用同一組 RPM，改用其他金鑰無法繞過限制。
quota_exceeded_user	429	帳戶層當期額度不足以完成本次請求。	重試無效。請先以 GET /api/v1/usage 確認用量，再聯絡業務團隊調整上限。
quota_exceeded_key	429	這把金鑰的當期額度不足以完成本次請求。	重試無效。目前金鑰層上限等同帳戶層，請以 GET /api/v1/usage 確認用量後，聯絡業務團隊調整帳戶額度。

429 有兩類，處理方式完全不同

rate_limited_* 是短期頻率限制，退避後重試就會恢復；quota_exceeded_* 是當期額度用盡，重試只會持續失敗，必須調整額度才能繼續。收到 429 時請務必讀取回應主體的 code 欄位再決定要不要重試，不要只看 HTTP 狀態碼。

方案與加購

額度上限依方案而定，套用於整個帳戶；契約期間內所有 API Key 共用這組上限。實際的方案內容、額度級距與加購方式會依使用情境調整，請與業務團隊確認最適合的組合。

正在尋找按量計費的方案？

我們將根據您的需求量身定制解決方案。