Z-Image IPAdapter in ComfyUI: What Actually Works (And When to Skip It)

I spent an evening last month trying to make Z-Image match a reference photo. Not "similar style" — the actual look of a specific image, the way IP-Adapter does for SDXL. I'd read that Z-Image shipped without any first-party adapter, and I assumed that meant someone had built a good community one by now.

Sort of. There is exactly one working path, it runs on converted SD3 weights, and the person maintaining it describes those weights — in the source code — as "hijacked." That's not a reason to avoid it. It is a reason to know what you're getting into before you spend two hours on a workflow that most people would be better off solving a different way.

This guide covers the one working IPAdapter route for Z-Image in ComfyUI, the exact settings that make it behave, the failure modes and what each error actually means, and the honest answer to when you should skip IPAdapter entirely and use Z-Image's edit model instead.

TL;DR

• Z-Image has no first-party IPAdapter. Alibaba's 6B image model shipped without an image-prompting adapter, and there's no official plan to add one.
• One community node works: Boyo Apply Z-Image IP-Adapter from the Boyonodes pack. It patches Z-Image's 30 transformer blocks with IP projection layers, so your reference image steers style while your text prompt still works.
• The blocker isn't the node — it's the weights. You need a converted SD3→Z-Image .safetensors in ComfyUI/models/ipadapter/, and the pack's README doesn't link one. Source it from the community or you can't run the workflow at all.
• Defaults that actually work: weight 0.7, start_percent 0.0, end_percent 0.6–1.0. Over 1.0 pushes the reference harder; negative values push away from it.
• For most jobs, Z-Image Edit beats IPAdapter. The community consensus is blunt: with the edit model available, an IPAdapter is largely unnecessary. Use the adapter only when you specifically want style transfer without changing content.
• Run it in fp16 on CUDA. CPU is technically selectable and painfully slow.

Quick Verdict: Should You Set This Up?

If you want a reference photo's style on new content without touching the content itself — yes, the Boyo node is the only route and it works. If you want to keep a character, product, or composition consistent across images — no, use Z-Image Edit instead and save yourself the weight hunt.

That second case is the one most people are actually in, and it's why threads asking "is there an IP Adapter for Z-Image?" get answered with "zero chance, use the edit model."

What "IPAdapter for Z-Image" Actually Means

IP-Adapter, as originally built for SD 1.5 and SDXL, does one specific thing: it takes a CLIP vision embedding of a reference image and injects it into the model's cross-attention, so the output inherits the reference's visual characteristics without you training a LoRA or swapping checkpoints.

For Z-Image, this has to be reimplemented because the architecture is different. The Boyo node does it like this:

1. Patches the transformer. Each of Z-Image's 30 transformer blocks gets extra to_k_ip / to_v_ip projection layers, applied to a clone of your model.
2. Encodes the reference. Your reference photo goes through ComfyUI's standard CLIP Vision Encode, producing a CLIP_VISION_OUTPUT embedding (the node uses penultimate hidden states, same as the SD3 implementation it derives from).
3. Resamples into tokens. A time-conditioned resampler turns that embedding into 64 IP tokens.
4. Injects via cross-attention. Those tokens get mixed into cross-attention alongside your text prompt. The text path is untouched — which is why your prompt still works while the reference steers style.

The consequence of that design: this is style conditioning, not identity lock. It biases the look. It doesn't guarantee the same face, and it isn't a substitute for reference-image workflows that keep composition intact.

Install: The Part That Actually Blocks People

Step 1 — Install Boyonodes

Through ComfyUI Manager, search "Boyonodes" and install. Or clone directly:

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

Restart ComfyUI after either route.

Step 2 — Get the converted weights

This is where the pipeline breaks for most people, and it's worth being explicit about it: the loader node (Boyo Load Z-Image IP-Adapter) expects a converted SD3→Z-Image weight file in ComfyUI/models/ipadapter/, and the pack's README does not link one.

You have three options:

• Find a community-converted .safetensors shared by other Z-Image users.
• Convert SD3 IP-Adapter weights yourself against Z-Image's 30-layer architecture.
• Skip the workflow (see the edit-model section below).

If your loader's ipadapter dropdown is empty, this is why. It reads models/ipadapter/ — no file there, no entries.

Step 3 — Build the graph

The wiring is short:

Checkpoint Loader (Z-Image)
    └── Boyo Load Z-Image IP-Adapter  →  ipadapter
    └── Boyo Apply Z-Image IP-Adapter  →  MODEL
            ├── model: (from checkpoint)
            ├── ipadapter: (from loader)
            ├── image_embed: CLIP Vision Encode output
            ├── weight: 0.70
            ├── start_percent: 0.00
            └── end_percent: 1.00
                                   ↓
                              KSampler

Plus a CLIP Vision Loader feeding CLIP Vision Encode on your reference photo. The Apply node's single output is a MODEL — you wire it into the KSampler exactly where your unpatched model was.

The Settings That Decide Whether It Works

Three parameters, and each one has a specific job.

weight (default 0.7, range -2 to 5)

