Boyo Apply Z-Image IP-Adapter

Z-Image is the 6B Alibaba model that made local photorealism a solved problem on 12GB cards, and the one thing it shipped without is a first-party image-prompting adapter. This node is the community answer: an IP-Adapter for Z-Image, dressed in Boyonodes' wrapper. Feed it a CLIP vision embedding of a reference photo, patch it into a Z-Image model, and the sampler starts matching that reference's look the same way IP-Adapter did for SD 1.5 and SDXL - no LoRA training, no new checkpoint, just an adapter on top.

Fair warning up front: this is the most experimental node in the whole pack. The source code literally describes the weights as "hijacked SD3 IP-Adapter" - SD3 weights converted to Z-Image's 30-layer architecture. It works, but you're one step off the beaten path the whole way.

How it works

The mechanism is the classic IP-Adapter trick, reimplemented for a different transformer. The Apply node clones your model, then patches each of Z-Image's 30 transformer blocks with extra to_k_ip / to_v_ip projection layers. Your reference image's CLIP vision embedding is pushed through a time-conditioned resampler that turns it into 64 IP tokens, and those tokens get mixed into cross-attention alongside the text prompt. The text path is left alone, which is why your prompt still works while the reference steers the style.

Two details worth knowing because they affect your results:

• weight (default 0.7, range -2 to 5) is the injection strength. Going over 1 is allowed and pushes the reference harder; going negative is allowed too, which is a crude "make it unlike the reference" lever.
• start_percent / end_percent (0 to 1) gate when in the denoise the injection is active. 0→1 applies it the whole way. If you want the composition steered early but fine detail left to the prompt, set end_percent around 0.6.

The node takes image_embed as a CLIP_VISION_OUTPUT - the output type of ComfyUI's built-in CLIP Vision Encode node. It uses the penultimate hidden states, same as the SD3 implementation it's derived from, so a stock CLIP Vision Loader + Encode pair plugs straight in.

Inputs and outputs that matter

Required: model, ipadapter (the IP_ADAPTER_ZIMAGE from the loader node), image_embed, and the three floats above. The single output is a MODEL, which you wire straight into your KSampler where the un-patched model went.

Installing and getting the weights

Same install as the rest of Boyonodes - ComfyUI Manager, search "Boyonodes", or:

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

Then restart. The hard part isn't the node, it's the model file: the Loader node (Boyo Load Z-Image IP-Adapter) expects a converted SD3→Z-Image weight file in ComfyUI/models/ipadapter/, and the pack README doesn't link one. You need to source a converted .safetensors from wherever the Z-Image community is trading them - that's the gap in this pipeline, and the reason it's not the default image-prompting path for Z-Image. Most people who want reference conditioning on Z-Image end up on in-context editors or Kontext-style workflows instead. This node is for the specifically stubborn.

If you're that stubborn: run everything in fp16 on CUDA. The resampler and all 30 processors are loaded fp16, and CPU is technically selectable but painfully slow.

Troubleshooting

• No weights, no dropdown entries: the Loader's ipadapter dropdown reads models/ipadapter/. Drop the converted file there and refresh.
• No style effect: check weight isn't near 0 and that start_percent/end_percent covers the range you're sampling through.
• Errors about Z-Image transformer blocks: you're patching a model that isn't the Z-Image architecture. This node only works on a Z-Image checkpoint.