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,strengthset to 1.0, andref_offset_hset 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
modeloutput 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
strengthin 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_hat 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/lorasbefore 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-adapterand write tomodels/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_namedropdown 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
strengthandref_offset_hto 1.0 while checking the setup.
