画像 API の再送前にエラーを診断
接続、認証、入力、残高、ポリシー、上流のエラーを分けます。HTTP 成功だけではタスク成功を判断できません。
技術確認日:
まず失敗した層を特定
DNS、TCP、TLS が HTTP 応答前に失敗した場合、解釈する HTTP ステータスはありません。時刻、ホスト名、機密情報を除いた通信エラーを記録し、モデル失敗と決めつけないでください。応答後は HTTP 状態、error.code、リクエスト ID、存在すればタスク ID を記録し、非同期ではタスク状態も確認します。問い合わせにキー、元画像、非公開プロンプト、顧客情報を含めないでください。
400・401・402・403：入力とアカウントを確認
400 は詳細を読み、モデル名、サイズ、非対応項目、参照ファイルなど原因に応じて入力を修正します。401 はキーを表示せず Bearer 認証の有無と有効性を確認します。402 は利用可能残高、予約、予算制御、403 はモデルとルート権限を調べます。JSON に制限ルート名を指定しても権限は得られません。同じ不正設定の再送は修正ではありません。
429・451・5xx を同じ原因にしない
429 は制限の調査と上限付き再試行方針が必要です。画像処理での 451 は詳細とポリシー上の状況を確認し、画像形式エラーと決めつけたり制限回避のため再送したりしません。5xx はサービス、上流、容量、タイムアウト等を示す場合がありますが、コードだけでは原因箇所を特定できません。ID を保存して最終状態を確認してから新しい仕事を判断します。
最小限の診断記録を用意
UTC 時刻、エンドポイント、公開モデル ID、指定ルート、サイズ・品質、参照枚数、HTTP 状態、エラーコード、リクエスト ID、タスク状態を記録します。送信か確認か、結果を受信したか、許可済み非機密画像 1 枚でも再現するかも示します。秘密情報なしで調査を始められます。GET /healthz の成功はそのエンドポイントの確認だけで、権限や生成全体の検証ではありません。
モデル別パラメーター
公開設定のスナップショットであり、現在の稼働状況ではありません。パラメーター、ルート、参照画像の上限は各モデルページを確認してください。
- Gemini 3.1 Flash Lite Image
google/gemini-3.1-flash-lite-image - Gemini 3.1 Flash Image Preview
google/gemini-3.1-flash-image-preview - GPT Image 2
openai/gpt-image-2