yijunwang2/krea2-reid

Krea 2 ReID Reference

Important: The Hugging Face auto-generated Diffusers snippet and ordinary style-LoRA workflows are not compatible with this functional adapter. For Python, use the included example.py and pipeline.py. For ComfyUI, use the included official workflow with the required Ostris custom nodes and keep reference K/V caching enabled.

This rank-32 LoRA uses one image as an identity reference while allowing the prompt to change clothing, pose, composition, and background. It works with both photorealistic and illustrated subjects. The adapter was trained against Krea 2 Raw and is intended for distilled 8-step inference with Krea 2 Turbo.

The adapter is deliberately different from a reconstruction or general edit model. Its goal is to retain stable identity features without copying every source-image detail. A close face or head-and-shoulders crop usually gives the prompt more freedom than a full-body reference.

The included pipeline is the pinned ostris/Krea2OstrisEdit reference pipeline used by this adapter.

Files

krea2_reid_rank32.safetensors  LoRA weights
pipeline.py                    Pinned Krea 2 reference pipeline
face_crop.py                   Optional YuNet reference-crop helper
models/face_detection_*.onnx   Bundled YuNet INT8 detector
example.py                     Minimal local example
LICENSE.pdf                    Krea 2 Community License
PIPELINE_LICENSE               Apache-2.0 license for pipeline/example code
COMFYUI_WORKFLOW_LICENSE       MIT license for the adapted ComfyUI graph
YUNET_LICENSE                  MIT license for YuNet
NOTICE                         attribution and derivative-work notice
SHA256SUMS                     release artifact hashes
showcase/                      fully synthetic reference/output examples
workflow/krea2_reid_comfyui.json  Official ComfyUI workflow

Tested capabilities

This release has been tested on:

• photorealistic and illustrated subjects;
• close portrait references driving three-quarter and full-body outputs;
• square references driving portrait outputs;
• substantial clothing, pose, framing, lighting, and background changes;
• distilled 8-step Krea 2 Turbo inference with reference K/V caching.

All people and characters shown below are fully synthetic images generated for this release. They do not depict a real person or an existing character IP. Each source and result is the first 8-step output from its preselected prompt and fixed seed (17072026 through 17072032); no rerolls or weaker candidates were removed from these showcase groups.

Photorealistic identity across clothing and scene changes

Synthetic reference	Red suit / glass gallery	Winter coat / city street

Illustrated identity across costume and composition changes

Synthetic reference	White-and-gold dress / conservatory

Stylized 3D identity across framing and environment changes

Synthetic reference	Exploration suit / alien desert

Input contract

The model takes exactly one RGB reference image and a prompt describing the desired output. The output aspect ratio is independent from the reference.

Both reference-conditioning routes are required:

1. Qwen3-VL image conditioning in the prompt embedding.
2. Clean reference VAE tokens appended through the edit pipeline.

The adapter was trained with isolated reference attention. kv_cache=True therefore belongs to the model contract: it precomputes the reference K/V once and reuses it through all denoising steps.

For best prompt control, crop the reference around the face, hair, and a modest amount of upper body. Full-body references can preserve clothing or pose more strongly. The example limits reference conditioning to a 384 * 384 pixel budget without changing its aspect ratio.

Optional automatic face crop

YuNet is not part of the LoRA and is not required by the reference pipeline. You may pass any prepared reference image directly. Automatic cropping is provided only as a convenient default for users who primarily want to preserve the subject's face while giving the prompt more freedom over clothing, pose, and composition.

The included example runs the bundled YuNet INT8 detector on a 320x320 view, selects the highest-confidence face at a 0.35 threshold, maps that box back to the original image, and builds a larger head crop around it. Detection and cropping do not reduce the source image before the final crop is taken. If no face passes the threshold, the original image is used unchanged.

This preprocessing is a recommendation, not a model requirement. Keep the full reference when clothing, body shape, pose, or surrounding context should remain influential. Pass --no-face-crop when the reference is already prepared or automatic cropping is undesirable.

Recommended settings

Setting	Value
Base	krea/Krea-2-Turbo
Steps	8
Guidance scale	0.0
LoRA scale	1.0
Reference pixel budget	384 * 384
Reference VLM encoding	enabled
Reference K/V cache	enabled
ComfyUI diffusion precision	Comfy-Org INT8 ConvRot

LoRA scale 1.0 is the tested default. Lower values relax identity retention; higher values can overconstrain the image and are not the primary tested path.

Usage

Install a current PyTorch build for your GPU, then install the dependencies:

pip install -U diffusers transformers accelerate safetensors huggingface_hub pillow opencv-python-headless

Run the included example after downloading this repository:

python example.py \
  --reference character.png \
  --output result.png \
  --prompt "a polished digital illustration of the character, full body, wearing a black suit, standing on a city street"

The example enables the optional face crop by default. To inspect exactly what the pipeline receives, add --save-reference-crop prepared_reference.png. To use the input image unchanged:

python example.py \
  --reference character.png \
  --no-face-crop \
  --output result.png \
  --prompt "a polished digital illustration of the character, full body, wearing a black suit, standing on a city street"

