README.md

---
license: other
license_name: mixed-license
base_model:
  - circlestone-labs/Anima
base_model_relation: finetune
pipeline_tag: text-to-image
tags:
  - anime
  - noob2-project
  - character-reference
  - single-reference
  - multi-reference
  - image-editing
  - image-conditioned-generation
  - native-reference
  - text-to-image
  - anima
  - research
---

# NOOB2 Project - Anima V7 Native Context 1024 E2

**Current release: V7 Native Context 1024 E2, continued from cumulative
512 epoch 4.** This is one self-contained Anima diffusion checkpoint for
standard T2I, single-reference generation, prompt-directed two-reference
generation, and maskless Edit.

> **ComfyUI hotfix 7.0.2:** package 7.0.1 had a Python helper-binding bug that blocked visual nodes. Replace the entire custom-node directory with 7.0.2 and restart ComfyUI. The model checkpoint itself is unchanged.

The V7 path uses native source/reference VAE latent sequences, structural image
instance/source-role metadata, read-only reference K/V attention, and learned
full-prompt competitive routing. It does not require an external LoRA, adapter,
IP-Adapter, ControlNet, runtime mask, or img2img denoise strength.

The ComfyUI node passes the visible prompt unchanged. It does not prepend `Use
Image 1`, infer hidden roles, parse clauses, or rewrite an empty prompt.

> **Research release:** the 1024 stage preserves the no-reference T2I path,
> but exact single-reference identity, strict multi-reference role binding, and
> fine local Edit remain imperfect. Maskless Edit can affect a broader region
> than requested. V7 512 E4 remains available as the previous release.

## V7 1024 release files

| Item | Value |
|---|---|
| Checkpoint | [`anima-native-context-v7-1024-e2.safetensors`](checkpoints/v7-native-context-1024-e2/anima-native-context-v7-1024-e2.safetensors) |
| SHA-256 | `a72081e46627677d775f52f8f7cd2941525d0fc16f8692b031e6c6997265393a` |
| Bytes | `4,303,082,856` |
| Tensor contract | `1,569` BF16 tensors; integrated `native_context_v1` |
| Training | 2 x 1024 nominal-area epochs from V7 512 E4; 19,620 updates over 235,435 rows |
| Geometry | ratio buckets 512..2048; reference maximum area 1,048,576 pixels |
| Prompt contract | exact/full prompt; no hidden rewrite |
| External weights | no adapter/LoRA; standard Anima Qwen encoder and VAE required |
| ComfyUI | existing V7 7.0.2 node/package; select this checkpoint and set 1024 dimensions |
| Evidence | [`release-metadata/v7-native-context-1024-e2/`](release-metadata/v7-native-context-1024-e2/) |

## Previous V7 512 release files

| Item | Value |
|---|---|
| Checkpoint | [`anima-native-context-v7-512-e4.safetensors`](checkpoints/v7-native-context-512-e4/anima-native-context-v7-512-e4.safetensors) |
| SHA-256 | `f8407d44ecea51d14a779756df326b143a29b12867743b6fc7afdd82f2a6e091` |
| Bytes | `4,303,082,816` |
| Tensor contract | `1,569` BF16 tensors; integrated `native_context_v1` |
| Training | cumulative 4 x 512-resolution epochs; 235,435 exposure rows |
| Prompt contract | exact/full prompt; no hidden rewrite |
| External weights | no adapter/LoRA; standard Anima Qwen encoder and VAE required |
| Comfy package | [`ZIP`](comfyui/releases/7.0.2-v7-native-context-512-e4/ComfyUI-Anima-Native-Context-v7.0.2-512-e4.zip) / [`tar.gz`](comfyui/releases/7.0.2-v7-native-context-512-e4/ComfyUI-Anima-Native-Context-v7.0.2-512-e4.tar.gz) |
| Workflows | [`comfyui/workflows/v7-native-context-512-e4/`](comfyui/workflows/v7-native-context-512-e4/) |
| Evidence | [`release-metadata/v7-native-context-512-e4/`](release-metadata/v7-native-context-512-e4/) |

## Supported paths and defaults

| Task | Visual input | Structural rule | Scale |
|---|---:|---|---:|
| T2I | 0 | true no-image hard bypass | n/a |
| Single reference | 1 | sole image is structural instance 0 | `1.0` |
| Multi reference | 2 | physical order is instances 0 then 1; no fixed roles | `1.0` |
| Maskless Edit | 1 aligned source | instance 0 plus non-text source-role bit | `1.4` |

The validated V7 1024 acceptance preset is 1024 x 1024, 20 steps, CFG 3.5,
flow shift 5.0, and a 1,048,576-pixel (`1024 x 1024`) maximum per reference.
The existing packaged workflows retain their 512 defaults; select this
checkpoint and update the width, height, and reference maximum area for 1024
inference. Aspect-ratio sizes can still be selected manually.

## ComfyUI quick start

1. Extract the [V7 ZIP](comfyui/releases/7.0.2-v7-native-context-512-e4/ComfyUI-Anima-Native-Context-v7.0.2-512-e4.zip)
   into `ComfyUI/custom_nodes/`.
2. Install `requirements.txt` with ComfyUI's Python interpreter.
3. Put [anima-native-context-v7-1024-e2.safetensors](checkpoints/v7-native-context-1024-e2/anima-native-context-v7-1024-e2.safetensors) in
   `ComfyUI/models/diffusion_models/`. The previous 512 E4 checkpoint remains
   available in its original path.
