Anima Reference Adapter for ComfyUI

Character and style from a reference image. Pose, place and framing from your prompt.

Showcase · Quick start · Guide · Speed · Nodes · How it works · Training code

English · 한국어 · 日本語

Give Anima one reference image and a prompt that describes only the scene. The adapter keeps who is drawn (hair, eyes, outfit, accessories) and much of how it is drawn; pose, background and composition follow the prompt. No character name, artist tag or outfit tags, so it works for original characters too. Two references side by side give two characters in one image.

[!NOTE]

Development is paused for lack of funding. Further training is not possible for now, and the planned

separate character and style references are not released. The training code, data generation and

experiment log are public in anima-ref-adapter-research.

What's new in v2

| | | |---|---| | ⚡ About 2x faster than the pilot | 2.1x per sampling step on an RTX PRO 6000. On an RTX 3060 Ti an 832x1216 image takes 65 s instead of 105 s: the reference adds 32 s instead of 72 s. The reference is encoded once per image instead of at every step. | | 🧩 One node | Anima Ref Adapter drops into the standard Anima workflow and works with KSampler and any other sampler. The weights download on first use. | | 👥 Two characters | Two references side by side, and a prompt that says who is on which side. | | 📚 More training data | 15,600 images of 2,300 characters in 1,952 artist styles (pilot: 3,600 images, 300 characters), rank 64. |

Showcase

The one-node workflow with Anima's default settings: er_sde, 30 steps, cfg 4.5, ref_guidance 4.5 with APG, prompt masterpiece, best quality, score_7, safe, 1girl, solo, and the negative prompt from the Anima model card. No other LoRAs. One seed per image, not cherry-picked, except the lying pose (the best of six).

One reference

Two characters

Put the two references side by side in one image (the core Image Stitch node), write who is on the left and who is on the right with a few words each, use 2girls or 1boy, 1girl instead of solo, and a landscape size. Workflow.

Quick start

cd ComfyUI/custom_nodes
git clone https://github.com/ArcAnima/ComfyUI-Anima-Ref-Adapter.git

1. Get Anima base v1.0, the Qwen3-0.6B text encoder and the Qwen-Image VAE from

1. Restart ComfyUI and open workflows/anima_ref_adapter.json: the Anima

1. Load a reference image, write a prompt that describes only the scene, and queue. The first run downloads

In your own workflow: put Anima Ref Adapter between the model (after any other LoRAs) and the sampler, and connect the VAE and the reference image.

Step by step, with prompt tips and troubleshooting: user guide.

SnapRef adapters

The Anima Ref Adapter node also reads SnapRef anima_ref_kv/1 adapters, including per-row FP8 weights. Download snapref_v2a.safetensors into ComfyUI/models/loras/ and open workflows/anima_ref_adapter_snapref.json. Connect the Anima CLIP output to the node's optional clip input; SnapRef needs it even when ref_caption is empty. The node shows only the inputs that apply to the selected file: pilot/v2 inputs for pilot/v2 adapters, SnapRef inputs for SnapRef adapters. The adapter format is detected from metadata, so renaming the file is fine. Existing pilot/v2 workflows keep their settings and behavior.

| setting | SnapRef behavior | |---|---| | snapref_mode | cs: character and style; char: character only, with style from your prompt/model | | ref_weight | Linear reference attention weight: 1 = trained default, 0 = bypass. pilot/v2 adapters use strength (LoRA multiplier) instead. | | ref_caption | Optional appearance tags for the reference; empty works. | | snapref_guidance | Off by default: only the positive CFG branch reads the reference, as trained. On: both branches read it and ref_guidance, correction, and ref_end apply. | | ref_megapixels | Maximum reference area; small images are not enlarged. |

SnapRef support here is for one reference through the integrated Anima Ref Adapter node. The separate Loader/Latent/Guider nodes remain for pilot/v2 adapters. For multiple references or Fidelity, use the original SnapRef nodes. Do not stack the two adapters on the same model chain. Reference K/V is released when sampling finishes, including on failure. This backend uses ComfyUI's Anima attention APIs; use ComfyUI 0.29.0 or newer. Core MultiGPU sampling is rejected because the stream hooks share adapter state.