The default BF16 example enables model CPU offload. Systems with enough VRAM may pass --full-gpu. Quantized Krea 2 runtimes may also load the LoRA, but quantization setup is runtime-specific and is not bundled here.

ComfyUI

The official workflow is workflow/krea2_reid_comfyui.json. It uses the MIT-licensed ostris/ComfyUI-Krea2-Ostris-Edit custom nodes, which implement the clean VAE reference-token path, Qwen3-VL image conditioning, isolated reference attention, and cached reference K/V required by this adapter.

Install the custom nodes and restart ComfyUI:

cd ComfyUI/custom_nodes
git clone https://github.com/ostris/ComfyUI-Krea2-Ostris-Edit.git
cd ComfyUI-Krea2-Ostris-Edit
git checkout 7756566160c4a1b24bb1bd9f0ff3ced1a83d7547

Download the standard ComfyUI Krea 2 components from Comfy-Org/Krea-2 and place them as follows:

ComfyUI/models/diffusion_models/krea2_turbo_int8_convrot.safetensors
ComfyUI/models/text_encoders/qwen3vl_4b_bf16.safetensors
ComfyUI/models/vae/qwen_image_vae.safetensors
ComfyUI/models/loras/krea2_reid_rank32.safetensors

Import the JSON workflow, select one prepared reference image, enter the desired output prompt, and queue the graph. The target width and height on the Empty Latent Image node are independent from the reference dimensions. The graph defaults to the official Comfy-Org INT8 ConvRot Krea 2 Turbo checkpoint at 1024x1024. This exact ComfyUI path was validated end to end on an RTX 5090 with the included LoRA and workflow settings. The repository's application runtime uses a separately packaged INT8 ConvRot checkpoint; do not substitute that internal file because stock ComfyUI expects the Comfy-Org quantization format.

BF16 remains a valid fallback, but 1024x1024 BF16 plus Qwen3-VL and reference K/V exceeded 31.35 GiB in the tested stock ComfyUI runtime. If using BF16, start at 512x512 or configure additional model offload.

Do not copy settings from a generic Krea 2 edit workflow. The tested contract is already preset in the included graph:

ComfyUI setting	Required/tested value
LoRA strength	1.0
Krea 2 Ostris Edit kv_cache	true
Steps	8
CFG	1.0
Sampler / scheduler	euler / simple
Prepared reference budget	384 * 384 total pixels
Diffusion checkpoint	krea2_turbo_int8_convrot.safetensors

ComfyUI CFG 1.0 is the no-CFG path corresponding to Diffusers guidance_scale=0.0. The workflow scales the prepared reference to the tested pixel budget. For maximum freedom over outfit and pose, prepare a close face or head-and-shoulders crop before loading it. The bundled automatic YuNet crop is currently part of the Python example, not the ComfyUI graph.

How it works

The target starts from normal Krea 2 flow-matching noise. The reference image is encoded by Qwen3-VL for high-level visual context and by the Qwen-Image VAE as a separate clean token sequence at flow time zero. The LoRA was trained with paired same-identity references. This teaches the reference path to preserve identity while releasing source-specific pose, clothing, framing, and background.

With isolated reference attention, reference tokens attend to one another and their per-block K/V is independent of the noisy target. The pipeline computes that K/V once and injects it at every denoising step.

Responsible use

Use reference images only when you have the subject's consent or another lawful basis to use them.

Do not use this model for deceptive impersonation, fraud, harassment, non-consensual intimate imagery, biometric identification, or misleading political or media content.

Deployments must comply with the Krea 2 Community License and Acceptable Use Policy, implement appropriate content moderation, and disclose AI-generated content where required.

Limitations

• A full-body or costume-heavy reference may still transfer clothing and pose.
• A very tight crop can omit identity-defining accessories or hair details.
• Similar-looking characters and heavily occluded faces can be confused.
• Identity retention varies with prompt, seed, crop, and stacked LoRAs.
• Fine facial age, skin texture, or makeup can drift under large scene and lighting changes in photorealistic outputs.
• The model does not guarantee biometric identity and is not a face-recognition system.
• The included BF16 example is provided as a portable reference path; the reported performance measurement below is from the tested INT8 runtime.

Training summary

The adapter is a transformer-only LoRA with rank/alpha 32/32. Training used paired images of the same identity, one reference per sample, Qwen3-VL image conditioning, clean VAE reference tokens, and isolated reference attention. The final candidate is the 25,600-step checkpoint. Training data and training infrastructure are not distributed.

In the tested INT8 ConvRot Krea 2 Turbo runtime on an RTX 5090, 1024x1024 8-step inference took approximately 4.55 seconds for the final checkpoint. This is an implementation- and hardware-specific measurement, not a BF16 benchmark claim.

License

The LoRA weights are a derivative of Krea 2 and are released under the Krea 2 Community License in LICENSE.pdf. The pinned pipeline and example code are distributed under Apache-2.0 in PIPELINE_LICENSE. This is an unofficial community release and is not endorsed by Krea or Ostris. The optional YuNet detector is distributed under its MIT license in YUNET_LICENSE. Use, modification, and distribution of the model weights are subject to the included Krea 2 Community License Agreement.