4. From [`circlestone-labs/Anima`](https://huggingface.co/circlestone-labs/Anima),
   place `qwen_3_06b_base.safetensors` in `models/text_encoders/` and
   `qwen_image_vae.safetensors` in `models/vae/`.
5. Restart ComfyUI and load a V7 workflow:
   - [T2I](comfyui/workflows/v7-native-context-512-e4/anima_v7_native_context_t2i.json)
   - [single reference](comfyui/workflows/v7-native-context-512-e4/anima_v7_native_context_single_ref.json)
   - [multi reference](comfyui/workflows/v7-native-context-512-e4/anima_v7_native_context_multi_ref.json)
   - [maskless Edit](comfyui/workflows/v7-native-context-512-e4/anima_v7_native_context_edit.json)

API graphs are in [`comfyui/workflows/v7-native-context-512-e4/api/`](comfyui/workflows/v7-native-context-512-e4/api/).

![V7 1024 final acceptance](comfyui/examples/v7-native-context-1024-e2/final_acceptance_generated_only_master.jpg)

![V7 1024 local attribute Edit sweep](comfyui/examples/v7-native-context-1024-e2/attribute_edit_scale_sweep_master.jpg)

![V7 1024 clothing Edit sweep](comfyui/examples/v7-native-context-1024-e2/clothing_edit_scale_sweep_master.jpg)

![V7 512 reference evaluation](comfyui/examples/v7-native-context-512-e4/cumulative_e2_e3_e4_reference_master.png)

![V7 512 Edit evaluation](comfyui/examples/v7-native-context-512-e4/cumulative_e2_e3_e4_edit_master.png)

---

## Previous release documentation

# NOOB2 Project — Anima V6 Unified Fullmix

**Current release: V6 Unified Fullmix E5 / step 45,500.**  This is one
self-contained Anima diffusion checkpoint for standard T2I, single-reference
generation, prompt-directed two-reference generation, and maskless Edit.

Source/reference images enter as native Anima/Qwen-Image VAE latent sequences,
with independent slot/index/boundary identity and integrated read-only
reference K/V attention.  Prompt tokens drive competitive text-to-slot and
attribute routing.  Edit uses an implicit source-scope path learned during
training; users do not provide a mask.  There is no external LoRA, adapter,
IP-Adapter, ControlNet, or img2img denoise-strength control.

> **Research release:** single- and multi-reference anime generation are the
> strongest paths.  Edit is usable with the calibrated per-task scale below,
> but local detail, exact counts, text, and strongly out-of-distribution edits
> can still fail.  Training used a 256-pixel nominal-area bucket regime;
> higher-resolution inference is experimental.

## V6 release files

| Item | Value |
|---|---|
| Checkpoint | [`anima-v6-unified-fullmix-e5-step45500-256area.safetensors`](checkpoints/v6-unified-fullmix/anima-v6-unified-fullmix-e5-step45500-256area.safetensors) |
| SHA-256 | `70ab64b6262530e73e3eb0993e20addc0fcf00675123ca942de0bbc01d80682f` |
| Bytes | `4,303,662,944` |
| Tensor contract | `1,628` BF16 tensors; `938` integrated native tensors |
| Training | 5 epochs; 45,500 optimizer updates; batch size 26; 236,160 source rows |
| Geometry | 256-pixel nominal area with aspect-ratio buckets |
| External weights | None beyond the standard Anima Qwen encoder and VAE |
| Comfy package | [`v0.3.0-v6-fullmix ZIP`](comfyui/releases/v0.3.0-v6-fullmix/ComfyUI-Anima-Native-Reference-v0.3.0-v6-fullmix.zip) / [`tar.gz`](comfyui/releases/v0.3.0-v6-fullmix/ComfyUI-Anima-Native-Reference-v0.3.0-v6-fullmix.tar.gz) |
| Release evidence | [`release-metadata/v6-unified-fullmix/`](release-metadata/v6-unified-fullmix/) |

Existing V4 and V2 checkpoints, packages, and workflows remain available in
their historical paths and have not been overwritten.


> **ComfyUI live-folder repair (2026-08-10):** the repository path
> `comfyui/custom_nodes/ComfyUI-Anima-Native-Reference/` now contains the same
> V6 nodes and `runtime_v6.py` as the v0.3.0 release archive. If you copied that
> live folder earlier, replace it completely rather than merging files.

## What V6 supports

| Task | Visual inputs | Slot rule | Recommended reference scale |
|---|---:|---|---:|
| Standard T2I | 0 | true no-reference bypass | n/a |
| Single-reference generation | 1 | explicitly choose slot 0 or slot 1 | `1.0` |
| Multi-reference generation | 2 | Image 1 → slot 0; Image 2 → slot 1 | `1.0` |
| Maskless Edit | 1 aligned source | explicitly choose source slot | **`1.4`** |

The two slots do not have hard-coded roles.  Image 1 is not inherently a scene
image, and Image 2 is not inherently an identity image.  Bind every requested
attribute in the prompt:

```text
Use Image 1 as the pose and composition reference. Use Image 2 as the character
identity and clothing reference. Generate a coherent anime illustration.
```

For Edit:

```text
Use Image 1 as the source image. Replace the daytime sky with a dramatic sunset
while preserving the character, pose, clothing, and composition.
```

## ComfyUI quick start

1. Download and extract the
   [`V6 ZIP`](comfyui/releases/v0.3.0-v6-fullmix/ComfyUI-Anima-Native-Reference-v0.3.0-v6-fullmix.zip)
   into `ComfyUI/custom_nodes/`.
2. Install `requirements.txt` with the same Python interpreter that launches
   ComfyUI.
3. Put the [V6 checkpoint](checkpoints/v6-unified-fullmix/anima-v6-unified-fullmix-e5-step45500-256area.safetensors)
   in `ComfyUI/models/diffusion_models/`.
4. From [`circlestone-labs/Anima`](https://huggingface.co/circlestone-labs/Anima),
   put `qwen_3_06b_base.safetensors` in `ComfyUI/models/text_encoders/` and
   `qwen_image_vae.safetensors` in `ComfyUI/models/vae/`.
5. Restart ComfyUI and load one of these UI workflows:
   - [T2I](comfyui/workflows/v6-fullmix/anima_v6_unified_t2i.json)
   - [single ref / slot 0](comfyui/workflows/v6-fullmix/anima_v6_unified_single_ref_slot0.json)
   - [multi ref](comfyui/workflows/v6-fullmix/anima_v6_unified_multi_ref.json)
   - [maskless Edit / slot 0 / scale 1.4](comfyui/workflows/v6-fullmix/anima_v6_unified_edit_slot0_scale140.json)

Machine-readable server graphs are in
[`comfyui/workflows/v6-fullmix/api/`](comfyui/workflows/v6-fullmix/api/).

The V6 nodes are `AnimaNativeRefV6Loader`, `AnimaNativeRefV6T2I`,
`AnimaNativeRefV6Generate1Ref`, `AnimaNativeRefV6Generate2Refs`, and
`AnimaNativeRefV6Edit`.  Edit has no mask, denoise, or denoise-strength socket.

## Sampling contract

The validated common preset is 30 steps, CFG 3.5, and flow shift 5.0.

- single/multi-reference: `native_reference_scale=1.0`;
- Edit balanced default: `1.4`;
- Edit stronger-change preset: `1.2`;
- Edit source-preservation preset: `1.5`;
- T2I: no reference branch at all.

Do not use 1.4 as a global default.  The Comfy runtime resets the scale on
every request so cached Edit state cannot leak into subsequent reference
generation.

## Real ComfyUI parity validation

The release package was imported inside the target ComfyUI environment, its
private vendored source manifest was verified, every UI/API workflow schema was
checked, and all four paths were executed with the final checkpoint.

- Edit at scale 1.4 reproduced the canonical CLI output pixel exactly:
  `max_abs=0`.
- Single-ref and multi-ref real Comfy invocations reproduced their canonical
  samples pixel exactly: `max_abs=0`.
- T2I loaded no references, supplied no visual tokens or edit mask, and the
  final checkpoint matched the M2 baseline exactly on the bypass test:
  `max_abs=0`.
- A deliberate Edit 1.4 → ref 1.0 sequence ended with model scale 1.0, proving
  per-call state isolation.

![V6 multi-reference evaluation](comfyui/examples/v6-fullmix/multi_ref_nspxt16_master.jpg)

![V6 single-reference evaluation](comfyui/examples/v6-fullmix/single_ref_ab8_master.png)

![V6 Edit scale calibration](comfyui/examples/v6-fullmix/edit_recommended_vs_default.png)

Full reports: [harvest report](release-metadata/v6-unified-fullmix/FINAL_HARVEST_REPORT.md),
[Edit calibration](release-metadata/v6-unified-fullmix/EDIT_INFERENCE_CALIBRATION.md),
and [Comfy validation](release-metadata/v6-unified-fullmix/COMFYUI_VALIDATION_REPORT.md).

## Architecture and text path

The checkpoint uses native source/reference VAE latent sequences, independent
visual slot/index/boundary encoding, read-only reference K/V, a competitive
text-to-slot router, an attribute router, and an implicit source-scope head.
Qwen3-0.6B provides raw prompt hidden states.  The "neutral T5" component in
Anima is a tokenizer/sequence-alignment target for the integrated `llm_adapter`;
no separate T5 encoder model is loaded.

## Limitations and intended use

- This is an experimental anime-oriented research model, not a production
  general-purpose photo editor.
- The quality claim is limited to 256-pixel nominal-area bucket training.
- Prompts that say only "use both images" may mix attributes; explicitly name
  Image 1/Image 2 and the property to obtain from each.
- Fine typography, exact object counts, hands, small faces, and unusual source
  domains may fail.
- Dataset targets are stochastic valid edits/references; pixel distance to a
  single target is not a complete semantic quality metric.

---

## Previous release documentation

The V4/V2 material below is retained unchanged for historical checkpoint
users.

# NOOB2 Project — Anima Native Reference V4 Scaled Mixture (49K)


**Anima Native Reference V4 Scaled Mixture 49K** is the latest integrated
research checkpoint in this repository. It extends the earlier two-reference
V2 E180 release with a text-slot competitive router and a mixed curriculum for:

- one-reference general image editing;
- one-reference anime-character generation;
- two-reference prompt-directed generation and editing.

Generation starts from pure noise. Reference images are encoded as native Anima
VAE latent sequences; they are not used as an img2img initialization canvas.
There is therefore no denoise-strength control. The reference route and router
weights are integrated into the diffusion checkpoint: no external LoRA,
IP-Adapter, or reference-adapter weight is required.

> **Research preview:** the dual-reference and anime single-reference paths are
> the strongest parts of this checkpoint. General editing is materially better
> than a wiring-only model, but exact object counts and fine local structure can
> still fail. Treat this as an experimental release rather than a production
> image editor.

## Latest V4 release

| Item | Value |
|---|---|
| Release name | Native Reference V4 Scaled Mixture 49K |
| Integrated checkpoint | `anima-v4-scaled-mix-50-30-20-e2-step49000-256area.safetensors` |
| Checkpoint path | `checkpoints/v4-scaled-49k/anima-v4-scaled-mix-50-30-20-e2-step49000-256area.safetensors` |
| Checkpoint SHA-256 | `4500a4aad657e0d8e821607afe050b09931f84bf601ea1447ce2a52cca782e2f` |
| Checkpoint bytes | `4302295014` |
| Optimizer updates | `49,000` |
| Epochs | `2` |
| Training geometry | 256-pixel nominal area with aspect-ratio buckets |
| Reference inputs | One or two ordered images |
| Generation path | Pure-noise image-conditioned generation |
| External adapter/LoRA | None |
| Primary interface | Updated ComfyUI custom nodes and UI/API workflows |
| Status | Experimental research preview |

The older V2 E180 checkpoint and its original workflows remain available under
`checkpoints/v2-e180/` and the historical V2 paths. They are not overwritten by
this release.

## What changed from V2 E180

V4 retains the integrated V2 native-reference latent/attention route, then adds
an integrated competitive text-slot router. For active references, the router
uses canonical prompt clauses aligned to the positive prompt's raw Qwen token
sequence. It can route one physical reference to logical slot 0 or slot 1 and
can route two ordered references independently.

For classifier-free guidance, the positive and negative denoising branches use
their own standard Anima text conditions, while both branches share the
positive prompt's router-only Qwen context, Qwen attention mask, and reference
clause masks. This split is required for the trained V4 checkpoint and is
implemented by the V4 runtime; a V2-only runtime is not compatible.

The two slots still have no permanently assigned scene, identity, pose, style,
foreground, or background roles. The prompt determines what should be taken
from each present image.

## Supported V4 reference layouts

| Present inputs | Logical slot IDs | Prompt requirement |
|---|---:|---|
| Reference Image 1 only | `[0]` | One canonical clause bound to `Image 1` |
| Reference Image 2 only | `[1]` | One canonical clause bound to `Image 2` |
| Both images | `[0, 1]` | Distinct canonical clauses for `Image 1` and `Image 2` |

The runtime must preserve the physical image-to-slot mapping exactly. A
single image connected to slot 1 must remain logical slot 1; it must not be
silently renumbered to slot 0.

### Single-reference prompt example

```text
Use Image 1 as the character identity reference. Generate the same character
in a new standing pose, wearing a dark school uniform, in a clean anime
illustration with detailed eyes.
```

### Two-reference prompt example

```text
Use Image 1 as the composition and pose reference. Use Image 2 as the character
identity and clothing reference. Generate a coherent new anime illustration
that follows the pose from Image 1 and the character from Image 2.
```

V4 competitive routing fails closed when references are present but the prompt
binding is missing, ambiguous, non-canonical, or truncated. The updated
ComfyUI nodes should surface that validation error rather than silently run an
unbound reference route.

## Training mixture

One 10-update task pattern was repeated with an exact `5:3:2` ratio:

| Task | Optimizer updates | Share | Training manifest |
|---|---:|---:|---:|
| General one-reference edit | 24,500 | 50% | 97,982 rows |
| Anime one-reference character generation | 14,700 | 30% | 58,700 rows |
| Ordered two-reference generation/edit | 9,800 | 20% | 10,127 transport rows / 5,408 logical groups |

The general-edit portion uses the selected GPT-Image-Edit data. The
single-reference character portion is derived from the recovered anime image
collection with exact-character grouping and within-label filtering. The
two-reference portion uses the GPT-generated LAXMAY subset. Flux-generated
targets were not used in this 49K run.

Single-reference samples were placed into logical slot 0 and slot 1 with exact
50/50 closure. Two-reference samples preserved their ordered `[0,1]` mapping.
The training run used batch size 8, BF16, two epochs, and 49,000 optimizer
updates on one NVIDIA RTX PRO 6000.

Only the integrated native-reference/router parameter set was trainable. The
postflight compared 688 frozen non-native tensors bit-for-bit against the warm
start and confirmed that they did not change.

## V4 ComfyUI assets

Install the updated package from:

```text
comfyui/releases/v0.2.0-v4-49k/
```

The new package must coexist with the legacy V2 class IDs so old workflows
continue to load. Use `AnimaNativeRefV4Loader` with `AnimaNativeRefV4Generate1Ref` or `AnimaNativeRefV4Generate2Refs` for the 49K checkpoint; the
legacy `AnimaNativeRefV2Loader` and `AnimaNativeRefV2Generate` nodes remain for
E180 only.

Validated workflows:

```text
comfyui/workflows/v4-49k/anima_ref_v4_final_single_slot0.json
comfyui/workflows/v4-49k/anima_ref_v4_final_single_slot1.json
comfyui/workflows/v4-49k/anima_ref_v4_final_dual.json
comfyui/workflows/v4-49k/api/anima_ref_v4_final_single_slot0_api.json
comfyui/workflows/v4-49k/api/anima_ref_v4_final_single_slot1_api.json
comfyui/workflows/v4-49k/api/anima_ref_v4_final_dual_api.json
```

### V4 quick start

1. Download the [ZIP](comfyui/releases/v0.2.0-v4-49k/ComfyUI-Anima-Native-Reference-v0.2.0-v4-49k.zip)
   or [tar.gz](comfyui/releases/v0.2.0-v4-49k/ComfyUI-Anima-Native-Reference-v0.2.0-v4-49k.tar.gz),
   then extract `ComfyUI-Anima-Native-Reference` to
   `ComfyUI/custom_nodes/ComfyUI-Anima-Native-Reference`.
2. With the Python interpreter used by ComfyUI, run
   `python -m pip install -r ComfyUI/custom_nodes/ComfyUI-Anima-Native-Reference/requirements.txt`.
3. Download the [V4 checkpoint](checkpoints/v4-scaled-49k/anima-v4-scaled-mix-50-30-20-e2-step49000-256area.safetensors) to
   `ComfyUI/models/diffusion_models/`; place `qwen_3_06b_base.safetensors`
   in `ComfyUI/models/text_encoders/` and `qwen_image_vae.safetensors` in
   `ComfyUI/models/vae/`.
4. Restart ComfyUI.
5. Load the matching UI workflow:
   [slot 0](comfyui/workflows/v4-49k/anima_ref_v4_final_single_slot0.json),
   [slot 1](comfyui/workflows/v4-49k/anima_ref_v4_final_single_slot1.json), or
   [dual reference](comfyui/workflows/v4-49k/anima_ref_v4_final_dual.json).
   Machine-readable graphs are in the
   [API workflow directory](comfyui/workflows/v4-49k/api/).

The official workflows set `verify_release_sha256=true`. The first load reads
and hashes the complete checkpoint, Qwen encoder, and VAE, so it incurs extra
one-time storage I/O before the cached runtime is ready.


Do not use the legacy V2-only runtime with the V4 checkpoint. That runtime
requires exactly two images and does not carry the raw-Qwen/source-mask/clause-
mask inputs required by the competitive router.

## V4 validated sampling preset

The checkpoint-time evaluation used:

| Setting | Value |
|---|---:|
| Output size | `256 × 256` |
| Denoising steps | `30` |
| CFG | `3.5` |
| Flow shift | `5.0` |
| Native reference scale | `1.0` |
| Maximum area per reference | `65,536` pixels |

The training data retained original source images and used online aspect-ratio
bucketing. The released quality claim is nevertheless limited to the
256-pixel nominal-area regime. Larger output sizes should be treated as
experimental until separately trained and evaluated.

## V4 qualitative progression

![V4 final training progression](comfyui/examples/v4-49k/final-quality-progression.png)

This board holds prompts and seeds fixed while showing the same training run at
steps 12.25K, 24.5K, 36.75K, and 49K. It is a within-run training progression,
not a cross-model A/B comparison.

## V4 limitations

- Exact object count and small local edit instructions may fail.
- Fine facial details, ornaments, hands, logos, and text may drift.
- Two references can still leak pose, clothing, background, or style into the
  wrong requested role.
- Multiple characters can cause identity mixing.
- The model can over-copy one reference or under-use the other.
- Output quality varies by seed and prompt phrasing.
- Photorealistic identity transfer is outside the primary target domain.
- This release does not guarantee exact reconstruction of a reference image.

---

## Legacy release: Anima Native Reference V2 (E180)


![cover-0721](https://cdn-uploads.huggingface.co/production/uploads/63d3a01ae149f591b950f5e8/CzXYAhk7i51-cgqo4pyru.png)

**Anima Native Reference V2 E180** is an experimental two-reference,
image-conditioned generation checkpoint developed as part of the
**NOOB2 Project — Character Reference Bypass Injector Research**.

The model generates a new anime illustration from pure noise while conditioning
on:

- a text prompt;
- Reference Image 1, assigned to ordered slot `0`;
- Reference Image 2, assigned to ordered slot `1`.

The two reference slots do not have permanently assigned scene, character,
identity, source, or style roles. Their order is preserved exactly, while the
prompt determines how the model should interpret and combine them.

The Native Reference V2 modules are already integrated into the E180 diffusion
checkpoint. No external LoRA, IP-Adapter, or separate reference-adapter weight
file is required.

> **Research preview:** This repository contains an experimental checkpoint,
> ComfyUI integration, reproducible workflows, and validation artifacts. It is
> not yet intended as a final production release.

## About the “Bypass Injector” Name

In this project, **bypass injector** refers to an auxiliary visual-conditioning
path that injects ordered reference features into the diffusion model through
its native reference sequence and reference-attention modules.

It does not refer to bypassing safety systems, content filters, platform
restrictions, or access controls.

## Release Information

| Item | Value |
|---|---|
| Model version | Native Reference V2 E180 |
| Base architecture | Anima |
| Integrated checkpoint | `anima-native-ref-v2-e180-step64080-256px.safetensors` |
| Checkpoint step | `64,080` |
| Training/validation bucket | 256-pixel-area buckets |
| Checkpoint size | `4,271,362,542` bytes |
| Reference inputs | Exactly two ordered images |
| Generation path | Pure-noise text-to-image generation |
| Primary interface | ComfyUI |
| Status | Experimental research preview |

## Key Properties

- One integrated Native Reference V2 diffusion checkpoint
- Two explicitly ordered reference-image inputs
- Prompt-defined reference semantics
- Pure-noise generation rather than img2img
- Native V2 reference-latent sequence
- Native V2 reference-attention route
- No denoise-strength control
- No external LoRA or reference-adapter weight
- No stock ComfyUI `KSampler` path
- UI and local `/prompt` API workflows included
- Bounded runtime, prompt-embedding, and reference-latent caches
- Optional release SHA-256 verification

## Model Architecture

This release uses the following integrated diffusion checkpoint:

```text
anima-native-ref-v2-e180-step64080-256px.safetensors
```

This file is the diffusion model used for generation. It replaces the stock
Anima diffusion-model checkpoint in this workflow.

**Do not load an additional stock Anima diffusion checkpoint alongside it.**

The following auxiliary Anima assets are still required:

```text
qwen_3_06b_base.safetensors
qwen_image_vae.safetensors
```

The complete runtime consists of:

```text
Integrated E180 Native Reference V2 DiT
+ Anima Qwen3-0.6B text encoder
+ Qwen-Image VAE
```

The two reference images are encoded by the VAE into two ordered reference
latent streams. These streams are supplied to the diffusion model through its
integrated Native Reference V2 sequence and reference-attention modules.

Generation starts from pure noise. The reference images are not used as an
initial denoising canvas.

Consequently:

- this is not a conventional img2img workflow;
- there is no denoise-strength parameter;
- the workflow does not use the stock ComfyUI `KSampler`;
- the workflow does not load an external LoRA;
- the workflow does not load an external IP-Adapter;
- the workflow does not load a separate learned reference adapter.

A custom inference plugin is still required because the standard Anima runtime
does not implement the additional Native Reference V2 modules contained in the
integrated checkpoint.

## Reference Semantics

![Workflow overview](comfyui/examples/anima_ref_v2_e180-workflow-thumbnail.jpg)
The two reference inputs are defined only by their order:

```text
Reference Image 1 → ordered slot 0
Reference Image 2 → ordered slot 1
```

The slots do not have hard-coded semantic roles.

They are not permanently defined as:

- scene and character;
- source and target;
- identity and style;
- foreground and background.

Instead, the prompt defines how the two references should be interpreted.

For example:

```text
Use the first image as the scene template and the second image as the
character template. Generate an edited result where the character matches
Image 2 and the scene remains faithful to Image 1.
```

A different prompt may assign entirely different roles to the same two ordered
slots.

The model preserves the input order, but the prompt determines the requested
relationship between the images.

## Included ComfyUI Nodes

The release contains two primary custom nodes.

| Node | Purpose |
|---|---|
| **Anima Reference V2 Loader (E180)** | Loads and caches the integrated E180 checkpoint, Anima Qwen3-0.6B text encoder, and Qwen-Image VAE. |
| **Anima Reference V2 Generate (2 Refs)** | Generates one image from a prompt and two explicitly ordered reference images. |

### Loader output

The Loader returns a custom pipeline object:

```text
ANIMA_NATIVE_REF_V2_PIPELINE
```

It does not expose conventional ComfyUI `MODEL`, `CLIP`, and `VAE` outputs.

### Generate inputs

The Generate node accepts:

- the loaded Native Reference V2 pipeline;
- Reference Image 1, ordered slot `0`;
- Reference Image 2, ordered slot `1`;
- positive prompt;
- negative prompt;
- seed;
- output width and height;
- sampling steps;
- CFG;
- flow shift;
- native reference scale;
- maximum preprocessing area for each reference.

The first release requires exactly two reference inputs.

Each input currently accepts exactly one image:

```text
IMAGE [1, H, W, 3]
```

Batched inputs with `B > 1` are rejected. For an animated or batched input,
select one frame first with `ImageFromBatch`.

## Repository Contents

```text
.
├── checkpoints/
│   └── v2-e180/
│       └── anima-native-ref-v2-e180-step64080-256px.safetensors
│
├── comfyui/
│   ├── custom_nodes/
│   │   └── ComfyUI-Anima-Native-Reference/
│   ├── examples/
│   │   ├── anima_ref_v2_e180-workflow-thumbnail.jpg
│   │   └── e180-heldout-000052-comfy-output.png
│   ├── releases/
│   │   └── v0.1.0-e180/
│   ├── workflows/
│   │   ├── anima_ref_v2_e180.json
│   │   └── anima_ref_v2_e180_api.json
│   ├── MANIFEST.json
│   ├── README.md
│   ├── SHA256SUMS
│   └── TEST_REPORT.md
│
├── .gitattributes
└── README.md
```

## Required Model Files

Place the required files in the following directories:

```text
ComfyUI/
└── models/
    ├── diffusion_models/
    │   └── anima-native-ref-v2-e180-step64080-256px.safetensors
    ├── text_encoders/
    │   └── qwen_3_06b_base.safetensors
    └── vae/
        └── qwen_image_vae.safetensors
```

### 1. Integrated E180 checkpoint

File:

```text
anima-native-ref-v2-e180-step64080-256px.safetensors
```

Repository path:

```text
checkpoints/v2-e180/anima-native-ref-v2-e180-step64080-256px.safetensors
```

Destination:

```text
ComfyUI/models/diffusion_models/
```

Size:

```text
4,271,362,542 bytes
```

SHA-256:

```text
1f970a7867dd7b65858d30b58135134ce84fd3b552ab27fc9f07e7f15209c6dd
```

This is the complete diffusion-model checkpoint used by the workflow.

Do not load a separate stock Anima diffusion checkpoint in addition to this
file.

### 2. Anima text encoder

File:

```text
qwen_3_06b_base.safetensors
```

Source:

[Anima text encoders](https://huggingface.co/circlestone-labs/Anima/tree/main/split_files/text_encoders)

Destination:

```text
ComfyUI/models/text_encoders/
```

Size:

```text
1,192,135,096 bytes
```

SHA-256:

```text
cd2a512003e2f9f3cd3c32a9c3573f820bb28c940f73c57b1ddaa983d9223eba
```

### 3. Qwen-Image VAE

File:

```text
qwen_image_vae.safetensors
```

Source:

[Anima VAE files](https://huggingface.co/circlestone-labs/Anima/tree/main/split_files/vae)

Destination:

```text
ComfyUI/models/vae/
```

Size:

```text
253,806,246 bytes
```

SHA-256:

```text
a70580f0213e67967ee9c95f05bb400e8fb08307e017a924bf3441223e023d1f
```

## Requirements

- A current ComfyUI installation
- Python 3.10 or newer
- NVIDIA CUDA GPU
- BF16 support
- Sufficient system RAM for the cached runtime
- The exact E180, Qwen, and VAE files listed above

The first release deliberately validates the expected checkpoint layouts
instead of silently loading similarly named but incompatible files.

## Installation

### 1. Install the custom node

Copy:

```text
comfyui/custom_nodes/ComfyUI-Anima-Native-Reference/
```

into:

```text
ComfyUI/custom_nodes/ComfyUI-Anima-Native-Reference/
```

Alternatively, use one of the packaged releases under:

```text
comfyui/releases/v0.1.0-e180/
```

### 2. Install dependencies

Use the same Python interpreter that starts ComfyUI:

```bash
cd ComfyUI/custom_nodes/ComfyUI-Anima-Native-Reference
python -m pip install -r requirements.txt
```

The package does not pin or install PyTorch.

Do not replace an existing working ComfyUI CUDA installation of `torch` or
`torchvision`.

### 3. Restart ComfyUI

Restart ComfyUI after installing the custom node and dependencies.

## Workflows

### Standard ComfyUI workflow

Load:

```text
comfyui/workflows/anima_ref_v2_e180.json
```

### Local API workflow

Use:

```text
comfyui/workflows/anima_ref_v2_e180_api.json
```

The UI workflow and API workflow use different ComfyUI JSON formats. They
should not be treated as interchangeable files.

## Basic Usage

1. Install the custom node and restart ComfyUI.
2. Place the integrated E180 checkpoint in `models/diffusion_models/`.
3. Place Qwen3-0.6B in `models/text_encoders/`.
4. Place the Qwen-Image VAE in `models/vae/`.
5. Load the provided standard ComfyUI workflow.
6. Select one image in the Reference Image 1 node.
7. Select one image in the Reference Image 2 node.
8. Write a prompt that explicitly describes how the two references should be
   used.
9. Select the validated generation settings.
10. Queue the workflow.

Do not load a separate Anima base diffusion model. The integrated E180
checkpoint is the diffusion model used by this workflow.

## Prompt Examples

### General two-reference generation

```text
Create a new anime illustration using both reference images. Preserve the
relevant visual information from Reference Image 1 and Reference Image 2 while
following this instruction: show the referenced character in a coherent new
composition with clean anime rendering and detailed eyes.
```

### Scene from Image 1 and character from Image 2

```text
Use the first image as the scene template and the second image as the
character template. Generate an edited result where the character matches
Image 2 and the scene remains faithful to Image 1.
```

### Character design from both references

```text
Create a new anime illustration that combines the character identity and
costume details shown across both reference images. Preserve the most
recognizable facial features, hairstyle, colors, and accessories while
placing the character in a new full-body composition.
```

These prompts are examples only. They do not permanently assign semantic roles
to either reference slot.

## Validated Settings

| Setting | Value |
|---|---:|
| Output size | `256 × 256` |
| Steps | `40` |
| CFG | `1.0` |
| Flow shift | `5.0` |
| Native reference scale | `1.0` |
| Maximum area per reference | `65,536` pixels |
| Ordered slot IDs | `[0, 1]` |
| Attention mode | `torch` |
| Default offload mode | `balanced` |

The checkpoint was trained and validated with 256-pixel-area buckets.

Larger dimensions that are multiples of 16 are accepted by the current
implementation, but they should be treated as experimental rather than as a
validated quality guarantee.

## Memory Modes

| Mode | Behavior |
|---|---|
| `balanced` | Keeps the DiT on the GPU and moves Qwen and the VAE to the GPU only during their respective phases. |
| `high_vram` | Keeps the DiT, Qwen, and VAE on the GPU for faster repeated generation. |
| `text_encoder_cpu` | Runs text encoding on the CPU as a slower fallback for constrained GPU memory. |

The plugin maintains bounded caches for:

- loaded model runtimes;
- prompt embeddings;
- preprocessed reference latents.

Changing the prompt, seed, reference images, or sampling settings does not
normally require reading the 4.27 GB checkpoint from disk again.

## Verified Held-Out Output

![Verified held-out output](comfyui/examples/e180-heldout-000052-comfy-output.png)

The image above is the generated-only result for held-out integration case
`000052`.

Prompt:

```text
Use the first image as the scene template and the second image as the
character template. Generate an edited result where the character matches
Image 2 and the scene remains faithful to Image 1.
```

Generation settings:

| Setting | Value |
|---|---:|
| Seed | `20260720` |
| Resolution | `256 × 256` |
| Steps | `40` |
| CFG | `1.0` |
| Flow shift | `5.0` |
| Native reference scale | `1.0` |
| Reference maximum area | `65,536` |
| Ordered slots | `[0, 1]` |

The release package contains the generated frame rather than a combined
Reference 1 / Reference 2 / Generated comparison sheet.

It should therefore be interpreted as a verified integration and
reproducibility artifact, not as a complete standalone qualitative comparison.

## Integration Verification

The packaged runtime was validated using the exact release files on an
NVIDIA RTX PRO 6000 Blackwell.

The validation covered:

- loading the complete integrated E180 checkpoint;
- loading the Qwen3-0.6B text encoder;
- loading the Qwen-Image VAE;
- two-reference pure-noise generation;
- fixed ordered slots `[0, 1]`;
- the native V2 reference sequence;
- the native V2 reference-attention route;
- prompt and reference-latent caching;
- repeated runtime reuse;
- UI workflow schema validation;
- local `/prompt` API execution;
- generated-image saving;
- Unicode Chinese and Japanese prompt preservation.

The generated ComfyUI output for held-out case `000052` was pixel-identical to
the accepted native command-line result when decoded to RGB pixels:

```text
Maximum absolute pixel difference: 0
Mean absolute pixel difference:    0
Nonzero channel values:            0
```

Pixel SHA-256:

```text
20ba2661e8667bea3448c05021d5694d470474f7d39105ef1ee54096c394d04f
```

These results verify runtime and workflow parity. They should not be
interpreted as a comprehensive benchmark of character-reference quality.

## Intended Uses

This release is intended for research and experimental creative workflows
involving:

- anime character-reference conditioning;
- two-reference character and scene composition;
- character appearance transfer;
- costume and accessory reference;
- prompt-controlled changes to pose and composition;
- visual-development workflows;
- evaluation of native multi-reference conditioning;
- research into alternatives to per-character LoRA training;
- development and testing of Anima Native Reference V2 inference.

## Out-of-Scope Uses

This release is not designed to guarantee:

- exact identity reconstruction;
- biometric identification;
- exact face replication;
- reliable photorealistic identity transfer;
- exact reproduction of small accessories;
- exact reproduction of complex clothing;
- reliable multi-character identity assignment;
- accurate text or logo rendering;
- unrestricted production deployment;
- compatibility with arbitrary Anima checkpoints;
- compatibility with unrelated diffusion architectures.

## Known Limitations

- Exactly two reference inputs are supported.
- Each reference input currently accepts one image only.
- Reference slots are ordered but have no automatically inferred semantic
  roles.
- The release accepts the exact E180 Native Reference V2 model layout.
- Arbitrary stock Anima or future Native Reference checkpoints are not
  automatically supported.
- CUDA BF16 is required by the initial release.
- The plugin does not expose the conventional ComfyUI
  `MODEL / CLIP / VAE / KSampler` workflow path.
- The trained and validated output scale is based on 256-pixel-area buckets.
- Larger outputs remain experimental.
- Fine facial features may drift.
- Hair ornaments and small accessories may be changed or omitted.
- Clothing information from the two references may become mixed.
- Complex backgrounds may leak into the generated image.
- Extreme poses or camera angles may reduce character consistency.
- Multiple characters may lead to identity mixing.
- The generated composition may over-copy one of the references.
- Output quality may vary between random seeds.
- Photorealistic references are outside the primary target domain.
- The model does not guarantee exact reconstruction of either reference.

## Responsible Use

Only use reference images that you own or are authorized to use.

Do not use this model to:

- impersonate real people;
- misrepresent generated content as authentic evidence;
- harass or defame individuals;
- violate privacy or publicity rights;
- reproduce private or sensitive imagery without permission;
- infringe copyright or contractual restrictions;
- create illegal or exploitative content.

This model is not a safety classifier and does not guarantee that generated
outputs will be appropriate, accurate, or lawful.

Users are responsible for applying suitable content moderation, human review,
and access controls in downstream applications.

## Runtime Provenance

The Native Reference V2 inference implementation includes a pinned and
namespaced runtime snapshot derived in part from:

[akatsuki-neo/anima-edit](https://github.com/akatsuki-neo/anima-edit.git)

Audited source commit:

```text
2ae811d296ff4159c6024c4a86415d19961a388c
```

The vendored runtime:

- contains no model weights;
- uses a private namespace to avoid collisions with other custom nodes;
- retains upstream provenance and licensing information;
- is verified against a per-file integrity manifest before import.

## License

### Integrated Model Checkpoint

The integrated E180 checkpoint is distributed separately from the custom-node
source code.

Its use remains subject to:

- the terms published with this repository;
- the applicable terms of the underlying Anima model and assets;
- the repository access conditions;
- any other applicable third-party licenses.

Access to the gated repository does not grant rights beyond the applicable
license terms.

Users should review the current upstream and repository licenses before:

- redistributing the checkpoint;
- creating or distributing derivative models;
- hosting a public inference service;
- using the model commercially.

### Required Anima Assets

The Qwen3 text encoder and Qwen-Image VAE are downloaded from the Anima
repository and remain subject to their corresponding upstream terms.

### Custom Node and Runtime Code

The packaged ComfyUI integration and its vendored inference-source components
are provided under the licenses included in their respective `LICENSE` files.

The included runtime source retains the Apache-2.0 license and upstream
attribution where applicable.

A software license applying to the inference code does not override the
license governing the model checkpoint or required upstream model assets.

## Access and Integrity

The model repository may require users to:

- sign in to Hugging Face;
- accept the repository access conditions;
- provide the information requested by the repository owner.

Keep Hugging Face access tokens outside workflow JSON files and scripts.

Checksum files are included for validating release artifacts:

```text
comfyui/SHA256SUMS
comfyui/custom_nodes/ComfyUI-Anima-Native-Reference/SHA256SUMS
comfyui/releases/v0.1.0-e180/SHA256SUMS
comfyui/releases/v0.2.0-v4-49k/SHA256SUMS
```

Verify downloaded files before installation or redistribution.

## Acknowledgements

This project was made possible through the contributions of many developers,
researchers, and testers.

- **Yidhar** and **Nebulae** contributed to model training and dataset
  development.
- **spawner** provided important inspiration and portions of the code through
  the [`akatsuki-neo/anima-edit`](https://github.com/akatsuki-neo/anima-edit.git)
  project.
- **potato** contributed to the early development of the project.
- **GHOSTLXH**, **年糕特工队**, **轻松**, **Free Will**, and **韩小强**
  contributed testing, feedback, and early validation.

We also thank **CircleStone Labs** and **Comfy Org** for the development and
release of Anima, and the broader **ComfyUI** developer community for the
inference framework and ecosystem.

**Special thanks to Comfy.org for providing GPU sponsorship.**

## Project Credits

- Project: **NOOB2 Project**
- Model and integration release: **LAXMAYDAY / Laxhar Lab**
- Base architecture: **Anima**
- Primary interface: **ComfyUI**

## Citation

```bibtex
@misc{noob2_anima_native_reference_v2_2026,
  title        = {NOOB2 Project: Anima Native Reference V2 E180},
  author       = {LAXMAYDAY and Laxhar Lab},
  year         = {2026},
  howpublished = {Hugging Face model repository},
  note         = {Experimental two-reference native-conditioning checkpoint for Anima}
}
```

## Changelog

### v0.2.0-v4-49k

- Added the integrated V4 Scaled Mixture 49K checkpoint.
- Added one-reference slot-0 and slot-1 generation nodes.
- Added prompt-directed dual-reference competitive routing.
- Added three UI workflows and three `/prompt` API workflows.
- Retained the V2 E180 checkpoint, class IDs, workflows, and release.

### v0.1.0-e180

- Released the integrated Native Reference V2 E180 checkpoint.
- Added two explicitly ordered reference-image inputs.
- Added prompt-defined reference semantics.
- Added the Native Reference V2 Loader node.
- Added the Native Reference V2 Generate node.
- Added the standard ComfyUI workflow.
- Added the local `/prompt` API workflow.
- Added balanced, high-VRAM, and CPU text-encoder modes.
- Added bounded runtime and conditioning caches.
- Added fail-closed checkpoint-layout validation.
- Added optional release SHA-256 verification.
- Added runtime and workflow validation tests.
- Added a verified held-out generated output.
- Added pixel-exact comparison against the accepted native CLI result.
- Added manifests, provenance records, and release checksums.

## V6 512 fullmix (e2 / step19688)

The V6 unified fullmix checkpoint trained with 512 resolution buckets is available here:

- [Checkpoint](checkpoints/v6-unified-fullmix-512/anima-v6-unified-fullmix-e2-step19688-512area.safetensors)
- [Release metadata](release-metadata/v6-unified-fullmix-512/README.md)
- [ComfyUI 512 workflows](comfyui/workflows/v6-fullmix-512/)

This is a 2-epoch / 19,688-update native source/reference routing model.