---

license: apache-2.0 task_categories:

• image-to-image language:
• en tags:
• comfyui
• qwen
• character-generation
• custom-node
• workflow
• image-generation pretty_name: ComfyUI Character Composer version: 2.0 release_date: 2026-5-18 size_categories:
• n<1K

---

ComfyUI Character Composer

Version: 2.0 • Release Date: 2026-05-18 • License: Apache-2.0

Structured, JSON-driven character prompt system for ComfyUI.

Designed for consistent, controllable character generation with Qwen-style workflows, replacing random prompt chaos with a more deterministic composition layer.

Spicier companion dataset: https://huggingface.co/datasets/unh1nge/comfyui-character-composer

<img src="preview/ComfyUI_01625_.png" width="100%" />

New / Advanced UI & Prompt generation (v2.0)

• Character creation node now prints the final prompt it generates for easier debugging.
• Character creation node now accepts up to 3 input images at the same time

New / Advanced toggles (v1.2)

• preserve_input_position (BOOLEAN, advanced): If True and a reference image is supplied, injects a short preserve-position hint into the prompt (or replace {preserve_position} if present).

• preserve_character_look (BOOLEAN, advanced): Strictly preserve known look traits from UI selections or prompt inference, and from the reference image if supplied. When active, unknown character look traits are no longer auto-filled so the same person identity remains stable. Only traits with actual values are locked so fill_auto_traits can still populate non-look fields like pose, setting, and props.

• outfit_mode (COMBO): auto / keep / random — keeps or randomizes the outfit trait when used with preserve_character_look and/or fill_auto_traits.

---

Recommended Stack

• Model: Qwen-Image-Edit-Rapid-AIO
• Workflow: QWEN AIO CC 3X WORKFLOW.json
• Node: ComfyUI Character Composer

This setup combines:

• Qwen spatial reasoning
• structured prompt composition
• controllable character generation

---

Text-to-image

Use QWEN AIO CC 3X WORKFLOW.json with the image sockets left disconnected or just bypass them for normal prompt-driven generation.

<img src="preview/text-to-image.png" width="100%" />

3-image image-to-image

Use QWEN AIO CC 3X WORKFLOW.json when you want to feed three reference images into the Qwen image-edit encoder.

<img src="preview/3-image-to-image.png" width="100%" />

---

Why This Node Exists

Most character-generation pipelines:

• rely on random prompts
• produce inconsistent characters
• become hard to reproduce
• break down when too many pose, style, and scene tags pile up

This node provides:

• structured trait composition
• seed-based deterministic behavior
• prompt cleanup and conflict handling
• JSON-driven customization without rewriting Python

---

Current Features

• JSON-driven trait libraries via tags.json and tags_NSFW.json
• Selectable tag source file with merged UI dropdowns
• Smart prompt assembly with weighted core traits
• Wildcard support such as {hair_color} or {interaction}
• Backward compatibility for legacy {pose_x} placeholders
• Workflow-level smart presets
• Composition-aware defaults and conflict handling
• Scene sanitization for unstable interaction / pose / camera combinations
• Complexity guard that trims low-priority details when prompts get overloaded
• Alias matching from JSON, such as blond -> blonde
• Tag conflict rules from JSON, such as kokoshnik vs ushanka
• Detail budgets and category weights from JSON
• A compact output surface: final prompt, negative prompt, and image passthroughs

<img src="preview/ComfyUI_01543_.png" width="100%" />

---

Main Controls

Core inputs

• input_prompt
• seed
• tag_file
• extra_modifiers

High-level steering

• smart_preset

  • none
  • safe portrait
  • high detail character
  • winter fashion
  • paired cinematic
  • simple anatomy-safe

• composition_mode

• auto

• solo portrait

• fashion

• paired

• close-up

• full body

• winter

• fantasy

• subject_count

• auto (recommended) — node will infer 1/2/3/4/group from prompt/interaction/pose

• 1

• 2

• 3

• 4

• group

• detail_level

  • minimal
  • balanced
  • rich

• style_strength

  • subtle
  • balanced
  • strong

Utility toggles

• fill_auto_traits

  • fills unresolved auto fields from the active tag file

• reset_overrides

  • pushes trait dropdowns back to auto for the current generation

• bypass_generator

  • returns the raw input_prompt unchanged

Trait sections

The node UI is grouped into:

• CORE CREATIVE
• CHARACTER LOOK
• CAMERA & FRAMING
• STYLE & SCENE
• OPTIONAL EXTRAS

