> ## 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.

# 如何生成滿意的圖片

> 用一個真實的圖片編輯案例，講清網頁版與 API 的本質差異、單次呼叫波動的來源，以及改提示詞、重試、換模型、用測試工具定位四個實用策略。

一次出圖不滿意是常態，**不滿意 ≠ 模型不行，更 ≠ 通道不行**。本文用一個真實客戶案例，講清「同一個模型，為什麼網頁版和 API 表現不一樣」，波動到底來自哪裡，以及四個能實際提高出圖成功率的策略。

## 案例復盤：一次「顏色改錯」的圖片編輯

任務是一張玩具茶具套裝的產品圖，圖中左下角「Cups」的兩隻杯子（一灰一綠）被紅框框住。提示詞：

> 把紅框中的物品換成黑色，並去除紅框，其他不變

<Frame caption="輸入原圖：紅框框住左下角的兩隻杯子（一灰一綠），要求換成黑色並去除紅框">
  <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="玩具茶具套裝產品圖，左下角兩隻杯子被紅色方框標註" width="1024" height="1021" data-path="images/image-edit-case-teaset-original.jpg" />
</Frame>

客戶用 `gemini-3.1-flash-image`（Nano Banana 2）通過 API 呼叫，得到的結果是：

<Frame caption="API 單次呼叫的失敗結果：兩隻杯子被改成了綠色，紅框也沒有去除">
  <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="編輯失敗的結果圖：紅框內兩隻杯子變成綠色而非要求的黑色，紅框仍然存在" width="1024" height="1024" data-path="images/image-edit-case-teaset-api-result.jpg" />
</Frame>

**顏色改錯了**——要求換黑色，結果出來是兩隻綠杯，紅框還在。而客戶在 gemini 網頁版（`gemini.google.com`）用同一個模型做同樣的編輯，效果很好。客戶的反饋是：

> API 和官方（網頁版）輸出的內容完全不一樣，感覺 API 理解層面沒有那麼到位。

這個感受很真實，但歸因需要修正。下面逐層拆解。

## 先講清：網頁版是 Agent，API 是單次原子呼叫

拿 `gemini.google.com` 的效果直接對比裸 API，本身就不是同一條鏈路的對比：

|       | Gemini 網頁版             | API 直調                     |
| ----- | ---------------------- | -------------------------- |
| 產品形態  | **綜合 Agent**           | **單次原子呼叫**                 |
| 你的提示詞 | 可能被系統**改寫、擴充、增強**後再進模型 | **原樣**進模型                  |
| 執行過程  | 可能有多步編排、內部重試/擇優        | 一次取樣、直接返回                  |
| 底層模型  | gemini-3.1-flash-image | gemini-3.1-flash-image（相同） |

同一個模型、兩種產品形態。網頁版幫你把「口語化指令」加工成了模型更容易執行好的形式，這層加工在 API 裡**需要你自己做**（這也正是 API 的價值：一切可控、可復現、可整合）。

<Info>
  所以「網頁版效果更好」的主要來源是**鏈路差異**，不能直接得出「API 理解不到位」的結論。API 拿到的是沒有任何加工的原始提示詞，表現自然更依賴提示詞本身的品質。
</Info>

## 單次呼叫有波動，是生成模型的固有屬性

