Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-Anima-Ref-Adapter > Anima Ref Adapter Loader

ComfyUI Node: Anima Ref Adapter Loader

Class Name

AnimaRefAdapterLoader

Category
Anima Ref Adapter
Author
ArcAnima (Account age: 5days)
Extension
ComfyUI-Anima-Ref-Adapter
Latest Updated
2026-11-05
Github Stars
0.22K

How to Install ComfyUI-Anima-Ref-Adapter

Install this extension via the ComfyUI Manager by searching for ComfyUI-Anima-Ref-Adapter
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-Anima-Ref-Adapter in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

Anima Ref Adapter Loader Description

Loads reference-adapter weights into Anima models for reference-guided image generation.

Anima Ref Adapter Loader:

AnimaRefAdapterLoader, displayed as “Anima Ref Adapter Loader,” prepares an Anima diffusion model to work with reference-adapter weights so that reference information can be used during image generation. The adapter adds learned adjustments to the model and enables reference-aware processing, providing the model-side setup needed for a reference-guided workflow. This node handles loading and installing the adapter rather than encoding a reference image itself; reference preparation and delivery must be handled elsewhere in your workflow. It also sets up the model to receive reference information through the extension’s sampling integration, including additional handling for adapters identified as asymmetric. Its main benefit is that you can add reference-adapter support to a compatible model while continuing to use a model-based sampling workflow.

Anima Ref Adapter Loader Input Parameters:

model

A required MODEL connection containing the diffusion model you want to prepare for reference-adapter use. The node accesses the underlying diffusion model, installs the selected adapter’s hooks, and creates a cloned model wrapper with the reference-processing patches needed during sampling. Connect a model compatible with the selected Anima reference adapter; this node does not convert an unrelated model architecture into a compatible one. Compatibility matters because the adapter must work with the model’s internal structure. There is no numeric range or default value: you must supply this connection from an appropriate model-loading node or another compatible MODEL-producing node.

lora_name

A required COMBO selection identifying the reference-adapter weights to load. Although the parameter is named lora_name, its role here is to select an adapter supported by this extension, not to guarantee compatibility with any ordinary LoRA file. The default is anima_ref_adapter_v2_r64.safetensors. The released files listed in the supplied source are anima_ref_adapter_v2_r64.safetensors and anima_ref_adapter_pilot_r32.safetensors; these download on first use from ElectronGirl/anima-ref-adapter on Hugging Face into models/loras. The full dropdown is generated dynamically by the extension’s file-listing helper, so the supplied code does not establish an exhaustive list of locally available choices. Your selection determines which learned adapter weights and associated processing configuration are installed. This parameter has selectable file options rather than minimum and maximum numeric values.

strength

A required FLOAT controlling the strength value used when obtaining the adapter. The default is 1.0, the minimum is 0.0, the maximum is 2.0, and the adjustment step is 0.05. This setting controls the contribution of the adapter’s learned adjustments, allowing you to adjust their influence within the supported range. Start at 1.0 as the node’s baseline, then compare small changes while keeping the rest of your workflow fixed. The visible loader code does not define a linear relationship between this value and visual similarity, so doubling it should not be interpreted as doubling resemblance to a reference. Also, setting it to 0.0 does not skip the loader’s installation and reference-processing setup; it should not be assumed to be equivalent to removing the node.

ref_offset_h

A required FLOAT controlling the reference frame’s RoPE positional shift, measured in target-image heights. RoPE is part of how the model represents position; this setting changes the positional relationship assigned to the reference during reference-aware processing rather than physically moving or cropping your reference image. The default is 1.0, the minimum is 0.0, the maximum is 4.0, and the adjustment step is 0.05. For example, 1.0 expresses a shift of one target height in this positional representation, while 0.0 requests no shift from this setting. The tooltip explicitly states that training used 1.0, making that the best-supported starting point. The loader passes this value into its sampling wrapper, but the supplied code does not establish how consistently every adapter variant responds to changes.

Anima Ref Adapter Loader Output Parameters:

model

A MODEL containing the reference-adapter setup for downstream sampling. The returned value is a cloned model wrapper with additional handling for reference conditions and a diffusion-model wrapper configured for the selected adapter and positional offset. For an adapter identified as asymmetric, the node also adds an outer-sampling wrapper. Connect this output to the sampling stage, or to compatible downstream model-processing nodes, so generation uses the configured reference-adapter integration. This output is not an image, an encoded reference, or a separately saved checkpoint. Reference data still needs to be supplied through the appropriate workflow connections; in the provided processing code, a call without references for the adapter’s supported slots falls back to the original model execution path.

