Three provider modes: OpenRouter, local OpenAI-compatible API servers, and direct Hugging Face model loading
Optional image-aware prompt enhancement for vision-capable models
Standalone prompt enhancer or all-in-one integrated KSampler workflow
Optional session history with manual session_id control; blank session_id runs are stateless
Direct-model quantization support with cache unloading tools
Detailed debugging through the debug_log output, console logs, and z_image_debug.log

Installation

Clone the repository into your ComfyUI custom nodes directory:

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

Install the extra dependencies required only for the Direct provider:

pip install bitsandbytes huggingface-hub

Optional for faster Hugging Face downloads:

pip install hf_transfer

ComfyUI already provides torch, transformers, and accelerate in a normal installation.

Restart ComfyUI.

Included Nodes

| Node | Description | |------|-------------| | Z-Image API Config | Configure OpenRouter, local API, or direct Hugging Face model loading | | Z-Image Options | Optional inference settings with per-option enable toggles | | Z-Image Prompt Enhancer | Enhance prompts with text-only or vision-capable LLMs | | Z-Image Integrated KSampler | Prompt enhancement plus encoding, sampling, decoding, and optional auto-save | | Z-Image Unload Models | Unload cached direct models from memory | | Z-Image Clear Sessions | Clear saved chat sessions |

Quick Start

Standalone enhancement workflow:

[Z-Image API Config] -> [Z-Image Prompt Enhancer] -> [CLIP Text Encode] -> [KSampler]
                                ^
                    [Z-Image Options] (optional)

Integrated generation workflow:

[Checkpoint Loader] -> [Z-Image Integrated KSampler] -> [Preview Image]
         |                         ^
         +--> model / clip / vae   |
                         [Z-Image API Config]

If you use the integrated sampler in image_to_image mode, connect at least one image input.

Provider Setup

OpenRouter

provider: openrouter
model: any compatible OpenRouter chat model
api_key: your OpenRouter API key

If you want to send an image into Z-Image Prompt Enhancer, use a vision-capable model. The current default model value in the node is qwen/qwen3-235b-a22b:free.

Local API Server

The local provider expects an OpenAI-compatible /v1/chat/completions endpoint.

provider: local
model: model name exposed by your server
local_endpoint: server URL such as http://localhost:11434/v1

Common endpoint examples:

| Server | Endpoint | |--------|----------| | Ollama | http://localhost:11434/v1 | | LM Studio | http://localhost:1234/v1 | | vLLM | http://localhost:8000/v1 | | text-generation-webui | http://localhost:5000/v1 |

Direct Hugging Face Loading

provider: direct
model: Hugging Face repo ID
quantization: 4bit, 8bit, or none
device: auto, cuda, cpu, or mps
llm_path: optional local model folder root
auto_download_fallback: if enabled, try llm_path first and download if not found

Downloaded direct models are stored under ComfyUI/models/LLM/Z-Image/.

If you want to use image input with the Direct provider, choose a vision-language model. Text-only models will reject image input.

Node Reference

Z-Image API Config

Configures the LLM backend connection.

| Parameter | Notes | |-----------|-------| | provider | openrouter, local, or direct | | model | OpenRouter model ID, local server model name, or Hugging Face repo ID | | api_key | Used for OpenRouter | | local_endpoint | Used for the local provider | | llm_path | Optional manual model root for the Direct provider | | auto_download_fallback | Direct provider only | | quantization | Direct provider only | | device | Direct provider only |

Output: config

Z-Image Options

Provides optional inference settings. Values are only sent when their matching enable toggle is on.

| Toggle | Value | |--------|-------| | enable_temperature | temperature | | enable_top_p | top_p | | enable_top_k | top_k | | enable_seed | seed | | enable_repeat_penalty | repeat_penalty | | enable_max_tokens | max_tokens | | Always available | debug_mode |

Notes:

If enable_temperature is off, the provider default temperature is used.
If enable_max_tokens is off, the provider default max token limit is used.
Support for seed, top_k, and similar settings depends on the backend model/provider.

Output: options

Z-Image Prompt Enhancer

Enhances a text prompt into a longer image-generation prompt.

| Parameter | Notes | |-----------|-------| | config | From Z-Image API Config | | prompt | Input prompt text | | prompt_template | auto, chinese, english, or custom | | options | Optional ZIMAGE_OPTIONS input | | image | Optional image input for vision-capable models | | retry_count | Retry attempts on API failure | | max_output_length | Character limit; 0 means unlimited | | session_id | Reuse the same value for persistent conversation history | | reset_session | Clears the named session before use | | keep_model_loaded | Direct provider only; keeps the loaded HF model cached | | utf8_sanitize | Replaces some Unicode punctuation with ASCII-safe characters | | custom_system_prompt | Required only when prompt_template is custom; must include {prompt} |

Notes:

Blank session_id means stateless execution.
With debug_mode enabled, the full report is returned in debug_log and also written to logs.

Outputs: enhanced_prompt, debug_log

Z-Image Integrated KSampler

All-in-one node for prompt enhancement and image generation.

Required inputs:

model
clip
vae
config
positive_prompt
negative_prompt
generation_mode
width
height
seed
steps
cfg
sampler_name
scheduler

Important optional inputs/settings:

| Parameter | Notes | |-----------|-------| | options | Optional LLM options | | image_1 to image_4 | Optional images for vision enhancement and image_to_image mode | | latent | Optional latent override | | prompt_template | auto, chinese, english, or custom | | enable_prompt_enhance | If off, the prompt is used as-is | | batch_size | Number of images to generate | | auraflow_shift | Applies AuraFlow sampling shift when greater than 0 | | cfg_norm_strength | Applies CFGNorm when greater than 0 | | enable_clean_gpu | Clears GPU cache before and after sampling | | enable_clean_ram | Runs garbage collection after completion | | auto_save_folder | Empty disables auto-save; relative paths resolve inside ComfyUI output | | output_prefix | Filename prefix for auto-saved images | | custom_system_prompt | Used with prompt_template = custom | | instruction | Vision-language instruction text for image_to_image mode | | denoise | Standard KSampler denoise strength |

Notes:

image_to_image mode requires at least one connected image.
The starting latent is prepared at the requested width and height.
This node always calls the prompt enhancer statelessly.

Outputs: images, latent, enhanced_prompt, debug_log

Z-Image Unload Models

Unloads cached Direct-provider models.

| Parameter | Notes | |-----------|-------| | unload_all | When true, unloads all cached direct models | | passthrough | Optional passthrough input for graph chaining |

Output: status

Z-Image Clear Sessions

Clears saved prompt-enhancer session history.

| Parameter | Notes | |-----------|-------| | clear_all | Clears every saved session | | session_id | Clears one specific session when clear_all is false |

Output: status

Troubleshooting

| Issue | What to check | |-------|---------------| | Empty or failed response | Verify API key, endpoint, model name, and retry_count | | Rate limits from OpenRouter | The node retries automatically, but free models can still hit upstream 429 limits | | Image input fails on Direct provider | Use a vision-language model instead of a text-only model | | Local provider errors | Make sure the server exposes an OpenAI-compatible /v1 endpoint | | Out of memory | Use 4bit, a smaller model, or unload cached direct models | | Repetitive output | Enable repeat_penalty in Z-Image Options | | Need deeper logs | Turn on debug_mode and inspect debug_log or z_image_debug.log |

Credits

System prompt source: Z-Image Turbo Space
Author: Koko-boya

References:

License

Apache License 2.0. See LICENSE.