Injection strength. The usable band:

Value	Effect
0.0–0.4	Barely visible; text prompt dominates
0.5–0.8	The sweet spot — style transfers, composition survives
1.0–1.5	Reference dominates; layout starts copying the reference
1.5+	Overbaked: muddy texture, prompt ignored
Negative	Pushes away from the reference — the crude but useful "not this" lever

Start at 0.7. If you can't see the reference's influence, go to 0.9 before you go to 2.0.

start_percent / end_percent (0 to 1)

These gate when in the denoising process the injection is active. This is the parameter most people ignore and then blame the node for.

• 0 → 1.0: injection active throughout. Strongest style transfer, most risk of copying the reference's layout.
• 0 → 0.6: style applied early, fine detail left to the prompt. My default for anything where composition matters.
• 0.3 → 1.0: composition decided first, style applied late. Useful for matching color and texture on a locked layout.

If your output is copying the reference's arrangement when you wanted only its look, drop end_percent to 0.5–0.6 before touching weight.

Precision

Run everything in fp16 on CUDA. The resampler and all 30 block processors load in fp16. CPU is technically selectable and painfully slow — if you're on CPU, this workflow isn't worth attempting.

Failure Modes and What They Mean

Symptom	Cause	Fix
ipadapter dropdown empty	No weights in ComfyUI/models/ipadapter/	Drop the converted file there, refresh
No visible style effect	Weight near 0, or the start/end gate excludes the sampled range	Weight to 0.7, end_percent to 1.0
Output copies the reference's composition	Injection too strong across the whole denoise	Lower end_percent to 0.5–0.6
Errors about Z-Image transformer blocks	You're patching a non-Z-Image checkpoint	Load an actual Z-Image checkpoint
Extremely slow, or crashes on a small GPU	Running fp32 or on CPU	Switch to fp16, use CUDA
Washed-out, over-textured result	Weight above ~1.5	Back down to 0.7–0.9

That last row is worth dwelling on: the weight range goes to 5, which invites people to crank it. More injection doesn't mean more accurate. Past about 1.5 you're not transferring style harder, you're corrupting the attention path.

If you want output today, start here: Launch Z-Image Now →

Real Strengths: What This Workflow Is Good For

Style transfer onto new subject matter. Give it a photo with a specific film look — grain structure, color grading, contrast curve — and generate a different subject in that look. This is the job IPAdapter was invented for and the node does it competently at weight 0.7 with end_percent around 0.6.

Mood and palette matching for a series. If you're producing a set of product images that must share a visual language, a single reference plus this adapter gives you more consistency than prompt engineering alone.

Texture and material transfer. Leather, brushed metal, fabric weave — the adapter carries material character well, better than most text descriptions of it.

A visual "seed" for exploration. Set weight low (0.4–0.5) and use the reference as a nudge rather than a target. Useful when you have a vibe and no words for it.

If your goal is a repeatable look across a batch, the Z-Image Turbo reference-image consistency workflow covers the non-adapter approach and is worth reading before you commit to community weights.

The Honest Alternative: Z-Image Edit

Here's the part the IPAdapter tutorials don't tell you. The community's own answer to "any chance for IP Adapter for Z-Image?" is essentially no, and you don't need one anymore — because the edit model handles reference conditioning natively.

The distinction matters:

Job	IPAdapter (Boyo node)	Z-Image Edit
Match a look/palette to new content	✅ What it's built for	Possible, less direct
Keep a character or product consistent	⚠️ Weak — biases, doesn't lock	✅ Native strength
Change one element of an existing image	❌ Wrong tool	✅ Correct tool
Reliable, maintainable setup	⚠️ Unofficial weights, one maintainer	✅ First-party
Works without hunting weights	❌	✅
Predictable across model updates	❌ Breaks on architecture changes	✅

The rule I'd give anyone: if your reference image needs to survive into the output as content, use the edit model. If it only needs to survive as style, use IPAdapter — and only if you can get the weights.

There's a second consideration that doesn't show up in feature tables: maintenance. Community nodes that patch specific transformer block counts break when the architecture changes. If you're building a workflow you'll run monthly, a node whose weights the author describes as hijacked is a liability you should price in. For a closer look at how it stacks up against other models, see GLM. If you want to test it without installing anything, the free Z-Image generator works in the browser.

A Workflow That Uses It Well

The setup I've landed on for a recurring "same look, different product" job:

1. Pick one reference image that represents the exact look you want. Not a mood board — one image with the grain, palette, and contrast you're targeting.
2. Encode it with CLIP Vision Loader → Encode, feeding the Apply node.
3. Set weight 0.7, start 0.0, end 0.6. This transfers the look without dragging the reference's layout along.
4. Write the prompt for content only — describe the product, the light, the framing. Don't describe the style; the adapter is doing that.
5. Batch the prompts, keep the reference fixed. That's the whole value: one locked reference, many subjects.
6. Animate the winner if it needs motion. A still that already carries the look can go straight into an image-to-video pass — I use Wan 2.7 image-to-video for this step, since it keeps the source composition while adding camera movement.

