レート制限

全員のレイテンシを安定させるため、2つの制限があります：認証済み呼び出しのリクエストレート上限と、同時に実行する生成数の同時実行数上限です。リクエストレートを超えると429 rate_limitedが返り、料金はかかりません。同時実行数を超えても拒否はされません：生成はアカウントのキューで待機し、実行中の生成が1件完了するとすぐに開始します。

デフォルトの制限#

リクエストレートはトークンバケット方式です。一度に最大20件を送信でき、容量は1秒あたり10ずつ回復します。毎秒10リクエスト未満の安定したトラフィックは制限されません。

キュー#

• 同時実行数上限を超えた生成も通常どおり受け付けます：idはすぐに返り、料金分が確保され、ステータスはqueuedになります。実行中の生成が1件完了すると、古いものから順に自動で開始します。
• 待機時間は生成の制限時間に含まれません：キューで待っていることを理由に失敗やタイムアウトになることはありません。
• キューで待機中の生成は、いつでもキャンセル（POST /generations/{id}/cancel）または削除でき、確保された料金はすぐに返金されます。開始した後は、通常のキャンセルのルールが適用されます。
• キューに入る生成は同時実行数上限の最大10倍です（新規アカウントは200件）。それを超えるとリクエストには429 rate_limitedが返り、生成は作成されず料金もかかりません。
• キューはアカウントごとに独立しており、待機中の生成は処理容量を使いません。キューが長くても、ほかのアカウントの生成を遅らせることはありません。

自分の上限を確認する#

表はデフォルト値です。アカウント固有の上限と進行中の生成数は、ダッシュボード → 設定 と、GET /api/v1/account（および MCP ツール get_account）の limits フィールドで確認できます：

{
  "object": "account",
  "balance_usd": 42.5,
  "limits": {
    "unlimited": false,
    "concurrent_generations": 20,
    "in_flight": 3,
    "requests_per_second": 10,
    "burst": 20,
    "tier": null
  }
}

concurrent_generations は同時に実行できる生成数（超えた分はキューで待機）、in_flight は現在進行中の数（キュー内の生成を含む）です。requests_per_second と burst はリクエストレートとバーストで、アカウント全体と各 API キーに適用されます。

制限に達した場合#

{
  "error": {
    "code": "rate_limited",
    "message": "Your queue is full: 200 generations are already waiting for your 20 concurrent slots (up to 200 can wait). Nothing was submitted or charged. Retry when some have finished (webhook_url tells you when), or cancel queued ones; GET /api/v1/account shows your limits. For a higher limit, contact us: contact@cheapergen.com."
  }
}

すべての 429 には Retry-After ヘッダー（待機秒数）が付きます。上限に達した場合はメッセージにその上限が示され、キューが満杯の場合は待機中の生成数も示されます。

• リクエストレート：超過時は少し待ってから、指数バックオフとジッターで再試行してください（最初は約1秒）。安全に再試行するをご覧ください。
• キューが満杯：同時実行数による429は、キューが満杯のときにだけ返ります。生成が完了するのを待つか（webhook_urlで通知されます）、キュー内の生成をキャンセルしてから、次を送信してください。

制限内で使うには#

頻繁なポーリングの代わりにWebhookを使う#

毎秒数十件のジョブをポーリングすると、リクエスト枠を使い切ります。代わりにwebhook_urlを指定して、当社から通知を受け取ってください。詳しくはWebhookをご覧ください。動画をポーリングする場合は、5〜10秒間隔に延ばしてください。

自分の環境で送信をキューに入れる#

短時間の集中した送信は問題ありません：キューが受け止めます。キューより大きいバッチは、未処理分を自分の側で保持し、生成の完了に合わせて送信してください（Webhookで通知されます）。そうすればキュー満杯の429は発生しません。

サービスごとにキーを使い分ける#

リクエストレートはキー単位、同時実行数はアカウント単位で数えます。キーを増やしても、同時に実行できる生成数は増えません。