Qwen Image 2.1 Edit Prompt Enhancer (GPUStack Vision)

What it is, and why it exists

Instruction editing works right up until you have to describe what to change. "把背景改成蓝色，人物保持不变" is easy. "Take the jacket from image 2, put it on the person in image 1, keep the pose, the face, and the logo on the sleeve" is where people start writing three paragraphs and still lose the logo.

This node's job is that paragraph. Hand it one to ten reference images plus your rough instruction, and a vision model returns a single precise editing directive - naming the images as <image1>, <image2> and so on, spelling out what changes and what must hold. It matters because the editor is a whole-frame model: nothing in Qwen-Image-Edit's architecture pins the pixels you didn't ask about, so drift compounds across a chain of edits. A prompt that explicitly says preserve this is the cheapest defence short of masking and stitching.

How it works

A vision request, OpenAI-style. Your instruction goes in as one text part and each image follows as an image_url part carrying a base64 JPEG data URI. It POSTs to the same kind of /v1/chat/completions endpoint as its text-only sibling, stream: false, top_p pinned at 0.95.

Two details set the limits. First, every reference image is downscaled - max long side 1024px, JPEG quality 85. Second, it must return only a JSON object with three string fields, rewritten_prompt, wh_ratio and ratio_follow, which the node parses and validates. Reply with markdown or a preamble and you get "returned invalid JSON fields", not markdown in your conditioning. That's the failure mode that ruins most LLM-in-the-graph setups, and this one refuses to have it.

The default system prompt is worth reading once: it treats image content as evidence and never as instructions to obey, changes only the named attributes for a local edit, and uses Chinese prose for Chinese instructions. The caveat the source repeats: Qwen's PE-I2I checkpoint is fine-tuned, this is a general VLM adapted to its public edit contract - not weight-equivalent, so A/B it against the official thing with the same image, parameters and seed.

Inputs and outputs

images is the one to get right. It takes a ComfyUI IMAGE batch, 1–10 images, and the order is your batching - the first image in the batch is <image1>. Load your canvas first, references after, build the batch in that order, or the model will write an authoritative-sounding prompt about the wrong image.

prompt is your rough instruction (up to 8000 characters). model defaults to qwen3.8-27b, a GPUStack alias rather than a public name; point it at whatever vision model your endpoint serves. The rest of the dials: temperature 0.7, max_tokens 2048, timeout 180 seconds, reasoning_effort at medium rather than off - reading images and emitting strict JSON is harder than rewriting text, so the default costs you latency.

You get three STRINGs. enhanced_prompt goes to your edit node's prompt input. wh_ratio and ratio_follow are the aspect-ratio fields, deliberately mutually exclusive: state a ratio and the model fills wh_ratio (16:9) and leaves ratio_follow empty; say nothing and it puts the tag of the image that should define the canvas - <image1> - in ratio_follow and leaves wh_ratio empty. Wire them into the width/height fields of your edit node, not into the prompt text. The real reference images still go to that edit node directly; the 1024px JPEG exists only for the LLM's eyes.

Install

Same pack as the text enhancer. ComfyUI Manager, search "ZMG" or ComfyUI-ZMG-Nodes, or:

cd ComfyUI/custom_nodes
git clone https://github.com/vanche1212/ComfyUI-ZMG-Nodes
cd ComfyUI-ZMG-Nodes && pip install -r requirements.txt

The README's own clone URL points at a differently-named GitHub account than the canonical repo, so use the one above. Nothing downloads locally, and requirements pull the whole pack's list (oss2, pydub) that these nodes don't touch. If you only install what you need: pip install requests numpy Pillow.

Where people get burned

The endpoint lives in an environment variable, not the node. Unset, you get the author's private LAN address, http://10.27.89.24/v1/chat/completions. Set ZMG_QWEN_PE_API_URL - which must start with http:///https:// and end in /v1/chat/completions - plus ZMG_GPUSTACK_API_KEY for the credential. Keep that key in the server's environment rather than the node's api_key field, which the README warns can land in workflow JSON and task history:

export ZMG_QWEN_PE_API_URL="http://your-server:8080/v1/chat/completions"
export ZMG_GPUSTACK_API_KEY="sk-..."

Your model has to actually see, and it sees a thumbnail. A text-only model at that endpoint will fail or ignore the images and then invent a prompt. And since every reference is downscaled to 1024px, treat small text, logos and fine markings as things it may misread - exactly the details that matter for a product or character reference. Ten images is the cap; oversized batches raise.

"Returned inconsistent aspect ratio fields." The node validates the JSON hard: both ratio fields filled, neither filled, a wh_ratio that isn't N:N, or a ratio_follow naming an image index past your batch. That's usually a model too small to hold the format - try a bigger one, or drop reasoning_effort so it stops thinking out loud.

The model reads a thumbnail. Since every reference is downscaled to 1024px, treat small text, logos and fine markings as things it may misread - exactly the details that matter for a product or character reference. And ten images is the cap; oversized batches raise.

If the edit still drifts, that's the model, not the prompt. None of this pins the pixels you didn't name. The durable fix is the mask: crop, edit, stitch.