Easy Anima IP-Adapter Hook

Anima's one structural weakness has always been the same one: no ControlNet, and for most of 2026 no reference-image path either. People kept asking for consistent characters without training a LoRA, and the answer kept being "not really, not on Anima". So here's the first proper answer, in two halves: LuciferTC's Anima IP-Adapter pack does the actual cross-attention injection, and this node - Easy Anima IP-Adapter Hook - bolts that into the first pass of Anima AiO Generator so you don't have to wire a second model pipeline.

Read the fine print before you get excited. This is a reviewed integration, not a general one.

What it does, and why it needs a "hook"

Anima is a 2B DiT on Cosmos-Predict2 with a Qwen3-0.6B text encoder, and image conditioning happens inside 28 transformer blocks' cross-attention. Classic IP-Adapter works the same way in spirit - a small adapter injects an image embedding through its own cross-attention path so your text prompt keeps working - but on a DiT you're patching module internals: fresh ip_k_proj / ip_v_proj layers, replaced block forwards, extra modules on the diffusion model. That's why the external Apply node exists and why you don't wire it here.

The AiO generator runs first pass, Highres, Detailer and Upscale as stages. This node emits an aio_hook that AiO applies at the SAMPLER_SAMPLE boundary of the first pass only - after model loading and normal LoRA patching, before sampling. Inside that call it snapshots the blocks, calls the upstream Apply logic programmatically, samples with the patched model, then restores added modules, attention hooks, block forwards and cross-attention layers on success, error or interruption. Encoder device placements too. That rollback is the whole reason this node exists: raw Apply mutates your model and forgets about it.

The inputs that matter

ip_adapter takes the external pack's ANIMA_IP_ADAPTER output (Anima IP-Adapter Loader (SigLIP2)). ref_image takes one RGB IMAGE - one, not a batch. Then:

• strength (0–2, default 1.0) - upstream's weight meaning. SDXL-era advice like "stay at 0.3–0.6" doesn't transfer blindly; start at the default and move deliberately.
• ref_image_size (default 512, 224–2048, step 16) - the node raises Reference image size must be a multiple of 16 if you break the alignment by scripting it.
• siglip_layer (default -1, range -1 to 24) - match it to how the checkpoint was trained.
• ip_cfg_scale / ip_cfg_separate - separate IP CFG costs extra model evaluations, i.e. real seconds per image. Off by default; leave it off until you have a reason.
• gray_null, use_lora - use_lora is about the LoRA inside the IP checkpoint, not your AiO LoRA stack.

One output, aio_hook, into the Generator's aio_hook socket. Multiple hooks go through Anima AiO Hook Combine.

Installing both halves

The pack itself is the usual routine - ComfyUI Manager, search "ComfyUI EasyUse Anima" (registry id comfyui-easyuse-anima), or:

cd ComfyUI/custom_nodes
git clone https://github.com/n0va39/ComfyUI-EasyUseAnima
pip install -r ComfyUI-EasyUseAnima/requirements.txt   # requests, googletrans-py

Then the part that actually matters for this node: the external pack and its SigLIP2 and IP-Adapter weights, which are neither bundled nor downloaded for you. Community threads through July 2026 are full of people failing to find those weights on GitHub; they live on HuggingFace at LuciferTC/Anima-IP-Adapter. Restart ComfyUI after both.

Where it breaks

The hook verifies the upstream implementation by source SHA-256 at commit 6b77cd0c, not by folder name. git pull the external pack to a newer revision and you'll get "Unsupported Anima IP-Adapter implementation" - the pack fails loudly rather than producing garbage, which is the right call and still annoying. Pin that commit.

Other errors you'll meet, all deliberate:

• requires ComfyUI --disable-dynamic-vram and requires a fully loaded model; use --highvram. The adapter needs every diffusion weight on the sampling GPU.
• requires the ComfyUI sampler with Spectrum disabled; same for Torch Compile. Standard CFG only - any other CFG patch means it refuses.
• supports generation batch size 1 only, requires one RGB reference image.
• 28-block Anima only. Anima 2.9B / 40-block is explicitly out of scope, so if you've moved to a bigger Anima variant, this is a dead end for now.
• If you ran the external Apply node on the same model first, blocks aren't clean and the hook errors - restart ComfyUI.

Last thing: with a hook connected, AiO stops reusing its output cache, because mutable external weights and image tensors aren't a serializable fingerprint. Expect every run to be a real run. Save the Loader, the reference image and these settings inside the workflow.