要約:APIキーにクォータを設定しても、費用が想定を超えることはあります。本記事ではその原因を説明し、AIトライアルの予算管理を順序立った3本の予算ラインに分解します。
先に結論から言うと、ゲートウェイ上のKeyクォータはソフト上限であり、並行リクエスト下では請求額のハード上限として扱えません。 APIYIのトークンに関するドキュメントを例にすると、クォータはリクエスト開始時にチェックされます。複数のリクエストが同時にチェックを通過したり、1回のリクエスト自体の価格が高かったりすると、最終的な消費量は設定したクォータを超える可能性があります。
信頼できる方法は3層に分けて対応することです:
- アプリケーションバックエンドでリクエスト送信前にチェックを完了し、アトミックに予算を予約する。
- ゲートウェイ側ではトライアルトラフィック専用のKeyを発行し、クォータとモデルホワイトリストを設定して、このKeyが悪用された際の影響範囲を狭める。
- アカウント残高アラートは通知のみを担当し、人手による対応を促すために使う。
これら3層の役割は互いに代替できません。実際の予算受け入れ判定は、アプリケーション自身の台帳内で行われます。

知識マップと索引:3本の予算ラインの順序と役割分担
この表は知識マップと索引を兼ねています。3本の予算ラインがどの順序で有効になり、それぞれ何を担当し、なぜそう配置するのか、そして対応する本文の番号を示しています。
| 順序 | 予算ライン | 担当範囲 | この位置に置く理由 | 目標 | 本文 |
|---|---|---|---|---|---|
| 前提 | ソフトクォータの理解 | リクエスト前チェック、事前確保(プリデビット)、実デビットの区別 | 課金のタイミングを理解していなければ、後の3層は設計できない | 超過がどのように起きるのかを把握する | 1、1.1 |
| 第1のライン | アプリケーションバックエンドの予算 | ユーザー単位・トライアルプール単位でのアトミックな予約と決済 | 「誰が使っているか、どれだけ使えるか」を知っているのはアプリだけ | リクエスト送信前に超過を止める | 2.1、3 |
| 第2のライン | 独立したトライアルキー | クォータ、モデルのホワイトリスト、本番トラフィックとの分離 | アプリにバグが出たとき、ゲートウェイが第二の境界になる | 1本のキーの露出面を小さくする | 2.2 |
| 第3のライン | アカウント残高アラート | 残高がしきい値を下回ったときの通知 | アラートは事後シグナルで、ブロックする能力はない | 人が早めに介入できるようにする | 2.3 |
| 実装 | 同時実行の台帳とリリース前チェック | 予約、決済、失敗時の処理、突合(照合)、わかりやすい表示 | 前述の原則を検証可能なフローに落とし込む | リリース前に項目ごとに検収できる | 3、4 |
読む順序のおすすめ:まず第1節でタイミングを理解し、次に第2節で役割分担を明確にし、第3節が実装パートです。第4節はリリース前に単独で照合する用途に向いています。
To Know:予算ラインを理解する前の必須用語
| 用語 | 簡潔な説明 |
|---|---|
| ソフト上限 | リクエスト開始時に枠を確認するが、確認を通過しても総消費が上限を超えないことは保証されない |
| プリホールド | ゲートウェイが推定値に基づいて先に一部の枠を差し引き、リクエスト終了後に実使用量で精算する |
| アトミック予約 | 単一の不可分操作で「残量確認と確保」を完了し、同時リクエストが一斉に通過するのを防ぐ |
| インフライト予約 | リクエスト送信済みで実費用が未確定の間、台帳上で占有状態のままの予算部分 |
| remain_quota | APIYI トークンの一括総枠フィールド。ドキュメント上の基準は 500000 が $1 に相当 |
| 突合 | ゲートウェイログと自社台帳を1件ずつ照合し、推定と実績の差異を修正する |
1 APIキーの枠が並行リクエストで超過されうる理由
APIYI のトークンドキュメントはこの点を明確に示しています。APIキーの枠はソフト上限であり、リクエスト開始時に確認されます。そのため、並行リクエストや単価の高い1回のリクエストによって、実際の消費が設定枠を超える可能性があります。これは「開始時に確認し、終了時に精算する」という課金構造そのものの特性であり、特定のプラットフォームにバグがあるかどうかとは関係ありません。
理解のために仮想的なシナリオを考えてみましょう(数値はすべてイメージで、実測値ではありません)。ある試用APIキーの残り枠が $1 相当だとします。同じ瞬間に 20 件のリクエストが押し寄せます。各リクエストは開始時点で「残高はプラス」と認識するため、すべて通過します。それらが順次終了し、実際の使用量で精算されるころには、総消費は $1 をはるかに超えています。並行リクエストがなくても、長いコンテキストと大きな出力を伴う1回のリクエストでは、単発費用が残り枠を超えることもあります。
よくある2つの誤解も補足しておきます。
- 枠は毎日自動で回復しません。 ドキュメントでは remain_quota が一括総枠であると説明されており、「毎日リセット」はアプリケーション側が自分で定期スクリプトを書いて実装する必要があります。
- モデルのホワイトリストは費用上限ではありません。 呼び出せるモデルを制限するだけで、同じモデルの呼び出し回数や1回あたりの規模には制約をかけません。