Ready to try it yourself? Try Z-Image Free →

Two hours of setup, then a reusable look across a whole catalog. That's the case for the node. Anything short of "I need this look repeatedly" doesn't justify it.

Common Mistakes

1. Chasing weights for an hour, then discovering the node patches the wrong architecture. Confirm you're loading a real Z-Image checkpoint before anything else.
2. Treating weight as a quality knob. It's an injection-strength knob. Higher is not better; past 1.5 it's worse.
3. Leaving end_percent at 1.0 and wondering why compositions copy. This is the single most common complaint and the fix is one number.
4. Expecting identity lock. If faces must match, you want the edit model or a purpose-built character-consistency workflow, not style injection.
5. Running fp32. The node's internals are fp16; fp32 costs you time and gains nothing.
6. Building production dependencies on an unmaintained custom node. Keep a fallback path.

Try the Image Half Without the Setup

You don't need community weights and a hijacked SD3 conversion to get a Z-Image-class image. Generate the still in the browser, then take it into your local pipeline — or straight to video.

Generate a Z-Image still in the browser — no install, no weight hunt — then move it into whatever adapter workflow you've built.

• No models/ipadapter/ scavenger hunt — skip the step that blocks most people.
• Test the composition before the setup — find out whether the shot works before you invest an evening in ComfyUI.
• Straight to motion — still frames feed directly into video generation on the same site.
• Z-Image, GLM Image, and Wan in one place — compare what the models actually produce before committing to one pipeline.
• ComfyUI guides for the parts that matter — the Qwen Image 2.1 ComfyUI setup walkthrough covers a comparable local install with fewer footguns.

If all you need is one good image, this is the whole answer. If you need a repeatable look across fifty, build the adapter workflow.

The Bottom Line

There is exactly one working Z-Image IPAdapter in ComfyUI, it's the Boyo node, and it works — with converted SD3 weights the author calls hijacked, three parameters you have to tune deliberately, and fp16 on CUDA.

Set weight to 0.7, cap end_percent at 0.6, and keep the reference fixed while you vary the prompt. That's the workflow. If your actual goal is consistency rather than style, close this tab and use Z-Image Edit — the community's consensus on that is right, and it will save you an evening.

Related guides

• Keeping characters consistent with Z-Image Turbo reference images
• GLM Image vs Z-Image on the same prompts
• A full Qwen Image 2.1 ComfyUI install walkthrough

FAQ

Is there an official IPAdapter for Z-Image?

No. Z-Image shipped without a first-party image-prompting adapter, and there's no official ComfyUI node from Alibaba for it. The only working route is the community Boyo Apply Z-Image IP-Adapter node in the Boyonodes pack.

Where do I get the Z-Image IPAdapter weights?

You need a converted SD3→Z-Image .safetensors placed in ComfyUI/models/ipadapter/. The Boyonodes README doesn't link one — you have to source it from the Z-Image community or convert SD3 IP-Adapter weights yourself against Z-Image's 30-layer architecture. This is the main reason most people don't use this workflow.

What weight should I use for Z-Image IPAdapter?

Start at the default 0.7. The usable band is roughly 0.5–0.9 for style transfer that preserves composition. Above 1.0 the reference starts dominating layout; above 1.5 results get muddy. Negative values push the output away from the reference.

Why isn't my Z-Image IPAdapter doing anything?

Two likely causes: weight is near zero, or start_percent/end_percent aren't covering the range you're sampling through. Set weight to 0.7 and end_percent to 1.0 first, confirm the effect appears, then narrow the gate.

What does end_percent actually do?

It sets when during denoising the IPAdapter injection stops. At 0.6, the reference steers early composition and fine detail is left to the text prompt. At 1.0 the injection runs the whole way and the output tends to copy the reference's layout.

Can I run Z-Image IPAdapter on a 12GB GPU?

Yes — Z-Image itself is a 6B model that runs on 12GB cards, and the adapter is lightweight relative to the checkpoint. Run in fp16 on CUDA; the resampler and block processors are fp16 internally.

Is IPAdapter better than Z-Image Edit for character consistency?

No. IPAdapter biases style; it doesn't lock identity. For keeping a character, product, or composition consistent, Z-Image Edit is the native and more reliable path — which is why the community's answer to "is there an IPAdapter for Z-Image" is usually "you don't need one."

References

• Boyo Apply Z-Image IP-Adapter — ComfyUI node documentation — mechanism, parameter ranges, install steps, and troubleshooting for the Boyonodes Z-Image adapter.
• Boyonodes — GitHub — node pack source and weight loader.
• Z-Image IP-Adapter Reference Image Style Transfer — ernie-image.app — third-party walkthrough of the style-transfer workflow.
• Any chance for IP Adapter for Z-image? — r/comfyui — community consensus that the edit model supersedes the adapter for most use cases.
• Z-Image IPAdapter-style workflow discussion — ComfyUI Facebook group — practitioner thread on reference-image workflows for Z-Image Turbo.