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 SPA

ComfyUI Node: HunyuanImage-3.0 SPA

Class Name

HunyuanImage3SPA

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 SPA Description

Applies spatial position alignment to stabilize HunyuanImage-3.0 composition above 1024×1024.

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 steps set 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 MODEL output rather than the original model connection.
  • Treat steps as 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 steps value 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 steps to 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 MODEL connection 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.

HunyuanImage-3.0 SPA 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 SPA