チュートリアル

画像生成 API レート制限の詳細解説：想定される動作と HiAPI がバーストトラフィックにどう対応するか

Jun 28, 2026

画像 API における「レート制限」の本当の意味

画像生成リクエストが HTTP 429 で失敗したり、バッチ処理が毎回まったく同じ並列数で止まったりする場合、それはバグではなくレート制限に遭遇しています。実運用レベルの画像 API はすべて、少なくとも次の 3 つの次元のいずれかでトラフィックを制限しており、これらの違いを理解することがデバッグには不可欠です：

RPM（1 分あたりのリクエスト数）——ローリング 60 秒ウィンドウ内で発行できる POST 呼び出しの回数。バーストトラフィックに強く、回復も早い。
RPD（1 日あたりのリクエスト数）——1 日の上限で、通常はプラン階層に連動する。UTC の深夜（またはアカウントの課金日）にリセットされる。
並列数 / 進行中タスク数——同時に実行できる画像タスクの数。RPM が正常でも、5 番目の進行中タスクはキューに入れられるか拒否される。

画像生成に限って言えば、ボトルネックはほぼ常に並列数であり、RPM ではありません。単一の 1024×1024 タスクはエンドツーエンドで 8〜30 秒かかることがあるため、10 個の並列タスク ≠ 10 RPM です。この 2 つを混同することが、「リトライしたら状況が悪化した」という最もよくある原因です。

発生頻度順のよくある原因

並列度が並列上限を超えている。最も可能性が高い原因です。ループが一度に 50 個の POST /v1/tasks 呼び出しを発行し、プロバイダーが最初の N 個を受け入れ、残りが 429 を返します。ほとんどのプロバイダーの並列上限は、キーごとに個別に文書化されておらず、プラン階層から推測されるものです。
一過性エラー後のリトライストーム。1 つのタスクが 5xx を返すと即座にリトライが発生し、他のすべての進行中タスクも同じことをするため、実効並列数が 1 秒で倍になります。
知らないうちに適用されているモデル別 RPM 上限。高 tier の汎用キーでも、特に新しいモデルや上位モデルではモデル次元の制限を受けることがあります。同じキーで gpt-image-2 と flux-1-pro を呼び出しても、それらが 1 つのクォータを共有しているわけではありません。
日次クォータが昼過ぎに枯渇する。それほど多くはないものの最も混乱しやすい原因です——リクエストは正常に動いていたのに、毎日同じ壁時計時刻に失敗し始めます。これは常に RPD です。
共有サブアカウント上のノイジーネイバー。環境ごとにキーを分けていても、それらが 1 つの課金アカウントを共有している場合、ステージングのトラフィックが本番のクォータを食いつぶします。

修正手順

以下の手順を順番に実行してください。各ステップは異なる次元を切り分けます。

ステータスコードだけでなく、エラーレスポンスボディを読む。HiAPI から返される実際の 429 は次のようになります：
```
{
  "error": {
    "code": "rate_limit_exceeded",
    "type": "hiapi_error",
    "request_id": "req_01HXXXXXXXXXXXXXXX"
  }
}
```
request_id を控えてください。これはサポートチームがどの制限に引っかかったのかを正確に追跡できる唯一の情報です。
429 と 401 を区別する。{"error":{"code":"permission_denied","type":"hiapi_error","request_id":...}} を伴う 401 はレート制限ではなく、認証または権限の失敗です。401 にバックオフを追加しないでください。どれだけ待っても 200 にはなりません。
リトライ回数より先にクライアント側の並列数を制限する。シンプルなセマフォで十分です：
```
import asyncio, httpx
sem = asyncio.Semaphore(4)  # この値をプロバイダーの並列上限に合わせる

async def submit(client, payload):
    async with sem:
        return await client.post("https://api.hiapi.ai/v1/tasks", json=payload)
```
4 から始めてください。バッチ全体が一度も 429 を出さずに完走した場合にのみ、値を上げてください。

429 のときだけフルジッター付き指数バックオフを使う。

import asyncio, random
async def backoff(attempt):
    # 1s, 2s, 4s, 8s、上限 30s、サンダリングハードを避けるためランダム化
    delay = min(30, 2 ** attempt) * random.random()
    await asyncio.sleep(delay)

リトライ回数の上限は 5 に設定してください。それ以降は失敗を表面化させ、無限にリトライしないでください。

Retry-After が存在するときはそれに従う。レスポンスに Retry-After ヘッダーがある場合、それはプロバイダーがウィンドウのリセット時刻を明示しているものです。そのリトライでは、自分で計算したバックオフ値ではなく、それを使用してください。
環境ごとにキーを分離する。ステージングと本番が 1 つのキーを共有していると、並列上限も共有されます。環境ごとに 1 キー + 高トラフィックのワーカープールごとに 1 キーとすることが、「制限がドキュメントより低く感じる」問題を解決する最も安価な方法です。

