HunyuanImage-3.0 SPA:
HunyuanImage3SPA applies spatial position alignment (SPA), a technique from HRDiT, to help HunyuanImage-3.0 maintain a more consistent composition when generating images larger than 1024 × 1024. At higher resolutions, a composition can drift away from the appearance of a 1024-resolution render, with smaller subjects or more repeated elements. During the first generation steps, SPA groups image positions back into the grid used during training and averages attention across shifted groupings. In simpler terms, it helps the model organize a larger canvas using a spatial arrangement it already understands, while combining several shifted arrangements rather than relying on just one. The intended benefit is a composition closer to a 1024-resolution render, with larger subjects and fewer repetitions. This comes with trade-offs: the node description reports approximately 30% additional generation time at 2048 × 2048 and notes that some stray specks can reappear. SPA has no effect at or below 1024 × 1024.
HunyuanImage-3.0 SPA Input Parameters:
model
The required MODEL connection supplies the model to which the SPA setting will be applied. This node is intended for HunyuanImage-3.0 workflows; a generic MODEL connection does not guarantee that another model supports this setting. The node clones the supplied model wrapper and adds the SPA configuration to the clone, leaving the incoming model's configuration unchanged. This lets you keep an unpatched branch for comparison while using the patched branch for high-resolution generation. The node does not generate an image or change the requested image dimensions itself. There is no default value, numerical minimum, maximum, or selectable option for this input; connect the appropriate model from an upstream model-loading or model-patching node.
steps
The required INT parameter specifies how many of the first generation steps use SPA. Its default value is 3, its minimum is 1, and its maximum is 100. For example, a value of 3 requests spatial position alignment during the first three steps, rather than throughout the entire generation process. This setting controls the duration of the early alignment treatment, not the sampler's total number of steps or the output resolution. Raising it requests SPA over more initial steps, while lowering it limits the treatment to a shorter early period; more SPA steps should not be assumed to guarantee better results. The default is a practical starting point for evaluating the intended composition benefits against extra processing time and possible stray specks. At or below 1024 × 1024, changing this value has no SPA effect.
HunyuanImage-3.0 SPA Output Parameters:
MODEL
The MODEL output is the cloned model configured to request SPA during the specified number of initial generation steps. Internally, the node stores this request as the hy3_spa setting in the model's transformer options. Connect this output to the model input of the downstream generation path so that compatible HunyuanImage-3.0 code can use the setting during sampling. The output is a model object, not an image, latent image, or quality score, and producing it does not mean that image generation has already occurred. Because the incoming model is cloned before the setting is added, the original model connection remains available for a separate comparison branch without this node's SPA change.
HunyuanImage-3.0 SPA Usage Tips:
- Use SPA for generation above 1024 × 1024 when you want larger subjects or fewer repeated elements. Do not expect an effect at or below 1024 × 1024. - Start with
stepsset to 3. Compare it with 1 or another small value while keeping the prompt, seed, resolution, sampler, and total sampling steps unchanged so you can judge the effect of SPA more clearly. - Place the node in the model connection path before sampling, and make sure the sampler receives its
MODELoutput rather than the original model connection. - Treat
stepsas the number of initial steps receiving SPA, not as the total sampling-step count. Set the overall generation length separately in your sampling workflow. - Budget extra generation time for high-resolution work. The node description reports about 30% additional time at 2048 × 2048, but this is an estimate rather than a guaranteed cost for every workflow or setting.
- Inspect smooth backgrounds and other clean areas for stray specks. If they become distracting, compare a lower
stepsvalue or bypass SPA to decide whether the composition improvement is worth the artifact trade-off. - To disable SPA for a comparison, bypass this node or use the original upstream model connection. Setting
stepsto 0 is not supported by the declared input range.
HunyuanImage-3.0 SPA Common Errors and Solutions:
Missing required input: model — illustrative validation message
- Explanation: The node requires a
MODELconnection and cannot configure SPA without it. The supplied source does not define a custom error message for a missing connection; the exact wording depends on ComfyUI. - Solution: Connect the model output from your HunyuanImage-3.0 loader or an appropriate upstream model patch to
model, then connect this node's output to the downstream sampling path.
Invalid steps value: expected an integer from 1 to 100 — illustrative validation message
- Explanation: The declared interface accepts whole numbers from 1 through 100. A value of 0, a negative number, a fractional value, or a value above 100 falls outside that interface. The exact validation message depends on how the workflow is submitted.
- Solution: Use a whole number within the supported range, starting with 3. If you want to turn SPA off, bypass the node instead of entering 0.
No visible change after enabling SPA — troubleshooting symptom
- Explanation: SPA has no effect at or below 1024 × 1024. It also cannot affect sampling if the sampler still receives the original model, and its setting requires compatible model code that reads
hy3_spa. A subtle difference is not necessarily an execution error. - Solution: Test at a higher resolution such as 2048 × 2048, verify that the sampler uses this node's output, and use the intended HunyuanImage-3.0 implementation. Compare patched and unpatched results with the same generation settings.
Generation takes longer after enabling SPA — expected performance trade-off
- Explanation: SPA averages attention over shifted spatial groupings during the initial steps, adding computation. The node description reports approximately 30% additional time at 2048 × 2048; this slowdown alone does not indicate a fault.
- Solution: Start with the default of 3 SPA steps, compare a lower value such as 1, or bypass SPA when generation speed matters more than its composition benefits.
Stray specks appear in the generated image — documented visual trade-off
- Explanation: The node description explicitly notes that SPA can bring back some stray specks. This can occur alongside the intended improvement in subject scale and repetition, so it is not necessarily a sign of incorrect wiring.
- Solution: Compare the result with fewer SPA steps and with SPA bypassed, keeping the other generation settings unchanged. Choose the version that best balances composition and image cleanliness.
A different model accepts the connection but shows no SPA benefit — compatibility symptom
- Explanation: The input type is
MODEL, but the node only adds a HunyuanImage-3.0-specific transformer option. Its source does not check the model family or implement a general-purpose SPA method for all models. - Solution: Use the node with the intended HunyuanImage-3.0 workflow. Do not assume that a successful connection means another model architecture will interpret or apply the SPA setting.
