# Anima Reference Adapter: user guide

**English** · [한국어](guide.ko.md) · [日本語](guide.ja.md)

This guide walks through installing the adapter in ComfyUI, making a first image, writing prompts, using
two characters, tuning the settings and fixing common problems. For the method and measurements, see the
[README](https://github.com/ArcAnima/ComfyUI-Anima-Ref-Adapter).

## 1. What you need

- **ComfyUI** that runs Anima. If you can already make images with Anima, you have everything.
- The Anima files from [circlestone-labs/Anima](https://huggingface.co/circlestone-labs/Anima):
  - `anima-base-v1.0.safetensors` in `ComfyUI/models/diffusion_models/`
  - `qwen_3_06b_base.safetensors` in `ComfyUI/models/text_encoders/`
  - `qwen_image_vae.safetensors` in `ComfyUI/models/vae/`
- About 1 GB of free VRAM on top of what Anima needs (the reference's cached keys and values at 1 MP).
  It was tested on an 8 GB RTX 3060 Ti.

The adapter weights do not need a separate download: the node fetches them on first use.

## 2. Install the nodes

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

Restart ComfyUI. Without git, download the repository as a ZIP from GitHub (Code → Download ZIP) and
unpack it into `ComfyUI/custom_nodes/`.

## 3. Your first image

1. Download [`anima_ref_adapter.json`](https://github.com/ArcAnima/ComfyUI-Anima-Ref-Adapter/blob/main/workflows/anima_ref_adapter.json)
   and drag it onto the ComfyUI canvas. It is the standard Anima text-to-image workflow with one extra node,
   **Anima Ref Adapter**, between the model loader and the KSampler.
2. In **Load Image**, choose your reference image.
3. In the positive prompt, keep the quality tags and describe only the scene (see section 4).
4. Queue. The first run downloads `anima_ref_adapter_v2_r64.safetensors` (183 MB) into
   `ComfyUI/models/loras/`; later runs start right away.

<img src="https://raw.githubusercontent.com/ArcAnima/ComfyUI-Anima-Ref-Adapter/main/docs/showcase/v2_police.jpg" width="100%" alt="reference and results">

## 4. Writing the prompt

The reference supplies the character (face, hair, eyes, outfit, accessories) and much of the drawing style.
The prompt supplies everything else.

| write | do not write |
|---|---|
| quality tags: `masterpiece, best quality, score_7, safe,` | the character's name |
| `1girl` or `1boy`, and `solo` | artist tags |
| framing: `cowboy shot`, `full body`, `upper body`, `portrait` | hair, eye and outfit tags (a few are fine) |
| pose and action: `sitting`, `lying, on side`, `holding cup` | |
| expression: `smile`, `sleepy`, `laughing` | |
| place, time and light: `cafe, indoors, day`, `beach, sunset` | |

Example: `masterpiece, best quality, score_7, safe, 1girl, solo, cowboy shot, sitting, cafe, holding cup, smile, looking at viewer, indoors, window, day`

Tips:

- Write a pose that differs from the reference's. The adapter is trained not to copy the reference's pose,
  and a clear pose in the prompt helps.
- Parts the reference does not show (the legs in a bust-up image, the back of an outfit) are guessed by the
  model. A reference that shows the whole character gives more consistent outfits.
- Anima's negative prompt from its model card works as is.

## 5. Two characters

<img src="https://raw.githubusercontent.com/ArcAnima/ComfyUI-Anima-Ref-Adapter/main/docs/showcase/v2_duo_police_mecha.jpg" width="100%" alt="two references and the result">

1. Open [`anima_ref_adapter_two_characters.json`](https://github.com/ArcAnima/ComfyUI-Anima-Ref-Adapter/blob/main/workflows/anima_ref_adapter_two_characters.json).
   It has two **Load Image** nodes joined side by side by the core **Image Stitch** node.
2. Load the left character in the first image and the right character in the second.
3. Replace `solo` with `2girls` (or `1boy, 1girl`, `2boys`) and say who is where, with a few words each:
   `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`
4. Use a landscape size such as 1216x832.

The two drawing styles tend to merge into one; the characters themselves stay apart.

## 6. Settings

All on the **Anima Ref Adapter** node.

| setting | default | what it does |
|---|---|---|
| `ref_guidance` | 4.5 | How hard to push toward the reference. Raise it (5-6) when the character drifts; lower it when colors get too strong. At 1 there is no extra model call, so it is faster but weaker. |
| `correction` | `apg` | Keeps colors in check at high guidance. `rescale` is an alternative; `none` turns it off. |
| `ref_end` | 1.0 | The point in the schedule after which `ref_guidance` stops (the reference itself stays). About 0.6 is faster with nearly the same image. |
| `ref_megapixels` | 1.0 | Size the reference is resized to. Lower it (0.5-0.7) to save VRAM. |
| `strength` | 1.0 | Strength of the adapter LoRA. |

Other LoRAs (style, detail) go **in front of** the adapter node, between the model loader and Anima Ref
Adapter.

## 7. Making it faster

| method | how | effect (RTX 3060 Ti, 832x1216) |
|---|---|---|
| turbo LoRA | a turbo LoRA for Anima base in front of the adapter; 10 steps, cfg 1, `ref_guidance` 1 | 67 s → 11 s; the reference style weakens |
| `ref_guidance` 1 | on the node | 67 s → 50 s |
| SageAttention | KJNodes **Patch Sage Attention** in front of the adapter | about 7% |
| EasyCache | the core **EasyCache** node after the adapter | about 7% |
| `ref_end` 0.6 | on the node | about 7% |

## 8. Troubleshooting

| problem | what to do |
|---|---|
| The result looks like an ordinary Anima image, not the reference | Check that the KSampler's `model` comes from **Anima Ref Adapter**, not from the model loader directly. Raise `ref_guidance`. |
| Colors are too strong or burnt | Lower `ref_guidance` (3-4) and keep `correction` on `apg`. |
| The pose copies the reference | Write a clear, different pose and framing in the prompt. |
| The reference character appears again as a poster or a figure in the scene | A known limitation; change the seed or lower `ref_guidance`. |
| The download fails | Download [`anima_ref_adapter_v2_r64.safetensors`](https://huggingface.co/ElectronGirl/anima-ref-adapter/blob/main/anima_ref_adapter_v2_r64.safetensors) by hand into `ComfyUI/models/loras/`. |
| Out of memory | Lower `ref_megapixels`, or use a smaller output size. |
| You want the pilot adapter | Use [`anima_ref_adapter_advanced.json`](https://github.com/ArcAnima/ComfyUI-Anima-Ref-Adapter/blob/main/workflows/anima_ref_adapter_advanced.json): the pilot needs the reference at the output size. |

## 9. Forge Neo

An extension for Stable Diffusion WebUI Forge (Neo) is available:
[sd-forge-anima-ref-adapter](https://github.com/ElectronGirl/sd-forge-anima-ref-adapter).