> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 納得できる画像を得る方法

> WebアプリとAPIの根本的な違い、単発呼び出しでばらつきが生じる理由、そしてより良い prompt、再試行、モデルの切り替え、テストツールによる問題の切り分けという4つの実践的な戦略を説明する、実際の画像編集ケーススタディです。

最初の試みで満足のいく画像が得られないのは普通です — **満足のいかない結果 ≠ モデルが悪い、そしてもちろん ≠ ゲートウェイが悪い**。このページでは、実際のお客様の事例をもとに、同じモデルがウェブアプリではなく API ではなぜ異なる挙動を示すのか、実際にどこから差異が生まれるのか、そして成功率を目に見えて改善する 4 つの戦略を解説します。

## ケーススタディ: 色を間違えた編集

タスク: おもちゃのティーセットの商品シートで、左下の 2 つの「カップ」（1 つはグレー、1 つはグリーン）を赤い枠で示したものです。プロンプト:

> 赤い枠の中のアイテムを黒に変更し、赤い枠を削除し、それ以外はすべて変更しないでください

<Frame caption="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">
  <img src="https://mintcdn.com/apiyillc/YlApNMokaLGR-mkl/images/image-edit-case-teaset-original.jpg?fit=max&auto=format&n=YlApNMokaLGR-mkl&q=85&s=f5b3a4848c8d8256c574ffa72a0fc88a" alt="左下の 2 つのカップが赤い枠で示されたおもちゃのティーセットの商品シート" width="1024" height="1021" data-path="images/image-edit-case-teaset-original.jpg" />
</Frame>

顧客は API 経由で `gemini-3.1-flash-image`（Nano Banana 2）を呼び出し、次の結果を得ました:

<Frame caption="Failed result from a single API call: both cups turned green, and the red box was not removed">
  <img src="https://mintcdn.com/apiyillc/LihN1TRFUvEsZ0oh/images/image-edit-case-teaset-api-result.jpg?fit=max&auto=format&n=LihN1TRFUvEsZ0oh&q=85&s=ba1ec09f532b9266ad0e6012384a98d0" alt="編集失敗の結果: 赤い枠の中の 2 つのカップは、指定された黒ではなくグリーンに変わっており、赤い枠もまだ残っています" width="1024" height="1024" data-path="images/image-edit-case-teaset-api-result.jpg" />
</Frame>

**色が間違って出力されました** — 黒が指定されていたのに、結果には 2 つのグリーンのカップが表示され、赤い枠もそのまま残っています。一方で、顧客は同じモデルで同じ編集を Gemini のウェブアプリ（`gemini.google.com`）で実行したところ、うまく動作しました。顧客のフィードバック:

> API の出力は公式（Web）の出力と完全に異なります — API はあまり理解していないように感じます。

苛立ちはもっともですが、原因の捉え方は修正が必要です。整理して見ていきましょう。

## まず理解する: Web アプリはエージェントであり、API は単一のアトミック呼び出しです

`gemini.google.com` の結果を生の API 呼び出しと直接比較するのは、同条件の比較ではありません:

|             | Gemini web app                                | Direct API call            |
| ----------- | --------------------------------------------- | -------------------------- |
| 製品形態        | **完全なエージェント**                                 | **単一のアトミック呼び出し**           |
| あなたの prompt | モデルに届く前に、システムによって **書き換えられ、拡張され、強化される** ことがある | モデルに **そのまま** 届く           |
| 実行          | 複数ステップのオーケストレーション、内部リトライ/選択の可能性あり             | 1 回のサンプリングパスで、そのまま返される     |
| 基盤モデル       | gemini-3.1-flash-image                        | gemini-3.1-flash-image（同一） |

同じモデルでも、製品形態が 2 つあります。Web アプリは、あなたのカジュアルな指示をモデルがより確実に実行できる形に整えます。API では、その整形はあなたの役目です（そしてそれこそが API の価値です。すべてを制御可能、再現可能、統合可能にできます）。

