vLLM HunyuanImage3

vLLM HunyuanImage3 is a thin client for a very thick model. It sends a text prompt to a local vLLM server that's serving Tencent's Hunyuan Image 3, and drops the returned image back into your ComfyUI graph as a normal IMAGE tensor. It's from Duanyll Nodepack, and it's the easy half of the equation - the hard half is that this node is only useful if you already have a vLLM server running an 80-billion-parameter image model behind http://127.0.0.1:8000.

Let's be blunt about the model, because it decides whether this node is for you. Hunyuan Image 3 is Tencent's 80B image MoE - the KB's Hunyuan panel puts it at needing roughly 320GB of VRAM for a serious deployment, and the community's reaction when the weights landed was "ggufs are off the menu for us consumers" and "way too bloated and inefficient." So this is not a node for your home rig unless you own a multi-GPU box. It's for people who've already stood up a vLLM inference server for HunyuanImage3 - locally, or on a rented machine whose URL you point the node at.

How it works

The node builds a standard chat-completions payload and POSTs it to api_url. The interesting fields travel in task_type: "hunyuan_image3" plus task_extra_kwargs: diff_infer_steps, use_system_prompt, bot_task, and the concrete pixel size derived from your aspect ratio. The vLLM server responds with a base64 image, which the node decodes into a [1, H, W, 3] tensor ready for a preview or VAE-free save.

Inputs that matter

• prompt (STRING, multiline) - the default is a Chinese movie-poster description, but any language the model handles works.
• api_url - default http://127.0.0.1:8000/v1/chat/completions. This is the thing you'll actually change; point it at your server.
• model_name - default vllm_hunyuan_image3; must match what your vLLM deployment registered the model under.
• aspect_ratio - six choices (1:1, 4:3, 3:4, 16:9, 9:16, 21:9), each mapped to a concrete resolution, from 1024×1024 up to 1408×640.
• bot_task - image for plain text-to-image; auto switches the chat template to the <boi><image_shape_1024> marker for the model's auto/understanding mode.
• use_system_prompt - None by default; choose custom to feed your own prompt via the optional system_prompt input, or one of the built-in dynamic / en_vanilla / en_recaption / en_think_recaption variants if your vLLM build supports them.
• diff_infer_steps (default 50), seed, and temperature (default 0) round out the sampler controls.

Output is a single image (IMAGE).

The trap that will cost you time

Read the source and you'll find the node's error handling: on any API failure, it returns a 512×512 black image instead of raising. Server not running, wrong model name, bad URL - the result is a black square with only a line in the ComfyUI console ([VLLMHunyuanImage3] Error: ...) to tell you why. If your output suddenly comes out black, that's not the model being moody; that's the node swallowing an exception. Check the console before you blame the prompt. It's a friendlier-than-it-looks failure, but only if you know to look.

Install

Same as the rest of Duanyll Nodepack: ComfyUI Manager → search Duanyll Nodepack → install → restart, or:

cd ComfyUI/custom_nodes
git clone https://github.com/Duanyll/duanyll_nodepack

Nothing downloads here and no API key is needed - this node is local-only, which is honestly refreshing next to the pack's cloud API nodes. The real install project is the vLLM server on the other end of that URL, and Tencent's Hunyuan Image 3 repo is where that setup actually lives.