HiAPI がバーストトラフィックをどう処理するか

HiAPI は POST /v1/tasks エンドポイントを前面に提供しており、タスクを受け取るとすぐにタスク id を返し、その後で完了状態をポーリングします。この分離はレート制限の計算において重要です。作成呼び出しはオーバーヘッドが小さく短時間で済むため、RPM 制限は緩く、重い処理はモデル側の並列制御で行われます。これが本来あるべき姿です。下流のプロバイダーが輻輳しているときでも作成呼び出しは成功し、タスクはキューで待機するだけであり、GET /v1/tasks/{id} はスロットが空くまで status: "queued" を返します。下流の一時的な負荷で 429 が返ることはなく、あなたが自分のキーのクォータを超えたときにのみ返ります。

これこそが、チームの画像ワークロードが単一アカウントの処理能力を超えたときに、プロバイダー直接統合から HiAPI へ移行する実質的な理由です。1 つの Bearer キー、推論可能なレート制限予算、バーストトラフィックはリトライループではなくキューによって吸収されます。

最小限の検証例

これを使って、キーが正常で並列設定が妥当であることを確認してください。gpt-image-2 に画像タスクを送信し、タスク id を出力します：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "a single red apple on a wooden table, soft daylight",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

想定されるレスポンス：

200 と {"id":"task_...","status":"queued"} → キーは正常、クォータも問題なし。
429 と {"error":{"code":"rate_limit_exceeded",...}} → RPM、RPD、または並列制限を超えています。上記の修正手順に従って速度を落としてください。
401 と {"error":{"code":"permission_denied",...}} → 認証失敗であり、レート制限ではありません。キーを確認してください。

高速な seq 1 10 | xargs -n1 -P10 curl ... ループでこの呼び出しを繰り返し、並列上限を見つけてください。最初に 429 を返した時点が実効上限です。

HiAPI タスクのハングとタイムアウトの診断——タスクが queued または processing 状態に想定以上に留まる場合。
HiAPI タスクのコールバックが発火しない理由——/v1/tasks フローの非同期コールバックのトラブルシューティング。
model_not_available エラーの解決——隣接するエラーカテゴリで、レート制限と誤読されがちです。
モデルカタログ——モデル別の価格とエンドポイントタイプ。
料金——tier ごとの明細。

よくある質問

HiAPI 上の gpt-image-2 に公開されている RPM の数値はありますか？ 制限は tier に基づいており、プロバイダーがそれぞれの上限を調整すると変わる可能性があります。ブログ記事の数値をハードコードするのではなく、ダッシュボードで現在の有効な制限を確認してください。

リトライが 429 を悪化させることがあるのはなぜですか？ N 個の並列ワーカーで sleep(1) リトライを素朴に使うと、1 つの 429 が N 個の同期リトライになり、すべてが再びヒットします。固定遅延ではなくフルジッター（sleep * random.random()）を使用してください。

HiAPI は 429 レスポンスに課金しますか？ いいえ。失敗したタスク作成（429、401、一般的な 4xx）は課金されません。料金が発生するのは、出力を正常に生成したタスクのみです。

クライアント側で並列数を上げれば上限は上がりますか？ いいえ。並列上限はサーバー側でキーごとに設定されています。クライアント側の並列度は、上限未満に留まるか上限に達するかを決めるだけです。

RPM と TPM の違いは何ですか？ 画像 API はトークン（TPM）ではなくリクエスト（RPM）で制限されます。画像タスクには意味のある「トークン」単位がありません。ダッシュボードに TPM 制限が表示されている場合、それはテキスト/チャットエンドポイントに適用されるものであり、/v1/tasks の画像タスクには適用されません。

高並列のキー 1 つと低並列のキー複数のどちらを使うべきですか？ 画像ワークロードでは、論理ワーカープールごとに 1 キーとするのが最もシンプルなメンタルモデルです。1 つの課金アカウント下の複数キーは実際にはクォータを倍増させません。クォータを共有します。

より高い並列上限を申請できますか？ はい——現在の tier で継続的な使用実績を示せば可能です。サポートチームに代表的な 429 の request_id を提供すれば、どの次元に達しているかを追跡できます。

Retry-After ヘッダーが表示されないのはなぜですか？ すべてのプロバイダーが送信するわけではありません。存在しない場合は、1 秒から始まるジッター付き指数バックオフにフォールバックしてください。存在する場合は、そのリトライではそれを信頼してください。