The SnapRef path also works with other extensions that steer the target, such as sorryhyun's Spectrum/Mod Guidance, without relying on their internals: the clean reference runs the blocks' own forward, so module hooks on them do not reach it, and the model call keeps its CFG batch whole while only the rows that use the reference read it inside self-attention. This prevents the reported 4-vs-2 batch error. Spectrum 2.13.4 additionally needs its own projection-row expansion fix for actual image batches larger than one; that is separate from SnapRef's CFG handling.

Speed and compatibility

Anima-2.9B's known 40-block depth expansion is detected automatically when a released 28-block adapter is loaded. The adapter's hooks follow the original layers at 0, 1, 3, 4, 6, 7, 9, 10, 12, 13, 15, 16, 18, 19, 20, 22, 23, 25, 26, 28, 29, 31, 32, 34, 35, 37, 38, 39. The 12 inserted layers keep their own weights; no adapter weights are copied into them. Reference K/V encoding and lookup still follow all 40 actual layers. Native model/adapter layouts keep their original routing; other block-count mismatches raise an error instead of silently attaching to the wrong layers. No extra node or setting is needed.

This fixes hook routing, not the training distribution: the adapters were trained on Anima base v1.0. Reference quality on 2.9B and its finetunes still needs render evaluation. CPU routing and reference-cache regression tests (PyTorch required, no ComfyUI or model downloads): python -m unittest discover -s tests -p 'test_block_layout.py'.

RTX 3060 Ti 8 GB (fp16), 832x1216, one reference; the faster of two runs:

| setup | time per image | |---|---| | Anima base, er_sde 30 steps, cfg 4.5, no reference | 33 s | | + pilot adapter, ref_guidance 4.5 | 105 s | | + v2 adapter, ref_guidance 4.5 | 65-67 s | | ref_guidance 1 (no extra model call) | 50 s | | + SageAttention (KJNodes Patch Sage Attention) | 62 s | | + EasyCache (core) | 63 s | | ref_end 0.6 | 62 s | | turbo LoRA (strength 1), 10 steps, cfg 1, ref_guidance 1 | 11 s |

• SageAttention, EasyCache and ref_end 0.6 each save about 7% on this GPU, with nearly the same image.
• A turbo LoRA for Anima base (tested: anima-turbo-lora-v0.2) goes in front of the adapter. It keeps

The whole showcase with the turbo LoRA (10 steps, cfg 1)

Not tested: the Anima-Turbo and Anima-Aesthetic full models, SamplerSPEED, torch.compile.

Nodes

| node | | |---|---| | Anima Ref Adapter | The one to use. MODEL + VAE + reference IMAGE + adapter LoRA -> MODEL for any sampler. The released adapter files are listed before they are downloaded and fetched on first use. The reference is resized to ref_megapixels (1.0) with its aspect ratio. ref_guidance runs as a post-CFG patch, one extra model call per step when it is not 1; ref_end stops that call early. | | Anima Ref Adapter Loader, Anima Ref Latent, Anima Ref Guider | The separate nodes, for the pilot adapter (it needs the reference at the output size) and the guider options ref_start and outside. Workflow. |

Recommended settings

| | recommended | notes | |---|---|---| | base model | Anima base v1.0 | the adapter was trained on it; a turbo LoRA also works | | sampler | any; er_sde or Euler, 30 steps, simple | as for Anima without the adapter | | cfg | 4.5 | text guidance; 1 with a turbo LoRA | | ref_guidance | 4.5 | 1 = cheaper and weaker; higher = more character detail and style, more saturation | | correction | apg | or rescale (phi 0.5) | | ref_end | 1.0 | ~0.6 is faster with nearly the same image | | prompt | quality + 1girl / 1boy + solo + scene tags | no character name, artist tag or outfit tags; a few appearance tags are fine | | other LoRAs | in front of the adapter node | |