Notable rename:

• pose_x is now interaction

---

Example

Input:

{hair_color} {hair_style} woman in {setting}

Possible output:

gravure, photorealistic, soft lighting, 8k, (1woman:1.20), model blonde beach waves hair, shot on 35mm film grain, modern portrait, wearing bikini minimal fabric, shot as a three-quarter shot natural perspective, at the tropical beach open horizon

---

Installation

1. Clone into your ComfyUI/custom_nodes directory:

cd ComfyUI/custom_nodes
git clone https://github.com/unh1nge/comfyui-character-composer

2. Restart ComfyUI.

3. Add the node: ComfyUICharacterComposer Category: Prompt

For the fastest setup, load QWEN AIO CC 3X WORKFLOW.json. It works for text-to-image when the image inputs are disconnected, and for three-reference image editing when image1, image2, and image3 are connected.

<img src="preview/ComfyUI_01645_.png" width="100%" />

---

Usage

1. Start with an optional natural-language base prompt.
2. Pick a tag_file.
3. Set a smart_preset or composition_mode if you want the node to bias defaults for you.
4. Choose subject_count, detail_level, and style_strength.
5. Leave most dropdowns on auto unless you need exact overrides.
6. Use fill_auto_traits when you want the node to complete unresolved traits.
7. Use {tags} inside input_prompt if you want explicit wildcard injection.
8. Check the final prompt preview after each run.

<img src="preview/ComfyUI_01877_.png" width="100%" />

---

JSON Customization

The node is intentionally data-driven. Most tuning can now happen in JSON.

Trait lists

The standard visible dropdown values still live in keys such as:

• hair_color
• outfit
• interaction
• setting
• prop

interaction will also load from legacy pose_x arrays if needed.

_composer_rules

Optional rule block for prompt behavior and scene stability.

Examples:

• interaction_scene_families
• scene_compatible_pose_hints
• complexity_level_terms
• extreme_focus_terms
• extreme_camera_terms
• accessory_drop_terms
• setting_drop_terms
• setting_restricted_scenes
• camera_downgrade
• detail_budgets
• category_weights
• complexity_thresholds

_tag_aliases

Optional synonym mapping for prompt detection without bloating the UI.

Examples:

• blond -> blonde
• fur hat -> ushanka fur hat
• snow maiden outfit -> snegurochka costume

_tag_conflicts

Optional conflict map for incompatible selections.

Examples:

• kokoshnik headdress conflicts with ushanka fur hat
• cat ears conflicts with bunny ears
• winter boots conflicts with high heels

---

Prompt Behavior Notes

• Core traits are weighted more strongly than decorative traits.
• Composition mode can auto-bias camera, focus, scene, and style defaults.
• Smart presets can override default detail_level, style_strength, subject_count, and composition intent.
• Complex interaction scenes may automatically drop risky focus, props, accessories, or settings.
• The complexity guard trims low-priority traits when the prompt becomes too crowded.

This is meant to improve stability, not produce perfectly identical prompts for every setup or model.

---

Outputs

• positive_prompt

  • final assembled prompt

• negative_prompt

  • built-in negative terms

• image1

  • passthrough image input

• image2

  • second passthrough image input for multi-reference Qwen image-edit workflows

• image3

  • third passthrough image input for multi-reference Qwen image-edit workflows

---

Included Workflows

This repository includes workflow JSON files adapted from the Qwen ecosystem and adjusted for structured prompt composition.

• QWEN AIO CC 3X WORKFLOW.json - recommended all-in-one workflow for Qwen-Image-Edit-Rapid-AIO and ComfyUICharacterComposer. Leave the composer image inputs disconnected for text-to-image, or connect image1, image2, and image3 for three-reference image-to-image.

If you want text-to-image, leave image1, image2, and image3 disconnected or bypass the input images in the Qwen workflow.

The included workflows are useful as starting points for:

• text-to-image
• character-consistent edits

---

What This Is Not

• Not a LoRA trainer
• Not a ControlNet pipeline
• Not a full workflow engine

This is a prompt composition layer.

---

Acknowledgements

Built on top of:

Phr00t - Qwen Image Edit ecosystem https://huggingface.co/Phr00t/Qwen-Image-Edit-Rapid-AIO

---

Keywords

ComfyUI, prompt engineering, structured prompts, character generation, Qwen workflow

---

License

Free to use and modify.