How to use from the
Use from the
Diffusers library
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]

MiniMax-H3-Image ยท Character Swap

Character swap on images, merged and ready. This repo is MiniMaxAI/MiniMax-H3-Image with akatz-ai/MiniMax-H3-Character-Swap-LoRA fused directly into the image DiT โ€” the first merged checkpoint that ports the video-trained character-swap adapter onto the H3 image model. No LoRA files, no key remapping, no ComfyUI graph: load the pipeline and swap.

Feed it a scene photo as <Picture 1> and a character reference as <Picture 2>, name who to replace, and it swaps the person while preserving the background, the lighting, the other people and the pose โ€” including cross-style swaps (anime/illustrated character โ†’ photoreal scene) that the base image model fails on.

Showcase

Original scene (<Picture 1>) ยท character reference (<Picture 2>) ยท character swap โ€” all single-seed, straight out of the merged model.

Anime character swapped into a side-profile bookstore scene โ€” the case native H3-Image fails on every seed

Photoreal hiker character swapped into a cafรฉ conversation

Anime character swapped into a full-body jogging scene

The case that motivated this repo

Native MiniMax-H3-Image is a strong multi-reference editor, but it systematically fails cross-style swaps onto non-frontal faces: given an anime character and a strict side-profile photo, it kept the original face on 3 out of 3 seeds (producing a hybrid, pasting the character into the newspaper, or ignoring the swap). And even where native appears to succeed, it drifts โ€” skin tones lighten, poses change, outfit details wander (see the comparisons below). The merged model nails the hard case on the same seed and holds the details everywhere else:

Scene (<Picture 1>) Character (<Picture 2>) Native H3-Image This model
scene character โŒ kept the source face โœ…
native fail merged

More swaps (native vs merged, same seed)

Photoreal character โ†’ cafรฉ scene. Native drifts โ€” the swapped woman's skin tone comes out visibly lighter than the reference. The merged model keeps her identity.

Scene Native Merged
scene native merged

Anime character โ†’ full-body scene. Native changes the pose โ€” the jog becomes a standing hand-in-pocket. The merged version keeps the stride and the reference outfit detail.

Scene Native Merged
scene native merged

Full test set (8 hard cases: profile, small face, occlusion, full-body, group): akhaliq/h3-image-swap-tests.

Three-way labeled comparison (native vs standalone LoRA vs merged). 6 scenes x 2 characters x 3 seeds, same prompt, 4 MP each โ€” 17 scored comparisons. The merged checkpoint was preferred in 14/17 (82%), the standalone LoRA in 2, native H3-Image in 1. Single labeler, so read it as a strong preference signal rather than a benchmark; the full grid (scene + reference + all three outputs, every seed) is public in akhaliq/h3-image-swap-tests (blind-v1/, blind-v2/).

FAQ

โ€œDo you even need a LoRA for this? Doesn't H3-Image do swaps with the right prompt?โ€ It produces something plausible on most cases โ€” but look closely. In 17 labeled three-way comparisons (6 scenes x 3 seeds), native was picked best only once (6%). And the pattern of its losses is consistent โ€” across our 8-case test set, native H3-Image drifts on exactly the details that make a swap a swap: skin tone shifts (cafรฉ case: the swapped woman comes out visibly lighter than the reference), pose changes (full-body case: the jogging stride becomes a standing hand-in-pocket), outfit details wander, and on cross-style swaps onto non-frontal faces it fails outright โ€” anime character โ†’ strict-profile photo failed on 3/3 seeds (a hybrid face, the character printed into a prop, and the swap ignored). The merged model held identity, outfit and pose on every case we validated. If โ€œclose enough at a glanceโ€ is fine, the stock model plus our prompt template may do. If the person has to actually look like your reference โ€” that's what the merge is for.