How it works

flowchart LR
    R[reference image] -->|VAE| RL[reference latent]
    RL --> RS["reference stream<br/>self-attention only, timestep 0<br/>run once per image"]
    RS -->|"keys and values, every block"| T
    N[noisy target latent] --> T["target stream<br/>attends to itself + the reference"]
    P[scene-only prompt] -->|cross-attention| T
    T --> O[denoised target]

• Asymmetric attention. Target tokens attend to themselves and the reference; reference tokens attend

• The reference sits at shifted RoPE coordinates, past the target grid, so it is read as appearance and

• A rank-64 LoRA, active only with the reference, learns to read it. Training pairs are the same character

• Separate text and reference guidance, with adaptive projected guidance (APG) against over-saturation.

The pilot instead appended the reference as a second latent frame and recomputed it at every step. Its method, data and failure modes: technical report.

Pilot (v1)

The pilot (anima_ref_adapter_pilot_r32.safetensors, rank 32) stays available and works with the advanced workflow.

Pilot gallery and held-out characters

Prompt masterpiece, best quality, score_7, newest, highres, absurdres, safe, , solo, ; Euler 28 steps, cfg 4.5, reference guidance 4.5 + APG, context detailer LoRA 0.3, base slider LoRA 0.6, Anima Safe PAG. Not cherry-picked.

_{full body, walking, hands in pockets, city, street, night, rain  ·  upper body, sitting, holding cup, drinking, cafe, indoors, window, sunlight  ·  cowboy shot, looking at viewer, smile, beach, ocean, sunset  ·  portrait, from side, looking afar, cherry blossoms, petals  ·  upper body, reading, holding book, library, bookshelf  ·  full body, standing, snow, forest, winter full body, walking, smile, city, street, night, neon lights  ·  upper body, sitting, eating, cake, cafe, indoors  ·  cowboy shot, looking back, smile, beach, ocean, sunset  ·  portrait, closed eyes, smile, cherry blossoms, petals, wind  ·  full body, sitting, on chair, crossed legs, classroom, sunlight  ·  upper body, holding umbrella, rain, street, looking at viewer}

Held-out characters, excluded from training. Each row: the reference, the adapter's result for a new scene, the same scene-only prompt without the adapter, and the base model with the character named and its appearance tags.

| character | scene tags | |---|---| | Tohru | full body, looking at viewer, heart hands, crying, simple background, white background | | Eternity Larva | full body, looking at viewer, against wall, closed eyes, gradient background, sunlight | | Meiko | portrait, from side, writing, crying, beach, ocean, light rays | | Crocodile | upper body, from below, drinking, sad, bookshelf, indoors |

Limitations

• Identity transfers much better than style; strongly painterly styles barely transfer.
• Small patterns, scars, earrings and unusual skin tones are often lost; large garments can drift in color.
• The reference character occasionally reappears as an object in the scene.
• Trained only on images generated by Anima; it inherits the base model's biases.

Roadmap

| | status | |---|---| | Single reference: character and style from one image | ✅ pilot, v2 | | Asymmetric attention with a cached reference | ✅ v2 | | Two characters from two references side by side | ✅ v2 | | Separate character and style references | ⏸️ paused (experiments only) | | Higher-resolution training, better painterly styles and fine details | ⏸️ paused |

License

The node code is Apache-2.0 (LICENSE). The adapter weights are a derivative of the CircleStone Model and are distributed on Hugging Face under the CircleStone Non-Commercial License. This project is not affiliated with or endorsed by CircleStone Labs.

Citation

@misc{anima_ref_adapter_2026,
  title  = {Anima Reference Adapter: Single-Image Character and Style Transfer with an Offset-RoPE Reference Frame},
  author = {ElectronGirl},
  year   = {2026},
  url    = {https://github.com/ArcAnima/ComfyUI-Anima-Ref-Adapter}
}