Z-Image Prompt Enhancer

This is the node the whole pack orbits. You type amateur photo of someone eating cereal in a bathtub, it hands the idea to an LLM, and you get back a wall of detailed scene description - lighting, wall color, the towel hanging behind the subject - that's dramatically better for Z-Image to work from. The 2026-generation models like Z-Image encode your prompt with an actual LLM (Qwen3-4B here), and they reward verbose natural-language descriptions. The enhancer exists to give them that verbosity without you having to write it.

The pack's author built it around the official Z-Image Turbo system prompt from the Tongyi-MAI Space, and the mechanism is straightforward: your prompt gets formatted into that system template, sent to the LLM backend configured by Z-Image API Config, and the returned text is cleaned and trimmed to max_output_length before it comes out the enhanced_prompt output. Wire that into a CLIP Text Encode, then a KSampler, and you have the pack's standalone workflow. The output isn't the whole story - it also returns a debug_log string that spells out the exact system instruction sent, the raw response, and the cleanup, which is invaluable when output looks wrong.

The template setting matters more than it looks

prompt_template defaults to chinese, and that's not a bug. The author's own comparison testing found the translated English template degraded quality - the original Chinese system prompt enhanced properly whether your input is English or Chinese. So the default is the safe one. Your choices:

• auto - detects the input prompt's language.
• chinese - the good template, regardless of input language. Default.
• english - the translated template; use with caution.
• custom - you supply custom_system_prompt, which must include the {prompt} placeholder or the node raises an error.

The inputs you'll actually set

• config - required, from Z-Image API Config.
• prompt - your idea. Short and single-line works best; the enhancer does little for prompts that are already detailed, a finding from the author's own tests.
• image - optional; with a vision-capable model you can feed in a reference image, which gets base64-encoded into the request. Text-only models will reject it.
• retry_count - retries on API failure with exponential backoff, default 3.
• max_output_length - character cap, default 6000 (≈800 words). The tooltip notes Z-Image-Turbo works best around 4500–7500 characters; 0 means unlimited.
• session_id - leave blank for stateless runs. Give it a value and the node keeps multi-turn conversation history for that ID; reset_session clears it before the run.
• keep_model_loaded - Direct provider only; keeps the HF model cached between runs.
• utf8_sanitize - swaps some Unicode punctuation for ASCII-safe characters.
• options - optional Z-Image Options wiring for temperature and friends.

What's normal vs. what's a problem

Real-world reports from users running this node: verbose, "overly narrative" output is normal and generally works great - one r/StableDiffusion user ran it through a local qwen2.5-7b in LM Studio and got long, oddly charming descriptions that generated well. On the problem side, the stock OpenRouter models are unreliable for NSFW prompts (abliterated variants do better), free-tier models hit rate limits even with retries, and a detailed input prompt won't get better with enhancement - disable the enhancer via the integrated sampler's toggle instead.

Installing

Manager, or:

cd ComfyUI/custom_nodes
git clone https://github.com/Koko-boya/ComfyUI-Z-Image-Utilities.git

Restart ComfyUI. You only need pip install bitsandbytes huggingface-hub if you use the Direct provider; the OpenRouter and local-API routes need nothing extra beyond an account or server.