| --- |
| license: apache-2.0 |
| library_name: ComfyUI |
| pipeline_tag: image-to-image |
| tags: |
| - comfyui |
| - image-editing |
| - joyai |
| base_model: jdopensource/JoyAI-Image-Edit-Diffusers |
| --- |
| |
| # JoyAI-Image-Edit (ComfyUI weights) |
|
|
| Single-file `.safetensors` checkpoints of [JoyAI-Image-Edit](https://github.com/jd-opensource/JoyAI-Image), repackaged for **native ComfyUI** support (no custom node required). |
|
|
| JoyAI-Image-Edit is the single-image instruction-guided editing model of the [JoyAI-Image](https://github.com/jd-opensource/JoyAI-Image) family. It takes one reference image plus a text instruction and generates the edited result. |
|
|
| ## Files |
|
|
| | File | Size | Goes into | Component | |
| |------|------|-----------|-----------| |
| | `diffusion_models/joy_image_edit_bf16.safetensors` | ~31 GB | `ComfyUI/models/diffusion_models/` | `JoyImageEditTransformer3DModel` (bf16) | |
| | `text_encoders/qwen3vl_joyimage_bf16.safetensors` | ~17 GB | `ComfyUI/models/text_encoders/` | Qwen3-VL-8B text encoder (bf16) | |
| | `vae/joy_image_edit_vae.safetensors` | ~243 MB | `ComfyUI/models/vae/` | `AutoencoderKLWan` | |
|
|
| The repo's directory layout already matches `ComfyUI/models/`, so a single `hf download` into your models root drops every file where it needs to go. |
|
|
| ## Installation |
|
|
| The model runs natively in ComfyUI. Native support is proposed upstream in [Comfy-Org/ComfyUI#14428](https://github.com/Comfy-Org/ComfyUI/pull/14428); until it is merged, install the fork branch: |
|
|
| ```bash |
| git clone -b joyimage-edit-pr https://github.com/feice-huang/ComfyUI.git |
| cd ComfyUI |
| pip install -r requirements.txt |
| ``` |
|
|
| Once the PR is merged upstream, the stock ComfyUI release will run these weights with no fork needed. |
|
|
| Then download the weights straight into `ComfyUI/models/`: |
|
|
| ```bash |
| hf download jdopensource/JoyAI-Image-Edit-ComfyUI \ |
| --local-dir /path/to/ComfyUI/models |
| ``` |
|
|
| Restart ComfyUI. |
|
|
| ## Usage |
|
|
| Build the graph from these native nodes: |
|
|
| 1. **Load Diffusion Model** (`UNETLoader`) → `diffusion_models/joy_image_edit_bf16.safetensors` |
| 2. **Load CLIP** (`CLIPLoader`) → `text_encoders/qwen3vl_joyimage_bf16.safetensors`, type `joyimage` |
| 3. **Load VAE** (`VAELoader`) → `vae/joy_image_edit_vae.safetensors` |
| 4. **Load Image** (`LoadImage`) for the reference |
| 5. **TextEncodeJoyImageEdit** — feed `clip`, `vae`, the instruction, and the reference `image`. Wire one instance for the positive prompt and one (empty prompt, same image) for the negative. The node bucket-resizes the reference to the 1024-base buckets, VAE-encodes it, and appends the reference latent to the conditioning; its `image` output feeds `VAEDecode` / empty-latent sizing. |
| 6. **KSampler** → **VAEDecode** → **SaveImage** |
|
|
| Example workflow: [workflow_joyimage_edit.json](https://github.com/user-attachments/files/28871922/workflow_joyimage_edit.json) |
|
|
| ## Recommended parameters |
|
|
| | Parameter | Value | |
| |-----------|-------| |
| | Steps | 40 | |
| | CFG | 4.0 | |
| | Sampler | `euler` | |
| | Scheduler | `simple` | |
| | dtype | bf16 | |
| | Resolution | auto (1024-base buckets) | |
|
|
| ## GGUF quantizations |
|
|
| Lower-bit GGUF quants of the transformer and text encoder are available at [huangfeice/JoyAI-Image-Edit-Diffusers-GGUF](https://huggingface.co/huangfeice/JoyAI-Image-Edit-Diffusers-GGUF) (community contribution). The VAE here is the only VAE you need — GGUF doesn't quantize the VAE. |
|
|
| ## Links |
|
|
| - Source code and documentation: [github.com/jd-opensource/JoyAI-Image](https://github.com/jd-opensource/JoyAI-Image) |
| - Original Diffusers-format weights: [jdopensource/JoyAI-Image-Edit-Diffusers](https://huggingface.co/jdopensource/JoyAI-Image-Edit-Diffusers) |
| - Multi-image edit model (ComfyUI): [jdopensource/JoyAI-Image-Edit-Plus-ComfyUI](https://huggingface.co/jdopensource/JoyAI-Image-Edit-Plus-ComfyUI) |
|
|
|
|
