ComfyUI-Anima-Ref-Adapter Introduction
Anima Reference Adapter v2 banner
Use a reference image to guide the character’s appearance, and use your prompt to describe the new scene.
ComfyUI-Anima-Ref-Adapter is a reference-image extension for Anima in ComfyUI. It helps you draw a character in different situations without having to describe every part of their appearance in text.
The reference supplies visual information such as hair, eyes, clothing, accessories, and some drawing style. Your prompt supplies the action, pose, setting, lighting, and framing.
For example, you can provide a character portrait and ask for that character:
- Sitting in a café and holding a cup.
- Flying above clouds in a dynamic pose.
- Reading in a library.
- Walking through a city at night. You do not need a recognized character name, an artist tag, or a detailed outfit description. This makes the extension useful for original characters as well as existing characters.
What you can do
- Reuse a character across scenes: carry recognizable appearance information into new images.
- Transfer some visual style: preserve aspects of how the reference is drawn, alongside its character.
- Direct the composition with text: describe a new pose, environment, expression, and camera view.
- Generate two characters together: combine two references side by side and identify their positions in your prompt.
- Use a familiar ComfyUI workflow: the main adapter node works with KSampler and other samplers. Important: character identity transfers more reliably than drawing style. The extension is not an exact-copy tool, and fine details may change.
How ComfyUI-Anima-Ref-Adapter Works
Think of the extension as giving Anima two complementary instructions:
Reference image: “This is who to draw, and roughly how they look.” Prompt: “This is what they are doing, and where the scene takes place.”
1. The reference becomes a visual guide
A VAE—the image encoder already used in the Anima workflow—converts your reference into a compact representation the model can read. This representation is called a latent.
The adapter learns to use that information while generating a different image. You are not simply painting over the reference.
2. The prompt describes the new scene
Your text focuses on what should change:
- Pose and action.
- Facial expression.
- Background and location.
- Lighting and time of day.
- Framing, such as portrait, upper body, or full body. A typical single-character prompt is:
text masterpiece, best quality, score_7, safe, 1girl, solo, upper body, sitting, cafe, holding cup, smile, looking at viewer, indoors, window, day
The reference supplies the character’s appearance, so you normally leave out character names, artist tags, and detailed outfit tags. A few appearance cues are still acceptable when helpful.
3. Appearance is separated from image placement
The adapter uses shifted positional coordinates, described technically as offset RoPE. In practical terms, this helps the model read the reference as a source of appearance rather than as a layout to copy.
This is why you can request a different pose or framing. It does not mean every requested pose will be reproduced perfectly.
4. Version 2 reads the reference once
Version 2 uses asymmetric attention:
- The image being generated can consult the reference.
- The reference representation does not depend on the changing generated image or the scene prompt. This lets the extension compute and cache the reference information once per generated image, rather than recomputing it at every sampling step.
An analogy is preparing a character reference sheet before drawing: the model can keep consulting the same prepared sheet instead of rebuilding it repeatedly.
5. Text and reference have separate guidance controls
cfgcontrols text guidance.ref_guidancecontrols additional reference guidance. This gives you a way to adjust reference influence without treating it as the same control as prompt influence. The recommended APG correction helps limit excessive saturation from guidance.
For implementation details, see the technical report and research repository.
ComfyUI-Anima-Ref-Adapter Features
Single-reference character and style transfer
One image provides both the character reference and whatever style information the adapter can preserve.
This is useful when you want a new scene without repeatedly writing long appearance descriptions.
One character reference used for two different scenes
Example scene prompts:
text cowboy shot, sitting, cafe, holding cup, coffee, smile, looking at viewer, indoors, window, day
text full body, lying, on side, on bed, head rest, looking at viewer, smile, bedroom, indoors, night, lamp light
“Cowboy shot” describes framing around the thighs upward.
Two-character scenes
You can provide two characters by combining their reference images into one side-by-side image with ComfyUI’s core Image Stitch node.
For this workflow:
- Put one reference on the left and the other on the right.
- Use a landscape output size.
- Replace
solowith an appropriate subject count, such as2girlsor1boy, 1girl. - Briefly identify the character on each side.
- Describe their shared action and setting. Example:
text 2girls, the girl on the left is a policewoman with black hair over one eye, the girl on the right is a mecha girl with aqua hair and mechanical wings, standing side by side, peace sign, smile, city, street, day
Two side-by-side character references and a generated shared scene
Use the two-character workflow as your starting point.
This is not separate character-and-style referencing. Both images supply characters for the same scene; they are not independent identity and style inputs.
One main node
Anima Ref Adapter is the recommended node for normal use.
It takes:
- An Anima
MODEL. - The workflow’s
VAE. - A reference
IMAGE. - An adapter weight selection.
It outputs a modified
MODELthat connects to your sampler.
In an existing workflow, the order is:
text Anima model → other LoRAs, if used → Anima Ref Adapter → sampler
Connect the reference image and VAE to the adapter as well.
Released adapter files appear in the selection list before they are downloaded. The selected weights are retrieved on first use.
Reference-size handling
Version 2 resizes the reference according to ref_megapixels, while preserving its aspect ratio. The default is 1.0 megapixel, or approximately one million pixels.
This means the reference does not need to have the same dimensions or shape as the output.
The older pilot adapter has different requirements: it needs the reference prepared at the output size through the advanced workflow.
Adjustable guidance and correction
| Setting | Recommended starting point | What it means for your artwork |
|---|---|---|
| cfg | 4.5 | Text guidance. Use 1 with the tested turbo LoRA setup. |
| ref_guidance | 4.5 | Reference guidance. Higher values can strengthen character details and style, but also increase saturation. |
| correction | apg | Helps counter excessive saturation from guidance. |
| Alternative correction | rescale, phi 0.5 | Another supported correction option. |
| ref_end | 1.0 | Keeps the additional reference-guidance call active through the full sampling process. |
| ref_megapixels | 1.0 | Reference processing resolution, with aspect ratio preserved. |
Two useful reference-guidance choices are:
ref_guidance = 4.5: the recommended starting point for character and style fidelity.ref_guidance = 1: weaker reference guidance, but faster because it avoids the extra model call used by additional reference guidance. Settingref_guidanceto1does not remove the reference.
Setting ref_end to about 0.6 stops the additional guidance call earlier. In the author’s benchmark, this improved speed with nearly the same image. It should not be interpreted as removing all reference information after that point.
Advanced nodes
The extension also includes:
- Anima Ref Adapter Loader
- Anima Ref Latent
- Anima Ref Guider
These separate nodes support the pilot adapter and advanced guider options such as
ref_startandoutside.
For these controls, use the advanced workflow and user guide. Most artists should start with the single main node.
ComfyUI-Anima-Ref-Adapter Workflow and Prompt Guide
Start with the supplied workflow
Open the one-node workflow, load a reference image, and describe a new scene.
The workflow uses the same model components as Anima:
- Anima base v1.0
- Qwen3-0.6B text encoder
- Qwen-Image VAE These components are documented on the Anima model page.
No additional custom-node packages are needed for the supplied one-node workflow.
Recommended baseline
| Component | Starting setting |
|---|---|
| Base model | Anima base v1.0 |
| Adapter | v2, rank 64 |
| Sampler | er_sde or Euler |
| Sampling steps | 30 |
| Scheduler | simple |
| CFG | 4.5 |
| Reference guidance | 4.5 |
| Correction | apg |
| Reference end | 1.0 |
For the negative prompt, refer to the Anima model card.
Write prompts around the scene
A useful structure is:
text quality tags + subject count + solo, if appropriate + scene description
For example:
text masterpiece, best quality, score_7, safe, 1girl, solo, full body, flying, from below, sky, clouds, sunlight, dynamic pose, outstretched arm
Reference character shown flying and sitting in a hangar
For a single character, avoid unnecessarily repeating the character’s name, artist, or full outfit description. For two characters, short appearance descriptions help distinguish left from right.
Understand the showcase settings
The author’s v2 showcase uses:
er_sde, 30 steps.- CFG
4.5. - Reference guidance
4.5with APG. - The negative prompt from the Anima model card.
- No additional LoRAs. The author reports using one seed per showcased image without cherry-picking, except for the lying pose, which was selected from six attempts. Treat the examples as demonstrations, not guarantees for every reference or pose.
ComfyUI-Anima-Ref-Adapter Models
Released adapters
| Adapter | File | Purpose and recommended use |
|---|---|---|
| v2 — rank 64 | anima_ref_adapter_v2_r64.safetensors | Recommended for normal use. Transfers identity and some style, caches reference information, and supports the simpler one-node workflow. |
| Pilot / v1 — rank 32 | anima_ref_adapter_pilot_r32.safetensors | Earlier release retained for comparison and existing advanced workflows. Slower, with reference preparation tied to output size. |
The v2 file is 183 MB. Both releases are available from the adapter weights repository.
“Rank” describes the adapter’s internal configuration. You do not need to adjust it: choose the released file appropriate to your workflow.
Base-model compatibility
Anima base v1.0 is the recommended base because the adapter was trained on it.
The author also tested anima-turbo-lora-v0.2, applied to Anima base before the adapter. It offers much faster generation, but shifts the drawing toward the turbo LoRA’s own appearance, reducing reference-style preservation.
The following were not tested in the supplied documentation:
- Anima-Turbo full model.
- Anima-Aesthetic full model.
- SamplerSPEED.
torch.compile. A tested turbo LoRA should not be confused with a tested turbo full model.
Research experiments are not additional supported releases
The research repository documents several experiments:
| Experiment | Reported outcome |
|---|---|
| dual_r32 | Separate character and style slots were trained, but the style slot did not work. |
| char_v2 / char_v3 | A proposed style_transfer strength was ignored; these experiments were stopped. |
| style_asym_r64 | A style-only adapter was trained, but did not copy the reference style. |
| Character-only adapter | Planned, but not started. |
The research name copy_asym_r64 corresponds to the released v2 adapter.
These experiments do not provide a released, reliable way to control character and style independently.
What's New with ComfyUI-Anima-Ref-Adapter
Pilot / v1
The pilot established the basic single-reference workflow:
- Character identity and some style from one image.
- A rank-32 adapter.
- Training on 3,600 images covering 300 characters.
- A two-frame approach that recomputed reference information at each sampling step.
- Separate loader, reference-latent, and guider nodes. It remains available through the advanced workflow.
Version 2
| Change | Why it matters | |---|---| | Cached reference processing | Reduces repeated computation during sampling. | | About 2.1× faster per sampling step in the reported RTX PRO 6000 test | Makes reference-based generation more practical, although whole-image speedups vary. | | One main node | Simplifies connecting the adapter to a standard Anima workflow. | | Two-character workflow | Lets you use two side-by-side references for a shared scene. | | Reference aspect ratio preserved | Removes the pilot’s requirement to prepare the reference at output size. | | Larger training set | Expands training coverage to 15,600 images, 2,300 characters, and 1,952 artist styles. | | Rank-64 adapter | Replaces the pilot’s rank-32 configuration. |
Development status
The research documentation records development as paused as of October 29, 2026. Further training and planned improvements are on hold.
Unreleased or paused work includes:
- Separate character and style references.
- Higher-resolution training.
- Better painterly-style transfer.
- Improved fine-detail preservation. The author has made the training code, data-generation tools, and experiment log public.
ComfyUI-Anima-Ref-Adapter Performance and Compatibility
The author reports these results on an RTX 3060 Ti 8 GB, using fp16, an 832 × 1216 output, and one reference. Measurements used the faster of two runs.
| Setup | Reported time per image |
|---|---:|
| Anima base without reference, 30 steps, CFG 4.5 | 33 seconds |
| Pilot adapter, reference guidance 4.5 | 105 seconds |
| v2 adapter, reference guidance 4.5 | 65–67 seconds |
| v2 with reference guidance 1 | 50 seconds |
| v2 with SageAttention | 62 seconds |
| v2 with core EasyCache | 63 seconds |
| v2 with ref_end = 0.6 | 62 seconds |
| Tested turbo LoRA, strength 1, 10 steps, CFG 1, reference guidance 1 | 11 seconds |
These are examples, not expected timings for every system. Hardware, image size, workflow, and settings affect performance.
Same-seed comparison of performance-related settings
Choosing a speed trade-off
- Start with v2: it is substantially faster than the pilot.
- Try
ref_guidance = 1: useful when speed matters more than stronger reference fidelity. - Try
ref_end ≈ 0.6: the author observed a modest speed improvement with little visible change in the tested example. - Consider the tested turbo LoRA: useful for fast iteration, but expect less faithful reference style.
- Treat optimization results individually: SageAttention, EasyCache, and reduced
ref_endeach saved about 7% in the reported test; combined gains are not established. The tested SageAttention option is Patch Sage Attention from KJNodes. It is optional, not a requirement for the main workflow.
Troubleshooting ComfyUI-Anima-Ref-Adapter
The steps below combine documented settings with practical checks based on the supplied workflows.
The character does not resemble the reference strongly enough
- Confirm that you are using Anima base v1.0 and the recommended v2 adapter.
- Check that the reference image and VAE connect to Anima Ref Adapter.
- Check that the sampler receives the adapter’s output model.
- If
ref_guidanceis1, try the recommended4.5. - Simplify the prompt to focus on the scene rather than competing appearance descriptions.
- Keep APG correction enabled when using stronger guidance. Some differences are known limitations. Small details and unusual skin tones may remain unreliable.
Colors look too saturated
- Check whether reference guidance has been raised above the recommended starting point.
- Reduce
ref_guidanceand compare the result. - Use
correction = apg. - Alternatively, try the documented
rescalecorrection with phi0.5. Higher reference guidance can increase both fidelity and saturation, so the highest setting is not necessarily the best.
The character transfers, but the art style does not
- Check whether a turbo LoRA is active; it can pull the result toward its own look.
- Compare with the standard v2 workflow without additional LoRAs.
- Return to the recommended reference-guidance and APG settings.
- Account for the documented limitation: strongly painterly styles barely transfer. There is no released independent style-strength control or working separate style-reference slot.
Two characters are mixed up or poorly distinguished
- Open the supplied two-character workflow.
- Confirm the references are stitched side by side into one image.
- Remove
solo. - Specify the correct subject count.
- Identify the left and right characters with short, distinctive descriptions.
- Use a landscape output. This follows the documented method, but does not guarantee perfect separation in every generation.
Generation takes longer than expected
- Confirm that you selected v2 rather than the pilot.
- Compare your resolution and step count with the benchmark.
- Remember that
ref_guidancevalues other than1require an extra model call per step while additional guidance is active. - Try
ref_guidance = 1orref_end ≈ 0.6. - If appropriate, compare the tested turbo LoRA setup while accepting its style trade-off.
The first run downloads a file
This is expected. Released adapter names are shown before their files are present locally, and the selected weights download on first use.
The v2 file is 183 MB. If retrieval fails, check the file’s availability on the weights page and your connection before retrying.
The reference dimensions differ from the output
- With v2: this is supported; the reference is resized with its aspect ratio preserved.
- With the pilot: use the advanced workflow, which prepares the reference at the output size.
Small accessories, markings, or clothing colors change
This is a documented limitation rather than necessarily a workflow error. Known weak points include:
- Small patterns.
- Scars.
- Earrings.
- Unusual skin tones.
- Color consistency in large garments. The character can also occasionally reappear as an object in the scene. Further training to address these issues is paused.
Frequently asked questions
Can you use original characters? Yes. The reference supplies appearance, so a recognized character name is not required.
Do you need to train an adapter for each character? The released workflow accepts a reference image directly; it does not require character-specific training as part of normal use.
Does it copy the reference pose? It is designed to transfer appearance rather than pixel-aligned layout. Describe the desired pose in your prompt, while allowing for normal generation errors.
Can you use one image for identity and another for style? Not through a released supported feature. Two-character stitching is a different capability.
Does reference guidance of 1 disable the reference?
No. It removes the extra guidance model call, producing a cheaper and weaker reference-guidance setup.
Can you use other LoRAs? Yes. Place them before the adapter node. They may affect the result; the tested turbo LoRA also changes the drawing style.
Does the training hardware requirement apply to ordinary generation? No. The research repository’s approximately 70 GB GPU-memory requirement concerns training. The author’s inference benchmark used an 8 GB RTX 3060 Ti, although your workflow’s memory needs can differ.
ComfyUI-Anima-Ref-Adapter Limitations and Licensing
Creative limitations
The adapter was trained only on images generated by Anima and inherits the base model’s biases.
Expect stronger transfer of character identity than of style. It is not a guarantee of exact character-sheet consistency, precise accessory reproduction, or faithful painterly rendering.
Licensing
The code and model weights have different licenses:
- Node code: Apache-2.0.
- Adapter weights: CircleStone Non-Commercial License, because they derive from the CircleStone model. The research documentation also states that images generated with Anima are subject to its license. Review the applicable terms before using outputs commercially; the code’s Apache license does not replace the model’s restrictions.
The project is not affiliated with or endorsed by CircleStone Labs.
Learn More about ComfyUI-Anima-Ref-Adapter
Artist-focused guides and workflows
- English user guide — step-by-step usage, prompting advice, and troubleshooting.
- Single-reference workflow — the recommended starting point.
- Two-character workflow — side-by-side references and shared scenes.
- Advanced workflow — pilot compatibility and separate guider nodes.
- Anima model card — base-model information and prompt guidance.
Project and model resources
- ComfyUI extension repository — node source, workflows, and project documentation.
- Released adapter weights — adapter files and weight-license information.
- KJNodes — the optional Patch Sage Attention node used in the performance comparison.
For a deeper understanding
- Technical report — the pilot method, training data, and failure modes.
- Research repository — training, evaluation, and data-generation code.
- Experiment log — documented experiments, evaluation results, and explanations of approaches that did not work.