我們用**完全相同的提示詞 + 圖片**，在 [imagen.apiyi.com](https://imagen.apiyi.com) 測試工具上重試了這個任務：**一次就編輯對了**——杯子變黑、紅框去除、其他不變。

<Info>
  需要澄清：imagen.apiyi.com 與裸 API 呼叫的唯一區別，是內建了一個「生成圖片」的意圖提示詞。它有助於讓模型明確「要輸出圖片」這個意圖，但與本案例「精準編輯是否成功」沒有關係——**工具上成功並不是因為工具「加了料」**。
</Info>

同樣的輸入、同樣的模型、同樣的通道，一次失敗一次成功，說明什麼？

**生成式模型的單次輸出本身就有隨機性**。每次呼叫都是一次獨立取樣，複雜指令（框選定位 + 換色 + 去框 + 保持其他）恰好是容易在個別取樣中「掉鏈子」的型別。這不是通道問題，也不是 API 被「降智」，而是模型固有的波動。

理解了波動來源，應對策略就清晰了——下面四個，按價效比排序。

## 策略一：改進提示詞

提示詞寫得越少歧義、越可執行，單次成功率越高。以本案例為例：

**原提示詞**（口語化，依賴模型自行推斷）：

> 把紅框中的物品換成黑色，並去除紅框，其他不變

**改進方向**：

| 技巧        | 原寫法      | 改進寫法                            |
| --------- | -------- | ------------------------------- |
| 用具體名詞替代指代 | 「紅框中的物品」 | 「紅框內的**兩隻杯子**」                  |
| 顏色寫具體     | 「換成黑色」   | 「改為**啞光純黑色**，保留原有材質質感」          |
| 保持項逐條列出   | 「其他不變」   | 「畫面其餘所有物品的顏色、位置、文字標註**全部保持不變**」 |
| 動作拆解明確    | 混在一句裡    | 「完成兩件事：① 兩隻杯子改為黑色；② 刪除紅色方框線」    |

**改進後的完整提示詞示例**：

> 編輯這張圖片，完成兩件事：① 把紅框內的兩隻杯子改為啞光純黑色，保留原有材質質感和形狀；② 刪除紅色方框線本身。畫面其餘所有物品的顏色、位置、尺寸標註和文字全部保持不變。

<Tip>
  通用原則：**一次只改一類東西**。如果編輯動作很多（換色 + 換背景 + 加文字），拆成多輪編輯，每輪的成功率都會顯著高於一次性下達複合指令。
</Tip>

### 不知道怎麼改？讓 AI 幫你改

改提示詞本身也可以交給 AI——方法很簡單，把三樣材料一起發給當下知名可靠的 AI 對話產品（如 `chatgpt.com`、`gemini.google.com`）：

1. **原始提示詞**（原樣貼上）；
2. **問題描述**（例如「要求換黑色，結果改成了綠色，紅框也沒去掉」）；
3. **出圖效果對比**（原圖 + 實際出圖，一起上傳）。

然後讓它「針對這個失敗結果，改寫出一個更精準、少歧義的圖片編輯提示詞」，通常一輪就能拿到明顯更好的版本。

如果無法訪問外網，用 API易 同樣能滿足 AI 對話需求：搭配 **Cherry Studio** 或 **Chatbox** 等對話客戶端接入我們的 API 即可，教程見文件中心「應用場景 - 對話」：

* [Cherry Studio 接入教程](/zh-Hant/scenarios/chat/cherry-studio)
* [Chatbox 接入教程](/zh-Hant/scenarios/chat/chatbox)

## 策略二：失敗就重試

既然失敗來自單次取樣的波動，**重試本身就是有效手段**——同樣的請求再發一次，很可能就對了（本案例正是如此）。

* 建議在業務程式碼裡對「結果不符合預期」保留 1–2 次自動重試的預算；
* 注意區分「出圖了但改錯」和「沒出圖」兩類失敗：後者（HTTP 200 但無圖片）通常是內容稽核攔截，處理方式見 [Gemini 生圖 API 錯誤處理指南](/zh-Hant/api-capabilities/gemini-image-error-handling)。

## 策略三：換模型

本案例中我們用同樣的提示詞 + 圖片實測了其他模型，**全部一次成功**：

| 模型                                    | 結果     |
| ------------------------------------- | ------ |
| `gemini-3-pro-image`（Nano Banana Pro） | ✅ 一次成功 |
| `gemini-3.1-flash-lite-image`         | ✅ 一次成功 |
| `gpt-image-2` 系列                      | ✅ 一次成功 |

不同模型對同一類指令的「擅長程度」不同，某個模型反覆失敗的任務，換一個模型可能一次就過。在 API易 聚合閘道下，換模型只需改 `model` 引數（同一個 key、同一個端點），成本極低——**把「換模型」納入你的出圖工作流，是達成出圖目標的正經策略，不是妥協**。

實踐中可以按「先快後強」組織一個梯隊：

1. 首選快而便宜的模型（如 `gemini-3.1-flash-image`）跑常規任務；
2. 精準編輯類任務失敗 1–2 次後，自動升級到 `gemini-3-pro-image` 或 `gpt-image-2` 系列重試；
3. 都不理想再回頭改提示詞。

## 策略四：先用測試工具定位問題

排查「為什麼出圖不對」時，先把變數隔離開。[imagen.apiyi.com](https://imagen.apiyi.com) 可以免程式碼快速驗證「提示詞 + 圖片」這個組合本身：

* **工具上也失敗** → 大機率是提示詞/任務本身的問題，回到策略一改提示詞，或按策略三換模型；
* **工具上成功、自己程式碼裡失敗** → 檢查程式碼：圖片是否完整上傳、引數是否正確、提示詞是否被截斷或轉義出錯；
* **時好時壞** → 就是取樣波動，按策略二加重試。

這樣能避免把「提示詞問題」誤判成「通道問題」，少走彎路。

## 速查總結

* **網頁版 ≠ API**：網頁版是帶提示詞改寫和多步編排的綜合 Agent，API 是原始提示詞的單次原子呼叫——觀感差異主要來自鏈路，不是「API 理解不行」。
* **單次輸出有隨機波動**是生成模型的固有屬性，一次失敗不代表模型/通道有問題。
* **策略一改提示詞**：具體名詞、具體顏色、保持項列清楚、動作拆解編號，一次只改一類東西。
* **策略二重試**：為「改錯」保留 1–2 次重試預算；「無圖」是另一類問題（見錯誤處理指南）。
* **策略三換模型**：本案例 `gemini-3-pro-image`、`gemini-3.1-flash-lite-image`、`gpt-image-2` 系列均一次成功；聚合閘道下換模型只改一個引數。
* **策略四用測試工具定位**：imagen.apiyi.com 先驗證「提示詞+圖」，區分提示詞問題、程式碼問題和取樣波動。

## 相關文件

* [Gemini 生圖 API 錯誤處理指南](/zh-Hant/api-capabilities/gemini-image-error-handling)
* [圖片壓縮與輸出解析度說明](/zh-Hant/api-capabilities/image-compression-resolution)
* [Nano Banana 系列開發指南](/zh-Hant/api-capabilities/nano-banana-dev-guide)