Getting an unsatisfying image on the first try is normal — unsatisfying ≠ bad model, and definitely ≠ bad gateway. This page walks through a real customer case to explain why the same model behaves differently in the web app versus the API, where the variance actually comes from, and four strategies that measurably improve your success rate.
Case Study: an Edit That Got the Color Wrong
The task: a product sheet of a toy tea set, with the two “Cups” in the lower left (one gray, one green) marked by a red box. The prompt:
Change the items in the red box to black, remove the red box, keep everything else unchanged
The customer called gemini-3.1-flash-image (Nano Banana 2) via the API and got this:
The color came out wrong — black was requested, but the result shows two green cups with the red box still in place. Meanwhile, the customer ran the same edit with the same model on the Gemini web app (gemini.google.com) and it worked well. Their feedback:
The API output is completely different from the official (web) output — it feels like the API just doesn’t understand as well.
The frustration is real, but the attribution needs correcting. Let’s break it down.
First, Understand: the Web App Is an Agent; the API Is a Single Atomic Call
Comparing gemini.google.com results directly against a raw API call is not an apples-to-apples comparison:
| Gemini web app | Direct API call |
|---|
| Product form | Full agent | Single atomic call |
| Your prompt | May be rewritten, expanded, enhanced by the system before reaching the model | Reaches the model verbatim |
| Execution | Possibly multi-step orchestration, internal retries/selection | One sampling pass, returned directly |
| Underlying model | gemini-3.1-flash-image | gemini-3.1-flash-image (identical) |
So “the web app works better” mostly comes from pipeline differences — it does not support the conclusion that “the API understands less”. The API receives your raw, unprocessed prompt, so results naturally depend more on the prompt’s own quality.
Single-Call Variance Is Inherent to Generative Models
We retried the task with the exact same prompt + image on the imagen.apiyi.com test tool: it succeeded on the first try — cups turned black, red box removed, everything else untouched.
To be clear: the only difference between imagen.apiyi.com and a raw API call is a built-in “generate an image” intent prompt. It helps the model commit to producing an image, but has nothing to do with whether this case’s precise edit succeeds — the tool did not succeed because it “added secret sauce”.
Strategy 1: Improve the Prompt
The less ambiguous and more executable the prompt, the higher the single-call success rate. Using this case as the example:
Original prompt (casual, relies on the model to infer):
Change the items in the red box to black, remove the red box, keep everything else unchanged
Improvements:
| Technique | Original | Improved |
|---|
| Concrete nouns over references | ”the items in the red box" | "the two cups inside the red box” |
| Be specific about color | ”change to black" | "change to matte pure black, preserving the original material texture” |
| Enumerate what to preserve | ”keep everything else unchanged" | "keep the colors, positions, and text labels of all other items in the image unchanged” |
| Number the actions explicitly | Mixed into one sentence | ”Do two things: ① recolor the two cups to black; ② delete the red box outline” |
Edit this image and do two things: ① change the two cups inside the red box to matte pure black, preserving their original material texture and shape; ② delete the red box outline itself. Keep the colors, positions, dimension labels, and text of all other items in the image completely unchanged.
General principle: change one category of thing at a time. If the edit involves many actions (recolor + replace background + add text), split it into multiple editing rounds — each round’s success rate will be significantly higher than one compound instruction.
Not Sure How to Improve It? Let an AI Rewrite It for You
Improving the prompt is itself a job you can hand to AI — simply send three things together to a well-known, reliable AI chat product (such as chatgpt.com or gemini.google.com):
- The original prompt (pasted verbatim);
- A description of the problem (e.g. “asked for black, got green, and the red box wasn’t removed”);
- The before/after comparison (upload the original image and the actual output together).
Then ask it to “rewrite this into a more precise, less ambiguous image-editing prompt based on this failed result” — one round usually yields a noticeably better version.
If you can’t reach those sites, APIYI covers the AI-chat need just as well: connect our API to a chat client like Cherry Studio or Chatbox — see the tutorials under “Scenarios - Chat” in the docs:
Strategy 2: Retry on Failure
Since failures come from single-sample variance, retrying is itself an effective remedy — sending the identical request again often just works (exactly what happened in this case).
- Budget 1–2 automatic retries in your business code for “result doesn’t match expectations”;
- Distinguish two failure types: “an image came back but the edit is wrong” versus “no image at all”. The latter (HTTP 200 but no image) is usually a content-moderation block — see the Gemini Image API Error Handling Guide.
Strategy 3: Switch Models
For this case we tested other models with the identical prompt + image — all succeeded on the first try:
| Model | Result |
|---|
gemini-3-pro-image (Nano Banana Pro) | ✅ First-try success |
gemini-3.1-flash-image-lite | ✅ First-try success |
gpt-image-2 series | ✅ First-try success |
model parameter (same key, same endpoint) — nearly zero cost. Make “switch models” a first-class step in your image workflow — it’s a legitimate strategy for reaching the goal, not a compromise.
In practice, organize a “fast first, strong later” ladder:
- Default to a fast, inexpensive model (e.g.
gemini-3.1-flash-image) for routine tasks;
- When a precise-editing task fails 1–2 times, automatically escalate to
gemini-3-pro-image or the gpt-image-2 series and retry;
- If nothing works, go back and rework the prompt.
When debugging “why is the output wrong”, isolate the variables first. imagen.apiyi.com lets you validate the “prompt + image” combination quickly, without writing code:
- Fails on the tool too → most likely a prompt/task issue; go back to Strategy 1, or switch models per Strategy 3;
- Succeeds on the tool, fails in your code → check your code: is the image fully uploaded, are the parameters correct, is the prompt truncated or mangled by escaping;
- Works sometimes, fails sometimes → that’s sampling variance; add retries per Strategy 2.
This keeps you from misdiagnosing a prompt issue as a gateway issue and saves a lot of detours.
Quick Reference
- Web app ≠ API: the web app is a full agent with prompt rewriting and multi-step orchestration; the API is a single atomic call with your verbatim prompt — the perceived gap mostly comes from the pipeline, not from “the API understanding less”.
- Random single-call variance is inherent to generative models — one failure says nothing about the model or the gateway.
- Strategy 1, improve the prompt: concrete nouns, specific colors, enumerate what to preserve, number the actions — change one category of thing at a time.
- Strategy 2, retry: budget 1–2 retries for “wrong edit”; “no image” is a different problem (see the error handling guide).
- Strategy 3, switch models: in this case
gemini-3-pro-image, gemini-3.1-flash-image-lite, and the gpt-image-2 series all succeeded first try; on a unified gateway it’s a one-parameter change.
- Strategy 4, use the test tool to isolate: validate “prompt + image” on imagen.apiyi.com first, to tell prompt issues, code issues, and sampling variance apart.