<Info>
  したがって、「Web アプリのほうがうまく動く」のは主に **パイプラインの違い** によるものです。これは、「API の理解が劣る」という結論を支持しません。API は未加工の prompt をそのまま受け取るため、結果は prompt 自体の品質に、より強く左右されます。
</Info>

## 単一呼び出しのばらつきは生成モデルに本質的です

[imagen.apiyi.com](https://imagen.apiyi.com) のテストツールで、**まったく同じ prompt + 画像** を使ってタスクを再試行しましたが、**1回目で成功**しました。カップは黒くなり、赤い箱は削除され、ほかはすべてそのままでした。

<Info>
  はっきり言うと、imagen.apiyi.com と生の API 呼び出しの違いは、内部に「画像を生成する」という意図プロンプトがあることだけです。これはモデルが画像を生成する方向に確実に進む助けにはなりますが、このケースの厳密な編集が成功するかどうかには関係ありません。**ツールが成功したのは、何か「特別な工夫」を足したからではありません**。
</Info>

同じ入力、同じモデル、同じゲートウェイで、1回は失敗し、1回は成功しました。これが示すのは何でしょうか？

**生成モデルの個々の出力は、本質的に確率的です。** 各呼び出しは独立したサンプリング処理であり、複合的な指示（箱を基準に位置を特定 + 色を変更 + 箱を削除 + ほかはすべて保持）は、単一サンプルではときどき抜け落ちる種類のものです。これはゲートウェイの問題でも、API が「簡略化された」わけでもなく、モデル固有のばらつきです。

ばらつきの発生源が分かれば、対策は明確です。費用対効果の高い順に、4つ紹介します。

## 戦略1: prompt を改善する

prompt が曖昧でなく、実行しやすいほど、単発での成功率は高くなります。このケースを例にすると:

**元の prompt**（くだけた表現で、モデルに推測を任せている）:

> 赤い枠の中の物を黒に変えて、赤い枠を हटして、ほかはすべてそのままにする

**改善点**:

| 手法              | 元の表現            | 改善後                                         |
| --------------- | --------------- | ------------------------------------------- |
| 参照表現より具体的な名詞を使う | 「赤い枠の中の物」       | 「赤い枠の中にある**2つのカップ**」                        |
| 色を具体的に指定する      | 「黒に変える」         | 「元の素材感を保ったまま、**マットな純黒**に変える」                |
| 保持する内容を列挙する     | 「ほかはすべてそのままにする」 | 「画像内の**ほかのすべての要素**の色、位置、テキストラベルをそのままにする」    |
| 変更内容を明示的に番号付けする | 1文に混在している       | 「2つのことを行う: ① 2つのカップを黒に再着色する; ② 赤い枠の輪郭を削除する」 |

**改善後の complete prompt の例**:

> この画像を編集して、2つのことを行ってください: ① 赤い枠の中にある2つのカップを、元の素材感と形状を保ったままマットな純黒に変える; ② 赤い枠の輪郭そのものを削除する。画像内のほかのすべての要素の色、位置、寸法ラベル、テキストは完全にそのままにしてください。

<Tip>
  一般原則: **1回の編集では、1種類の対象だけを変える**ことです。編集に多くの操作（再着色 + 背景差し替え + テキスト追加など）が含まれる場合は、複数回の編集ラウンドに分けてください。各ラウンドの成功率は、1つの複合指示よりも大幅に高くなります。
</Tip>

### どう改善すればよいかわからない場合は？ AI に書き直してもらいましょう

prompt の改善自体も、AI に任せられる作業です。よく知られた信頼性の高い AI チャット製品（たとえば `chatgpt.com` や `gemini.google.com`）に、次の3つをまとめて送るだけです:

1. **元の prompt**（そのまま貼り付ける）;
2. **問題の説明**（例: 「黒を指定したのに緑になったし、赤い枠も消えなかった」）;
3. **ビフォー/アフターの比較**（元の画像と実際の出力を一緒にアップロードする）。

そのうえで、「この失敗結果をもとに、より正確で曖昧さの少ない画像編集用の prompt に書き直してください」と依頼してください。1回で、かなり改善された版が得られることがよくあります。

そのサイトにアクセスできない場合でも、APIYI なら AI チャットの用途は十分にカバーできます。API を **Cherry Studio** や **Chatbox** のようなチャットクライアントに接続してください。ドキュメントの「Scenarios - Chat」には、次のチュートリアルがあります:

* [Cherry Studio セットアップチュートリアル](/ja/scenarios/chat/cherry-studio)
* [Chatbox セットアップチュートリアル](/ja/scenarios/chat/chatbox)

## 戦略 2: 失敗時にリトライする

失敗は単一サンプルのばらつきから生じるため、**リトライ自体が有効な対処法です** — 同じリクエストをもう一度送るだけで、そのままうまくいくことがよくあります（今回もまさにそれでした）。

* 業務コードでは、「結果が期待に一致しない」場合に備えて、自動リトライを1〜2回分見込んでください;
* 2種類の失敗を区別してください: 「画像は返ってきたが編集が गलत」 versus 「画像がまったく返ってこない」です。後者（HTTP 200 だが画像なし）は、通常コンテンツモデレーションによるブロックです — [Gemini Image API Error Handling Guide](/ja/api-capabilities/gemini-image-error-handling) を参照してください。

## 戦略 3: モデルを切り替える

このケースでは、同一の prompt + image で他のモデルも試しましたが、**すべて1回目で成功しました**:

| モデル                                    | 結果       |
| -------------------------------------- | -------- |
| `gemini-3-pro-image` (Nano Banana Pro) | ✅ 1回目で成功 |
| `gemini-3.1-flash-lite-image`          | ✅ 1回目で成功 |
| `gpt-image-2` シリーズ                     | ✅ 1回目で成功 |

モデルごとに得意な指示の種類は異なります。あるモデルでは何度やっても失敗するタスクでも、別のモデルならすぐ通ることがあります。APIYI の統合ゲートウェイでは、モデルを切り替えるときに変更するのは `model` パラメータだけです（キーもエンドポイントも同じ）— コストはほぼゼロです。**「モデルを切り替える」を image ワークフローの第一級のステップにしてください。これは目標に到達するための正当な戦略であり、妥協ではありません。**

実運用では、「高速を先に、強力なモデルは後で」という段階構成にします:

1. 日常的なタスクには、高速で低コストなモデル（例: `gemini-3.1-flash-image`）を標準にします;
2. 精密編集のタスクが1〜2回失敗したら、自動的に `gemini-3-pro-image` または `gpt-image-2` シリーズに切り替えて再試行します;
3. それでもうまくいかなければ、いったん戻って prompt を見直します。

## Strategy 4: まずテストツールで問題を切り分ける

「出力がなぜかおかしい」ときは、まず変数を切り分けてください。 [imagen.apiyi.com](https://imagen.apiyi.com) を使えば、コードを書かずに「prompt + 画像」の組み合わせをすばやく検証できます。

* **ツールでも失敗する** → ほぼ確実に prompt/タスクの問題です。Strategy 1 に戻るか、Strategy 3 に従ってモデルを切り替えてください;
* **ツールでは成功するが、コードでは失敗する** → コードを確認してください。画像が完全にアップロードされているか、パラメータが正しいか、prompt が途中で切れていないか、エスケープで壊れていないかを見てください;
* **成功したり失敗したりする** → それはサンプリングのばらつきです。Strategy 2 に従ってリトライを追加してください。

これで、prompt の問題をゲートウェイの問題と誤診せずに済み、無駄な回り道をかなり減らせます。

## クイックリファレンス

* **ウェブアプリ ≠ 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 の問題、コードの問題、サンプリングのばらつきを切り分けます。

## 関連ドキュメント

* [Gemini 画像 API エラー処理ガイド](/ja/api-capabilities/gemini-image-error-handling)
* [画像圧縮と出力解像度](/ja/api-capabilities/image-compression-resolution)
* [Nano Banana シリーズ開発者ガイド](/ja/api-capabilities/nano-banana-dev-guide)