Anima Ref Adapter Loader Usage Tips:

  • Start with anima_ref_adapter_v2_r64.safetensors, strength set to 1.0, and ref_offset_h set to 1.0. These are the node’s defaults, and the positional offset matches the value explicitly identified as used during training.
  • Make sure your sampler receives this node’s model output rather than a parallel connection from the original model loader. Otherwise, that sampling path will not receive the wrapper configuration created here.
  • Include the extension’s appropriate reference-preparation and conditioning steps. This loader does not accept or encode an image itself, and loading adapter weights alone does not supply reference content.
  • Adjust strength in small increments and compare results with the same reference, prompt, seed, and sampling settings. This makes it easier to identify the effect of the adapter setting without unrelated changes obscuring the comparison.
  • Leave ref_offset_h at 1.0 while first checking your workflow. Experiment with other values only after reference guidance is working, because this controls positional encoding rather than a straightforward image-placement adjustment.
  • Allow for a download on the first use of either released adapter. If your ComfyUI installation has no internet access, arrange for the required file to be available in models/loras before running the workflow.
  • Match your reference connections to the selected adapter’s supported slots. The supplied code explicitly handles single-reference adapters differently from adapters with a separate style slot; connecting a style reference does not create independent style support in a single-reference adapter.

Anima Ref Adapter Loader Common Errors and Solutions:

Adapter download fails on first use

  • Explanation: The released adapter files are downloaded from Hugging Face when first needed. Network restrictions, an unavailable connection, or inability to write into the model directory can prevent loading. The supplied source does not show a fixed exception message for these failures.
  • Solution: Check that your ComfyUI environment can reach huggingface.co/ElectronGirl/anima-ref-adapter and write to models/loras. If necessary, download the selected released file manually into that directory, then refresh the available files or restart ComfyUI.

Selected adapter file cannot be found

  • Explanation: The selected filename must resolve to an accessible adapter file, or to a released file that the extension can download. A workflow may retain a filename that was moved, renamed, or is unavailable on your current installation. The exact error depends on the file-resolution helper, whose implementation is not included.
  • Solution: Check the lora_name dropdown and select an available adapter. Confirm that the expected file exists in the appropriate model directory, and refresh or restart ComfyUI after adding files.

Adapter weights are incompatible with the connected model

  • Explanation: The loader installs the adapter into the connected diffusion model. An unrelated model architecture or an unsupported weights file may fail during loading, installation, or sampling. The provided source does not specify an exact compatibility-error message.
  • Solution: Use a model intended for this Anima reference-adapter extension and select a supported reference-adapter file rather than an arbitrary LoRA. Test with a released adapter and a minimal workflow before adding other model modifications.

Adapter file cannot be read as a valid weights file

  • Explanation: A damaged or incomplete download, or a file that is not actually the expected weights format, can cause file-reading errors. Although the extension imports Safetensors support, the supplied loader excerpt does not provide a specific error string for this situation.
  • Solution: Remove or replace the suspect file and download it again from the adapter repository. Check that the download completed and that you saved the actual weights file rather than a web page with a similar filename.

[Anima Ref Adapter] this adapter has one reference slot; style_latent is used only when ref_latent is not connected

  • Explanation: This is an explicit warning in the supplied code, not necessarily a failure. The selected adapter has no separate style slot. In that case, a style reference is used as the character reference only when no character reference is supplied; it does not provide independent style guidance alongside a character reference.
  • Solution: For a single-reference adapter, supply the intended reference through the character-reference path, or leave that path empty if you want the style reference to serve as the sole reference. Use an adapter with documented style-slot support if your workflow needs separate character and style references.

Sampling runs, but the reference appears to have no effect

  • Explanation: This may occur without an exception. The supplied wrapper returns to the original model execution when no reference is available for the adapter’s supported slots. Another possible wiring issue is that the sampler uses the original model connection instead of this node’s output.
  • Solution: Trace both the reference-data path and the MODEL connection to the sampler. Confirm that reference preparation has completed, the reference reaches a supported slot, and the sampler uses this node’s output. Restore strength and ref_offset_h to 1.0 while checking the setup.

Anima Ref Adapter Loader Related Nodes

Go back to the extension to check out more related nodes.
ComfyUI-Anima-Ref-Adapter
RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

Anima Ref Adapter Loader