1.1 APIキー枠の3つの時点:リクエスト前チェック、見積もり、実課金
1回の呼び出しには課金上3つの時点があり、それぞれ答える問いが異なります。
| 時点 | どこで発生するか | 答える問い | ハード上限として使えるか |
|---|---|---|---|
| リクエスト前チェック | ゲートウェイ、リクエスト開始時 | このAPIキーに現時点で残量があるか | 不可。並行時には同時に通過してしまう |
| 見積もりとプリホールド | ゲートウェイ、推定に基づく | 今回のリクエストで概ねどれだけ占有するか | 不可。推定と実績には差がある |
| 実課金 | ゲートウェイ、リクエスト終了後 | 今回のリクエストで実際にどれだけ使ったか | 事後データであり、事前の可否判定には使えない |
APIYI のプリホールド枠に関する説明は次のとおりです。ゲートウェイは推定に基づいて事前に差し引き、事後に実使用量で精算します。この仕組みは業務側のアトミック予約を置き換えるものではありません。ゲートウェイのプリホールドは自身の課金のためのものであり、あなたのあるユーザーが今日あとどれだけ試用枠を残しているかを知りません。したがって「このユーザーはもう一度リクエストを送れるか」という問いに答えられるのは、アプリケーションのバックエンドだけです。
2 AI試用の3つの予算ライン
この3つのラインは、それぞれ3種類のリスクに対応しています。業務ロジック層での過剰利用、Key層での乱用や漏洩、アカウント層での残高枯渇です。OWASP API Security Top 10(2023)のAPI4「Unrestricted Resource Consumption」も同じ種類の問題を扱っています。リソース消費に制限を設けていないインターフェースは、サービスとコストの両面でリスクを生みます。AIインターフェースでは、コストのリスクがより直接的であることが多いです。
2.1 1つ目の予算ライン:アプリケーションバックエンドのユーザー予算と試用プール予算
ここは「受け入れ可否の判断」ができる唯一の層であり、2つのレベルを管理する必要があります。
- ユーザーレベル予算:各試用ユーザーの総枠、または日次枠。日次枠はアプリ自身の定期タスクでリセットされ、ゲートウェイに依存しません。
- 試用プール予算:すべての試用ユーザーが共有する総上限。個々のユーザーが上限を超えていなくても、ユーザー数が急増するときは総コストに上限を設ける必要があります。
1つのリクエストは、ユーザーレベルとプールレベルの両方の予約を同時に通過しなければなりません。しかも両者は、同じアトミック操作または同じトランザクション内で完了する必要があります。そうでなければ、「ユーザーの予約は成功したのにプールはすでに満杯」という競合状態が起きます。
この層ではさらに、サーバー側でリクエストの規模を決める必要があります。どのモデルを許可するか、max_tokens の上限はいくつか、入力長はどこまでか。これらのパラメータを、フロントエンドから渡されたまま透過させることはできません。そうすると、ユーザーがパラメータを1つ変えるだけで見積金額が狂ってしまいます。
2.2 2つ目の予算ライン:独立した試用Key、枠、モデルホワイトリスト
ゲートウェイ側で試用トラフィックに専用のKeyを1本発行し、本番トラフィックと完全に分離します。このKeyの役割は露出面を制限することです。アプリの台帳にバグが出た場合や、Keyが漏洩した場合、損失はこのKeyの枠内に収まり、本番業務に波及しません。
設定時の注意点:
- 枠は「試用プール予算+一定のバッファ」で設定します。アプリ側のプール予算よりやや高めに設定し、フェイルセーフとして機能させます。プール予算と同じにしないでください。そうするとアプリ層の予約が形骸化します。
- モデルホワイトリストには、試用で開放するモデルだけを入れます。これにより試用Keyが高額モデルの呼び出しに使われるのを防げますが、回数や規模は制限されないため、2.1節のサーバー側の規模制限は依然として必須です。
- 枠はソフト上限なので、このラインは「軽微な越線」を許容します。その意義は越線の幅を許容範囲内に抑えることにあり、ゼロ超過支出を期待してはいけません。
プロジェクトごとにKey、枠、ログを分割する一般的な手法は別の話題です。ここでは1点だけ強調します。試用トラフィックには専用のKeyを1本。
2.3 3つ目の予算ライン:アカウント残高のアラート
APIYI の残高アラートのドキュメントには、アラートは通知であり、リクエストをブロックしないことが明記されています。残高がしきい値を下回ったとき、アラートはメッセージを担当者にプッシュし、チャージするか、試用入口を一時停止するか、異常なトラフィックを調査するかは人が判断します。
この層を使う際の2つの提案:
- アラートのしきい値は「発見から処理までに必要な時間内の最大消費」で決めます。何となく整数を設定しないでください。
- アラートは具体的な対応アクションと紐付けます。たとえば当番マニュアルに「アラートを受信したら、まず試用登録の入口を閉じる」と明記します。通知だけで後続のアクションがないアラートは形骸化します。
3 仮想の並行台帳:アトミックな予約から照合まで
本節では例示的な設計を示します。テーブル構造、価格、数値はいずれも仮定のもので、フローを説明するためのものです。実在するシステムの実測データを表すものではありません。フローは次の5ステップで構成されます。
アトミックなチェックと予約 → サーバー側で model と規模をロック → リクエスト送信
→ 精算 / 失敗処理 → オフライン照合による補正

