yijunwang2/krea2-reid

Krea 2 ReID Reference

Important: The Hugging Face auto-generated Diffusers snippet and ordinary LoRA importers are not compatible with this functional adapter. Use the included example.py and pipeline.py instead.

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
YUNET_LICENSE                  MIT license for YuNet
NOTICE                         attribution and derivative-work notice
SHA256SUMS                     release artifact hashes
showcase/                      fully synthetic reference/output examples

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

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.

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.