Image-to-Image
Diffusers
Safetensors
MiniMax H3
English
character-swap
image-editing
lora-merge
ml-intern
Instructions to use akhaliq/MiniMax-H3-Image-Character-Swap with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Diffusers
How to use akhaliq/MiniMax-H3-Image-Character-Swap with Diffusers:
pip install -U diffusers transformers accelerate
import torch from diffusers import DiffusionPipeline from diffusers.utils import load_image # switch to "mps" for apple devices pipe = DiffusionPipeline.from_pretrained("akhaliq/MiniMax-H3-Image-Character-Swap", dtype=torch.bfloat16, device_map="cuda") prompt = "Turn this cat into a dog" input_image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png") image = pipe(image=input_image, prompt=prompt).images[0] - Notebooks
- Google Colab
- Kaggle
Add FAQ (need-a-LoRA, standalone adapter files, gaze, commercial terms)
Browse files
README.md
CHANGED
|
@@ -75,6 +75,49 @@ outfit detail.
|
|
| 75 |
|
| 76 |
Full test set (8 hard cases: profile, small face, occlusion, full-body, group): [akhaliq/h3-image-swap-tests](https://huggingface.co/datasets/akhaliq/h3-image-swap-tests).
|
| 77 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 78 |
## ComfyUI
|
| 79 |
|
| 80 |
One file, no LoRA nodes, no adapters — character swap is built into the checkpoint itself.
|
|
@@ -110,6 +153,7 @@ character-swap built in. Fusion provenance: [`comfyui/minimax_h3_image_character
|
|
| 110 |
|
| 111 |
Because the adapter is fused in, there is nothing else to install: no LoRA node, no strength to
|
| 112 |
tune — every image you edit with this checkpoint has character swap built in.
|
|
|
|
| 113 |
|
| 114 |
*Note: end-to-end runs on this page were validated through the diffusers pipeline; the ComfyUI
|
| 115 |
checkpoint is the identical math in Comfy's own layout. Report any ComfyUI-specific surprises in
|
|
@@ -177,6 +221,8 @@ on one H200. The merged DiT is a drop-in replacement anywhere
|
|
| 177 |
|
| 178 |
- The LoRA was trained for **video** character swap (on Ref2VA, 24 fps clips); the port to images
|
| 179 |
is validated on 8 hard cases, not a broad benchmark. Report surprises in the discussions tab.
|
|
|
|
|
|
|
| 180 |
- Like the base model, it can drift on extreme poses, heavy occlusion, or very small faces.
|
| 181 |
- The character-swap LoRA is an experimental community model; identity fidelity varies with the
|
| 182 |
reference quality (a clean, multi-view character sheet works best).
|
|
|
|
| 75 |
|
| 76 |
Full test set (8 hard cases: profile, small face, occlusion, full-body, group): [akhaliq/h3-image-swap-tests](https://huggingface.co/datasets/akhaliq/h3-image-swap-tests).
|
| 77 |
|
| 78 |
+
## FAQ
|
| 79 |
+
|
| 80 |
+
**“Do you even need a LoRA for this? Doesn't H3-Image do swaps with the right prompt?”**
|
| 81 |
+
Often, yes — that was our first test too. Native H3-Image passes 7 of 8 hard cases (profile faces,
|
| 82 |
+
occlusion, small faces, full-body, group scenes) with a good prompt. It fails *systematically* on
|
| 83 |
+
cross-style swaps onto non-frontal faces: anime character → strict-profile photo failed on 3/3
|
| 84 |
+
seeds (a hybrid face, the character printed into a prop, and the swap ignored). That case — plus
|
| 85 |
+
tighter identity fidelity overall — is what this checkpoint adds. If your swaps are frontal and
|
| 86 |
+
photoreal, try the stock model with our prompt template first; if you hit its edge cases, this is
|
| 87 |
+
for you.
|
| 88 |
+
|
| 89 |
+
**“Where's the LoRA? Why is the ‘LoRA’ 40 GB?”**
|
| 90 |
+
It isn't a 40 GB adapter — this repo is the adapter *fused into* the full checkpoint (same size as
|
| 91 |
+
Comfy-Org's stock DiT), so there's one file and nothing to configure. If you want the 155 MB
|
| 92 |
+
adapter by itself:
|
| 93 |
+
|
| 94 |
+
| File | Layout | Use |
|
| 95 |
+
| --- | --- | --- |
|
| 96 |
+
| [`lora/h3_character_swap_v1.5.safetensors`](lora/h3_character_swap_v1.5.safetensors) (155 MB) | ComfyUI (akatz's original, unchanged) | `models/loras/` + **LoraLoaderModelOnly** @ strength 1.0 on the stock H3-Image DiT — all 208 targets verified to match |
|
| 97 |
+
| [`lora/h3_image_character_swap_diffusers.safetensors`](lora/h3_image_character_swap_diffusers.safetensors) (173 MB) | diffusers | `transformer.load_lora_adapter(state_dict, prefix=None)` for strength control |
|
| 98 |
+
|
| 99 |
+
No extraction needed — the merged checkpoint is exactly `W + B·A` of these adapters.
|
| 100 |
+
|
| 101 |
+
**“In some examples the character looks the wrong way.”**
|
| 102 |
+
That's the design, not a bug: a swap follows the *source* person's pose, position and gaze (it's
|
| 103 |
+
what makes it a swap instead of a paste). The model re-renders the reference character facing the
|
| 104 |
+
source's way; on extreme profile/cross-style combos that re-render can look off. Rephrase the
|
| 105 |
+
“same pose, position, scale and gaze” part of the prompt if you'd rather follow the reference's
|
| 106 |
+
orientation.
|
| 107 |
+
|
| 108 |
+
**“Can I use it commercially?”**
|
| 109 |
+
The checkpoint is under the [MiniMax-H3-Image Community License](LICENSE). Free, including
|
| 110 |
+
commercial use, in the Applicable Territory — which is worldwide **except the EU, UK, South Korea
|
| 111 |
+
and the USA**. Two triggers require MiniMax's prior written authorization (apply
|
| 112 |
+
[here](https://platform.minimax.io/console/license)): annualized revenue above **$1M**, or
|
| 113 |
+
providing it as a **hosted service** to third parties. In the excluded territories the community
|
| 114 |
+
license grants no rights — contact MiniMax. MiniMax claims no rights over your outputs. (This is a
|
| 115 |
+
summary, not legal advice — read the LICENSE.)
|
| 116 |
+
|
| 117 |
+
**“What prompt should I use?”**
|
| 118 |
+
See [Prompting tips](#comfyui) — scene as `<Picture 1>`, character as `<Picture 2>`, name the
|
| 119 |
+
person, and say what to preserve.
|
| 120 |
+
|
| 121 |
## ComfyUI
|
| 122 |
|
| 123 |
One file, no LoRA nodes, no adapters — character swap is built into the checkpoint itself.
|
|
|
|
| 153 |
|
| 154 |
Because the adapter is fused in, there is nothing else to install: no LoRA node, no strength to
|
| 155 |
tune — every image you edit with this checkpoint has character swap built in.
|
| 156 |
+
(Prefer the 155 MB adapter by itself with strength control? See [the FAQ](#faq) — it's in [`lora/`](lora/).)
|
| 157 |
|
| 158 |
*Note: end-to-end runs on this page were validated through the diffusers pipeline; the ComfyUI
|
| 159 |
checkpoint is the identical math in Comfy's own layout. Report any ComfyUI-specific surprises in
|
|
|
|
| 221 |
|
| 222 |
- The LoRA was trained for **video** character swap (on Ref2VA, 24 fps clips); the port to images
|
| 223 |
is validated on 8 hard cases, not a broad benchmark. Report surprises in the discussions tab.
|
| 224 |
+
- Swaps follow the source person's pose and gaze by design; on extreme profile/cross-style combos
|
| 225 |
+
the re-rendered viewing direction can look off — tune the pose/gaze phrase in the prompt.
|
| 226 |
- Like the base model, it can drift on extreme poses, heavy occlusion, or very small faces.
|
| 227 |
- The character-swap LoRA is an experimental community model; identity fidelity varies with the
|
| 228 |
reference quality (a clean, multi-view character sheet works best).
|