3.1 予算台帳のテーブル構造と状態
例示するデータ構造は2つのテーブルから成ります。budgets は各ユーザーおよびトライアルプールの上限、支出済み、予約済みを記録し、reservations は各予約とその状態を記録します。
| 予約状態 | 意味 | 「利用可能残量」への影響 |
|---|---|---|
| reserved | 予約済み、リクエストは実行中 | 推定金額を占有 |
| settled | 実際の使用量を取得し、精算済み | 支出済みに移行し、差額を解放 |
| released | リクエストが未実行であることを確認 | 全額を解放 |
| unknown | タイムアウトや切断で費用が不明 | 占有を継続、照合待ち |
利用可能残量は limit - spent - reserved で計算されます。ここで reserved には unknown 状態の予約も含まれます。
3.2 原子的なチェックと予約——並行処理で同時に通過するのを防ぐ
重要なのは、「チェック」と「占有(予約)」を 1 つの条件付き更新文にまとめ、原子性をデータベースに保証させることです。
-- 例:残量が十分なときだけ占有し、影響を受けた行数を返す
UPDATE budgets
SET reserved = reserved + :estimate
WHERE owner_id IN (:user_id, :pool_id)
AND limit_amount - spent - reserved >= :estimate;
-- 影響行数は 2(ユーザーとプールの両方が成功)と等しくなければならない。そうでなければトランザクションをロールバックし、リクエストを拒否する
見積金額は上限値を採用します。入力トークン数に入力単価を掛け、さらに max_tokens に出力単価を掛けた値を加算します。実際の使用量は通常これより少ないので、精算時に差額を返却すればよいだけです。少し多めに占有するのは構いませんが、少なく占有してはいけません。
3.3 サーバー側で model とタスク規模を固定する
予約に使う見積パラメータは、実際に送出するリクエストパラメータと完全に一致していなければなりません。サンプルコードは以下のとおりです:
ALLOWED_TRIAL_MODELS = {"trial-model-a"} # 例:トライアルで開放しているモデル
MAX_OUTPUT_TOKENS = 1024 # 例:サーバー側で強制する上限
MAX_INPUT_TOKENS = 8000
def build_trial_request(user_input, requested_model):
model = requested_model if requested_model in ALLOWED_TRIAL_MODELS \
else "trial-model-a"
input_tokens = count_tokens(user_input)
if input_tokens > MAX_INPUT_TOKENS:
raise InputTooLarge()
estimate = price_in(model) * input_tokens \
+ price_out(model) * MAX_OUTPUT_TOKENS
return model, MAX_OUTPUT_TOKENS, estimate
フロントエンドから渡される max_tokens と model はあくまで参考値であり、最終的にはサーバー側の判断が優先されます。
3.4 リクエスト送信、決済、失敗時の処理
リクエストを送信する前に、一意のリクエスト ID を生成して予約レコードに書き込んでおくと、後からログで照合しやすくなります。リクエストが返ってきたら、次の 3 つのケースに分けて処理します。
- 成功して usage を取得できた場合:実際の使用量に基づいて金額を計算し、
spent += actual、reserved -= estimateとし、予約ステータスを settled に変更します。 - 明確に未実行だった失敗:パラメータ検証の失敗や認証の失敗など、リクエストが課金対象に入っていないと確認できるエラーです。この場合は予約を解放し、ステータスを released に変更します。
- タイムアウトまたは接続切断:リクエストは上流で実行され費用が発生している可能性があるものの、結果が返ってきていないだけかもしれません。この場合、費用をゼロとして扱わないようにし、ステータスを unknown として記録し、予約は占有したままにしておきます。
3 番目のケースが最も間違えやすいところです。タイムアウトしたからといってそのまま予約を解放してしまうと、すでに発生しているかもしれない費用を台帳から消してしまうことになります。高並列・高タイムアウト率の時間帯では、こうした誤差が積み重なっていきます。
3.5 オフライン照合:unknown と見積もり誤差の修正
APIYI のログクエリは増分エクスポートに対応していますが、そのドキュメント上の位置づけはオフライン照合であり、リクエストごとの可否判断の根拠には使えません。そのため照合は定期タスクとして実行するのが適切です。
- 前回の照合以降の増分ログを取得し、リクエスト ID または時間ウィンドウで
reservationsテーブルと突き合わせます。 - ログ内で見つかった unknown の予約は、ログに記録された実際の金額に基づいて settled に変更します。あらかじめ定めた時間ウィンドウを過ぎても記録が見つからない場合は、released に変更します。
- 「見積もり金額と実際の金額」の誤差の分布を集計します。実際の金額がしばしば見積もりに近い、あるいはそれを超えている場合は、3.3 節の見積もり式に戻って見直しましょう。
照合結果は同時に、3 本目の予算ラインへの入力にもなります。台帳の合計とアカウントの実際の消費が継続的に合わない場合、それ自体が人手による調査を必要とするシグナルです。

