ケーススタディ: 色を間違えた編集
タスク: おもちゃのティーセットの商品シートで、左下の 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 ＋画像を用いて他のモデルをテストしたところ、すべて初回の試行で成功しました：
モデルによって得意とする指示のタイプは異なります。あるモデルで失敗し続けるタスクであっても、別のモデルでは即座に成功する場合があります。APIYI 統合ゲートウェイでは、モデルの切り替えは
model パラメータを変更するだけ（同一キー、同一エンドポイント）であり、コストはほぼゼロです。「モデルの切り替え」を画像ワークフローにおける主要なステップとして位置付けてください。これは妥協ではなく、目標を達成するための正当な戦略です。
実際には、「まずは高速、後から強力」という段階的なラダーを構成します：
- 通常のタスクには、デフォルトで高速かつ安価なモデル（例：
gemini-3.1-flash-image）を使用します； - 精密な編集タスクが 1〜2 回失敗した場合は、自動的に
gemini-3-pro-imageまたはgpt-image-2シリーズにエスカレーションして再試行します； - それでもうまくいかない場合は、戻って prompt を見直します。
特殊なケース：小さな文字のぼやけはモデルの問題ではなく、品質ティアの問題
画像にテキストが含まれている場合（ポスター、UI スクリーンショット、看板、グラフのラベルなど）、小さな文字がぼやける原因は通常、モデルの能力不足ではなく設定された品質ティアが低すぎることにあります。まずは、お使いのモデルでどのティアが利用可能かを確認してください：
同一のティア名であっても、モデル間で同じティアを意味するわけではありません：2.5 シリーズではラダーが再調整されているため、2.5 の
high はおおよそ gpt-image-2 の medium に相当し、2.5 の max のみが gpt-image-2 の high と一致します。quality を変更せずにそのまま gpt-image-2 から引き継ぐと、暗黙のうちにティアが1段階下がることになり、「新しいモデルはテキストの描画が劣っている」ように見えてしまいます。ティアごとの数値については、GPT-Image-2.5 / 2 画像生成/編集 を参照してください。
Gemini ファミリー（Nano Banana 2 / 2 Lite）は quality パラメータを受け付けません。ここで調整できるのは解像度と thinkingLevel です：画像内のテキスト配置や構図の整合性が極めて重要な場合は thinkingLevel: "high" を有効にしてください（コストは約 +54%、レイテンシは約 +55% 増加します）。gemini-3-pro-image はこの調整をサポートしていません。メカニズムの詳細は 利用フィールドと出力の解説 に記載されています。
Strategy 4: まずテストツールで問題を切り分ける
「出力がなぜかおかしい」ときは、まず変数を切り分けてください。 imagen.apiyi.com を使えば、コードを書かずに「prompt + 画像」の組み合わせをすばやく検証できます。- ツールでも失敗する → ほぼ確実に prompt/タスクの問題です。Strategy 1 に戻るか、Strategy 3 に従ってモデルを切り替えてください;
- ツールでは成功するが、コードでは失敗する → コードを確認してください。画像が完全にアップロードされているか、パラメータが正しいか、prompt が途中で切れていないか、エスケープで壊れていないかを見てください;
- 成功したり失敗したりする → それはサンプリングのばらつきです。Strategy 2 に従ってリトライを追加してください。
クイックリファレンス
- Webアプリ ≠ API：Webアプリはpromptの書き換えやマルチステップのオーケストレーションを備えた完全なエージェントです。一方、APIは指定したpromptをそのまま実行する単一のアトミックな呼び出しです。体感される差の大部分はパイプラインによるものであり、「APIの理解度が低い」からではありません。
- 単一呼び出しにおけるランダムなばらつきは生成モデル特有の性質です。1回の失敗だけでモデルやゲートウェイの優劣を判断することはできません。
- 戦略1：promptを改善する：具体的な名詞や特定の色を用い、保持する要素を列挙して、アクションに番号を付けます。一度に変更する要素は1つのカテゴリに留めてください。
- 戦略2：リトライする：「意図しない編集」に対しては1〜2回のリトライを想定しておきます。「画像が出力されない」場合は別の問題です（エラーハンドリングガイドを参照してください）。
- 戦略3：モデルを切り替える：今回のケースでは、
gemini-3-pro-image、gemini-3.1-flash-lite-image、およびgpt-image-2シリーズはすべて初回の試行で成功しました。統合ゲートウェイなら、パラメータを1つ変更するだけです。 - 小さな文字がぼやける場合：まずは品質ティアを上げる：テキストを含む画像には最低でも
high（2.5シリーズではxhigh/max）を指定し、事前にtokenコストを確認してください。Geminiファミリーでは代わりにthinkingLevel: "high"を使用します。 - 戦略4：テストツールを使用して問題を切り分ける：まずはimagen.apiyi.comで「prompt + 画像」を検証し、promptの問題、コードの問題、サンプリングのばらつきを切り分けるようにしてください。