ケーススタディ: 色を間違えた編集
タスク: おもちゃのティーセットの商品シートで、左下の 2 つの「カップ」（1 つはグレー、1 つはグリーン）を赤い枠で示したものです。プロンプト:赤い枠の中のアイテムを黒に変更し、赤い枠を削除し、それ以外はすべて変更しないでください
Input image: a red box marks the two cups (one gray, one green) in the lower left; the request is to make them black and remove the box
gemini-3.1-flash-image（Nano Banana 2）を呼び出し、次の結果を得ました:
Failed result from a single API call: both cups turned green, and the red box was not removed
gemini.google.com）で実行したところ、うまく動作しました。顧客のフィードバック:
API の出力は公式（Web）の出力と完全に異なります — API はあまり理解していないように感じます。苛立ちはもっともですが、原因の捉え方は修正が必要です。整理して見ていきましょう。
まず理解する: Web アプリはエージェントであり、API は単一のアトミック呼び出しです
gemini.google.com の結果を生の API 呼び出しと直接比較するのは、同条件の比較ではありません:
同じモデルでも、製品形態が 2 つあります。Web アプリは、あなたのカジュアルな指示をモデルがより確実に実行できる形に整えます。API では、その整形はあなたの役目です（そしてそれこそが API の価値です。すべてを制御可能、再現可能、統合可能にできます）。
したがって、「Web アプリのほうがうまく動く」のは主に パイプラインの違い によるものです。これは、「API の理解が劣る」という結論を支持しません。API は未加工の prompt をそのまま受け取るため、結果は prompt 自体の品質に、より強く左右されます。
単一呼び出しのばらつきは生成モデルに本質的です
imagen.apiyi.com のテストツールで、まったく同じ prompt + 画像 を使ってタスクを再試行しましたが、1回目で成功しました。カップは黒くなり、赤い箱は削除され、ほかはすべてそのままでした。はっきり言うと、imagen.apiyi.com と生の API 呼び出しの違いは、内部に「画像を生成する」という意図プロンプトがあることだけです。これはモデルが画像を生成する方向に確実に進む助けにはなりますが、このケースの厳密な編集が成功するかどうかには関係ありません。ツールが成功したのは、何か「特別な工夫」を足したからではありません。
戦略1: prompt を改善する
prompt が曖昧でなく、実行しやすいほど、単発での成功率は高くなります。このケースを例にすると: 元の prompt（くだけた表現で、モデルに推測を任せている）:赤い枠の中の物を黒に変えて、赤い枠を हटして、ほかはすべてそのままにする改善点:
改善後の complete prompt の例:
この画像を編集して、2つのことを行ってください: ① 赤い枠の中にある2つのカップを、元の素材感と形状を保ったままマットな純黒に変える; ② 赤い枠の輪郭そのものを削除する。画像内のほかのすべての要素の色、位置、寸法ラベル、テキストは完全にそのままにしてください。
どう改善すればよいかわからない場合は？ AI に書き直してもらいましょう
prompt の改善自体も、AI に任せられる作業です。よく知られた信頼性の高い AI チャット製品（たとえばchatgpt.com や gemini.google.com）に、次の3つをまとめて送るだけです:
- 元の prompt（そのまま貼り付ける）;
- 問題の説明（例: 「黒を指定したのに緑になったし、赤い枠も消えなかった」）;
- ビフォー/アフターの比較（元の画像と実際の出力を一緒にアップロードする）。
戦略 2: 失敗時にリトライする
失敗は単一サンプルのばらつきから生じるため、リトライ自体が有効な対処法です — 同じリクエストをもう一度送るだけで、そのままうまくいくことがよくあります（今回もまさにそれでした）。- 業務コードでは、「結果が期待に一致しない」場合に備えて、自動リトライを1〜2回分見込んでください;
- 2種類の失敗を区別してください: 「画像は返ってきたが編集が गलत」 versus 「画像がまったく返ってこない」です。後者（HTTP 200 だが画像なし）は、通常コンテンツモデレーションによるブロックです — Gemini Image API Error Handling Guide を参照してください。
戦略 3: モデルを切り替える
このケースでは、同一の prompt + image で他のモデルも試しましたが、すべて1回目で成功しました:
モデルごとに得意な指示の種類は異なります。あるモデルでは何度やっても失敗するタスクでも、別のモデルならすぐ通ることがあります。APIYI の統合ゲートウェイでは、モデルを切り替えるときに変更するのは
model パラメータだけです（キーもエンドポイントも同じ）— コストはほぼゼロです。「モデルを切り替える」を image ワークフローの第一級のステップにしてください。これは目標に到達するための正当な戦略であり、妥協ではありません。
実運用では、「高速を先に、強力なモデルは後で」という段階構成にします:
- 日常的なタスクには、高速で低コストなモデル（例:
gemini-3.1-flash-image）を標準にします; - 精密編集のタスクが1〜2回失敗したら、自動的に
gemini-3-pro-imageまたはgpt-image-2シリーズに切り替えて再試行します; - それでもうまくいかなければ、いったん戻って prompt を見直します。
Strategy 4: まずテストツールで問題を切り分ける
「出力がなぜかおかしい」ときは、まず変数を切り分けてください。 imagen.apiyi.com を使えば、コードを書かずに「prompt + 画像」の組み合わせをすばやく検証できます。- ツールでも失敗する → ほぼ確実に prompt/タスクの問題です。Strategy 1 に戻るか、Strategy 3 に従ってモデルを切り替えてください;
- ツールでは成功するが、コードでは失敗する → コードを確認してください。画像が完全にアップロードされているか、パラメータが正しいか、prompt が途中で切れていないか、エスケープで壊れていないかを見てください;
- 成功したり失敗したりする → それはサンプリングのばらつきです。Strategy 2 に従ってリトライを追加してください。
クイックリファレンス
- ウェブアプリ ≠ API: ウェブアプリはプロンプトの書き換えと複数ステップのオーケストレーションを備えた完全なエージェントですが、APIはそのままの prompt を使う単一のアトミックな呼び出しです。体感上の差は主にパイプラインに由来し、「APIがより少なく理解している」からではありません。
- ランダムな単発のばらつきは生成モデルに固有のものです。1回の失敗だけでは、モデルやゲートウェイについて何も判断できません。
- 戦略1、prompt を改善する: 具体的な名詞、明確な色、保持すべき内容の列挙、操作の番号付けを行い、1回に変える要素は1種類だけにします。
- 戦略2、再試行する: 「誤った編集」に対しては 1～2 回のリトライを見込みます。「画像がない」は別の問題です（エラー処理ガイドを参照してください）。
- 戦略3、モデルを切り替える: このケースでは
gemini-3-pro-image、gemini-3.1-flash-lite-image、およびgpt-image-2シリーズのいずれも初回で成功しました。統一ゲートウェイでは、変更するのは1つのパラメータだけです。 - 戦略4、テストツールで切り分ける: まず imagen.apiyi.com で「prompt + image」を検証し、prompt の問題、コードの問題、サンプリングのばらつきを切り分けます。