Hunyuan Instruct Generate

The base Hunyuan 3 pipeline has one annoying gap: it needs an external LLM API if you want prompt enhancement, because the base model just does text-to-image. Hunyuan Instruct Generate (class HunyuanInstructGenerate) is where that gap closes. The Instruct models bake the "think about the prompt" step into the model itself - no API key, no network call, no api_config.ini. You give it a vague prompt, it reasons about intent, rewrites it into a structured professional description, and then generates. The reasoning text comes back as an output you can read.

That's the headline feature, and it's genuinely good - this is the node that makes "a cool dragon" turn into a properly composed, lit, detailed render without you hand-crafting a 200-word prompt. But it's also the node with the biggest foot-gun in the pack, so read the bot_task section before you queue up.

The inputs that matter

• bot_task - the whole personality of this node:
  • image - direct generation, your prompt used as-is. Fast. Use it when your prompt is already well-structured.
  • recaption - the model rewrites your prompt into a detailed description (photography terms, composition, lighting) then generates.
  • think_recaption - Chain-of-Thought first: reason about intent, style, composition, then rewrite, then generate. Best quality, and the tooltip warns it adds several minutes of autoregressive text generation before the image even starts. Not hyperbole.
• system_prompt (default dynamic) - auto-selects the right system prompt for your bot_task. For image it sends nothing (system text can hurt direct generation); for recaption/think_recaption it guides the reasoning. Leave it on dynamic unless you know why you're changing it.
• resolution - all 33 model-native bucket resolutions plus Auto, from tall 512x2048 portraits to wide 2048x512 landscapes.
• seed - default -1 means random. Set a positive number to reproduce.

The optional inputs are where the real control lives: steps (-1 auto = 8 for Distil, 40 for full Instruct; the tooltip notes 50–80 reduces flow-matching artifacts at 2K+ but time scales linearly), guidance_scale (-1 auto, typically ~2.5), flow_shift (2.8 default; 2.0–2.5 for sharper portraits, 3.5–5.0 for cleaner landscape gradients), max_new_tokens (2048, raise if CoT output truncates), verbose, vae_tiling and vae_offload (leave on auto).

Outputs: image, cot_reasoning (STRING - the model's actual thought process, great for debugging why a prompt went sideways), and status.

How to install it

The pack plus an Instruct model. Pack:

cd ComfyUI/custom_nodes
git clone https://github.com/EricRollei/Comfy_HunyuanImage3
cd Comfy_HunyuanImage3
pip install -r requirements.txt

Then weights. The README recommends the Distil INT8 v2 (~81GB) for 96GB cards or Distil NF4 v2 (~45GB) for 48GB:

cd ComfyUI/models
huggingface-cli download EricRollei/HunyuanImage-3.0-Instruct-Distil-NF4-v2 --local-dir HunyuanImage-3.0-Instruct-Distil-NF4-v2

Restart ComfyUI and hard-refresh the browser. Instruct models need trust_remote_code=True - the loader handles that automatically.

Common issues & troubleshooting

Wrong loader. Base loaders are not compatible with Instruct generate nodes and vice versa. You need the Hunyuan Instruct Loader feeding this node's HUNYUAN_INSTRUCT_MODEL input, and its blocks_to_swap matters: BF16/INT8 Instruct models on 96GB cards effectively require block swap (blocks_to_swap=20–28), so set it in the loader, not here.

"Why is my render stuck thinking?" You picked think_recaption or recaption on a long prompt. That's the known cost - minutes of CoT text before the image. If you want the model to think and you want speed, use the Distil variant. If you have a good prompt already, bot_task=image skips the wait.

RAM creeps up over many Instruct runs. Known limitation in the README - references persist across loads. Restart ComfyUI occasionally, and use Hunyuan Instruct Unload when you're done.