Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-HunyuanImage3 > HunyuanImage-3.0 HAP

ComfyUI Node: HunyuanImage-3.0 HAP

Class Name

HunyuanImage3HAP

Category
model/patch/hunyuan image 3
Author
PedroMarinhoDev (Account age: 43days)
Extension
ComfyUI-HunyuanImage3
Latest Updated
2026-11-03
Github Stars
0.04K

How to Install ComfyUI-HunyuanImage3

Install this extension via the ComfyUI Manager by searching for ComfyUI-HunyuanImage3
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-HunyuanImage3 in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

HunyuanImage-3.0 HAP Description

Applies head-adaptive attention pruning to HunyuanImage-3.0 for images above 1024×1024.

HunyuanImage-3.0 HAP:

HunyuanImage3HAP applies head-adaptive attention pruning, abbreviated HAP, to HunyuanImage-3.0 to reduce attention computation when generating images larger than 1024×1024. Attention is the mechanism that lets different parts of an image exchange information during generation; its computational cost can become substantial at higher resolutions. This node uses a method from HRDiT that measures an attention radius for each attention head during the first generation step. After that step, each head limits its attention to nearby image tokens within its measured radius. Image tokens are the small image units processed by the model, and attention heads are separate components that learn different relationships between those units. Using a separate radius for each head makes the restriction adaptive rather than applying the same neighborhood everywhere. The goal is faster attention processing during high-resolution generation, although the supplied code does not establish a specific speed improvement or guarantee identical results to unpruned attention. The pruning has no effect at or below 1024×1024.

HunyuanImage-3.0 HAP Input Parameters:

model

The required MODEL connection supplies the model to which the HAP configuration will be applied. Use a compatible HunyuanImage-3.0 model from your workflow: this is a model-specific patch, not a general attention optimization for every image model. The node clones the supplied model wrapper and attaches its HAP configuration to that clone, leaving the original model connection available for an unpatched workflow branch. This cloning should not be interpreted as loading a second independent copy of all model weights. The node configures how the model will operate during subsequent generation; it does not generate an image itself. This parameter has no numeric minimum, maximum, or default value, and requires a MODEL connection.

mass

The required FLOAT parameter specifies the share of each attention head’s attention that its measured radius must retain. Its default is 0.95, its minimum is 0.5, its maximum is 1.0, and its interface adjustment step is 0.01. For example, 0.95 asks the radius-selection process to retain 95% of that head’s measured attention mass; it does not mean keeping 95% of image tokens or achieving a 95% speed improvement. A higher value sets a stricter retention target and generally allows less aggressive pruning, while a lower value permits a smaller retained attention share and potentially more aggressive pruning. Because the radius is determined separately for each head, the same setting can produce different neighborhoods across heads. Lower values may affect the generated result, so evaluate them visually rather than treating them as a guaranteed quality-preserving optimization. A value of 1.0 requests full attention-mass retention, but the supplied node code does not establish it as an explicit off switch.

HunyuanImage-3.0 HAP Output Parameters:

MODEL

The MODEL output is the cloned model with the HAP plan installed in its transformer options under hy3_hap. Connect this output to the sampling or generation stage that would otherwise receive the original model. Its importance is that the optimization is carried forward through this particular model connection: using the original model on a separate branch does not apply the newly configured HAP plan to that branch. This output is still a model, not an image, latent, attention map, or performance measurement. The node itself only installs the configuration; the compatible HunyuanImage-3.0 implementation uses that configuration during generation, with no pruning effect at or below 1024×1024.

