Qwen-Image-Edit does not need a better prompt. It needs a differently shaped one. You send one to three images plus a single instruction, and the model returns an edited PNG — no mask, no second pass. When that goes wrong, the failure is almost never “the prompt was too plain.” It is that the instruction described a scene instead of a change, buried the change behind description, or never said which of the three images it meant. That is why a Qwen-Image-Edit prompt guide has to be about instruction shape rather than prompt length — and why one of the highest-ranking results on this topic is a forum thread asking for exactly that guide, still unanswered as of September 10, 2026.
This article is the answer that thread never got. It is the prompt-craft half of a pair: model IDs, endpoints, parameters and the full price table live in our Qwen Image API guide; here we stay on the sentence you type. Every rule below traces to Qwen’s own repository or Alibaba’s official documentation, linked where it appears, and every dated fact carries the date it was read. One disclosure, up front: Modellix runs this blog and sells a single-key route to these models, so the route section at the end is not neutral. The prompt patterns are — they behave the same whichever door you come in through.
Why most Qwen-Image-Edit prompt guides fail (and why a longer prompt is not the fix)
Qwen-Image-Edit is built on the 20B Qwen-Image base and reads your input through two paths at once — a vision-language encoder for semantics, a VAE encoder for appearance. That is why Qwen’s own launch post splits editing into semantic editing (the whole frame may change; the meaning must survive) and appearance editing (change one thing; everything else stays pixel-stable). The distinction is the most useful thing on the official page, and it is announced rather than taught: the post ships 22 output images and not one prompt string.
The practical consequence inverts what most guides say. A text-to-image model wants a rich description; an edit model wants an instruction plus a declaration of what must not move. Write it like a generator and two failures follow:
- The instruction gets diluted. Three sentences of scene description with the verb at the end read as a target state, and the model repaints toward it — a background swap becomes a full restyle.
- The instruction gets rewritten for you. Qwen’s hosted editing models run intelligent prompt rewriting by default (
prompt_extend: true, documented as most effective for short or simple prompts). Missing information gets filled in — with a reasonable guess, not your intent.
The fix is not length. It is completeness in a specific shape, and Qwen published that shape in code — in the Edit Prompt Enhancer that ships inside the model’s own repository.
What a Qwen-Image-Edit prompt is made of: the five slots
The QwenLM organisation ships a sample prompt rewriter in its own repository — src/examples/tools/prompt_utils.py, function polish_edit_prompt(). Its system prompt, Edit Prompt Enhancer, opens with the most valuable sentence in this topic:
“If the instruction is clear (already includes task type, target entity, position, quantity, attributes), preserve the original intent and only refine the grammar. If the description is vague, supplement with minimal but sufficient details (category, color, size, orientation, position, etc.).”
That parenthetical is a checklist. An edit instruction is complete when it carries five slots:
| Slot | Answers | Weak | Complete |
|---|---|---|---|
| Task type | add / remove / replace / change | “make it nicer” | “Replace … with …” |
| Target entity | what is being edited | “the thing on the left” | “the person’s hat” |
| Position | where in the frame | (missing) | “in the bottom-right corner” |
| Quantity | how many | “add animals” | “add one cat” |
| Attributes | colour, size, material, orientation, style | “a new bag” | “a small canvas tote bag” |
The official vague-versus-rewritten pair shows the gap concretely: Add an animal becomes Add a light-gray cat in the bottom-right corner, sitting and facing the camera. Same intent, four more slots. When your instruction already carries all five, the enhancer’s own instruction is to leave it alone — the strongest available argument against padding.
Three more rules from the same file, worth knowing before you write:
- Replacement has a canonical order. Say “Replace Y with X” and briefly describe X’s key visual features. “Change the statue to something else” leaves X undefined, so the model defines it.
- Some edits are fixed templates. Colorization and old-photo restoration use
Restore and colorize the photo.Inpainting and outpainting open with fixed lines (Perform inpainting on this image. The original caption is: …). Deviating is not creative; it is out of distribution. - Contradictions get corrected, not obeyed. The enhancer names the case outright (“remove all trees but keep all trees”). Expect the model to resolve a conflict its own way.
The hard constraint behind the five slots: the official guide states the request must carry one to three image objects and exactly one text editing instruction, with input frames in JPG, JPEG, PNG, BMP, TIFF, WEBP or GIF, sized between 384 and 3072 pixels and no larger than 10 MB each. Screenshot of the Alibaba Cloud Model Studio documentation, captured September 10, 2026.
Referring to images by number: how the model knows which picture you mean
Multi-image edits are where instructions break most often, and the fix is one paragraph of Alibaba’s official editing guide almost nobody quotes: image numbers correspond to array position. The first image in your array is “image 1”, the second is “image 2”, and you can bracket them — [image 1], [image 2] — to remove ambiguity.
That makes the useful unit of thought not “an image plus a prompt” but a role assignment per slot. Every official example sentence does the same two things: names the image each element comes from, and names the single thing that changes.
| Pattern | Official example |
|---|---|
| Donor onto target | The girl in Image 1 wears the black dress from Image 2 and sits in the pose from Image 3. |
| Object into scene | Place the alarm clock from image 1 next to the vase on the dining table in image 2. |
| Accessory stacking | The girl in Image 1 wears the necklace from Image 2 and carries the bag from Image 3 on her left shoulder. |
The Qwen enhancer states the multi-image rule outright: rewritten prompts “must clearly point out which image’s element is being modified.” Its worked example adds the half most people omit — Replace the girl of picture 1 with the boy of picture 2, **keeping picture 2's background unchanged**. Target named, donor named, invariant stated.
Two operational details bite in production. More is not better: Qwen’s model card for the 2509 generation records that optimal performance is “currently achieved with 1 to 3 input images,” and both the official guide and the 3.0 reference cap input at three. And the last image can set your output frame — on the unified 2.0-series models the default output resolution is the same as the input image, and the documentation specifies the last one when several are sent; on the 3.0 series the documented default is a resolution chosen from the prompt instead. Either way, send a portrait donor last while expecting landscape and you will not get landscape. Set size explicitly when the frame matters. If you want the reference-image ceiling of the whole family side by side before choosing a tier, the Qwen Image series hub lists what each generation accepts.
Alibaba’s official Multi-image fusion example block: Input image 1, 2 and 3 map to a single edited output — the arrangement the numbering rule in your prompt depends on. Screenshot of the Alibaba Cloud Model Studio documentation, captured September 10, 2026.
Instruction patterns that work, edit type by edit type
Every pattern below follows the same shape: the instruction, what it does, why the phrasing matters, and what it looks like when it breaks. Examples are the vendor’s own, quoted from the official guide unless noted.
Replacing text inside the image
Instruction: Replace "HEALTH INSURANCE" on the Scrabble tiles with "Tomorrow Will Be Better".
Why it works: literal text goes in ASCII double quotes with its original language and capitalisation kept — the enhancer’s text rule requires it, and it treats adding text as a replacement task too. Since 2509 this covers font, colour and material as well (Change "Qwen-Image" to a black ink-drip font, Change the material of "Qwen-Image" to glass).
When it breaks: long strings, or several text regions in one call, come back as plausible-looking garbage. Shorten the string; keep one text region per call.
Adding, removing and moving an object
Instruction: Add a small wooden sign in front of the penguin that says "Welcome to Penguin Beach". / Remove the hair from the plate.
Why it works: the object is named by category and position — exactly the slots the enhancer inserts when they are missing.
When it breaks: Remove the object leaves the model to decide what “the object” is. Name it the way you would to a retoucher, and for removals say what should replace it, since the model must generate something where the object was.
Replacing the background or the scene
Instruction: The air conditioner is placed in a living room next to a sofa. plus a preservation clause.
Why it works: background replacement is an appearance edit, and the difference between a clean composite and a cut-and-paste look is whether you declared the invariant. This is the highest-frequency edit type on this topic’s SERP, and the type where the semantic/appearance split earns its keep.
When it breaks: the subject drifts — new outfit, new pose, softened face. Add the preservation clause (keep the person unchanged, keep the product pixel-identical) and, if it still drifts, disable prompt rewriting for that call.
Transferring a style from a reference image
Instruction: Change the girl in Picture 1 to the ink-wash style of Picture 2 — rendered in black-and-white watercolor with soft color transitions.
Why it works: the enhancer forbids naming a style and stopping. It asks for the reference’s key characteristics — colour, composition, texture, lighting, artistic style — spelled out. Disco style is weak; 1970s disco style: flashing lights, disco ball, mirrored walls, colorful tones is the corrected form.
When it breaks: you get a generic filter instead of the reference’s actual style, because the model had to guess which features you meant. If other changes are also wanted, the enhancer’s ordering rule applies: put the style description last.
Changing pose, viewpoint or lighting
Instruction: Get a front view. / Face left. / Get a rear view.
Why it works: the official examples are two to four words. This is the clearest counter-example to “write more” — the change is unambiguous, so the instruction stays short.
When it breaks: at large angle changes the identity drifts. Since 2509 the family accepts depth maps, edge maps and keypoint maps as ordinary reference images, which is the documented way to pin a pose instead of describing it.
Restoring and colorizing an old photo
Instruction: Restore and colorize the photo. (fixed template)
Why it works: the enhancer hard-codes that phrasing for colorization and restoration, making this the one place where the shortest instruction is also the correct one. The official showcase prompt adds a positive tail worth copying: … remove scratches, reduce noise, enhance details, high resolution, realistic image, natural skin tone, clear facial features, no distortion.
When it breaks: you stack creative instructions on top. Restoration wants the invariant preserved, not a redesign.
The official text-editing examples, and the closest thing on the vendor’s site to an instruction paired with its result: Replace 'HEALTH INSURANCE' on the Scrabble tiles with 'Tomorrow Will Be Better' and Change the phrase "Take a Breather" on the note to "Relax and Recharge". Screenshot of the Alibaba Cloud Model Studio documentation, captured September 10, 2026.
Six edit types cover most production work, and the instruction for each is a variation on the same skeleton: name the target, name the change, name what must not move. Where those six sit next to the deterministic transforms you should not be prompting for at all — cropping, upscaling, colour correction — is mapped in our image manipulation API guide.
Keeping the subject the same: consistency is a prompting problem
Consistency is usually sold as a capability. It behaves like an instruction problem, and the enhancer treats it like one: for any instruction touching a person it requires emphasis on that person’s “core visual consistency (ethnicity, gender, age, hairstyle, expression, outfit)”. Its worked example doubles as a template:
Change the person's hat→Replace the man's hat with a dark brown beret; **keep smile, short hair, and gray jacket unchanged**.
Two rules ride along. New elements must be consistent with the original style, and cosmetic changes — expression, beauty, makeup — “must be natural and subtle, never exaggerated.”
The failure this prevents has a name in Qwen’s release notes. The 2511 generation lists mitigate image drift as its first enhancement over 2509, alongside improved character consistency — including multi-person group shots — and integrated LoRA capabilities, with stronger product consistency arriving a generation earlier in 2509. Drift is what happens when the instruction’s blast radius is left unspecified: the model obeys your verb and repaints the neighbourhood. The fix has the same shape in all four domains:
- People: name the invariants (face, hair, expression, outfit), then the change.
- Products: say the product must stay identifiable, then place it — the same mechanic that lets the model build a poster from a plain-background product shot.
- Text: name the string, then the font, colour or material change.
- Scenes: state what must not move before you state what must.
If you take one habit from this article, take that ordering: invariant first, change second. It reads backwards to anyone used to writing image prompts, which is exactly why it works here. Consistency behaviour also moves between generations — the Qwen Image 2.0 API deep dive covers what the previous generation does differently when generation and editing share one model ID.
When the edit goes wrong: symptom → cause → rewrite
Most edit failures are diagnosable from the instruction alone. Keep this table open while iterating.
| Symptom | Likely cause | The rewrite |
|---|---|---|
| Nothing changed | Instruction buried after scene description, or two competing actions in one call | Lead with the imperative verb; one action per call |
| Far more changed than asked | No preservation clause, and prompt rewriting filled the gaps | Add “keep everything else unchanged”, naming the invariants; set prompt_extend: false when composition must hold |
| Extra objects appeared | Vague noun (“add something festive”) | Add category, colour, size, orientation and position |
| Text came back malformed | String too long, or several text regions in one call | Shorten it, quote it exactly, one region per call |
| The edit landed on the wrong subject | Element-to-image mapping left implicit | Rewrite as “the X in image 1”, “the Y from image 2” |
| The face or product drifted | The changed region overlapped the identity | Add the preservation clause; prefer the 2511-era models, which explicitly mitigate drift |
| Unexpected output aspect ratio | Default resolution follows the input — the last one, when several are sent (2.0 series); the 3.0 series picks it from the prompt | Set size explicitly |
| The instruction’s tail was ignored | Instruction exceeded the documented budget | The 3.0-series reference recommends a maximum of about 4,500 tokens; trim before blaming the model |
| HTTP 400 on an agent-mode call | prompt_extend_mode: agent is text-to-image only and is rejected for editing |
Use direct |
| A second text object was rejected | The request accepts exactly one instruction | Wrap each edit in its own call — editing is single-turn |
One structural note sits under all of it: because the request accepts exactly one instruction and no conversation, iteration means another call, not a follow-up message. That is also why the chained-editing technique in Qwen’s launch post matters — when one pass gets most of it right, re-select the specific failing region and instruct again on that region instead of re-rolling the whole edit. Chaining is cheap; a fresh full-image edit is not.
Qwen-Image-Edit Request Reference
See the exact request body for the Qwen Image 3.0 Edit models, including the image array, prompt and rewrite flags.
View DocsRunning these prompts: hosted API or local, and what one edit costs
The instruction shape above is the same everywhere. On a hosted single-key route the request is small enough to write by hand:
1 | curl --request POST \ |
Media generation on Modellix is asynchronous: the first call returns a task handle and you poll the get_result URL until the status is success, or send an X-Webhook-URL header and let the platform call you. The parameter set is documented on the per-model Qwen Image 3.0 Edit reference; the async lifecycle itself is in the Modellix API docs.
Locally the same instruction goes into QwenImageEditPlusPipeline from diffusers with the model card’s own settings — true_cfg_scale 4.0, guidance_scale 1.0, 40 steps, an empty negative prompt — which is why the 2511 model card is worth reading before concluding that prompting is your bottleneck.
Prices, read on September 10, 2026, per edited image:
| Route | Model | Price today |
|---|---|---|
| Modellix | qwen-image-3.0-edit |
$0.0297 / image |
| Modellix | qwen-image-3.0-pro-edit |
$0.0702 / image |
Billing follows successful outputs: ask for n: 2 and you are buying two images. Prompt craft does not change that number — the levers are output count and the resolution tier you request. For the direct-Alibaba tier prices, the per-input-image fee on the 3.0 series and the free-quota rules, the Qwen Image Edit API guide carries the full table.
Modellix operates this blog, so read that section with the commercial interest in view: those two figures are today’s list prices, not a claim that this is the cheapest way to edit an image, and at sustained volume on a single editing model direct Alibaba billing can still come out ahead per image. The patterns above do not depend on the answer.
Start Editing with Qwen on Modellix
Log in to run these prompt patterns against Qwen Image 3.0 Edit and 200+ other image and video models on one key.
LoginFrequently Asked Questions
How long can a Qwen-Image-Edit prompt be?
The 3.0-series reference recommends a maximum of roughly 4,500 tokens and supports both Chinese and English; other models in the family document smaller budgets. There is no penalty for being short if the five slots are present — the official instruction examples are often two to four words.
Do I have to write the instruction in English?
No. Alibaba’s own FAQ for the editing models states that the model supports Simplified Chinese and English, and that other languages can be attempted without a performance guarantee. The language of the instruction and the language of the text rendered inside the image are separate choices — the second should keep its original language and capitalisation.
Should I use a negative prompt with Qwen-Image-Edit?
Yes — negative_prompt is a documented parameter (the base qwen-image-edit excepted) and is the right place for failure modes you keep seeing: warped text, altered labels, extra objects, low resolution. It is a second line of defence, not the first: an instruction that declares what must not change beats a list of things you dislike.
How many reference images can I send?
One to three, on both the official editing route and the hosted route. Qwen’s model card records 1–3 as the current optimum, and the numbering in your prompt maps directly onto array order, so the practical ceiling is how many roles you can name clearly, not the API limit.
Why does the model change more than I asked it to?
Almost always one of two reasons: the instruction left slots empty and intelligent prompt rewriting filled them in, or the change overlapped something you never declared invariant. Add the preservation clause, name the invariants, and disable prompt rewriting for calls where composition must hold exactly.
Do I need to draw a mask to edit with Qwen?
No. Editing is instruction-based and mask-free — you describe the change in natural language. Selecting or boxing a region is still useful as a reference, which is how the official chained-editing demo isolates a failing component and instructs it again.
Can I edit the text inside an image and keep the font?
Yes, from the 2509 generation onward: text editing covers content, and also font, colour and material. Quote the target string exactly as it appears, keep its original language and capitalisation, and change one text region per call.
Is Qwen-Image-Edit open source?
The editing checkpoints are released under Apache 2.0 on Hugging Face and ModelScope, so self-hosting is a legitimate option; hosted APIs are still billed per image. For the family map — the generation-side models and how the versions relate — our Qwen Image API guide and the Qwen Image 2.0 API deep dive cover that side of the stack.
Capabilities, model versions and prices reflect public information as of September 10, 2026 and change frequently — Qwen’s editing checkpoints and the hosted catalogues behind them both move without notice. Validate behaviour against the official Alibaba documentation and pricing against the provider’s live page before committing budget. This article was written by Modellix, an API aggregator with a commercial interest in the single-key route it describes; the prompt rules above are quoted from Qwen’s and Alibaba’s own material and hold independently of which route you choose. Access image and video models, including the leading Chinese models, through a single API key at modellix.ai.