โ€œWhere's the LoRA? Why is the โ€˜LoRAโ€™ 40 GB?โ€ It isn't a 40 GB adapter โ€” this repo is the adapter fused into the full checkpoint (same size as Comfy-Org's stock DiT), so there's one file and nothing to configure. If you want the 155 MB adapter by itself:

File Layout Use
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
lora/h3_image_character_swap_diffusers.safetensors (173 MB) diffusers transformer.load_lora_adapter(state_dict, prefix=None) for strength control

No extraction needed โ€” the merged checkpoint is exactly W + BยทA of these adapters.

โ€œIn some examples the character looks the wrong way.โ€ That's the design, not a bug: a swap follows the source person's pose, position and gaze (it's what makes it a swap instead of a paste). The model re-renders the reference character facing the source's way; on extreme profile/cross-style combos that re-render can look off. Rephrase the โ€œsame pose, position, scale and gazeโ€ part of the prompt if you'd rather follow the reference's orientation.

โ€œCan I use it commercially?โ€ The checkpoint is under the MiniMax-H3-Image Community License. Free, including commercial use, in the Applicable Territory โ€” which is worldwide except the EU, UK, South Korea and the USA. Two triggers require MiniMax's prior written authorization (apply here): annualized revenue above $1M, or providing it as a hosted service to third parties. In the excluded territories the community license grants no rights โ€” contact MiniMax. MiniMax claims no rights over your outputs. (This is a summary, not legal advice โ€” read the LICENSE.)

โ€œWhat prompt should I use?โ€ See Prompting tips โ€” scene as <Picture 1>, character as <Picture 2>, name the person, and say what to preserve.

ComfyUI

One file, no LoRA nodes, no adapters โ€” character swap is built into the checkpoint itself.

โžก Download the character-swap workflow (drag the JSON onto the ComfyUI canvas; it's the official MiniMax-H3-Image: Image Edit template pre-wired with a second reference input and the swap prompt โ€” you only load your two images.)

Use the pre-merged ComfyUI checkpoint โ€” a drop-in replacement for Comfy-Org's stock file:

File Source Goes in
minimax_h3_image_character_swap_bf16.safetensors (40 GB) this repo, comfyui/ ComfyUI/models/diffusion_models/
qwen3vl_32b_minimax_h3_int8_convrot.safetensors (25 GB) Comfy-Org/MiniMax-H3-Image ComfyUI/models/text_encoders/
minimax_h3_image_vae_fp16.safetensors (1.2 GB) Comfy-Org/MiniMax-H3-Image ComfyUI/models/vae/
qwen3.5_9b_w4a8_gptq.safetensors (7.3 GB, optional prompt expander) Comfy-Org/MiniMax-H3-Image ComfyUI/models/text_encoders/
  1. Requires ComfyUI 0.45.0+ with template pack 0.11.104+.
  2. Open our character-swap workflow (or the stock "MiniMax-H3-Image: Image Edit" template) and point the diffusion model loader at minimax_h3_image_character_swap_bf16.safetensors.
  3. Load the scene as the first Load Image (<Picture 1>) and the character reference as a second one (<Picture 2>), then prompt, e.g.:

    Swap the person in <Picture 1> with the character in <Picture 2>. Keep the reference character's face, hair and outfit. Preserve the background, lighting, camera and all other people.

  4. Sampling comes pre-set by the template: euler / simple, 6 steps, CFG 1, denoise 1. 4 MP is a good starting canvas; the model is native at ~16 MP.

The merged file is numerically verified against the LoRA delta (208/208 targeted tensors, bit-exact W + BยทA) and ships the same pruned-bf16 layout as Comfy-Org's official file, so every stock template that loads minimax_h3_image_pruned_bf16.safetensors works unchanged โ€” just with character-swap built in. Fusion provenance: comfyui/minimax_h3_image_character_swap_bf16.provenance.json.

Because the adapter is fused in, there is nothing else to install: no LoRA node, no strength to tune โ€” every image you edit with this checkpoint has character swap built in. (Prefer the 155 MB adapter by itself with strength control? See the FAQ โ€” it's in lora/.)

Note: end-to-end runs on this page were validated through the diffusers pipeline; the ComfyUI checkpoint is the identical math in Comfy's own layout. Report any ComfyUI-specific surprises in the discussions tab.

Usage (diffusers)

Requires diffusers==0.43.0. The text encoder (~67 GB) is referenced from MiniMaxAI/MiniMax-H3-Image and loaded by the modular pipeline automatically.

import torch
from diffusers import ModularPipeline

REPO = "akhaliq/MiniMax-H3-Image-Character-Swap"
blocks = ModularPipeline.from_pretrained(REPO).blocks
pipe = blocks.init_pipeline(REPO)
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")  # full local run needs ~140 GB VRAM (DiT 66 GB + Qwen3-VL encoder 67 GB)

prompt = (
    "Swap the man in the purple shirt in <Picture 1> with the character in <Picture 2>. "
    "Keep the replacement character's face, hair, identity and outfit exactly as in <Picture 2>, "
    "including its art style. The replacement must hold the same pose, position, scale and gaze. "
    "Preserve everything else in <Picture 1> unchanged."
)
image = pipe(
    prompt=prompt,
    image=[scene_image, character_image],  # PIL images: <Picture 1>, <Picture 2>
    width=2720, height=1536,               # ~4 MP, multiple of 32; 16 MP also works
    generator=torch.Generator("cpu").manual_seed(904231),
    output="images",
)[0]

Single-GPU trick: the heavy part is the text encoder, not the swap. Run the encoder remotely (the official demo Space splits it out the same way) and only the 66 GB DiT + 2 GB VAE touch your GPU โ€” see merge/merge_and_validate.py, which runs exactly that way on one H200. The merged DiT is a drop-in replacement anywhere MiniMaxAI/MiniMax-H3-Image's transformer_diffusers/ is used.

Prompting tips (from the LoRA author's recipe, adapted to images):

  • Order matters: scene first (<Picture 1>), character second (<Picture 2>).
  • Name the target person explicitly ("the man in the yellow sweater, second from the left").
  • Say "keep the reference character's face, hair and outfitโ€ฆ preserve the scene, lighting, camera and all other people."
  • 6 sampling steps, CFG 1 (the model is distilled) โ€” no tuning needed.

What this is, exactly

  • Merge: h3_character_swap_v1.5.safetensors (rank 16, 312 modules: attention + FFN of all 50 DiT blocks and the 2 token-refiner blocks) converted with diffusers 0.43.0's _convert_non_diffusers_minimax_h3_lora_to_diffusers and fused at strength 1.0 (W += B @ A, alpha == rank) into transformer_diffusers/. Verified 624/624 key + shape match before fusing.
  • Validation: fused outputs match the LoRA-attached model within bf16 sampler rounding (21-27 dB PSNR). In extended 3-way labeled comparisons (17 cases, 6 scenes x 3 seeds) the merged checkpoint was preferred in 82% (14/17) โ€” native won once, the standalone LoRA twice.
  • Not included: the classic MiniMaxH3ImagePipeline layout (transformer/, PDD heads) โ€” the merge exists only in the modular transformer_diffusers/ layout. The audio/video capabilities of the H3 video model are unaffected (they live in a different checkpoint).
  • Provenance: merge + validation script: merge/merge_and_validate.py.

Limitations

  • The LoRA was trained for video character swap (on Ref2VA, 24 fps clips); the port to images is validated on 8 hard cases, not a broad benchmark. Report surprises in the discussions tab.
  • Swaps follow the source person's pose and gaze by design; on extreme profile/cross-style combos the re-rendered viewing direction can look off โ€” tune the pose/gaze phrase in the prompt.
  • Like the base model, it can drift on extreme poses, heavy occlusion, or very small faces.
  • The character-swap LoRA is an experimental community model; identity fidelity varies with the reference quality (a clean, multi-view character sheet works best).
  • Use responsibly: swapping real people into scenes carries consent and likeness rights. Do not use it to depict real people without their permission.

License & attribution

Downloads last month
133
Inference Providers NEW
This model isn't deployed by any Inference Provider. ๐Ÿ™‹ Ask for provider support

Model tree for akhaliq/MiniMax-H3-Image-Character-Swap

Spaces using akhaliq/MiniMax-H3-Image-Character-Swap 3