Boyo Load Z-Image IP-Adapter

Boyo Load Z-Image IP-Adapter is the front half of a two-node pipeline. On its own it does nothing visible - it loads a weight file and hands you an IP_ADAPTER_ZIMAGE object. The thing you actually do with that object is in the sibling node, Boyo Apply Z-Image IP-Adapter. They're a matched pair: this one gets the weights into memory, the Apply node splices them into a Z-Image model.

You reach for this because Z-Image - Alibaba's 6B model that became the local-photorealism default - has no first-party image-prompting adapter, and this pack carries the community's hack to add one. Whether the hack is worth it depends entirely on whether you can lay hands on the right weight file, which is where most people stall.

How it works

The loader reads a file from ComfyUI/models/ipadapter/ - the standard IP-Adapter folder, so it shows up in the dropdown as soon as you drop a file in. Two formats are accepted:

• a .safetensors state dict, or
• a .pt file in the pack's own "hijacked" format, which stores the weights under an ip_adapter_state_dict key plus some conversion_info.

What it builds from that file is the interesting part. The source describes the weights as SD3 IP-Adapter weights converted to Z-Image's shape, so the loader constructs a TimeResampler - the module that turns your reference image's embedding into IP tokens - sized for Z-Image's hidden dimension (3840) with 64 query tokens, plus 30 per-layer attention processors (ZImageIPAttnProcessor), one for each transformer block in Z-Image. Everything is loaded into fp16, and the whole object is handed to the Apply node when it's used.

The only real input you set is provider: cuda, cpu, or mps. cuda is the obvious choice - the resampler and all 30 processors live in fp16, and CPU inference here is a wait. mps exists for Apple Silicon users who want to test their patience.

The honest gap

The one thing this node will not do is download the weights for you. The ipadapter dropdown lists whatever's in your models/ipadapter/ folder, and the pack README doesn't point you at a converted file. The weights are SD3-derived and re-shaped for Z-Image's architecture, so a stock SD3 IP-Adapter file won't work - you need the Z-Image-converted variant that the community passes around. If you can't find it, the pipeline is dead on arrival no matter how clean the node is.

Installation

It's the standard Boyonodes install:

cd ComfyUI/custom_nodes && git clone https://github.com/DragonDiffusionbyBoyo/Boyonodes

then restart ComfyUI. The loader itself pulls in no extra Python packages - all its heavy lifting is torch, safetensors, and the pack's own resampler/wrapper modules. The dependency burden is in the model file, not the pip install.

Troubleshooting

• Dropdown is empty: nothing matching in models/ipadapter/. Drop your converted file there and refresh the node.
• Load errors on a .safetensors file: you're almost certainly feeding it a standard SD3/SDXL IP-Adapter file, not the converted Z-Image one. The two are not interchangeable despite the similar folder.
• "Failed to load some TimeResampler weights" in the log: the loader loads the resampler with strict=False, so it'll start anyway and produce garbage or nothing. That warning is your cue to double-check the weight source.

If you get it running, the Apply node is where the payoff is - style and identity transfer from a single reference photo, no training. If you can't source the weights, save yourself the afternoon and look at in-context editors for Z-Image instead.