comfyui-character

name

comfyui-character

description

Produce consistent character images and reference-driven edits inside ComfyUI. Use this Skill for scenarios 1–4 from `comfyui-studio`'s trigger index: 1=生图 (selfie from text), 2=模仿 (mimic a reference image), 3=改图 (Flux.2 Klein single-image edit), 4=融合 (Flux.2 Klein dual-image fuse). Ships four preset workflow templates: `workflows/selfie-text-to-image.json`, `workflows/selfie-mimicry.json`, `workflows/flux2-klein-image-edit.json`, `workflows/flux2-klein-image-edit-dual.json`.

ComfyUI Character

Four preset workflows for character-consistent selfies (with a user-trained LoRA) and reference-image-driven edits (with Flux.2 Klein). The Plugin does not distribute any character LoRA, face embedding, voice sample, or other private identity asset. Every character this Skill produces is one the user trained themselves and dropped into ComfyUI's standard models/loras/ directory.

The 4 trigger scenarios

These are scenarios 1–4 from comfyui-studio's index. The number is the trigger, the workflow is the implementation.

#	Trigger	User says	Preset workflow	Model stack at a glance
1	生图 (generate)	"用我的角色画一张自拍"	workflows/selfie-text-to-image.json	Z-Image base + 2 LoRAs (face + style)
2	模仿 (mimic)	"照着这张照片再画一张同款"	workflows/selfie-mimicry.json	ZIT-flavoured Z-Image finetune + 2 LoRAs + Z-Image Fun ControlNet + Qwen3.5 vision LLM
3	改图 (edit)	"把背景换成办公室"	workflows/flux2-klein-image-edit.json	Flux.2 Klein 9B + Qwen3 8B + bundled VAE
4	融合 (fuse)	"把这张图里的人物放到那张图里"	workflows/flux2-klein-image-edit-dual.json	same as #3, with 2x LoadImage inputs

