Anima IP-Adapter Loader

Every IP-Adapter workflow starts with the same move: point a loader at a .safetensors and hope the file is the right format. This is that node for Anima, and it's the least glamorous and most likely-to-fail piece of the pack, because the whole pack's usefulness hinges on what it accepts.

What it is

AnimaIPAdapterLoader takes a path to an IP-Adapter checkpoint and hands you an ANIMA_IPADAPTER object you plug into Anima IP-Adapter Apply. The adapter itself is the InstantCharacter-style architecture - SigLIP2 features in, a timestep-aware Perceiver resampler in the middle, and a separate cross-attention layer per DiT block. The loader doesn't invent any of that; it just reads the weights and reconstructs the right network from the state dict.

The thing worth understanding is that the loader is a format gatekeeper. It reads the checkpoint keys and decides which architecture you actually have:

• v3 (key resampler.time_proj.weight present) - the InstantCharacter-style architecture this pack targets. Loads fine, auto-derives block count, resampler depth, and dimensions from the file.
• v1/v2 (old Perceiver resampler, resampler.latents but no time_proj) - explicitly rejected with "v1/v2 checkpoint not compatible with v3 architecture. Please retrain with the latest code."
• Anything else - a KeyError telling you the format is unknown.

So this isn't a "load whatever you find" node. It's picky on purpose, because the v3 TimeResampler and the old Perceiver don't share weights. If you're holding an adapter trained for the earlier pipeline, no setting here will make it load.

The one input

There's exactly one required input: ipadapter_path, a plain string path to the .safetensors file. No dropdown, no auto-scan of a models folder - you type or paste the absolute path. That's the whole node. Output is a single ANIMA_IPADAPTER object, wired to the ipadapter socket on the Apply node.

Where do the weights come from?

Here's the honest catch, and it's the same one that's burned people on Anima IP-Adapter since the repo went public: the README ships no download link. The pack is code plus a training pipeline, not weights. The training/ folder has a kohya-style trainer (train_ipa_kohya.py) that dumps checkpoints as ipa_step{step}.safetensors, and there's a SLURM script showing the kind of rig it was built on - two GPUs, 128GB RAM, 100k steps. That's not a weekend project.

Practically that means: use the v3 adapter the author publishes (keep an eye on the repo's releases and HuggingFace, this pack is under active development), or train your own. If you try to use an SDXL/SD1.5 IP-Adapter you already have, it won't load - the architectures don't overlap at all, and the error message is your clue that you're holding the wrong generation of file.

Install

Same pack, same steps as everything else here:

cd ComfyUI/custom_nodes
git clone https://github.com/Wenaka2004/comfyui-anima-ipadapter
pip install -r comfyui-anima-ipadapter/requirements.txt

or use ComfyUI Manager and search "Anima IP-Adapter". The heavy dependency is transformers>=4.51 plus safetensors - nothing exotic, but the pin matters if your ComfyUI env has an old transformers sitting around; upgrade it or the SigLIP2 encode side of the pack will misbehave.

Troubleshooting

• "v1/v2 checkpoint not compatible" - you have a stale-format adapter. Retrain or find a v3 file. Not fixable in the UI.
• KeyError: Unknown checkpoint format - wrong file entirely, or a truncated download. Check the file actually ends in .safetensors and didn't half-download.
• Nothing loads and you get no error - the path is wrong. It's a raw string; there's no model-folder browser, so a typo means a silent-ish failure downstream. Verify the absolute path.

If you get the loader happy, the rest of the pack is smooth sailing - the Apply node is genuinely the easy part.