クォータとプラン

包括的な開発者ガイドとベストプラクティスで、すばやく開発を始められます。

コアコンセプト

クォータとリクエスト頻度という 2 種類の制限の違い、応答から使用量を読む方法、能動的な監視方法、上限到達時のエラーコードと対処方針を説明します。

本サービスには互いに独立した 2 種類の制限があります。クォータは当期の累積使用量で計算され、使い切った場合は追加購入するか次の契約期間を待つ必要があり、再試行しても解消しません。リクエスト頻度は毎分リクエスト数（RPM）で計算され、超過してもペースを落とすか時間をおいて再試行すれば回復します。どちらの制限も応答ではアカウント層と API キー層の 2 次元で報告されます。現在、契約期間中はすべての API キーがアカウント層の上限を共有するため、実際の上限はアカウントのプランで決まります。

クォータの 2 つの次元

2 つの次元はそれぞれ個別に集計されます。現在、すべての API キーは契約期間中アカウント層のクォータと RPM 上限を共有しており、個々のキーに低い上限を指定する機能は未提供のため、分母は共通です。一方で分子は独立しており、アカウント層はすべてのキーの使用量を合算し、キー層は当該キー自身の使用量のみを計上します。そのため、アカウントに複数のキーがある場合 key_percent は user_percent より低くなります。

次元	応答フィールド	計算方法	超過時のエラーコード
アカウント層	user_percent	アカウント全体の当期使用量 ÷ アカウント上限	quota_exceeded_user（429）
API キー層	key_percent	呼び出しに使ったキーの当期使用量 ÷ 当該キーの有効上限（分子は当該キー自身の使用量のみ、分母は現在アカウント層の上限）	quota_exceeded_key（429）

現在、すべての API キーはアカウント層の上限を共有します

クォータと RPM は現在アカウント層でのみ設定されます。契約期間中はすべての API キーに同一の上限が適用され、個々のキーに低い上限を指定する機能は未提供です。ただし「上限の共有」は「2 つの使用率が同じになること」を意味しません。使用量は個別に集計され、key_percent は当該キー自身の使用量のみを計上するため、アカウントに複数のキーがある場合 key_percent は user_percent より低くなり、先に上限へ到達するのは user_percent です。複数のキーを作成する目的は、利用環境を分けることと個別に失効できるようにすることであり、クォータの割り当てではありません。key_percent フィールドと quota_exceeded_key / rate_limited_key の 2 つのエラーコードは引き続き返却されるため、実装ではそのまま処理してください。将来キー層の上限が開放されてもコードの変更は不要です。

テキスト翻訳と音声認識の成功応答にはいずれも 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 は 2 種類あり、対処法が異なる

rate_limited_* は短期の頻度制限で、バックオフ後の再試行で回復します。quota_exceeded_* は当期クォータの枯渇であり、上限を調整しない限り再試行は失敗し続けます。429 を受け取ったら必ず応答ボディの code フィールドを読んでから再試行を判断してください。HTTP ステータスだけで分岐しないでください。

プランと追加購入

クォータ上限はプランによって決まり、アカウント全体に適用されます。契約期間中はすべての API キーがこの上限を共有します。実際のプラン内容・クォータ区分・追加購入の方法は利用状況に応じて調整されるため、最適な組み合わせは営業担当にご確認ください。

従量課金プランをお探しですか？

ご要望に合わせたソリューションをご提案します。