Scenarios 1 and 2 share the same two LoRA placeholders (your_face_lora.safetensors for the character's face, your_style_lora.safetensors for the artistic style). Scenarios 3 and 4 do not use LoRAs at all — the character / object identity is carried by the reference image itself, not by a LoRA.

Why scenarios 1 and 2 use different checkpoints

The two selfie presets use different checkpoints for a reason: the direct selfie is the "default look" (Z-Image base, 8 steps, the canonical character), while the mimicry preset is a "reference-driven" workflow that needs a ZIT-flavoured Z-Image finetune plus a ControlNet and a local vision LLM to do the imitation. They are not interchangeable — if you want scenario 1 (direct generation), use the Z-Image base; if you want scenario 2 (mimicry), use the ZIT finetune.

---

Scenario 1 — 生图 (generate) — selfie-text-to-image.json

Pipeline: Checkpoint → LoraLoaderModelOnly (face) → LoraLoaderModelOnly (style) → KSampler.

Models

Field	Value (as written in the JSON)	Where it lives on disk
CheckpointLoaderSimple.ckpt_name	Z-Image-Base-8steps-豹豹喵呜の白玉v2White_Marble-AIO_v2-bf16.safetensors	models/checkpoints/
LoraLoaderModelOnly[0].lora_name (face)	your_face_lora.safetensors (placeholder — replace with your file)	models/loras/
LoraLoaderModelOnly[1].lora_name (style)	your_style_lora.safetensors (placeholder — replace with your file)	models/loras/
CLIP / VAE	bundled with the CheckpointLoader (outputs […, 1] and […, 2])	—

Submit

1. Place the two LoRAs under <ComfyUI>/models/loras/. Edit the two LoraLoaderModelOnly.lora_name fields in the JSON to point at your filenames if they differ from the placeholders.
2. Compose the 4-module prompt (see references/prompt-patterns.md):

   <trigger word>, <identity block>, <outfit block>, <pose + scene block>
   

   Pass via --prompt on the CLI; the __PROMPT__ marker in the workflow gets replaced.
3. Submit via the Python script or the MCP server (see comfyui-workflow/SKILL.md).

Knobs

Knob	Default	What it does	When to change it
LoraLoaderModelOnly[0].strength_model (face)	1.0	How strongly the face LoRA controls the model	Lower to 0.7 if the character overpowers the scene
LoraLoaderModelOnly[1].strength_model (style)	1.0	How strongly the style LoRA controls the model	Lower to 0.7 if the style is too dominant
KSampler.steps	8	Distilled-model default; raise to 20+ for a non-distilled base	—
KSampler.cfg	1.5	Distilled-model default; raise to 6 for a non-distilled base	—

---

Scenario 2 — 模仿 (mimic) — selfie-mimicry.json

Pipeline: LoadImage (reference) → AIO_Preprocessor → ControlNet application → UNETLoader (ZIT-flavoured finetune) → KSampler → VAEDecode → SaveImage, with two LoraLoaderModelOnly nodes (face + style) and a llama_cpp_instruct_adv node that runs the vision LLM on the reference to produce the positive prompt.

This workflow does not use IP-Adapter. It uses a different mechanism: a ControlNet is fed the reference image's preprocessed output, and a vision LLM (Qwen3.5) looks at the reference and produces a text description that becomes the positive prompt. The two LoRAs then keep the character identity stable.

Models

Field	Value (as written in the JSON)	Where it lives on disk
UNETLoader.unet_name	ZIT-moodyPornMix_zitV10R1DPO_fp16.safetensors (ZIT-flavoured Z-Image finetune)	models/unet/ (or wherever your UNETLoader looks)
ControlNetLoader.control_net_name	Z-Image-Fun-Controlnet-Union-2.1.safetensors	models/controlnet/
LoraLoaderModelOnly[0].lora_name (face)	your_face_lora.safetensors (placeholder — replace)	models/loras/
LoraLoaderModelOnly[1].lora_name (style)	your_style_lora.safetensors (placeholder — replace)	models/loras/
llama_cpp_instruct_adv.ckpt_name (vision LLM)	Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-Q4_K_M.gguf	models/llama/ (or wherever the llama.cpp loader looks)
LoadImage.image	__IMAGE1__ (replace at submit time with --filename)	input/

Custom nodes required

The selfie-mimicry.json workflow depends on several custom nodes that ship outside the default ComfyUI install. Without these, submission will fail with missing_node_type.

Custom node	Used for	Install
comfyui_controlnet_aux (or any AIO_Preprocessor + ZImageFunControlnet provider)	ControlNet preprocessing and application	https://github.com/Fannovel16/comfyui_controlnet_aux
ComfyUI-Manager + the ModelPatchLoader / ZImageFunControlnet nodes	Loading the Z-Image Fun ControlNet union	any pack that ships ModelPatchLoader
ComfyUI-LLaMA-CPP (or a llama.cpp loader for ComfyUI)	Loading Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-Q4_K_M.gguf for vision reprompting	https://github.com/daniel-lewis-ab/ComfyUI-LLaMA-CPP (or compatible)
rgthree-comfy (or compatible Any Switch / Image Comparer pack)	The Any Switch (rgthree) nodes in the original workflow	https://github.com/rgthree/rgthree-comfy
ComfyUI-Impact-Pack (or any LayerUtility: ImageScaleByAspectRatio V2 provider)	Aspect-ratio-aware image scaling	https://github.com/ltdrdata/ComfyUI-Impact-Pack

Submit

1. Install the custom nodes above.
2. Place the model files under the standard ComfyUI directories.
3. Drop a reference image into the ComfyUI input folder and pass its filename with --filename on the CLI (the __IMAGE1__ marker in the workflow's LoadImage.image field gets replaced). Or edit the LoadImage.image field directly in the JSON.
4. Set the trigger word via --trigger (the __TRIGGER__ marker in the CR Text node gets replaced).
5. Submit via the Python script or the MCP server. The script will poll until the run finishes and download the saved image from outputs/.

The 4-module prompt (for the vision-LLM-reprompted positive prompt)

For scenario 2 the prompt is produced by the vision LLM, not by the user. The user provides only the trigger word (via --trigger). The vision LLM fills in the rest of the description from the reference image. See references/prompt-patterns.md for the rules of thumb on what the trigger word should and shouldn't include.

---

Scenario 3 — 改图 (edit) — flux2-klein-image-edit.json

Pipeline: LoadImage (reference) → Flux.2 Klein UNET + CLIP + VAE → KSampler → VAEDecode → SaveImage. One LoadImage input (__IMAGE1__).

Models

Field	Value (as written in the JSON)	Where it lives on disk
UNETLoader.unet_name	flux-2-klein-base-9b-fp8.safetensors	models/unet/
DualCLIPLoader.clip_name1	qwen_3_8b_fp8mixed.safetensors	models/clip/
DualCLIPLoader.clip_name2	diffusion_pytorch_model.safetensors	models/clip/
VAELoader.vae_name	bundled with the UNET, or the user's preferred Flux.2 Klein VAE	models/vae/
LoadImage.image	__IMAGE1__ (replace at submit time with --filename)	input/

Submit

1. Place the reference image into the ComfyUI input folder and pass its filename with --filename on the CLI.
2. Pass the edit prompt with --prompt. The prompt describes what to change (e.g. "the same person sitting in an office chair, professional lighting"). The reference image supplies the unchanged parts.
3. Submit via the Python script or the MCP server.

Knobs

Knob	Default	What it does	When to change it
KSampler.steps	20	Standard distilled-Klein default	Raise to 30+ for higher quality at the cost of latency
KSampler.cfg	1.0	Distilled-Klein default	Usually leave alone
KSampler.denoise	0.75	How much the prompt is allowed to change the reference	Lower to 0.4–0.5 for "subtle" edits; raise to 0.9+ for "full re-imagination"

---

Scenario 4 — 融合 (fuse) — flux2-klein-image-edit-dual.json

Same model stack as scenario 3, but with two LoadImage inputs (__IMAGE1__ and __IMAGE2__). The semantic is "the subject of image 1 in the scene of image 2, with the prompt describing the rest" — e.g. "the person from image 1, now wearing the outfit from image 2, in the office of image 2".

Models

Identical to scenario 3, with one extra LoadImage input. Replace __IMAGE1__ with --filename and __IMAGE2__ with --filename2 at submit time.

Submit

1. Place both reference images into the ComfyUI input folder.
2. Pass filenames with --filename (image 1, the subject) and --filename2 (image 2, the scene / outfit).
3. Pass the fusion prompt with --prompt describing how to combine them.
4. Submit via the Python script or the MCP server.

Knobs

Same as scenario 3, plus an extra ReferenceLatent strength control (default 0.85) that governs how much of image 2 the result should inherit.

---

Why most "consistent character" attempts fail (scenarios 1 and 2)

A LoRA is a strong prior on identity, but it is not magic. Three things derail consistency:

1. Inconsistent training data. Mix of angles, lighting, outfits, and stylizations. A LoRA trained on a single photo or on stylistically inconsistent reference images will not generalize. See references/lora-guide.md for the data-prep checklist.
2. Weak prompt structure. Putting the LoRA trigger word in a wall of adjectives loses the signal. The LoRA trigger must lead the prompt and the prompt must avoid words that fight it.
3. Wrong sampler / scheduler / CFG for the base model. Some samplers oversmooth identity features. See references/prompt-patterns.md for the rules of thumb.

LoRAs are required for scenarios 1 and 2

Both selfie workflows' LoraLoaderModelOnly nodes reference placeholder LoRA filenames (your_face_lora.safetensors and your_style_lora.safetensors). If those files do not exist on disk, ComfyUI will fail at submission. To swap in a different LoRA, edit the lora_name field in the workflow JSON to point at your file. The LoRAs are user identity assets; the Plugin does not bundle them and does not name anyone's private LoRAs.

What this Skill does not do

• It does not run LoRA training. Training is its own project and has its own tooling (Kohya, OneTrainer, ai-toolkit). The Skill only consumes a LoRA the user already has.
• It does not bundle or distribute any LoRA, model, face embedding, or voice sample. Every identity asset is user-supplied.
• It does not invent characters. The user must define who the character is.

Requirements

• ComfyUI running locally (see comfyui-workflow/SKILL.md for the transport).
• For scenarios 1 and 2: a face LoRA and a style LoRA in models/loras/. The workflow JSONs reference them as your_face_lora.safetensors and your_style_lora.safetensors.
• For scenario 2: the custom-node pack list above. Plus a ZIT-flavoured Z-Image finetune, a Z-Image Fun ControlNet, and a Qwen3.5 GGUF vision LLM.
• For scenarios 3 and 4: the Flux.2 Klein 9B UNET, the Qwen3 8B CLIP, and the bundled VAE.

License

Apache-2.0. See LICENSE.