> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API呼び出しの事前差し引きメカニズムとは？
> APIYIの事前差し引き（事前消費クォータ）の仕組み: リクエスト前にモデル価格と入力から見積もって保留し、その後は実際の使用量で精算します — さらに insufficient_user_quota エラーの読み方も説明します。
## クイックアンサー
リクエストが**実際に実行される前**に、APIYI は**事前差し引き**（「モデル価格 × 推定 token」＝発生しうる最大コスト）を計算し、その金額をいったん残高から確保します。リクエスト完了後に、**実際に消費した token で精算して差額を返金**します。つまり、事前差し引きはあくまで見積もりであり、最終請求額ではありません。
**2つの重要な行**
* **事前差し引き**: リクエスト前の見積もりで、「この呼び出しを支払えるか」を判断するために使います。
* **実際の請求**: リクエスト完了後に実際の token で精算されます。これが本当に請求される金額です。
**事前差し引きの見積もり > 現在の残高** であれば、リクエストは実行前に拒否され、`insufficient_user_quota` が返されます。これが「残高は明らかにあるのに、なぜか通らない」の根本原因です。
## 事前差し引きの仕組み
システムは、あなたの **入力**（prompt、画像、会話履歴など）を読み取り、モデルの現在の料金と **推定出力長** を使って、**最大想定コスト** を算出し、それをいったん残高から一時確保します。
見積もりはおおむね次のとおりです。
`pre-deduction ≈ model price × (input tokens + estimated output tokens)`
**事前差し引き** を **現在の残高** と比較します。
* 残高 ≥ 事前差し引き → 許可され、リクエストが送信されます
* 残高 \< 事前差し引き → `insufficient_user_quota` で拒否され、**実際には呼び出しは行われません**
完了すると、システムは実際の入力/出力 token 使用量を取得し、実際の使用量で再課金します。
* 実際のコストが **通常は** 事前差し引きより **少ない** → 余分に確保されていたクォータは残高に **返金** されます
* 失敗した/中断されたリクエスト → 通常は課金されず、確保されていたクォータは解放されます
**大きな事前差し引きがあっても、実際にその金額を使ったことを意味するわけではありません** — これは「最悪ケース向けの予備枠」の見積もりです。実際に課金されるのは、リクエスト完了後の実際の tokens です。
## insufficient\_user\_quota エラーの読み方
事前差し引きが残高を超えると、次のような内容が表示されます:
```json theme={null}
{
"error": {
"message": "user [25359] quota [50264897] preConsumedQuota [154753475] is not enough",
"localized_message": "Insufficient user quota",
"type": "shell_api_error",
"param": "",
"code": "insufficient_user_quota"
}
}
```
項目ごとの意味:
| フィールド | 意味 |
| ------------------------------- | ------------------------------------- |
| `quota [50264897]` | あなたの**現在利用可能な残高**（内部クォータ単位） |
| `preConsumedQuota [154753475]` | このリクエストが事前差し引きしたい**クォータ** |
| `is not enough` | 事前差し引き > 残高で保持できないため、**リクエストは拒否されます** |
| `code: insufficient_user_quota` | エラーコード: insufficient user quota |
重要なのは、2つの数値の**比率**です。ここでは事前差し引き`154753475`が残高`50264897`の約**3倍**なので、ブロックされています。
これらの数値は APIYI の**内部クォータ単位**であり、直接比較できます。USD で見ると、残高 ≈ \$100、このリクエストの事前差し引き見積もり ≈ \$310（内部では約500,000単位 ≈ \$1）です。つまり、この1件のリクエストは \$300 超を確保しようとした一方で、アカウントには \$100 しかなかったため、実行できませんでした。
## 「残高はあるのに実行できない」
大半のケースでは、**問題は残高そのものではなく、入力が大きすぎること**です。
実例: `gpt-5.5` は最大 1,050,000 tokens のコンテキストウィンドウを持っています。そこに**大規模なコードリポジトリ全体**を詰め込むと、入力 token 数が膨大になり、事前差し引きも大きく膨らみます。たとえ \$100 の残高があっても、\$300 の見積もりはリクエストが実行される前に拒否されます。
**入力が大きいほど、事前差し引きも大きくなる**
入力が大きすぎると、事前差し引きが膨らんで `insufficient_user_quota` を簡単に引き起こすだけでなく、次のような問題もあります。
* 通っても、**実際のコストが高い**（実際の tokens に基づいて課金される）;
* 関係のない内容を詰め込みすぎると、モデルが**平凡な結果**しか返さないことがある — お金は使ったのに、結果はよくない。
## どう修正し、回避するか
**関連する**コード/ドキュメントだけを送ってください。リポジトリ全体や長い文書を一度に投げ込まないことが、最も効果的な対処です。
出力の長さを明示的に上限設定して、「estimated output tokens」を下げ、それによって事前控除を抑えます。[max\_tokens ガイド](/ja/faq/max-tokens)をご覧ください。
どうしても大きな入力が必要な場合は、残高 > 事前控除 となるようにしておけば十分です。[支払い方法](/ja/faq/payment-methods)をご覧ください。
安価なモデルで入力が妥当かを検証してから、高性能なものに切り替えてください。支払える以上に「消費する」ことは避けましょう。
**大きな入力には注意**: 長いコンテキストウィンドウを持つモデル（`gpt-5.5` の 1.05M tokens など）は多くを保持できますが、「保持できる」ことと「保持すべき」ことは別です。リポジトリ全体を詰め込むのは、たいていコストが高いわりに品質もいまひとつです。まず本当に必要なコンテキストを考えましょう。
## よくある質問
いいえ。事前控除はあくまで**リクエスト前の一時的な仮押さえ**です。最終的な課金は、リクエスト完了後の**実際の token 使用量**で確定し、仮押さえしすぎた分は返金されます。表示されている`preConsumedQuota`は「最悪ケースの予備見積もり」であって、実際の請求額ではありません。
通常はされません。`insufficient_user_quota`エラーは**実行前**にブロックされるため、モデルは実際には呼び出されず、実コストも発生せず、仮押さえされたクォータは解放されます。
このエラーは、あなたの残高と「実際のコスト」を比較するのではなく、**事前控除**と残高を比較します。入力が大きすぎると、事前控除の見積もりが残高を大幅に上回るため、拒否されます。まず入力を減らすか、`max_tokens`を低く設定して推定出力を抑え、それでも必要ならチャージしてください。
モデルの単価はモデル自体で決まります。**ウィンドウが大きいほど単価が高い**わけではありません。とはいえ、ウィンドウが大きいほどより多くの入力を与えられ、実際にそれを埋めると入力 token が急増し、事前控除も実際の課金も高くなります。高くなるのは「どれだけ投入したか」であって、ウィンドウ自体ではありません。
## 関連ドキュメント
残高不足に関する完全なトラブルシューティングと解決策です。
出力長を制御し、事前差し引きの見積もりに影響します。
使用量ベースの精算の仕組みを理解します。
残高が少ないときにすばやくチャージする方法です。