HunyuanImage-3.0 HAP Usage Tips:

  • Place the node after your compatible HunyuanImage-3.0 model-loading stage and before sampling. Make sure the sampler receives this node’s MODEL output rather than the original model connection.
  • Start with the default mass of 0.95. It provides a 95% attention-mass retention target for each head and is a useful baseline before testing more aggressive pruning.
  • Use this optimization for high-resolution generation, such as 2048×2048. For images at or below 1024×1024, the documented behavior is no effect, so adding the node will not provide the intended attention speed-up.
  • If you want to explore stronger pruning, reduce mass gradually, for example from 0.95 to 0.94 or 0.93. Compare composition, repeated structures, fine detail, and overall visual consistency before lowering it further.
  • If a lower mass produces unwanted changes, increase it toward 1.0 or bypass the node for an unpatched comparison. Do not assume that setting 1.0 is identical to removing the patch.
  • Compare patched and unpatched runs using the same prompt, seed, resolution, sampling settings, and hardware. Measure complete generation time as well as visual results, since faster attention does not necessarily translate into the same proportional improvement for the entire workflow.
  • Expect the pruning benefit to begin after the first step. The first step supplies the measurements used to determine the per-head attention radii, so a short test may not represent the benefit over a longer generation.

HunyuanImage-3.0 HAP Common Errors and Solutions:

Missing required input: model or mass

  • Explanation: Both inputs are required by the node interface. A missing model connection or missing required value can prevent execution during workflow validation. The exact validation message depends on your ComfyUI version; the supplied node class does not define a custom missing-input message.
  • Solution: Connect a compatible HunyuanImage-3.0 MODEL to model and ensure mass has a value, such as the default 0.95.

mass is outside the supported range

  • Explanation: The declared range is 0.5 to 1.0. Values outside that range do not match the node’s interface constraints and may be rejected during validation. The node class does not provide a custom error string for this condition.
  • Solution: Set mass to a value between 0.5 and 1.0 inclusive. Enter 0.95 for a 95% attention-mass target, not 95.

HAP appears to have no effect

  • Explanation: This is a troubleshooting symptom rather than an explicit exception. The node is documented to have no effect at or below 1024×1024. The patch can also be absent from the active generation path if the sampler still receives the original model instead of this node’s output.
  • Solution: Test a clearly larger resolution, such as 2048×2048, and trace the MODEL connections to confirm that generation uses the patched output. Use a compatible HunyuanImage-3.0 model.

Incompatible model or patch not recognized

  • Explanation: This is a compatibility issue, not a specific error message defined by the node. The implementation installs a HunyuanImage-3.0-specific transformer option; accepting a MODEL connection does not establish that another model family supports it. An incompatible model may ignore the option or fail elsewhere during generation.
  • Solution: Use the node with the HunyuanImage-3.0 implementation provided by the relevant custom-node package. If generation fails, inspect the full ComfyUI error log and verify that the installed package and workflow are compatible.

CUDA out of memory

  • Explanation: This is a possible runtime error during high-resolution generation, not an error explicitly raised by this node. HAP targets attention computation and does not guarantee that the model, image dimensions, batch size, or other workflow stages will fit in your available GPU memory.
  • Solution: Reduce resolution or batch size, close other GPU-heavy applications, and use memory-management options supported by your model and ComfyUI setup. Do not rely on lowering mass as a guaranteed fix for insufficient memory.

Generation is not noticeably faster

  • Explanation: This is a performance symptom rather than an exception. HAP targets attention after the first step, while model loading, other model operations, and image decoding still contribute to total runtime. The supplied code does not promise a fixed speed-up.
  • Solution: Compare repeated runs after model loading under otherwise identical conditions. Test at a resolution above the documented threshold and start with mass at 0.95; consider gradually lower values only if the resulting image quality remains acceptable.

Generated images change after enabling HAP

  • Explanation: This is a possible consequence of restricting attention rather than a validation error. A lower retention target permits more attention to be excluded, and the supplied source does not guarantee that pruned generation will match an unpatched result.
  • Solution: Increase mass and compare against an unpatched run with the same seed and settings. If preserving the unpatched result is more important than the potential attention speed-up, bypass the node.

HunyuanImage-3.0 HAP Related Nodes

Go back to the extension to check out more related nodes.
ComfyUI-HunyuanImage3
RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

HunyuanImage-3.0 HAP