4 予算ラインのリリース前チェックと残量不足時のわかりやすい通知
4.1 3つの予算ラインのリリース前チェックリスト
| チェック項目 | 対象の予算ライン | 検証方法 |
|---|---|---|
| ユーザーとプールの予約が同一トランザクション内で完了する | 第1 | 並行リクエストで負荷テストを行い、消費済み+予約が上限を超えないことを確認 |
| model、max_tokens、入力長はサーバー側で決定する | 第1 | フロントエンドのパラメータを改ざんし、無効であることを確認 |
| タイムアウトしたリクエストは unknown として記録し、占有を維持する | 第1 | タイムアウト障害を注入し、台帳の状態を確認 |
| 照合タスクが定期的に実行され、unknown を処理する | 第1 | 照合ログとステータス遷移を確認 |
| トライアルキーが独立しており、クォータがプール予算よりやや多い | 第2 | キー設定とプール予算の数値を照合 |
| トライアルキーのモデル許可リストにトライアル用モデルのみが含まれる | 第2 | 許可リスト外のモデルで呼び出し、拒否されることを確認 |
| 日次クォータのリセットスクリプトが存在し、監視されている | 第1・第2 | 定期タスクの実行記録を確認 |
| 残高アラートのしきい値と対応マニュアルが対応している | 第3 | アラート発生から入口クローズまでの流れを一度演習 |
4.2 クォータ不足時のユーザーへの通知
予約に失敗した場合、アプリケーションは明確なビジネスエラーを返すべきです。リクエストがゲートウェイまで到達してから、理解しにくいエラーが返るのは避けたいところです。通知には次の3つの情報を含めることをおすすめします。
- 何が起きたか:たとえば「本日のトライアルクォータを使い切りました」「現在トライアル枠が満員です」。ユーザーのクォータ不足とトライアルプールの満杯は別々に通知します。
- いつ回復するか:日次クォータを設定している場合はリセット時刻を伝えます。一度きりのクォータを使い切った場合は、今後のアップグレード方法を案内します。
- 現在の状態:残りクォータを表示してもかまいませんが、台帳上の利用可能残量に基づき、処理中の予約も差し引いたうえで表示します。「残高があると表示されたのに拒否された」という状況を避けるためです。
これらのチェックを終えたら、シンプルな方法で予算ライン全体を検証できます。並行アクセスのピークに上流のタイムアウトを重ねた状況をシミュレートし、台帳の「消費済み+処理中の予約」が照合後の実際の消費量を常に下回らないこと、かつトライアルキーの消費がそのクォータを大きく超えていないことを確認します。この2つを満たせば、3つの予算ラインはようやく実用可能と言えます。
参考資料
- APIYI トークン管理ドキュメント:ソフト上限、remain_quota、日次リセット、モデルホワイトリストの説明
- リンク:
docs.apiyi.com/api-capabilities/token-management
- リンク:
- APIYI 事前控除クォータの説明:見積もりによる事前控除と事後精算の仕組み
- リンク:
docs.apiyi.com/faq/pre-deduction-quota
- リンク:
- APIYI 残高アラートの説明:アラートは通知のみで、リクエストをブロックしない
- リンク:
docs.apiyi.com/faq/balance-alerts
- リンク:
- APIYI ログ照会ドキュメント:増分エクスポートとオフライン照合
- リンク:
docs.apiyi.com/api-capabilities/log-query
- リンク:
- OWASP API Security Top 10 2023:API4 Unrestricted Resource Consumption(無制限のリソース消費)
- リンク:
api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption/
- リンク:
何事もあらかじめ準備すれば成し遂げられ、準備しなければ廃れてしまう。——『礼記』中庸
