> ## 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 接入教程](/scenarios/chat/cherry-studio)
* [Chatbox 接入教程](/scenarios/chat/chatbox)

## 策略二：失败就重试

既然失败来自单次采样的波动，**重试本身就是有效手段**——同样的请求再发一次，很可能就对了（本案例正是如此）。

* 建议在业务代码里对「结果不符合预期」保留 1–2 次自动重试的预算；
* 注意区分「出图了但改错」和「没出图」两类失败：后者（HTTP 200 但无图片）通常是内容审核拦截，处理方式见 [Gemini 生图 API 错误处理指南](/api-capabilities/gemini-image-error-handling)。

## 策略三：换模型

本案例中我们用同样的提示词 + 图片实测了其他模型，**全部一次成功**：

| 模型                                    | 结果     |
| ------------------------------------- | ------ |
| `gemini-3-pro-image`（Nano Banana Pro） | ✅ 一次成功 |
| `gemini-3.1-flash-image-lite`         | ✅ 一次成功 |
| `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-image-lite`、`gpt-image-2` 系列均一次成功；聚合网关下换模型只改一个参数。
* **策略四用测试工具定位**：imagen.apiyi.com 先验证「提示词+图」，区分提示词问题、代码问题和采样波动。

## 相关文档

* [Gemini 生图 API 错误处理指南](/api-capabilities/gemini-image-error-handling)
* [图片压缩与输出分辨率说明](/api-capabilities/image-compression-resolution)
* [Nano Banana 系列开发指南](/api-capabilities/nano-banana-dev-guide)