画像生成APIエラー完全ガイド：GPT Image・Gemini・Qwen
画像生成APIのエラーを、認証、モデル権限、パラメータ、クォータ、安全性、タイムアウト、レスポンス解析の各層で診断し、モデル別の確認手順まで整理します。
Ofox 
画像生成APIのエラーは一種類ではありません。 認証、モデル権限、パラメータ、クォータ、安全性判定、上流容量、タイムアウト、レスポンス解析のどこで失敗したかを先に切り分けます。
最初に保存する情報
日時とタイムゾーン:
ホストとエンドポイント:
正確なモデルID:
HTTPステータスと完全なエラー本文:
request IDとretry header:
SDKとバージョン:
生成または編集:
参照画像の有無:
サイズ、品質、形式、背景:
処理時間:
最小リクエストで再現: yes/noAPIキー、署名付きURL、非公開プロンプト、入力画像は共有前に削除します。
エラーコードから失敗した層を特定する
| 症状 | 主な原因 | 最初の対応 |
|---|---|---|
400 / INVALID_ARGUMENT | リクエスト形式、未対応パラメータ | エンドポイント、フィールド、APIバージョンを修正 |
401 | APIキーが未設定・形式不正 | 実際に送信された認証情報を確認 |
403 / PERMISSION_DENIED | プロジェクト、モデル権限、キー制限 | アカウントと完全な本文を確認 |
404 / model_not_found | モデルID、エンドポイント、権限 | エラーが指すリソースを確認 |
429 / RESOURCE_EXHAUSTED | RPM/IPM、日次枠、支出上限、残高 | クォータ指標を読み、一時的な場合だけ再試行 |
| 安全性コード、画像なし | 入力または出力のブロック | ブロック理由を読み、入力を見直す |
500 / 503 | 上流障害、容量不足 | request IDを保存し、限定的に再試行 |
504 / 接続リセット | モデル、ゲートウェイ、クライアント期限 | 最初に閉じた箇所を特定 |
HTTP 200だが画像なし | 解析または機能の不一致 | url、b64_json、MIME、アルファチャンネルを確認 |
GPT Imageのエラー
Direct Images APIかResponses内のimage generation toolかを記録します。両者のリクエストボディは同一ではありません。OpenAI画像生成ドキュメントと照合してください。
model_not_foundでは、完全なモデルID、接続先、エンドポイント、キーを所有するプロジェクトを確認します。モデルID・権限診断が詳しい手順です。
size、quality、background、output_formatはモデルごとに検証します。透明出力にはpngまたはwebpが必要で、jpegはアルファチャンネルを保持できません。GPT Image 2.5 APIガイドと透明背景診断を参照してください。
遅延や504は、クライアント期限と上流エラーを分けます。GPT Image 2の生成失敗診断（英語）で症状を照合します。
Gemini / Nano Bananaのエラー
GenerateContentはHTTPコードに加えてstatusとdetailsを返すことがあります。GenerateContentエラー表は、400、402、403、404、429、503、504を区別しています。
Interactions APIには別のエラー形式があり、rate_limit_exceeded、image_safety、image_prohibited_content、image_recitation、no_imageなどを使います。これらをGenerateContentの形式と混同しないでください。
429ではキーが属する実プロジェクトと名前付きクォータ指標を確認します。無料枠がゼロなら再試行では解決しません。一時的な429、408、5xxだけを公式トラブルシューティングに従って処理します。
Qwen Imageのエラー
次の表は、2026年7月23日にOfoxで実施したQwen Imageルート試験の観察結果です。
| 症状 | 診断 | 対応 |
|---|---|---|
429 Requests rate limit exceeded | 試用容量またはレート制限 | 直列化、バックオフ、現在のルート確認 |
b64_jsonがNone | URL返却をbase64として解析 | 文書化された両形式を処理 |
HTTP 200だが参照対象がない | 参照画像フィールドが無視された可能性 | 出力レベルで参照整合性を検証 |
model_not_found | 古い、利用不可、不正なID | 現在のカタログと権限を確認 |
検証条件と制約はQwen Image 3.0 Pro接続レポートにあります。特定日のルート試験を恒久仕様として扱わないでください。
Grok Imagine、Seedream、FLUX
Grokのエイリアス廃止や再割り当てでは、リクエストが成功しても出力が変わることがあります。Grok Imagineガイドと移行ガイドを確認します。
他の画像モデルでは、最小の文書化済みリクエストから開始し、正確なモデルIDを使います。URL、base64、非同期タスクのどれが返るか確認し、size、quality、reference image、edit、transparencyを一つずつ追加します。Ofox画像APIドキュメントも参照してください。
再試行の判断
ネットワーク中断、一時的な408、429、500、503だけを上限付き指数バックオフとジッターで再試行します。不正パラメータ、キー、権限、クォータゼロ、残高不足、安全性ブロック、パーサー不具合は原因を修正します。
SDKがすでに再試行していないか確認してください。期限超過では処理完了が不明な場合があります。タスクIDがあるAPIでは再送前に既存のタスクを取得し、idempotencyは文書化された場合だけ使います。無条件再試行は重複画像や二重の課金対象ジョブを作る可能性があります。
関連ガイド
| 症状 | 個別ガイド |
|---|---|
| GPT Imageが遅い、504 | GPT Image 2の生成失敗診断（英語） |
| 透明背景が未対応 | 透明背景エラー |
OpenAIのmodel_not_found | モデルID・権限診断 |
| Qwenの429、URL/base64不一致 | Qwen Imageルート試験 |
| 任意のプロバイダーの429 | 429再試行判断ガイド |
参考資料
よくある質問
- 画像生成APIが失敗したとき、何を保存すべきですか？
- 日時、接続先、エンドポイント、モデルID、HTTPステータス、機密情報を除いた完全なエラー本文、request ID、レスポンスヘッダー、SDKとバージョン、入出力設定、処理時間、最小リクエストで再現するかを保存します。
- 429エラーはすべて再試行すべきですか？
- いいえ。一時的なレート制限だけを上限付き指数バックオフとジッターで再試行します。クォータゼロ、残高不足、課金無効は設定変更が必要です。
- HTTP 200なのに画像を利用できないのはなぜですか？
- URLとbase64の取り違え、未対応の参照画像フィールド、透明度のない出力などが考えられます。ステータスだけでなくレスポンスと実ファイルを検証してください。
- 画像モデルを切り替えればエラーは直りますか？
- 原因がモデルの機能、権限、容量にある場合に限ります。APIキー、エンドポイント、ペイロード、パーサーの問題はモデル変更では直りません。
