qwen-edit ยท diff
git:20260826.290d7d3 to git:20261012.a62dd5a
48 added, 8 removed. Audit A to A.
---
name: qwen-edit
- description: AI image editing prompting patterns for Qwen-Image-Edit. Use when editing photos while preserving identity, reframing cropped images, changing clothing or accessories, adjusting poses, applying style transfers, or character transformations. Provides prompt patterns, parameter tuning, and examples.
+ description: AI image editing prompting patterns for Qwen-Image (Qwen-Image-Edit-2511 by default, Qwen-Image-2.1 as a non-commercial Modal opt-in). Use when editing photos while preserving identity, reframing cropped images, changing clothing or accessories, adjusting poses, applying style transfers, or character transformations. Provides prompt patterns, parameter tuning, and examples.
---
# Qwen-Image-Edit Skill
- AI-powered image editing using Qwen-Image-Edit-2511 via RunPod serverless.
+ AI-powered image editing via `tools/image_edit.py`. The model depends on the deployment:
- **Status:** Evolving - learnings being captured as we experiment
+ | Deployment | Model | License | Defaults | Max inputs |
+ |-----------|-------|---------|----------|------------|
+ | `--cloud modal` (default) | Qwen-Image-Edit-2511 | Apache-2.0, commercial OK | 8 steps, guidance 1.0 | 3 images |
+ | `--cloud modal`, app deployed with `IMAGE_EDIT_MODEL=qwen-image-2.1` | **Qwen-Image-2.1** (2026-09, unified gen+edit, 7B DiT, RGBA) | Qwen Research License -- **non-commercial** ("research or evaluation purposes only") | 40 steps, guidance 1.0 (no CFG) | 10 images |
+ | `--cloud runpod` | Qwen-Image-Edit-2511 + Lightning LoRA | Apache-2.0, commercial OK | 8 steps, guidance 1.0 | 3 images |
+ The tool prints `Model:` and `Steps:` after each edit, so you can tell which model the Modal app
+ runs and how many steps it took. Without `--steps`, each model runs its own default above.
+ Opt in with `IMAGE_EDIT_MODEL=qwen-image-2.1 uv run modal deploy docker/modal-image-edit/app.py`;
+ deploy again without it to switch back.
+
+ **Status:** Evolving - learnings being captured as we experiment. The prompt
+ patterns and parameter findings in `examples.md` / `parameters.md` were measured
+ on 2511; re-check them on 2.1 before relying on the exact numbers.
+
+ ### Qwen-Image-2.1 specifics (Modal opt-in)
+
+ - **Not step-distilled** -- 40 steps is the model card default. The old 8-step
+ default was tuned for 2511's Lightning LoRA, which 2.1 doesn't have here, so expect
+ low step counts to cost quality (untested).
+ - **Sampled without guidance.** `--guidance 1.0` (default) is how the model is meant
+ to run. `>1` switches on true CFG (blank negative prompt if you pass none) and
+ doubles the cost of every step.
+ - **Multi-image:** the first `--input` is the image being edited ("image 1"); the
+ rest are references in order ("image 2", ...). Up to 10. Output size follows the
+ first image's aspect ratio at ~1MP.
+ - **Local edits:** draw a circle or paint an annotation on the image, or pass a
+ separate mask as an extra `--input`, and say what to change there
+ (e.g. "Remove the watch inside the red circle").
+ - **RGBA:** transparent PNG inputs keep their alpha. For a cut-out, prompt
+ `"This is an RGBA image with transparency. <subject>. The image has alpha channel
+ and the background is transparent."` -- the result comes back as an RGBA PNG only
+ when the model actually produced transparency.
+
## When to Use This Skill
Use when the user wants to:
- Edit/transform photos while preserving identity
- Reframe cropped images (fix cut-off heads, etc.)
- Change clothing, add accessories
- Change pose (arm positions, hand placement)
- Apply style transfers (cyberpunk, anime, oil painting)
- Adjust lighting/color grading
- Add/remove objects
- Character transformations (Bond, Neo, etc.)
## When NOT to Use
- **Background replacement (single image)** - creates cut-out artifacts, halos
- **Face swapping** - cannot preserve identity from reference
- **Outpainting** - can't extend canvas reliably
## Use With Care
- **Multi-image compositing** - CAN work with explicit identity anchors (see examples.md for prompt patterns). Requires describing distinctive features (hair texture/color, ethnicity, outfit) and using guidance ~2.0
- **Camera angle changes** - Inconsistent results. Vertical angles (low/high) work better than rotational (three-quarter view)
## Quick Reference
```bash
# Basic edit
uv run tools/image_edit.py --input photo.jpg --prompt "Add sunglasses"
# With negative prompt (recommended)
uv run tools/image_edit.py --input photo.jpg \
--prompt "Reframe as portrait with full head visible" \
--negative "blur, distortion, artifacts"
# Style transfer
uv run tools/image_edit.py --input photo.jpg --style cyberpunk
# Background (use cautiously - often fails)
uv run tools/image_edit.py --input photo.jpg --background office
- # Higher quality
- uv run tools/image_edit.py --input photo.jpg --prompt "..." --steps 16 --guidance 3.0
+ # Higher quality (RunPod / 2511 -- on Modal / 2.1 the 40-step default already is)
+ uv run tools/image_edit.py --input photo.jpg --prompt "..." --steps 16 --guidance 3.0 --cloud runpod
- # Multi-image composite (identity-preserving)
+ # Extract the subject onto a transparent background (Modal / 2.1)
+ uv run tools/image_edit.py --input product.jpg --prompt "This is an RGBA image with transparency. The product from the photo. The image has alpha channel and the background is transparent." --output product_cutout.png
+
+ # Multi-image composite (identity-preserving) -- settings tuned on RunPod / 2511
uv run tools/image_edit.py --input person.jpg background.jpg \
--prompt "The [ethnicity] [gender] with [hair description] from first image is now in [scene] from second image. Same [features], [outfit]." \
--negative "different ethnicity, different hair color, different face shape, generic stock photo" \
- --steps 16 --guidance 2.0
+ --steps 16 --guidance 2.0 --cloud runpod
+
+ # Multi-image composite on Modal / 2.1 -- up to 10 references, defaults usually suffice
+ uv run tools/image_edit.py --input person.jpg outfit.jpg shoes.jpg background.jpg \
+ --prompt "The person from image 1 wearing the outfit from image 2 and the shoes from image 3, standing in the scene from image 4. Same face and hair."
```
## Key Files
- `prompting.md` - Prompt patterns and structure
- `examples.md` - Good/bad examples from experiments
- `parameters.md` - Tuning steps, guidance, negative prompts
## Tool Location
- `tools/image_edit.py` - CLI wrapper for RunPod endpoint
+ `tools/image_edit.py` - CLI wrapper for the Modal (`docker/modal-image-edit/`) and RunPod
+ (`docker/runpod-qwen-edit/`) endpoints
## Related Docs
- `docs/qwen-edit-patterns.md` - Character transformation patterns
- `.ai_dev/qwen-edit-research.md` - Research notes